Core Interface

open

acid.open(url, trace_path=None, txn_context=None)

Instantiate an engine described by url and return a new Store wrapping it. See Engines for supported URL schemes.

url:
Engine URL; may be prefixed with pkgname.modname+ to cause a module to be imported before instantiating the engine. This allows third party engines to register via acid.engines.register() before the URL is parsed.
trace_path:
If specified, the engine is wrapped in a acid.engines.TraceEngine to produce a complete log of interactions, written to trace_path.
txn_context:
If specified, use txn_context instead of the default acid.core.TxnContext implementation.

Example:

# Uses acid.engines.SkiplistEngine
store = acid.open('skiplist:/')

# Cause "mypkg.acid" to be imported, then use "myengine:/".
store = acid.open('mypkg.acid+myengine:/')

Store Class

class acid.Store(engine, txn_context=None, prefix='')

Represents access to the underlying storage engine, and manages counters.

txn_context:
If not None, override the default acid.core.TxnContext implementation to provide request-local storage of the active database transaction. The default implementation uses TLS.
prefix:
Prefix for all keys used by any associated object (record, index, counter, metadata). This allows the storage engine’s key space to be shared amongst several users.
add_collection(name, **kwargs)

Shorthand for acid.Collection(self, **kwargs).

add_encoder(encoder)

Register an acid.encoders.Encoder so that Collection can find it during decompression/unpacking.

begin(write=False)

Return a context manager that starts a database transaction when it is entered.

with store.begin(write=True):
    store['people'].put('me')

If the execution block completes without raising an exception, then the transaction will be committed. Otherwise it will be aborted, and the exception will be propagated as normal.

The acid.abort() function may be used anywhere on the stack to gracefully abort the current transaction, and return control to below with with: block without causing an exception to be raised.

count(name, n=1, init=1)

Increment a counter and return its previous value. The counter is created if it doesn’t exist.

name:
Name of the counter. Names beginning with "\x00" are reserved by the implementation.
n:
Number to add to the counter. If 0 or None, return the counter’s value without incrementing it.
init:
Initial value to give counter if it doesn’t exist.
get_encoder(prefix)

Get a registered acid.encoders.Encoder given its string prefix, or raise an error.

get_meta(kind, name)

Fetch a dictionary of metadata for the named object. kind may be any of the following acid.core constants:

acid.core.KIND_TABLE acid.core.KIND_INDEX acid.core.KIND_ENCODER acid.core.KIND_COUNTER acid.core.KIND_STRUCT
in_txn(func, write=False)

Execute func() inside a transaction, and return its return value. If a transaction is already active, func() runs inside the current transaction.

rename_collection(old, new)

Rename the collection named old to new. Any existing Collection instances will be updated. Raises acid.errors.NameInUse on error.

set_meta(kind, name, dct)

Replace the stored metadata for name using dct.

Collection Class

class acid.Collection(store, info, key_func=None, encoder=None, compressor=None, counter_name=None)

Provides access to a record collection contained within a Store, and ensures associated indices update consistently when changes are made.

store:
Store the collection belongs to. If metadata for the collection does not already exist, it will be populated during construction.
name:
ASCII string used to identify the collection, aka. the key of the collection itself.
key_func:
Function invoked as func(rec) to produce a key for the record value about to be saved. It should return a tuple that will become the record’s key. If the function returns a single value, it will be wrapped in a 1-tuple. If no function is given, keys are assigned using a counter (like auto-increment in SQL). See counter_name.
encoder:
acid.encoders.Encoder used to serialize record values to bytestrings; defaults to acid.encoders.JSON.
counter_name:
Specifies the name of the Store counter to use when generating auto-incremented keys. If unspecified, defaults to "key:<name>". Unused when key_func is specified.
delete(key)

Delete any existing record filed under key.

find(key=None, lo=None, hi=None, prefix=None, reverse=None, include=False, raw=None, default=None)

Return the first matching record, or None. Like next(itervalues(), default).

findkey(key=None, lo=None, hi=None, prefix=None, reverse=None, include=False, raw=None, default=None)

Return the first matching key, or None. Like next(iterkeys(), default).

get(key, default=None, raw=False)

Fetch a record given its key. If key is not a tuple, it is wrapped in a 1-tuple. If the record does not exist, return None or if default is provided, return it instead.

items(key=None, lo=None, hi=None, prefix=None, reverse=False, max=None, include=False, raw=False)

Yield all (key tuple, value) tuples in key order.

keys(key=None, lo=None, hi=None, prefix=None, reverse=None, max=None, include=False)

Yield key tuples in key order.

put(rec, key=None)

Create or overwrite a record.

