API docs for “sasync.items.Items”

I provide a public interface for non-blocking database access to persistently stored name:value items within a uniquely-identified group, e.g., for a persistent dictionary using PersistentDict.

Before you use any instance of me, you must specify the parameters for creating an SQLAlchemy database engine. A single argument is used, which specifies a connection to a database via an RFC-1738 url. In addition, the following keyword options can be employed, which are listed in the API docs for sasync and sasync.database.AccessBroker.

You can set an engine globally, for all instances of me via the sasync.engine package-level function, or via the AccessBroker.engine class method. Alternatively, you can specify an engine for one particular instance by supplying the parameters to my constructor.

IMPORTANT: Make sure you call my shutdown method for an instance of me that you're done with before allowing that instance to be deleted.

Method	__init__	Instantiates me for the items of a particular group uniquely identified
Method	shutdown	Shuts down my database `Transactor` and its synchronous task queue.
Method	write	Performs a database write transaction, returning a deferred to its
Method	load	Loads item name from the database, returning a deferred to the
Method	loadAll	Loads all items in my group from the database, returning a deferred
Method	update	Updates the database entry for item name = value, returning a
Method	insert	Inserts a database entry for item name = value, returning a
Method	delete	Deletes the database entries for the items having the supplied
Method	names	Returns a deferred that fires with a list of the names of all items

def __init__(self, ID, *url, **kw):

Instantiates me for the items of a particular group uniquely identified by the supplied hashable ID. Ensures that I have access to a class-wide instance of a Search object so that I can update the database's full-text index when writing values containing text content.

In addition to any engine-specifying keywords supplied, the following are particular to this constructor:

Parameters	ID	A hashable object that is used as my unique identifier.
Unknown Field: keyword	nameType	A `type` object defining the type that each name will be coerced to after being loaded as a string from the database.
	search	Set `True` if text indexing is to be performed on items as they are written.

def write(self, funcName, name, value, niceness=0):

Performs a database write transaction, returning a deferred to its completion.

If we are updating the search index, there's a nuance to the deferred processing. In that case, when the write is done, the deferred is fired and processing separately proceeds with indexing of the written value. Here's how it works:

Create a clean deferred d1 to return to the caller, whose callback(s) will be fired from the callback to the transaction's own deferred d2.
Start the write transaction and assign the writeDone function as the callback to its deferred d2. Note that the defer-to-queue transaction keeps a reference to the deferred object it instantiates, so we don't have to do so for either d2 or d3. Those references are merely defined in the method for code readability.

def delete(self, *names):

Deletes the database entries for the items having the supplied *names, returning a deferred that fires when the transaction is done.

If we are updating the search index, there's a nuance to the deferred processing. In that case, when the deletions are done, the deferred is fired and processing separately proceeds with dropping index entries for the deleted values. Here's how it works:

Create a clean deferred d1 to return to the caller, whose callback(s) will be fired from the callback to the transaction's own deferred d2.
Start the delete transaction and assign the deleteDone function as the callback to its deferred d2. Note that the defer-to-thread transaction keeps a reference to the deferred object it instantiates, so we don't have to do so for either d2 or d3. Those references are merely defined in the method for code readability.

Class s.i.Items(object):