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 ='./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, 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.


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


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

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

str – path/URI to the database to connect to


class – SQLAlchemy engine, defines what database to use


class – SQLAlchemy ORM session, manages persistance


method – SQLAlchemy ORM query builder method


dict – bound ORM classes


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.

  • 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.

  • 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

new ORM instance object

Return type:



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.

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

element(s) from the database

Return type:


get(typ, type_id)[source]

Fetch a specific element or ORM class.

Calls itself recursively when asked to fetch an element.

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

element or ORM class

Return type:



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

Get or create a record in the database.


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

Initialize a new database with the default tables and columns.

Return type:Store

Tear down a database (tables and columns).

Return type:Store