rec:
The value to put; must be a value recognised by the collection’s encoder.
key:
Optionaly use this exact key, otherwise assign a key using the collection’s key function.
values(key=None, lo=None, hi=None, prefix=None, reverse=None, max=None, include=False, raw=False)

Yield record values in key order.

Index Class

acid.add_index(coll, name, func)

Associate an index with the collection. Index metadata will be created in the storage engine it it does not exist. Returns the Index instance describing the index. This method may only be invoked once for each unique name for each collection.

Note

Only index metadata is persistent. You must invoke acid.add_index() with the same arguments every time you create a Collection instance.

name:
ASCII name for the index.
func:

Index key generation function accepting one argument, the record value. It should return a single primitive value, a tuple of primitive values, a list of primitive values, or a list of tuples of primitive values.

Caution

The index function must have no side-effects, as it may be invoked repeatedly.

Example:

coll = Collection(store, 'people')
coll.add_index('name', lambda person: person['name'])

coll.put({'name': 'David'})
coll.put({'name': 'Charles'})
coll.put({'name': 'Charles'})
coll.put({'name': 'Andrew'})

it = coll.indices['name'].iterpairs()
assert list(it) == [
    (('Andrew',),   (4,)),
    (('Charles',),  (2,)),
    (('Charles',),  (3,)),
    (('David',),    (1,))
]
class acid.Index(coll, info, func)

Provides query and manipulation access to a single index on a Collection. You should not create this class directly, instead use Collection.add_index() and the Collection.indices mapping.

Index.get() and the iteration methods take a common set of arguments that are described below:

args:
Prefix of the index entries to to be matched, or None or the empty tuple to indicate all index entries should be matched.
reverse:
If True, iteration should begin with the last naturally ordered match returned first, and end with the first naturally ordered match returned last.
max:
Maximum number of index records to return.
count(args=None, lo=None, hi=None, prefix=None, max=None, include=False)

Return a count of index entries matching the parameter specification.

find(args=None, lo=None, hi=None, prefix=None, reverse=None, include=False, raw=False, default=None)

Return the first matching record from the index, or None. Like next(itervalues(), default).

get(x, default=None, raw=False)

Return the first matching record from the index.

has(x)

Return True if an entry with the exact tuple x exists in the index.

items(args=None, lo=None, hi=None, prefix=None, reverse=None, max=None, include=False, raw=False)

Yield all (key, value) items referred to by the index, in tuple order.

keys(args=None, lo=None, hi=None, prefix=None, reverse=None, max=None, include=False)

Yield all keys in the index, in tuple order.

pairs(args=None, lo=None, hi=None, prefix=None, reverse=None, max=None, include=False)

Yield all (tuple, key) pairs in the index, in tuple order. tuple is the tuple returned by the user’s index function, and key is the key of the matching record.

Note: the yielded sequence is a list, not a tuple.

tups(args=None, lo=None, prefix=None, hi=None, reverse=None, max=None, include=False)

Yield all index tuples in the index, in tuple order. The index tuple is the part of the entry produced by the user’s index function, i.e. the index’s natural “value”.

values(args=None, lo=None, hi=None, prefix=None, reverse=None, max=None, include=False, raw=False)

Yield all values referred to by the index, in tuple order.

func = None

The index function.

Key Class

class acid.keylib.Key(*args)

Keys are immutable sequences used as indexes into an ordered collection. They behave like tuples, except that elements must be bytestrings, Unicode strings, signed integers, None, True, False, datetime.datetime instances, or uuid.UUID instances.

The key’s elements are internally stored using an encoding carefully designed to ensure a sort order that closely mirrors a tuple with the same elements, and that the representation is as compact as possible. Equality tests are implemented as string compares, and so are often faster than comparing Python tuples.

Keys may own a private buffer to contain their encoded representation, or may borrow it from another object. Since Keys can be constructed directly from an encoded representation in a shared buffer, it is possible to work with a Key as if it were a plain tuple without ever copying or decoding it.

The internal encoding is described in Key encoding.

classmethod from_raw(packed, prefix=None, source=None)

Construct a Key from its raw form, skipping the bytestring prefix at the start. If source is not None, packed must be a buffer and source should be a source object implementing the Memsink Protocol. Return None if the prefix does not match.

classmethod from_str(s)

Construct a Key from its raw form wrapped in hex. Return None if the key cannot be decoded.

prefix_bound()

Return a new Key that is larger than any key prefixed by this key, but smaller than all greater keys. This may return None if no such greater key exists (e.g. the prefix consists entirely of 0xff bytes when encoded). The returned instance is useful only for implementing compares for set_prefix, it may not decode to a valid key.

to_raw(prefix=None)

Get the bytestring representing this Key, optionally prefixed by prefix.

to_str()

Return to_raw('') encoded as hex.