Shelve extension

A storage/query backend for shelve which is bundled with Python.

status:stable database:any dbm-style database supported by shelve dependencies:the Python standard library suitable for:“smart” interface to a key/value store, small volume

A “shelf” is a persistent, dictionary-like object. The difference with “dbm” databases is that the values (not the keys!) in a shelf can be essentially arbitrary Python objects — anything that the pickle module can handle. This includes most class instances, recursive data types, and objects containing lots of shared sub-objects. The keys are ordinary strings.

This extension wraps the standard Python library and provides Document support and uniform query API.

Note

The query methods are inefficient as they involve iterating over the full set of records and making per-row comparison without indexing. This backend is not suitable for applications that depend on queries and require decent speed. However, it is an excellent tool for existing DBM databases or for environments and cases where external dependencies are not desired.

class doqu.ext.shelve_db.StorageAdapter(**kw)

Provides unified Doqu API for MongoDB (see doqu.backend_base.BaseStorageAdapter).

Parameters:path – relative or absolute path to the database file (e.g. test.db)

clear()

Clears the whole storage from data, resets autoincrement counters.

connect()

Connects to the database. Raises RuntimeError if the connection is not closed yet. Use reconnect() to explicitly close the connection and open it again.

delete(key)

Deletes record with given primary key.

disconnect()

Closes internal store and removes the reference to it. If the backend works with a file, then all pending changes are saved now.

find(doc_class=<type 'dict'>, **conditions)

Returns instances of given class, optionally filtered by given conditions.

Parameters:

• doc_class – Document class. Default is dict. Normally you will want a more advanced class, such as Document or its more concrete subclasses (with explicit structure and validators).
• conditions – key/value pairs, same as in where().

Note

By default this returns a tuple of (key, data_dict) per item. However, this can be changed if doc_class provides the method from_storage(). For example, Document has the notion of “saved state” so it can store the key within. Thus, only a single Document object is returned per item.

get(key, doc_class=<type 'dict'>)

Returns document instance for given document class and primary key. Raises KeyError if there is no item with given key in the database.

Parameters:

• key – a numeric or string primary key (as supported by the backend).
• doc_class – a document class to wrap the data into. Default is dict.

get_many(keys, doc_class=<type 'dict'>)

Returns an iterator of documents with primary keys from given list. Basically this is just a simple wrapper around get() but some backends can reimplement the method in a much more efficient way.

get_or_create(doc_class=<type 'dict'>, **conditions)

Queries the database for records associated with given document class and conforming to given extra conditions. If such records exist, picks the first one (the order may be random depending on the database). If there are no such records, creates one.

Returns the document instance and a boolean value “created”.

query_adapter

alias of QueryAdapter

reconnect()

Gracefully closes current connection (if it’s not broken) and connects again to the database (e.g. reopens the file).

save(key, data)

Saves given data with given primary key into the storage. Returns the primary key.

Parameters:

• key – the primary key for given object; if None, will be generated.
• data – a dict containing all properties to be saved.

Note that you must provide current primary key for a record which is already in the database in order to update it instead of copying it.

sync()

Synchronizes the storage to disk immediately if the backend supports this operation. Normally the data is synchronized either on save(), or on timeout, or on disconnect(). This is strictly backend-specific. If a backend does not support the operation, NotImplementedError is raised.

class doqu.ext.shelve_db.QueryAdapter(*args, **kw)

The Query class.

count()

Same as __len__ but a bit faster.

delete()

Deletes all records that match current query.

order_by(names, reverse=False)

Defines order in which results should be retrieved.

Parameters:

• names – the names of columns by which the ordering should be done. Can be an iterable with strings or a single string.
• reverse – If True, direction changes from ascending (default) to descending.

Examples:

q.order_by('name')                  # ascending
q.order_by('name', reverse=True)    # descending

If multiple names are provided, grouping is done from left to right.

Note

while you can specify the direction of sorting, it is not possible to do it on per-name basis due to backend limitations.

Warning

ordering implementation for this database is currently inefficient.

values(name)

Returns an iterator that yields distinct values for given column name.

Supports date parts (i.e. date__month=7).

Note

this is currently highly inefficient because the underlying library does not support columns mode (tctdbiternext3). Moreover, even current implementation can be optimized by removing the overhead of creating full-blown document objects.

Note

unhashable values (like lists) are silently ignored.

where(**conditions)

Returns Query instance filtered by given conditions. The conditions are specified by backend’s underlying API.

where_not(**conditions)

Returns Query instance. Inverted version of where().