offtheshelf - A simple embedded NoSQL database

offtheshelf is a pure-Python module providing a very simple and minimalist embedded NoSQL database. It uses the shelve module as backend for persistent storage and relies on file-locking as a simple mutual exclusion mechanism.

This module defines two classes: Database and Collection. A Database object is basically a container for one or more Collections. A Collection contains a list of documents (i.e. dictionaries), holding the actual data, and provides methods for inserting, updating, searching and removing items from documents.

Database instances support closures and can be either returned by a call to the openDB() function or instantiated directly.

offtheshelf.openDB([**kwargs])

Return a Database object; the optional keyword arguments are passed to the Database class constructor.

class offtheshelf.Database(filename[, protocol[, writeback[, collection[, use_lock]]]])

filename is the path of the DB file (a ".db" extension will be automatically appended); protocol is the version of pickle protocol to use for storing objects (default is pickle.HIGHEST_PROTOCOL); writeback, if set to True (default), enables the automatic saving of accessed collections on save() and close(); collection allows you to provide a custom collection class; lock, if set to True (default), enables the use of a lock file to manage concurrent access to the database.

class offtheshelf.Collection([name])

This class should not be instantiated directly; Database.get_collection() should be used instead. name is the name of the Collection.

1. Database objects

A Database object is basically a shelve file that can hold one or more collections.

Database.get_collection([name[, *args]])

Return a Collection object; if no Collection already exists with that name, a new one will be created. If no name is provided, the default collection (named __default__) will be implied.

Database.drop_collection([name])

Delete the specified collection from the DB; if no name is provided, the default collection will be deleted.

Database.collections

Return the dictionary made up of name/collection pairs.

Database.save()

Save data to file.

Database.close()

Save and close the DB file and release the lock (if locking is enabled).

2. Collection objects

A Collection object is a list of documents (dictionaries) accessible in a DB-like way; it is returned by the Database.get_collection() function and has the following methods:

Collection.insert(values)

Add a new document to the collection.

Collection.update(values[, where])

Update document(s) matching the where condition with the values provided.

Collection.upsert(values[, where])

Update document(s) matching the where condition with the values provided or, if no matches are found, insert values as a new document.

Collection.delete(where)

Delete document(s) matching the where condition.

Collection.truncate()

Delete all documents.

Collection.find([where])

Return a list of documents matching the where condition.

Collection.find_one([where])

Return the first document matching the where condition or None.

Collection.count([where])

Return the number of documents matching the where condition.

3. Examples

Create a new database and add some entries to a new collection:

>>> with offtheshelf.openDB("/tmp/music") as db:
...     coll = db.get_collection("CDCollection")
...     coll.insert({"Author": "W. A. Mozart",
...                  "Title":  "Symphony K.551 - Jupiter"})
...     coll.insert({"Author": "L. Van Beethoven",
...                  "Title":  "Symphony n.5 op.67"})

Collections can be queried, updated, counted and deleted:

...     coll.count({"Author": "L. Van Beethoven"})
1
...     coll.find({"Author": "W. A. Mozart"})
[{'Author': 'W. A. Mozart', 'Title': 'Symphony K.551 - Jupiter'}]
...     # Don't worry Ludwig, it's only an example! :-(
...     coll.delete({"Author": "L. Van Beethoven"})

The Database is automatically saved and closed upon exit from the closure, but can be also explicitely saved and closed:

>>> db = Database("/tmp/music")
>>> coll = db.get_collection("CDCollection")
>>> coll.update({"Genre": "Classical"})
>>> db.save()
>>> db.close()