Public API

This is the public API documentation. The functions and classes listed below exclusively make up the code scope which is guaranteed to stay consistent.

If you plan to make use of the Public API it would be a good idea to also check out the Developer’s Guide that coveres some additional implementation details.

Chanjo exclusively uses unicode strings throughout the interface. It therefore important to always specify ‘utf-8’ encoding when e.g. reading files from the OS. In Python 2:

>>> import io
>>> handle = io.open('./LICENSE', encoding='utf-8')
>>> next(handle)
u'The MIT License (MIT)\n'

Chanjo coverage store module

The central API for Chanjo SQL databases. Built on SQLAlchemy. From here you have access to contents of the database (models) and can access query interface that SQLAlchemy exposes.

class chanjo.store.Store(uri=None, debug=False)[source]

SQLAlchemy-based database object.

Bundles functionality required to setup and interact with various related genomic interval elements.

Changed in version 2.1.0: Lazy-loadable, all “init” arguments optional.

Examples

>>> chanjo_db = Store('data/elements.sqlite3')
>>> chanjo_db.set_up()

Note

For testing pourposes use :memory: as the path argument to set up in-memory (temporary) database.

Parameters:
  • uri (Optional[str]) – path/URI to the database to connect to
  • debug (Optional[bool]) – whether to output logging information
uri

str – path/URI to the database to connect to

engine

class – SQLAlchemy engine, defines what database to use

session

class – SQLAlchemy ORM session, manages persistance

query

method – SQLAlchemy ORM query builder method

classes

dict – bound ORM classes

add(elements)[source]

Add one or more new elements and commit the changes. Chainable.

Parameters:elements (orm/list) – new ORM object instance or list of such
Returns:self for chainability
Return type:Store
connect(db_uri, debug=False)[source]

Configure connection to a SQL database.

New in version 2.1.0.

Parameters:
  • db_uri (str) – path/URI to the database to connect to
  • debug (Optional[bool]) – whether to output logging information
create(class_id, *args, **kwargs)[source]

Create a new instance of an ORM element.

If attributes are supplied as a tuple they must be in the correct order. Supplying a dict doesn’t require the attributes to be in any particular order.

Parameters:
  • class_id (str) – choice between “superblock”, “block”, “interval”
  • *args (tuple) – list the element attributes in the correct order
  • **kwargs (dict) – element attributes in whatever order you like
Returns:

new ORM instance object

Return type:

orm

dialect

Return database dialect name used for the current connection.

Dynamic attribute.

Returns:name of dialect used for database connection
Return type:str
find(klass_id, query=None, attrs=None)[source]

Fetch one or more elements based on the query.

If the ‘query’ parameter is a string find() will fetch one element; just like get. If query is a list it will match element ids to items in that list and return a list of elements. If ‘query’ is None all elements of that class will be returned.

Parameters:
  • klass_id (str) – type of element to find
  • query (str/list, optional) – element Id(s)
  • attrs (list, optional) – list of columns to fetch
Returns:

element(s) from the database

Return type:

object/list

get(typ, type_id)[source]

Fetch a specific element or ORM class.

Calls itself recursively when asked to fetch an element.

Parameters:
  • typ (str) – element key or ‘class’
  • type_id (str) – element id or ORM model id
Returns:

element or ORM class

Return type:

model

Examples

>>> gene = db.get('gene', 'GIT1')
get_or_create(model, **kwargs)[source]

Get or create a record in the database.

save()[source]

Manually persist changes made to various elements. Chainable.

Changed in version 2.1.2: Flush session before commit.

Returns:self for chainability
Return type:Store
set_up()[source]

Initialize a new database with the default tables and columns.

Returns:self
Return type:Store
tear_down()[source]

Tear down a database (tables and columns).

Returns:self
Return type:Store