Main objects

exception sophia.Error

Exception raised for all database-related errors.

class sophia.Database

Main database class.

Keys or values passed as argument to the methods which accept them are expected to be byte strings. Returned keys or values are always byte strings.

setopt(constant, value1[, value2])

Configure this database.

Calling this method is only valid when the database is closed. See the sophia documentation for a summary of the available options. SPDIR and SPALLOC are not supported.


Open the database, creating it if doesn’t exist yet.

If a connection is already active, try to close it and open a new one; in this case, False can be returned, which means that the previous connection has not been successfully closed because a sophia.Cursor object is hanging around somewhere. Otherwise, True is returned.


Close the current connection, if any.

As above, a return value False indicates that it is not possible to close the database for the time being.


Is this database closed? True if so, False otherwise.

set(key, value)

Add a record, or replace an existent one.

get(key[, default])

Retrieve a record given its key. If it doesn’t exist, return default if given, None otherwise.


Delete a record.


Is this key in the database? True if so, False otherwise.


Start a transaction.


Commit the current transaction.


Abort the current transaction.


How many records are there in this database?

iterkeys(start_key=None, order=sophia.SPGTE)

Iterate over all the keys in this database, starting at start_key, and in order.

Possible values for order are:

  • sophia.SPGT - increasing order (skipping the key, if it is equal)
  • sophia.SPGTE - increasing order (with key)
  • sophia.SPLT - decreasing order (skipping the key, if it is equal)
  • sophia.SPLTE - decreasing order
itervalues(start_key=None, order=sophia.SPGTE)

Same as Database.iterkeys(), but for values.

iteritems(start_key=None, order=sophia.SPGTE)

Same as Database.iterkeys(), but for pairs of (key, value).

Database models

class sophia.ObjectDatabase(pack_key=pickle.dumps, unpack_key=pickle.loads, pack_value=pickle.dumps, unpack_value=pickle.loads)

Database model for storing arbitrary kinds of objects.

pack_key, unpack_key, pack_value, and unpack_value, should be callables that, when passed an object as parameter, return a byte representation of it, suitable for storage. By default, all these functions use the pickle module.

class sophia.ThreadedDatabase

Thread-safe database model.

It should only be used if you want to use a database in a threaded environment AND need to iterate over it. Otherwise, the vanilla Database class is suitable (and more efficient).

class sophia.ThreadedObjectDatabase(pack_key=pickle.dumps, unpack_key=pickle.loads, pack_value=pickle.dumps, unpack_value=pickle.loads)

Mixing of a ThreadedDatabase and an ObjectDatabase.