API¶

Configuration¶

class coda.db.Session(host='localhost', port=27017, write=True, dbname='coda')¶

Object for managing connection to internal database.

Parameters:	host (str) – Host with database to connect to. port (int) – Port to connect to database with. write (bool) – Whether or not to allow writing to the database. dbname (str) – Name of database to use.

db¶: Internal property for managing connection to mongodb database.

options¶: Return JSON with options on the session.

coda.db.options(*args, **kwargs)¶

Set options for the current session.

Parameters:	kwargs (dict) – List of arbitrary config items to set.

Examples

>>> # set options to defaults
>>> coda.options()
>>> coda.find_one({'name': 'test'}).path
'/file/on/localhost/server'
>>>
>>> # connect to a database for a different host
>>> coda.options({'host': 'remote'})
>>> coda.find_one({'name': 'test'}).path
'/file/on/remote/server'

Files and Collections¶

class coda.File(path, metadata={})¶

Abstract class for file object.

Parameters:	path (list) – List of file object to manage. metadata (dict) – Dictionary with common metadata for collection, specified a priori.

__add__(other)¶

Addition operator for files or collections. Using this, you can add File objects to other File objects to form a Collection, or add File objects to Collection objects to form a new Collection.

Examples

>>> # add files to create collection
>>> one = coda.File('/file/one.txt')
>>> two = coda.File('/file/two.txt')
>>> collection = one + two
>>> print collection
'/file/one.txt'
'/file/two.txt'
>>>
>>> # add file to collection to create new collection'
>>> three = coda.File('/file/three.txt')
>>> collection = three + collection
>>> print collection
'/file/three.txt'
'/file/one.txt'
'/file/two.txt'

__contains__(item)¶: Check if specified string exists in file name.

__eq__(other)¶: Test equality for File objects.

__getattr__(name)¶: Proxy for accessing metadata directly as a property on the class.

__getitem__(name)¶: Proxy for accessing metadata directly as a property on the class.

__gt__(other)¶: Comparison operator. Compares left and right file paths alphanumerically.

__lt__(other)¶: Comparison operator. Compares left and right file paths alphanumerically.

__repr__()¶: Return string representation for file (file path).

__setattr__(name, value)¶: Proxy for setting metadata directly as a property on the class.

__str__()¶: Return string representation for file (file path).

extension¶: Return extension for file.

location¶: Return dirname for file.

metadata¶: Proxy for returning metadata – if the file exists in the database, then pull metadata for it if none already exists. If metadata exists for the object, then return that.

name¶: Return basename for file.

class coda.Collection(files, metadata={})¶

Abstract class for collection of file objects.

Parameters:	files (list) – List of file objects to manage, or path to directory to generate collection from. metadata (dict) – Dictionary with common metadata for collection, specified a priori.

__add__(other)¶

Addition operator for collections or files. Using this, you can add Collection objects to other Colletion objects to form a Collection, or add Collection objects to File objects to form a new Collection.

Examples

>>> # add files to create collection
>>> one = coda.File('/file/one.txt')
>>> two = coda.File('/file/two.txt')
>>> onetwo = one + two
>>> three = coda.File('/file/three.txt')
>>> four = coda.File('/file/four.txt')
>>> threefour = three + four
>>>
>>> # add collection objects to create new collection
>>> print onetwo + threefour
'/file/one.txt'
'/file/two.txt'
'/file/three.txt'
'/file/four.txt'
>>>
>>> # add collection to file object to create new collection
>>> print onetwo + three
'/file/one.txt'
'/file/two.txt'
'/file/three.txt'

__contains__(item)¶: Check if item exists in file set. Input item should be a File object.

__eq__(other)¶: Compare equality for collections.

__getattr__(name)¶: Proxy for accessing metadata directly as a property on the class.

__getitem__(item)¶: Proxy for accessing metadata directly as a property on the class.

__gt__(other)¶: Compare collection objects by number of files in the collections.

__iter__()¶: Iterator for collection object. Iterates by returning each file.

