s.s.Store(object) : class documentation

Part of storm.store View In Hierarchy

The Storm Store.

This is the highest-level interface to a database. It manages transactions with commit and rollback, caching, high-level querying with find, and more.

Note that Store objects are not threadsafe. You should create one Store per thread in your application, passing them the same backend Database object.

Method __init__
Method get_database Return this Store's Database object.
Static Method of Get the Store that the object is associated with.
Method execute Execute a basic query.
Method close Close the connection.
Method commit Commit all changes to the database.
Method rollback Roll back all outstanding changes, reverting to database state.
Method get Get object of type cls with the given primary key from the database.
Method find Perform a query.
Method using Specify tables to use explicitly.
Method add Add the given object to the store.
Method remove Remove the given object from the store.
Method reload Reload the given object.
Method autoreload Set an object or all objects to be reloaded automatically on access.
Method invalidate Set an object or all objects to be invalidated.
Method reset Reset this store, causing all future queries to return new objects.
Method add_flush_order Explicitly specify the order of flushing two objects.
Method remove_flush_order Cancel an explicit flush order specified with add_flush_order.
Method flush Flush all dirty objects in cache to database.
Method block_implicit_flushes Block implicit flushes from operations like execute().
Method unblock_implicit_flushes Unblock implicit flushes from operations like execute().
Method block_access Block access to the underlying database connection.
Method unblock_access Unblock access to the underlying database connection.
Method _mark_autoreload Undocumented
Method _flush_one Undocumented
Method _get_changes_map Return a {column: variable} dictionary suitable for inserts/updates.
Method _fill_missing_values Fill missing values in variables of the given obj_info.
Method _validate_alive Perform cache validation for the given obj_info.
Method _load_object Undocumented
Method _get_object Return object for obj_info, rebuilding it if it's dead.
Static Method _run_hook Undocumented
Method _set_values Undocumented
Method _is_dirty Undocumented
Method _set_dirty Undocumented
Method _set_clean Undocumented
Method _iter_dirty Undocumented
Method _add_to_alive Add an object to the set of known in-memory objects.
Method _remove_from_alive Remove an object from the cache.
Method _iter_alive Undocumented
Method _enable_change_notification Undocumented
Method _disable_change_notification Undocumented
Method _variable_changed Undocumented
Method _enable_lazy_resolving Undocumented
Method _disable_lazy_resolving Undocumented
Method _resolve_lazy_value Resolve a variable set to a lazy value when it's touched.
def __init__(self, database, cache=None):
ParametersdatabaseThe storm.database.Database instance to use.
cacheThe cache to use. Defaults to a Cache instance.
def get_database(self):
Return this Store's Database object.
@staticmethod
def of(obj):
Get the Store that the object is associated with.

If the given object has not yet been associated with a store, return None.

def execute(self, statement, params=None, noresult=False):
Execute a basic query.

This is just like storm.database.Database.execute, except that a flush is performed first.

def close(self):
Close the connection.
def commit(self):
Commit all changes to the database.

This invalidates the cache, so all live objects will have data reloaded next time they are touched.

def rollback(self):
Roll back all outstanding changes, reverting to database state.
def get(self, cls, key):
Get object of type cls with the given primary key from the database.

If the object is alive the database won't be touched.

ParametersclsClass of the object to be retrieved.
keyPrimary key of object. May be a tuple for composed keys.
ReturnsThe object found with the given primary key, or None if no object is found.
def find(self, cls_spec, *args, **kwargs):

Perform a query.

Some examples:

   store.find(Person, Person.name == u"Joe") --> all Persons named Joe
   store.find(Person, name=u"Joe") --> same
   store.find((Company, Person), Person.company_id == Company.id) -->
       iterator of tuples of Company and Person instances which are
       associated via the company_id -> Company relation.
Parameterscls_specThe class or tuple of classes whose associated tables will be queried.
argsInstances of Expr.
kwargsMapping of simple column names to values or expressions to query for.
ReturnsA ResultSet of instances cls_spec. If cls_spec was a tuple, then an iterator of tuples of such instances.
def using(self, *tables):

Specify tables to use explicitly.

The find method generally does a good job at figuring out the tables to query by itself, but in some cases it's useful to specify them explicitly.

This is most often necessary when an explicit SQL join is required. An example follows:

   join = LeftJoin(Person, Person.id == Company.person_id)
   print list(store.using(Company, join).find((Company, Person)))

The previous code snippet will produce an SQL statement somewhat similar to this, depending on your backend:

   SELECT company.id, employee.company_id, employee.id
   FROM company
   LEFT JOIN employee ON employee.company_id = company.id;
ReturnsA TableSet, which has a find method similar to Store.find.
def add(self, obj):
Add the given object to the store.

The object will be inserted into the database if it has not yet been added.

The added event will be fired on the object info's event system.

def remove(self, obj):
Remove the given object from the store.

The associated row will be deleted from the database.

def reload(self, obj):
Reload the given object.

The object will immediately have all of its data reset from the database. Any pending changes will be thrown away.

def autoreload(self, obj=None):
Set an object or all objects to be reloaded automatically on access.

When a database-backed attribute of one of the objects is accessed, the object will be reloaded entirely from the database.

