Utilities

Various useful functions. Some can be imported from doqu.utils, some are available directly at doqu.

These utilities are either stable and well-tested or possible changes in their API are not considered harmful (i.e. they are marginal). Important functions which design is likely to change or which lack proper tests are located in doqu.future.

doqu.utils.dump_doc(self, raw=False, as_repr=False, align=True, keys=None, exclude=None)

Returns a multi-line string with document keys and values nicely formatted and aligned.

Parameters:

• raw – If True, uses “raw” values, as fetched from the database (note that this will fail for unsaved documents). If not, the values are obtained in the normal way, i.e. by __getitem__(). Default is False.
• align – If True, the keys and values are aligned into two columns of equal width. If False, no padding is used. Default is True.
• keys – a list of document keys to show. By default all existing keys are included.
• exclude – a list of keys to exclude. By default no keys are excluded.

Prarm as_repr:

If True, uses repr() for values; if not, coerces them to Unicode. Default if False.

doqu.utils.get_db(settings_dict=None, **settings_kwargs)

Storage adapter factory. Expects path to storage backend module and optional backend-specific settings. Returns storage adapter instance. If required underlying library is not found, exception pkg_resources.DistributionNotFound is raised with package name and version as the message.

Parameters:backend – string, dotted path to a Doqu storage backend (e.g. doqu.ext.tokyo_tyrant). See Extensions for a list of bundled backends or Backend API for backend API reference.

Usage:

import doqu

db = doqu.get_db(backend='doqu.ext.shelve', path='test.db')

query = SomeDocument.objects(db)

Settings can be also passed as a dictionary:

SETTINGS = {
    'backend': 'doqu.ext.tokyo_cabinet',
    'path': 'test.tct',
}

db = doqu.get_db(SETTINGS)

The two methods can be combined to override certain settings:

db = doqu.get_db(SETTINGS, path='another_db.tct')

doqu.utils.camel_case_to_underscores(class_name)

Returns a pretty readable name based on the class name. For example, “SomeClass” is translated to “some_class”.

doqu.utils.load_fixture(path, db=None)

Reads given file (assuming it is in a known format), loads it into given storage adapter instance and returns that instance.

Parameters:

• path – absolute or relative path to the fixture file; user constructions (“~/foo”) will be expanded.
• db – a storage adapter instance (its class must conform to the BaseStorageAdapter API). If not provided, a memory storage will be created.

Usage:

import doqu

db = doqu.load_fixture('account.csv')

query = SomeDocument.objects(db)