__len__()¶: Return length of collection object (number of files in collection).

__lt__(other)¶: Compare collection objects by number of files in the collections.

__repr__()¶: Return string representation for collection (list of file paths).

__setattr__(name, value)¶: Proxy for setting metadata directly as a property on the class.

__str__()¶: Return string representation for collection (list of file paths).

__sub__(other)¶

Subtraction operator for collections or files. Using this, you can subtract Collection objects from other Colletion objects to form a Collection with the difference in files, or subtract File objects from Collection objects to return a new Collection without the File object.

Examples

>>> # add files to create collection
>>> one = coda.File('/file/one.txt')
>>> two = coda.File('/file/two.txt')
>>> onetwo = one + two
>>> three = coda.File('/file/three.txt')
>>> onetwothree = onetwo + three
>>>
>>> # subtract collection objects to create new collection
>>> print onetwothree - onetwo
'/file/three.txt'
>>>
>>> # subtract file from collection object to create new collection
>>> print onetwothree - three
'/file/one.txt'
'/file/two.txt'

add_metadata(*args, **kwargs)¶: Add metadata for all objects in the collection.

filelist¶: Return list with full paths to files in collection.

filter(func=<function <lambda>>)¶

Filter collection using specified function. This function allows for filtering files from collection objects by an arbitrary operator. This could be used for filtering more specifically by existing metadata tags, or by more complex methods that read in the file and perform some operation to it.

Parameters:	func (function) – Function to filter with.

Examples

>>> # query collection for tag
>>> cl = coda.find({'group': 'testing'})
>>>
>>> # query file by data_type tag (assuming tags exist)
>>> cl.filter(lambda x: x.data_type in ['csv', 'txt'])

metadata¶: If no metadata is initially specified for a file, query the database for metadata about the specified file.

Querying¶

coda.find(query)¶

Search database for files with specified metadata.

Parameters:	query (dict) – Dictionary with query parameters.
Returns:	Collection object with results.
Return type:	Collection

Examples

>>> # assuming the database has already been populated
>>> print coda.find({'type': 'test'})
'/my/testing/file/one.txt'
'/my/testing/file/two.txt'
>>>
>>> # assuming 'count' represents line count in the file
>>> print coda.find({'type': 'test', 'count': {'$lt': 30}})
'/my/testing/file/two.txt'
>>>
>>> # using the filter() method on collections instead
>>> print coda.find({'type': 'test'}).filter(lambda x: x.count < 30)
'/my/testing/file/two.txt'

coda.find_one(query)¶

Search database for one file with specified metadata.

Parameters:	query (dict) – Dictionary with query parameters.
Returns:	File object with results.
Return type:	File

Examples

>>> # assuming the database has already been populated
>>> print coda.find_one({'type': 'test'})
'/my/testing/file/one.txt'
>>>
>>> # assuming 'count' represents line count in the file
>>> print coda.find({'type': 'test', 'count': {'$lt': 30}})
'/my/testing/file/two.txt'

coda.add(obj)¶

Add file object or collection object to database.

Parameters:	obj (File, Collection) – File or collection of files to add.

Examples

>>> # instantiate File object and add metadata
>>> fi = coda.File('/path/to/test/file.txt')
>>> fi.type = 'test'
>>>
>>> # add file to database
>>> coda.add(fi)
>>>
>>> # instantiate directory as Collection with common metadata
>>> cl = coda.Collection('/path/to/test/dir/')
>>> cl.type = 'test'
>>> coda.add(cl)

coda.delete(obj)¶

Delete file or collection of files from database.

Parameters:	obj (File, Collection) – File or collection of files to delete.

Examples

>>> # instantiate File object and delete
>>> fi = coda.File('/path/to/test/file.txt')
>>> coda.delete(fi)
>>>
>>> # instantiate directory and delete
>>> cl = coda.Collection('/path/to/test/dir/')
>>> coda.delete(cl)
>>>
>>> # query by metadata and delete entries
>>> cl = coda.find({'type': 'testing'})
>>> coda.delete(cl)