ParametersobjIf passed, only mark the given object for autoreload. Otherwise, all cached objects will be marked for autoreload.
def invalidate(self, obj=None):
Set an object or all objects to be invalidated.

This prevents Storm from returning the cached object without first verifying that the object is still available in the database.

This should almost never be called by application code; it is only necessary if it is possible that an object has disappeared through some mechanism that Storm was unable to detect, like direct SQL statements within the current transaction that bypassed the ORM layer. The Store automatically invalidates all cached objects on transaction boundaries.

def reset(self):
Reset this store, causing all future queries to return new objects.

Beware this method: it breaks the assumption that there will never be two objects in memory which represent the same database object.

This is useful if you've got in-memory changes to an object that you want to "throw out"; next time they're fetched the objects will be recreated, so in-memory modifications will not be in effect for future queries.

def _mark_autoreload(self, obj=None, invalidate=False):
Undocumented
def add_flush_order(self, before, after):
Explicitly specify the order of flushing two objects.

When the next database flush occurs, the order of data modification statements will be ensured.

ParametersbeforeThe object to flush first.
afterThe object to flush after before.
def remove_flush_order(self, before, after):
Cancel an explicit flush order specified with add_flush_order.
ParametersbeforeThe before object previously specified in a call to add_flush_order.
afterThe after object previously specified in a call to add_flush_order.
def flush(self):
Flush all dirty objects in cache to database.

This method will first call the __storm_pre_flush__ hook of all dirty objects. If more objects become dirty as a result of executing code in the hooks, the hook is also called on them. The hook is only called once for each object.

It will then flush each dirty object to the database, that is, execute the SQL code to insert/delete/update them. After each object is flushed, the hook __storm_flushed__ is called on it, and if changes are made to the object it will get back to the dirty list, and be flushed again.

Note that Storm will flush objects for you automatically, so you'll only need to call this method explicitly in very rare cases where normal flushing times are insufficient, such as when you want to make sure a database trigger gets run at a particular time.

def _flush_one(self, obj_info):
Undocumented
def block_implicit_flushes(self):
Block implicit flushes from operations like execute().
def unblock_implicit_flushes(self):
Unblock implicit flushes from operations like execute().
def block_access(self):
Block access to the underlying database connection.
def unblock_access(self):
Unblock access to the underlying database connection.
def _get_changes_map(self, obj_info, adding=False):
Return a {column: variable} dictionary suitable for inserts/updates.
Parametersobj_infoObjectInfo to inspect for changes.
addingIf true, any defined variables will be considered a change and included in the returned map.
def _fill_missing_values(self, obj_info, primary_vars, result=None):
Fill missing values in variables of the given obj_info.

This method will verify which values are unset in obj_info, and set them to AutoReload, or if it's part of the primary key, query the database for the actual values.

Parametersobj_infoObjectInfo to have its values filled.
primary_varsVariables composing the primary key with up-to-date values (cached variables may be out-of-date when this method is called).
resultIf some value in the set of primary variables isn't defined, it must be retrieved from the database using database-dependent logic, which is provided by the backend in the result of the query which inserted the object.
def _validate_alive(self, obj_info):
Perform cache validation for the given obj_info.
def _load_object(self, cls_info, result, values):
Undocumented
def _get_object(self, obj_info):
Return object for obj_info, rebuilding it if it's dead.
@staticmethod
def _run_hook(obj_info, hook_name):
Undocumented
def _set_values(self, obj_info, columns, result, values, keep_defined=False, replace_unknown_lazy=False):
Undocumented
def _is_dirty(self, obj_info):
Undocumented
def _set_dirty(self, obj_info):
Undocumented
def _set_clean(self, obj_info):
Undocumented
def _iter_dirty(self):
Undocumented
def _add_to_alive(self, obj_info):
Add an object to the set of known in-memory objects.

When an object is added to the set of known in-memory objects, the key is built from a copy of the current variables that are part of the primary key. This means that, when an object is retrieved from the database, these values may be used to get the cached object which is already in memory, even if it requested the primary key value to be changed. For that reason, when changes to the primary key are flushed, the alive object key should also be updated to reflect these changes.

In addition to tracking objects alive in memory, we have a strong reference cache which keeps a fixed number of last-used objects in-memory, to prevent further database access for recently fetched objects.

def _remove_from_alive(self, obj_info):
Remove an object from the cache.

This method is only called for objects that were explicitly deleted and flushed. Objects that are unused will get removed from the cache dictionary automatically by their weakref callbacks.

def _iter_alive(self):
Undocumented
def _enable_change_notification(self, obj_info):
Undocumented
def _disable_change_notification(self, obj_info):
Undocumented
def _variable_changed(self, obj_info, variable, old_value, new_value, fromdb):
Undocumented
def _enable_lazy_resolving(self, obj_info):
Undocumented
def _disable_lazy_resolving(self, obj_info):
Undocumented
def _resolve_lazy_value(self, obj_info, variable, lazy_value):
Resolve a variable set to a lazy value when it's touched.

This method is hooked into the obj_info to resolve variables set to lazy values when they're accessed. It will first flush the store, and then set all variables set to AutoReload to their database values.

API Documentation for storm, generated by pydoctor at 2011-03-15 08:53:51.