API

Store

The Store interface to a database.

This module contains the highest-level ORM interface in Storm.

class storm.store.Store(database, cache=None)

Bases: object

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.

Parameters:
  • database – The storm.database.Database instance to use.
  • cache – The cache to use. Defaults to a Cache instance.
get_database()

Return this Store’s Database object.

static 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.

execute(statement, params=None, noresult=False)

Execute a basic query.

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

close()

Close the connection.

begin(xid)

Start a new two-phase transaction.

Parameters:xid – A Xid instance holding identification data for the new transaction.
prepare()

Prepare a two-phase transaction for the final commit.

Note:It must be called inside a two-phase transaction started with begin.
commit()

Commit all changes to the database.

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

rollback()

Roll back all outstanding changes, reverting to database state.

get(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.

Parameters:
  • cls – Class of the object to be retrieved.
  • key – Primary key of object. May be a tuple for composed keys.
Returns:

The object found with the given primary key, or None if no object is found.

find(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.
Parameters:
  • cls_spec – The class or tuple of classes whose associated tables will be queried.
  • args – Instances of Expr.
  • kwargs – Mapping of simple column names to values or expressions to query for.
Returns:

A ResultSet of instances cls_spec. If cls_spec was a tuple, then an iterator of tuples of such instances.

using(*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;
Returns:A TableSet, which has a find method similar to Store.find.
add(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.

remove(obj)

Remove the given object from the store.

The associated row will be deleted from the database.

reload(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.

autoreload(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.

Parameters:obj – If passed, only mark the given object for autoreload. Otherwise, all cached objects will be marked for autoreload.
invalidate(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.

reset()

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.

add_flush_order(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.

Parameters:
  • before – The object to flush first.
  • after – The object to flush after before.
remove_flush_order(before, after)

Cancel an explicit flush order specified with add_flush_order.

Parameters:
  • before – The before object previously specified in a call to add_flush_order.
  • after – The after object previously specified in a call to add_flush_order.
flush()

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.

block_implicit_flushes()

Block implicit flushes from operations like execute().

unblock_implicit_flushes()

Unblock implicit flushes from operations like execute().

block_access()

Block access to the underlying database connection.

unblock_access()

Unblock access to the underlying database connection.

class storm.store.EmptyResultSet(ordered=False)

Bases: object

An object that looks like a ResultSet but represents no rows.

This is convenient for application developers who want to provide a method which is guaranteed to return a ResultSet-like object but which, in certain cases, knows there is no point in querying the database. For example:

def get_people(self, ids):
    if not ids:
        return EmptyResultSet()
    return store.find(People, People.id.is_in(ids))

The methods on EmptyResultSet (one, config, union, etc) are meant to emulate a ResultSet which has matched no rows.

get_select_expr(*columns)

Get a Select expression to retrieve only the specified columns.

Parameters:columns – One or more storm.expr.Column objects whose values will be fetched.
Raises:FeatureError – Raised if no columns are specified.
Returns:A Select expression configured to use the query parameters specified for this result set. The result of the select will always be an empty set of rows.
class storm.store.block_access(*args)

Bases: object

Context manager blocks database access by one or more Stores in the managed scope.

class storm.store.ResultSet(store, find_spec, where=Undef, tables=Undef, select=Undef)

Bases: object

The representation of the results of a query.

Note that having an instance of this class does not indicate that a database query has necessarily been made. Database queries are put off until absolutely necessary.

Generally these should not be constructed directly, but instead retrieved from calls to Store.find.

copy()

Return a copy of this ResultSet object, with the same configuration.

config(distinct=None, offset=None, limit=None)

Configure this result object in-place. All parameters are optional.

Parameters:
  • distinct – If True, enables usage of the DISTINCT keyword in the query. If a tuple or list of columns, inserts a DISTINCT ON (only supported by PostgreSQL).
  • offset – Offset where results will start to be retrieved from the result set.
  • limit – Limit the number of objects retrieved from the result set.
Returns:

self (not a copy).

is_empty()

Return True if this result set doesn’t contain any results.

any()

Return a single item from the result set.

Returns:An arbitrary object or None if one isn’t available.
See:one, first, and last.
first()

Return the first item from an ordered result set.

Raises:UnorderedError – Raised if the result set isn’t ordered.
Returns:The first object or None if one isn’t available.
See:last, one, and any.
last()

Return the last item from an ordered result set.

Raises:
Returns:

The last object or None if one isn’t available.

See:

first, one, and any.

one()

Return one item from a result set containing at most one item.

Raises:NotOneError – Raised if the result set contains more than one item.
Returns:The object or None if one isn’t available.
See:first, last, and any.
order_by(*args)

Specify the ordering of the results.

The query will be modified appropriately with an ORDER BY clause.

Ascending and descending order can be specified by wrapping the columns in Asc and Desc.

Parameters:args – One or more storm.expr.Column objects.
remove()

Remove all rows represented by this ResultSet from the database.

This is done efficiently with a DELETE statement, so objects are not actually loaded into Python.

group_by(*expr)

Group this ResultSet by the given expressions.

Parameters:expr – The expressions used in the GROUP BY statement.
Returns:self (not a copy).
having(*expr)

Filter result previously grouped by.

Parameters:expr – Instances of Expr.
Returns:self (not a copy).
count(expr=Undef, distinct=False)

Get the number of objects represented by this ResultSet.

max(expr)

Get the highest value from an expression.

min(expr)

Get the lowest value from an expression.

avg(expr)

Get the average value from an expression.

sum(expr)

Get the sum of all values in an expression.

get_select_expr(*columns)

Get a Select expression to retrieve only the specified columns.

Parameters:columns – One or more storm.expr.Column objects whose values will be fetched.
Raises:FeatureError – Raised if no columns are specified or if this result is a set expression such as a union.
Returns:A Select expression configured to use the query parameters specified for this result set, and also limited to only retrieving data for the specified columns.
values(*columns)

Retrieve only the specified columns.

This does not load full objects from the database into Python.

Parameters:columns – One or more storm.expr.Column objects whose values will be fetched.
Raises:FeatureError – Raised if no columns are specified or if this result is a set expression such as a union.
Returns:An iterator of tuples of the values for each column from each matching row in the database.
set(*args, **kwargs)

Update objects in the result set with the given arguments.

This method will update all objects in the current result set to match expressions given as equalities or keyword arguments. These objects may still be in the database (an UPDATE is issued) or may be cached.

For instance, result.set(Class.attr1 == 1, attr2=2) will set attr1 to 1 and attr2 to 2, on all matching objects.

cached()

Return matching objects from the cache for the current query.

find(*args, **kwargs)

Perform a query on objects within this result set.

This is analogous to Store.find, although it doesn’t take a cls_spec argument, instead using the same tables as the existing result set, and restricts the results to those in this set.

Parameters:
  • args – Instances of Expr.
  • kwargs – Mapping of simple column names to values or expressions to query for.
Returns:

A ResultSet of matching instances.

union(other, all=False)

Get the Union of this result set and another.

Parameters:all – If True, include duplicates.
difference(other, all=False)

Get the difference, using Except, of this result set and another.

Parameters:all – If True, include duplicates.
intersection(other, all=False)

Get the Intersection of this result set and another.

Parameters:all – If True, include duplicates.
class storm.store.TableSet(store, tables)

Bases: object

The representation of a set of tables which can be queried at once.

This will typically be constructed by a call to Store.using.

find(cls_spec, *args, **kwargs)

Perform a query on the previously specified tables.

This is identical to Store.find except that the tables are explicitly specified instead of relying on inference.

Returns:A ResultSet.
storm.store.AutoReload

A marker for reloading a single value.

Often this will be used to specify that a specific attribute should be loaded from the database on the next access, like so:

storm_object.property = AutoReload

On the next access to storm_object.property, the value will be loaded from the database.

It is also often used as a default value for a property:

class Person(object):
    __storm_table__ = "person"
    id = Int(allow_none=False, default=AutoReload)

person = store.add(Person)
person.id # gets the attribute from the database.

Defining tables and columns

Base

class storm.base.Storm

Bases: object

An optional base class for objects stored in a Storm Store.

It causes your subclasses to be associated with a Storm PropertyRegistry. It is necessary to use this if you want to specify References with strings.

Properties

class storm.properties.Property(name=None, primary=False, variable_class=<class 'storm.variables.Variable'>, variable_kwargs={})

Bases: object

A property representing a database column.

Properties can be set as attributes of classes that have a __storm_table__, and can then be used like ordinary Python properties on instances of the class, corresponding to database columns.

Parameters:
  • name – The name of this property.
  • primary – A boolean indicating whether this property is a primary key.
  • variable_class – The type of storm.variables.Variable corresponding to this property.
  • variable_kwargs – Dictionary of keyword arguments to be passed when constructing the underlying variable.
class storm.properties.SimpleProperty(name=None, primary=False, **kwargs)

Bases: storm.properties.Property

Parameters:
  • name – The name of this property.
  • primary – A boolean indicating whether this property is a primary key.
  • default – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • default_factory – If specified, this will immediately be called to get the initial value.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • kwargs – Other keyword arguments passed through when constructing the underlying variable.
class storm.properties.Bool(name=None, primary=False, **kwargs)

Bases: storm.properties.SimpleProperty

Boolean property.

This accepts integer, float, or decimal.Decimal values, and stores them as booleans.

Parameters:
  • name – The name of this property.
  • primary – A boolean indicating whether this property is a primary key.
  • default – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • default_factory – If specified, this will immediately be called to get the initial value.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • kwargs – Other keyword arguments passed through when constructing the underlying variable.
variable_class

alias of storm.variables.BoolVariable

class storm.properties.Int(name=None, primary=False, **kwargs)

Bases: storm.properties.SimpleProperty

Integer property.

This accepts integer, float, or decimal.Decimal values, and stores them as integers.

Parameters:
  • name – The name of this property.
  • primary – A boolean indicating whether this property is a primary key.
  • default – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • default_factory – If specified, this will immediately be called to get the initial value.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • kwargs – Other keyword arguments passed through when constructing the underlying variable.
variable_class

alias of storm.variables.IntVariable

class storm.properties.Float(name=None, primary=False, **kwargs)

Bases: storm.properties.SimpleProperty

Float property.

This accepts integer, float, or decimal.Decimal values, and stores them as floating-point values.

Parameters:
  • name – The name of this property.
  • primary – A boolean indicating whether this property is a primary key.
  • default – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • default_factory – If specified, this will immediately be called to get the initial value.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • kwargs – Other keyword arguments passed through when constructing the underlying variable.
variable_class

alias of storm.variables.FloatVariable

class storm.properties.Decimal(name=None, primary=False, **kwargs)

Bases: storm.properties.SimpleProperty

Decimal property.

This accepts integer or decimal.Decimal values, and stores them as text strings containing their decimal representation.

Parameters:
  • name – The name of this property.
  • primary – A boolean indicating whether this property is a primary key.
  • default – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • default_factory – If specified, this will immediately be called to get the initial value.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • kwargs – Other keyword arguments passed through when constructing the underlying variable.
variable_class

alias of storm.variables.DecimalVariable

class storm.properties.Bytes(name=None, primary=False, **kwargs)

Bases: storm.properties.SimpleProperty

Bytes property.

This accepts bytes, buffer (Python 2), or memoryview (Python 3) objects, and stores them as byte strings.

Deprecated aliases: Chars, RawStr.

Parameters:
  • name – The name of this property.
  • primary – A boolean indicating whether this property is a primary key.
  • default – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • default_factory – If specified, this will immediately be called to get the initial value.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • kwargs – Other keyword arguments passed through when constructing the underlying variable.
variable_class

alias of storm.variables.BytesVariable

storm.properties.RawStr

alias of storm.properties.Bytes

class storm.properties.Unicode(name=None, primary=False, **kwargs)

Bases: storm.properties.SimpleProperty

Unicode property.

This accepts unicode (Python 2) or str (Python 3) objects, and stores them as text strings. Note that it does not accept str objects on Python 2.

Parameters:
  • name – The name of this property.
  • primary – A boolean indicating whether this property is a primary key.
  • default – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • default_factory – If specified, this will immediately be called to get the initial value.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • kwargs – Other keyword arguments passed through when constructing the underlying variable.
variable_class

alias of storm.variables.UnicodeVariable

class storm.properties.DateTime(name=None, primary=False, **kwargs)

Bases: storm.properties.SimpleProperty

Date and time property.

This accepts aware datetime.datetime objects and stores them as timestamps; it also accepts integer or float objects, converting them using datetime.utcfromtimestamp. Note that it does not accept naive datetime.datetime objects (those that do not have timezone information).

Parameters:
  • name – The name of this property.
  • primary – A boolean indicating whether this property is a primary key.
  • default – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • default_factory – If specified, this will immediately be called to get the initial value.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • kwargs – Other keyword arguments passed through when constructing the underlying variable.
variable_class

alias of storm.variables.DateTimeVariable

class storm.properties.Date(name=None, primary=False, **kwargs)

Bases: storm.properties.SimpleProperty

Date property.

This accepts datetime.date objects and stores them as datestamps; it also accepts datetime.datetime objects, converting them using datetime.datetime.date.

Parameters:
  • name – The name of this property.
  • primary – A boolean indicating whether this property is a primary key.
  • default – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • default_factory – If specified, this will immediately be called to get the initial value.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • kwargs – Other keyword arguments passed through when constructing the underlying variable.
variable_class

alias of storm.variables.DateVariable

class storm.properties.Time(name=None, primary=False, **kwargs)

Bases: storm.properties.SimpleProperty

Time property.

This accepts datetime.time objects and stores them as datestamps; it also accepts datetime.datetime objects, converting them using datetime.datetime.time.

Parameters:
  • name – The name of this property.
  • primary – A boolean indicating whether this property is a primary key.
  • default – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • default_factory – If specified, this will immediately be called to get the initial value.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • kwargs – Other keyword arguments passed through when constructing the underlying variable.
variable_class

alias of storm.variables.TimeVariable

class storm.properties.TimeDelta(name=None, primary=False, **kwargs)

Bases: storm.properties.SimpleProperty

Time delta property.

This accepts datetime.timedelta objects and stores them as time intervals.

Parameters:
  • name – The name of this property.
  • primary – A boolean indicating whether this property is a primary key.
  • default – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • default_factory – If specified, this will immediately be called to get the initial value.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • kwargs – Other keyword arguments passed through when constructing the underlying variable.
variable_class

alias of storm.variables.TimeDeltaVariable

class storm.properties.UUID(name=None, primary=False, **kwargs)

Bases: storm.properties.SimpleProperty

UUID property.

This accepts uuid.UUID objects and stores them as their text representation.

Parameters:
  • name – The name of this property.
  • primary – A boolean indicating whether this property is a primary key.
  • default – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • default_factory – If specified, this will immediately be called to get the initial value.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • kwargs – Other keyword arguments passed through when constructing the underlying variable.
variable_class

alias of storm.variables.UUIDVariable

class storm.properties.Pickle(name=None, primary=False, **kwargs)

Bases: storm.properties.SimpleProperty

Pickle property.

This accepts any object that can be serialized using pickle, and stores it as a byte string containing its pickled representation.

Parameters:
  • name – The name of this property.
  • primary – A boolean indicating whether this property is a primary key.
  • default – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • default_factory – If specified, this will immediately be called to get the initial value.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • kwargs – Other keyword arguments passed through when constructing the underlying variable.
variable_class

alias of storm.variables.PickleVariable

class storm.properties.JSON(name=None, primary=False, **kwargs)

Bases: storm.properties.SimpleProperty

JSON property.

This accepts any object that can be serialized using json, and stores it as a text string containing its JSON representation.

Parameters:
  • name – The name of this property.
  • primary – A boolean indicating whether this property is a primary key.
  • default – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • default_factory – If specified, this will immediately be called to get the initial value.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • kwargs – Other keyword arguments passed through when constructing the underlying variable.
variable_class

alias of storm.variables.JSONVariable

class storm.properties.List(name=None, **kwargs)

Bases: storm.properties.SimpleProperty

List property.

This accepts iterable objects and stores them as a list where each element is an object of the given value type.

Parameters:
  • name – The name of this property.
  • type – An instance of Property defining the type of each element of this list.
  • default_factory – If specified, this will immediately be called to get the initial value.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • kwargs – Other keyword arguments passed through when constructing the underlying variable.
variable_class

alias of storm.variables.ListVariable

class storm.properties.Enum(name=None, primary=False, **kwargs)

Bases: storm.properties.SimpleProperty

Enumeration property, allowing used values to differ from stored ones.

For instance:

class Class(Storm):
    prop = Enum(map={"one": 1, "two": 2})

obj.prop = "one"
assert obj.prop == "one"

obj.prop = 1 # Raises error.

Another example:

class Class(Storm):
    prop = Enum(map={"one": 1, "two": 2}, set_map={"um": 1})

obj.prop = "um"
assert obj.prop is "one"

obj.prop = "one" # Raises error.
variable_class

alias of storm.variables.EnumVariable

class storm.properties.PropertyRegistry

Bases: object

An object which remembers the Storm properties specified on classes, and is able to translate names to these properties.

get(name, namespace=None)

Translate a property name path to the actual property.

This method accepts a property name like "id" or "Class.id" or "module.path.Class.id", and tries to find a unique class/property with the given name.

When the namespace argument is given, the registry will be able to disambiguate names by choosing the one that is closer to the given namespace. For instance get("Class.id", "a.b.c") will choose a.Class.id rather than d.Class.id.

add_class(cls)

Register properties of cls so that they may be found by get().

add_property(cls, prop, attr_name)

Register property of cls so that it may be found by get().

clear()

Clean up all properties in the registry.

Used by tests.

References

class storm.references.Reference(local_key, remote_key, on_remote=False)

Bases: object

Descriptor for one-to-one relationships.

This is typically used when the class that it is being defined on has a foreign key onto another table:

class OtherGuy(object):
    ...
    id = Int()

class MyGuy(object):
    ...
    other_guy_id = Int()
    other_guy = Reference(other_guy_id, OtherGuy.id)

but can also be used for backwards references, where OtherGuy’s table has a foreign key onto the class that you want this property on:

class OtherGuy(object):
    ...
    my_guy_id = Int() # in the database, a foreign key to my_guy.id

class MyGuy(object):
    ...
    id = Int()
    other_guy = Reference(id, OtherGuy.my_guy_id, on_remote=True)

In both cases, MyGuy().other_guy will resolve to the OtherGuy instance which is linked to it. In the first case, it will be the OtherGuy instance whose id is equivalent to the MyGuy’s other_guy_id; in the second, it’ll be the OtherGuy instance whose my_guy_id is equivalent to the MyGuy’s id.

Assigning to the property, for example with C{MyGuy().other_guy = OtherGuy()}, will link the objects and update either MyGuy.other_guy_id or OtherGuy.my_guy_id accordingly.

String references may be used in place of storm.expr.Column objects throughout, and are resolved to columns using PropertyResolver.

Create a Reference property.

Parameters:
  • local_key – The sibling column which is the foreign key onto remote_key. (unless on_remote is passed; see below).
  • remote_key – The column on the referred-to object which will have the same value as that for local_key when resolved on an instance.
  • on_remote – If specified, then the reference is backwards: It is the remote_key which is a foreign key onto local_key.
class storm.references.ReferenceSet(local_key1, remote_key1, remote_key2=None, local_key2=None, order_by=None)

Bases: object

Descriptor for many-to-one and many-to-many reference sets.

This is typically used when another class has a foreign key onto the class being defined, either directly (the many-to-one case) or via an intermediate table (the many-to-many case). For instance:

class Person(Storm):
    ...
    id = Int(primary=True)
    email_addresses = ReferenceSet("id", "EmailAddress.owner_id")

class EmailAddress(Storm):
    ...
    owner_id = Int(name="owner", allow_none=False)
    owner = Reference(owner_id, "Person.id")

class TeamMembership(Storm):
    ...
    person_id = Int(name="person", allow_none=False)
    person = Reference(person_id, "Person.id")
    team_id = Int(name="team", allow_none=False)
    team = Reference(team_id, "Team.id")

class Team(Storm):
    ...
    id = Int(primary=True)
    members = ReferenceSet(
        "id", "TeamMembership.team_id",
        "TeamMembership.person_id", "Person.id",
        order_by="Person.name")

In this case, Person().email_addresses resolves to a BoundReferenceSet of all the email addresses linked to that person (a many-to-one relationship), while Team().members resolves to a BoundIndirectReferenceSet of all the members of that team (a many-to-many relationship). These can be used in a somewhat similar way to ResultSet objects.

String references may be used in place of storm.expr.Column objects throughout, and are resolved to columns using PropertyResolver.

Parameters:
  • local_key1 – The sibling column which has the same value as that for remote_key1 when resolved on an instance.
  • remote_key1 – The column on the referring object (in the case of a many-to-one relation) or on the intermediate table (in the case of a many-to-many relation) which is the foreign key onto local_key1.
  • remote_key2 – In the case of a many-to-many relation, the column on the intermediate table which is the foreign key onto local_key2.
  • local_key2 – In the case of a many-to-many relation, the column on the referred-to object which has the same value as remote_key2 when resolved on an instance.
  • order_by – If not None, order the resolved BoundReferenceSet or BoundIndirectReferenceSet by these columns, as in storm.store.ResultSet.order_by.
class storm.references.Proxy(reference, remote_prop)

Bases: storm.expr.ComparableExpr

Proxy exposes a referred object’s column as a local column.

For example:

class Foo(object):
    bar_id = Int()
    bar = Reference(bar_id, Bar.id)
    bar_title = Proxy(bar, Bar.title)

For most uses, Foo.bar_title should behave as if it were a native property of Foo.

class RemoteProp

Bases: object

This descriptor will resolve and set the _remote_prop attribute when it’s first used. It avoids having a test at every single place where the attribute is touched.

Variables

class storm.variables.LazyValue

Bases: object

Marker to be used as a base class on lazily evaluated values.

storm.variables.VariableFactory

alias of functools.partial

class storm.variables.Variable(value=Undef, value_factory=Undef, from_db=False, allow_none=True, column=None, event=None, validator=None, validator_object_factory=None, validator_attribute=None)

Bases: object

Basic representation of a database value in Python.

Variables:
  • column – The column this variable represents.
  • event – The event system on which to broadcast events. If None, no events will be emitted.
Parameters:
  • value – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • value_factory – If specified, this will immediately be called to get the initial value.
  • from_db – A boolean value indicating where the initial value comes from, if value or value_factory are specified.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • column (storm.expr.Column) – The column that this variable represents. It’s used for reporting better error messages.
  • event (storm.event.EventSystem) – The event system to broadcast messages with. If not specified, then no events will be broadcast.
get_lazy(default=None)

Get the current LazyValue without resolving its value.

Parameters:default – If no LazyValue was previously specified, return this value. Defaults to None.
get(default=None, to_db=False)

Get the value, resolving it from a LazyValue if necessary.

If the current value is an instance of LazyValue, then the resolve-lazy-value event will be emitted, to give third parties the chance to resolve the lazy value to a real value.

Parameters:
  • default – Returned if no value has been set.
  • to_db – A boolean flag indicating whether this value is destined for the database.
set(value, from_db=False)

Set a new value.

Generally this will be called when an attribute was set in Python, or data is being loaded from the database.

If the value is different from the previous value (or it is a LazyValue), then the changed event will be emitted.

Parameters:
  • value – The value to set. If this is an instance of LazyValue, then later calls to get will try to resolve the value.
  • from_db – A boolean indicating whether this value has come from the database.
delete()

Delete the internal value.

If there was a value set, then emit the changed event.

is_defined()

Check whether there is currently a value.

Returns:boolean indicating whether there is currently a value for this variable. Note that if a LazyValue was previously set, this returns False; it only returns True if there is currently a real value set.
has_changed()

Check whether the value has changed.

Returns:boolean indicating whether the value has changed since the last call to checkpoint.
get_state()

Get the internal state of this object.

Returns:A value which can later be passed to set_state.
set_state(state)

Set the internal state of this object.

Parameters:state – A result from a previous call to get_state. The internal state of this variable will be set to the state of the variable which get_state was called on.
checkpoint()

“Checkpoint” the internal state.

See has_changed.

copy()

Make a new copy of this Variable with the same internal state.

parse_get(value, to_db)

Convert the internal value to an external value.

Get a representation of this value either for Python or for the database. This method is only intended to be overridden in subclasses, not called from external code.

Parameters:
  • value – The value to be converted.
  • to_db – Whether or not this value is destined for the database.
parse_set(value, from_db)

Convert an external value to an internal value.

A value is being set either from Python code or from the database. Parse it into its internal representation. This method is only intended to be overridden in subclasses, not called from external code.

Parameters:
  • value – The value, either from Python code setting an attribute or from a column in a database.
  • from_db – A boolean flag indicating whether this value is from the database.
class storm.variables.BoolVariable(value=Undef, value_factory=Undef, from_db=False, allow_none=True, column=None, event=None, validator=None, validator_object_factory=None, validator_attribute=None)

Bases: storm.variables.Variable

Parameters:
  • value – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • value_factory – If specified, this will immediately be called to get the initial value.
  • from_db – A boolean value indicating where the initial value comes from, if value or value_factory are specified.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • column (storm.expr.Column) – The column that this variable represents. It’s used for reporting better error messages.
  • event (storm.event.EventSystem) – The event system to broadcast messages with. If not specified, then no events will be broadcast.
parse_set(value, from_db)

Convert an external value to an internal value.

A value is being set either from Python code or from the database. Parse it into its internal representation. This method is only intended to be overridden in subclasses, not called from external code.

Parameters:
  • value – The value, either from Python code setting an attribute or from a column in a database.
  • from_db – A boolean flag indicating whether this value is from the database.
class storm.variables.IntVariable(value=Undef, value_factory=Undef, from_db=False, allow_none=True, column=None, event=None, validator=None, validator_object_factory=None, validator_attribute=None)

Bases: storm.variables.Variable

Parameters:
  • value – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • value_factory – If specified, this will immediately be called to get the initial value.
  • from_db – A boolean value indicating where the initial value comes from, if value or value_factory are specified.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • column (storm.expr.Column) – The column that this variable represents. It’s used for reporting better error messages.
  • event (storm.event.EventSystem) – The event system to broadcast messages with. If not specified, then no events will be broadcast.
parse_set(value, from_db)

Convert an external value to an internal value.

A value is being set either from Python code or from the database. Parse it into its internal representation. This method is only intended to be overridden in subclasses, not called from external code.

Parameters:
  • value – The value, either from Python code setting an attribute or from a column in a database.
  • from_db – A boolean flag indicating whether this value is from the database.
class storm.variables.FloatVariable(value=Undef, value_factory=Undef, from_db=False, allow_none=True, column=None, event=None, validator=None, validator_object_factory=None, validator_attribute=None)

Bases: storm.variables.Variable

Parameters:
  • value – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • value_factory – If specified, this will immediately be called to get the initial value.
  • from_db – A boolean value indicating where the initial value comes from, if value or value_factory are specified.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • column (storm.expr.Column) – The column that this variable represents. It’s used for reporting better error messages.
  • event (storm.event.EventSystem) – The event system to broadcast messages with. If not specified, then no events will be broadcast.
parse_set(value, from_db)

Convert an external value to an internal value.

A value is being set either from Python code or from the database. Parse it into its internal representation. This method is only intended to be overridden in subclasses, not called from external code.

Parameters:
  • value – The value, either from Python code setting an attribute or from a column in a database.
  • from_db – A boolean flag indicating whether this value is from the database.
class storm.variables.DecimalVariable(value=Undef, value_factory=Undef, from_db=False, allow_none=True, column=None, event=None, validator=None, validator_object_factory=None, validator_attribute=None)

Bases: storm.variables.Variable

Parameters:
  • value – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • value_factory – If specified, this will immediately be called to get the initial value.
  • from_db – A boolean value indicating where the initial value comes from, if value or value_factory are specified.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • column (storm.expr.Column) – The column that this variable represents. It’s used for reporting better error messages.
  • event (storm.event.EventSystem) – The event system to broadcast messages with. If not specified, then no events will be broadcast.
static parse_set(value, from_db)

Convert an external value to an internal value.

A value is being set either from Python code or from the database. Parse it into its internal representation. This method is only intended to be overridden in subclasses, not called from external code.

Parameters:
  • value – The value, either from Python code setting an attribute or from a column in a database.
  • from_db – A boolean flag indicating whether this value is from the database.
static parse_get(value, to_db)

Convert the internal value to an external value.

Get a representation of this value either for Python or for the database. This method is only intended to be overridden in subclasses, not called from external code.

Parameters:
  • value – The value to be converted.
  • to_db – Whether or not this value is destined for the database.
class storm.variables.BytesVariable(value=Undef, value_factory=Undef, from_db=False, allow_none=True, column=None, event=None, validator=None, validator_object_factory=None, validator_attribute=None)

Bases: storm.variables.Variable

Parameters:
  • value – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • value_factory – If specified, this will immediately be called to get the initial value.
  • from_db – A boolean value indicating where the initial value comes from, if value or value_factory are specified.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • column (storm.expr.Column) – The column that this variable represents. It’s used for reporting better error messages.
  • event (storm.event.EventSystem) – The event system to broadcast messages with. If not specified, then no events will be broadcast.
parse_set(value, from_db)

Convert an external value to an internal value.

A value is being set either from Python code or from the database. Parse it into its internal representation. This method is only intended to be overridden in subclasses, not called from external code.

Parameters:
  • value – The value, either from Python code setting an attribute or from a column in a database.
  • from_db – A boolean flag indicating whether this value is from the database.
storm.variables.RawStrVariable

alias of storm.variables.BytesVariable

class storm.variables.UnicodeVariable(value=Undef, value_factory=Undef, from_db=False, allow_none=True, column=None, event=None, validator=None, validator_object_factory=None, validator_attribute=None)

Bases: storm.variables.Variable

Parameters:
  • value – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • value_factory – If specified, this will immediately be called to get the initial value.
  • from_db – A boolean value indicating where the initial value comes from, if value or value_factory are specified.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • column (storm.expr.Column) – The column that this variable represents. It’s used for reporting better error messages.
  • event (storm.event.EventSystem) – The event system to broadcast messages with. If not specified, then no events will be broadcast.
parse_set(value, from_db)

Convert an external value to an internal value.

A value is being set either from Python code or from the database. Parse it into its internal representation. This method is only intended to be overridden in subclasses, not called from external code.

Parameters:
  • value – The value, either from Python code setting an attribute or from a column in a database.
  • from_db – A boolean flag indicating whether this value is from the database.
class storm.variables.DateTimeVariable(*args, **kwargs)

Bases: storm.variables.Variable

parse_set(value, from_db)

Convert an external value to an internal value.

A value is being set either from Python code or from the database. Parse it into its internal representation. This method is only intended to be overridden in subclasses, not called from external code.

Parameters:
  • value – The value, either from Python code setting an attribute or from a column in a database.
  • from_db – A boolean flag indicating whether this value is from the database.
class storm.variables.DateVariable(value=Undef, value_factory=Undef, from_db=False, allow_none=True, column=None, event=None, validator=None, validator_object_factory=None, validator_attribute=None)

Bases: storm.variables.Variable

Parameters:
  • value – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • value_factory – If specified, this will immediately be called to get the initial value.
  • from_db – A boolean value indicating where the initial value comes from, if value or value_factory are specified.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • column (storm.expr.Column) – The column that this variable represents. It’s used for reporting better error messages.
  • event (storm.event.EventSystem) – The event system to broadcast messages with. If not specified, then no events will be broadcast.
parse_set(value, from_db)

Convert an external value to an internal value.

A value is being set either from Python code or from the database. Parse it into its internal representation. This method is only intended to be overridden in subclasses, not called from external code.

Parameters:
  • value – The value, either from Python code setting an attribute or from a column in a database.
  • from_db – A boolean flag indicating whether this value is from the database.
class storm.variables.TimeVariable(value=Undef, value_factory=Undef, from_db=False, allow_none=True, column=None, event=None, validator=None, validator_object_factory=None, validator_attribute=None)

Bases: storm.variables.Variable

Parameters:
  • value – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • value_factory – If specified, this will immediately be called to get the initial value.
  • from_db – A boolean value indicating where the initial value comes from, if value or value_factory are specified.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • column (storm.expr.Column) – The column that this variable represents. It’s used for reporting better error messages.
  • event (storm.event.EventSystem) – The event system to broadcast messages with. If not specified, then no events will be broadcast.
parse_set(value, from_db)

Convert an external value to an internal value.

A value is being set either from Python code or from the database. Parse it into its internal representation. This method is only intended to be overridden in subclasses, not called from external code.

Parameters:
  • value – The value, either from Python code setting an attribute or from a column in a database.
  • from_db – A boolean flag indicating whether this value is from the database.
class storm.variables.TimeDeltaVariable(value=Undef, value_factory=Undef, from_db=False, allow_none=True, column=None, event=None, validator=None, validator_object_factory=None, validator_attribute=None)

Bases: storm.variables.Variable

Parameters:
  • value – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • value_factory – If specified, this will immediately be called to get the initial value.
  • from_db – A boolean value indicating where the initial value comes from, if value or value_factory are specified.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • column (storm.expr.Column) – The column that this variable represents. It’s used for reporting better error messages.
  • event (storm.event.EventSystem) – The event system to broadcast messages with. If not specified, then no events will be broadcast.
parse_set(value, from_db)

Convert an external value to an internal value.

A value is being set either from Python code or from the database. Parse it into its internal representation. This method is only intended to be overridden in subclasses, not called from external code.

Parameters:
  • value – The value, either from Python code setting an attribute or from a column in a database.
  • from_db – A boolean flag indicating whether this value is from the database.
class storm.variables.UUIDVariable(value=Undef, value_factory=Undef, from_db=False, allow_none=True, column=None, event=None, validator=None, validator_object_factory=None, validator_attribute=None)

Bases: storm.variables.Variable

Parameters:
  • value – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • value_factory – If specified, this will immediately be called to get the initial value.
  • from_db – A boolean value indicating where the initial value comes from, if value or value_factory are specified.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • column (storm.expr.Column) – The column that this variable represents. It’s used for reporting better error messages.
  • event (storm.event.EventSystem) – The event system to broadcast messages with. If not specified, then no events will be broadcast.
parse_set(value, from_db)

Convert an external value to an internal value.

A value is being set either from Python code or from the database. Parse it into its internal representation. This method is only intended to be overridden in subclasses, not called from external code.

Parameters:
  • value – The value, either from Python code setting an attribute or from a column in a database.
  • from_db – A boolean flag indicating whether this value is from the database.
parse_get(value, to_db)

Convert the internal value to an external value.

Get a representation of this value either for Python or for the database. This method is only intended to be overridden in subclasses, not called from external code.

Parameters:
  • value – The value to be converted.
  • to_db – Whether or not this value is destined for the database.
class storm.variables.EnumVariable(get_map, set_map, *args, **kwargs)

Bases: storm.variables.Variable

parse_set(value, from_db)

Convert an external value to an internal value.

A value is being set either from Python code or from the database. Parse it into its internal representation. This method is only intended to be overridden in subclasses, not called from external code.

Parameters:
  • value – The value, either from Python code setting an attribute or from a column in a database.
  • from_db – A boolean flag indicating whether this value is from the database.
parse_get(value, to_db)

Convert the internal value to an external value.

Get a representation of this value either for Python or for the database. This method is only intended to be overridden in subclasses, not called from external code.

Parameters:
  • value – The value to be converted.
  • to_db – Whether or not this value is destined for the database.
class storm.variables.PickleVariable(*args, **kwargs)

Bases: storm.variables.EncodedValueVariable

class storm.variables.JSONVariable(*args, **kwargs)

Bases: storm.variables.EncodedValueVariable

class storm.variables.ListVariable(item_factory, *args, **kwargs)

Bases: storm.variables.MutableValueVariable

parse_set(value, from_db)

Convert an external value to an internal value.

A value is being set either from Python code or from the database. Parse it into its internal representation. This method is only intended to be overridden in subclasses, not called from external code.

Parameters:
  • value – The value, either from Python code setting an attribute or from a column in a database.
  • from_db – A boolean flag indicating whether this value is from the database.
parse_get(value, to_db)

Convert the internal value to an external value.

Get a representation of this value either for Python or for the database. This method is only intended to be overridden in subclasses, not called from external code.

Parameters:
  • value – The value to be converted.
  • to_db – Whether or not this value is destined for the database.
get_state()

Get the internal state of this object.

Returns:A value which can later be passed to set_state.
set_state(state)

Set the internal state of this object.

Parameters:state – A result from a previous call to get_state. The internal state of this variable will be set to the state of the variable which get_state was called on.

SQLObject emulation

A SQLObject emulation layer for Storm.

SQLObjectBase is the central point of compatibility.

storm.sqlobject.DESC

alias of storm.expr.Desc

storm.sqlobject.AND

alias of storm.expr.And

storm.sqlobject.OR

alias of storm.expr.Or

storm.sqlobject.NOT

alias of storm.expr.Not

storm.sqlobject.IN

alias of storm.expr.In

storm.sqlobject.LIKE

alias of storm.expr.Like

storm.sqlobject.SQLConstant

alias of storm.expr.SQL

storm.sqlobject.SQLObjectMoreThanOneResultError

alias of storm.exceptions.NotOneError

exception storm.sqlobject.SQLObjectNotFound

Bases: storm.exceptions.StormError

class storm.sqlobject.SQLObjectBase(*args, **kwargs)

Bases: storm.base.Storm

The root class of all SQLObject-emulating classes in your application.

The general strategy for using Storm’s SQLObject emulation layer is to create an application-specific subclass of SQLObjectBase (probably named “SQLObject”) that provides an implementation of _get_store to return an instance of storm.store.Store. It may even be implemented as returning a global Store instance. Then all database classes should subclass that class.

class storm.sqlobject.SQLObjectResultSet(cls, clause=None, clauseTables=None, orderBy=None, limit=None, distinct=None, prejoins=None, prejoinClauseTables=None, selectAlso=None, by={}, prepared_result_set=None, slice=None)

Bases: object

SQLObject-equivalent of the ResultSet class in Storm.

Storm handles joins in the Store interface, while SQLObject does that in the result one. To offer support for prejoins, we can’t simply wrap our ResultSet instance, and instead have to postpone the actual find until the very last moment.

is_empty()

Return True if this result set doesn’t contain any results.

class storm.sqlobject.StringCol(dbName=None, notNull=False, default=Undef, alternateID=None, unique=<object object>, name=<object object>, alternateMethodName=None, length=<object object>, immutable=None, storm_validator=None)

Bases: storm.sqlobject.PropertyAdapter, storm.sqlobject.AutoUnicode

class storm.sqlobject.IntCol(dbName=None, notNull=False, default=Undef, alternateID=None, unique=<object object>, name=<object object>, alternateMethodName=None, length=<object object>, immutable=None, storm_validator=None)

Bases: storm.sqlobject.PropertyAdapter, storm.properties.Int

class storm.sqlobject.BoolCol(dbName=None, notNull=False, default=Undef, alternateID=None, unique=<object object>, name=<object object>, alternateMethodName=None, length=<object object>, immutable=None, storm_validator=None)

Bases: storm.sqlobject.PropertyAdapter, storm.properties.Bool

class storm.sqlobject.FloatCol(dbName=None, notNull=False, default=Undef, alternateID=None, unique=<object object>, name=<object object>, alternateMethodName=None, length=<object object>, immutable=None, storm_validator=None)

Bases: storm.sqlobject.PropertyAdapter, storm.properties.Float

class storm.sqlobject.UtcDateTimeCol(dbName=None, notNull=False, default=Undef, alternateID=None, unique=<object object>, name=<object object>, alternateMethodName=None, length=<object object>, immutable=None, storm_validator=None)

Bases: storm.sqlobject.PropertyAdapter, storm.properties.DateTime

class storm.sqlobject.DateCol(dbName=None, notNull=False, default=Undef, alternateID=None, unique=<object object>, name=<object object>, alternateMethodName=None, length=<object object>, immutable=None, storm_validator=None)

Bases: storm.sqlobject.PropertyAdapter, storm.properties.Date

class storm.sqlobject.IntervalCol(dbName=None, notNull=False, default=Undef, alternateID=None, unique=<object object>, name=<object object>, alternateMethodName=None, length=<object object>, immutable=None, storm_validator=None)

Bases: storm.sqlobject.PropertyAdapter, storm.properties.TimeDelta

class storm.sqlobject.SQLMultipleJoin(otherClass=None, joinColumn=None, intermediateTable=None, otherColumn=None, orderBy=None, prejoins=None)

Bases: storm.references.ReferenceSet

storm.sqlobject.SQLRelatedJoin

alias of storm.sqlobject.SQLMultipleJoin

class storm.sqlobject.SingleJoin(otherClass, joinColumn, prejoins=<object object>)

Bases: storm.references.Reference

class storm.sqlobject.CONTAINSSTRING(expr, string)

Bases: storm.expr.Like

Expressions

class storm.expr.Compile(parent=None)

Bases: object

Compiler based on the concept of generic functions.

when(*types)

Decorator to include a type handler in this compiler.

Use this as:

>>> @compile.when(TypeA, TypeB)
>>> def compile_type_a_or_b(compile, expr, state):
>>>     ...
>>>     return "THE COMPILED SQL STATEMENT"
add_reserved_words(words)

Include words to be considered reserved and thus escaped.

Reserved words are escaped during compilation when they’re seen in a SQLToken expression.

create_child()

Create a new instance of Compile which inherits from this one.

This is most commonly used to customize a compiler for database-specific compilation strategies.

class storm.expr.CompilePython(parent=None)

Bases: storm.expr.Compile

class storm.expr.State

Bases: object

All the data necessary during compilation of an expression.

Variables:
  • aliases – Dict of Column instances to Alias instances, specifying how columns should be compiled as aliases in very specific situations. This is typically used to work around strange deficiencies in various databases.
  • auto_tables – The list of all implicitly-used tables. e.g., in store.find(Foo, Foo.attr==Bar.id), the tables of Bar and Foo are implicitly used because columns in them are referenced. This is used when building tables.
  • join_tables – If not None, when Join expressions are compiled, tables seen will be added to this set. This acts as a blacklist against auto_tables when compiling Joins, because the generated statements should not refer to the table twice.
  • context – an instance of Context, specifying the context of the expression currently being compiled.
  • precedence – Current precedence, automatically set and restored by the compiler. If an inner precedence is lower than an outer precedence, parenthesis around the inner expression are automatically emitted.
push(attr, new_value=Undef)

Set an attribute in a way that can later be reverted with pop.

pop()

Revert the topmost push.

class storm.expr.Context(name)

Bases: object

An object used to specify the nature of expected SQL expressions being compiled in a given context.

class storm.expr.Expr

Bases: storm.variables.LazyValue

class storm.expr.ComparableExpr

Bases: storm.expr.Expr, storm.expr.Comparable

class storm.expr.BinaryExpr(expr1, expr2)

Bases: storm.expr.ComparableExpr

class storm.expr.CompoundExpr(*exprs)

Bases: storm.expr.ComparableExpr

storm.expr.build_tables(compile, tables, default_tables, state)

Compile provided tables.

Tables will be built from either tables, state.auto_tables, or default_tables. If tables is not Undef, it will be used. If tables is Undef and state.auto_tables is available, that’s used instead. If neither tables nor state.auto_tables are available, default_tables is tried as a last resort. If none of them are available, NoTableError is raised.

class storm.expr.Select(columns, where=Undef, tables=Undef, default_tables=Undef, order_by=Undef, group_by=Undef, limit=Undef, offset=Undef, distinct=False, having=Undef)

Bases: storm.expr.Expr

class storm.expr.Insert(map, table=Undef, default_table=Undef, primary_columns=Undef, primary_variables=Undef, values=Undef)

Bases: storm.expr.Expr

Expression representing an insert statement.

Variables:
  • map – Dictionary mapping columns to values, or a sequence of columns for a bulk insert.
  • table – Table where the row should be inserted.
  • default_table – Table to use if no table is explicitly provided, and no tables may be inferred from provided columns.
  • primary_columns – Tuple of columns forming the primary key of the table where the row will be inserted. This is a hint used by backends to process the insertion of rows.
  • primary_variables – Tuple of variables with values for the primary key of the table where the row will be inserted. This is a hint used by backends to process the insertion of rows.
  • values – Expression or sequence of tuples of values for bulk insertion.
class storm.expr.Update(map, where=Undef, table=Undef, default_table=Undef, primary_columns=Undef)

Bases: storm.expr.Expr

class storm.expr.Delete(where=Undef, table=Undef, default_table=Undef)

Bases: storm.expr.Expr

class storm.expr.Column(name=Undef, table=Undef, primary=False, variable_factory=None)

Bases: storm.expr.ComparableExpr

Representation of a column in some table.

Variables:
  • name – Column name.
  • table – Column table (maybe another expression).
  • primary – Integer representing the primary key position of this column, or 0 if it’s not a primary key. May be provided as a bool.
  • variable_factory – Factory producing Variable instances typed according to this column.
class storm.expr.Alias(expr, name=Undef)

Bases: storm.expr.ComparableExpr

A representation of “AS” alias clauses. e.g., SELECT foo AS bar.

Create alias of expr AS name.

If name is not given, then a name will automatically be generated.

class storm.expr.FromExpr

Bases: storm.expr.Expr

class storm.expr.Table(name)

Bases: storm.expr.FromExpr

class storm.expr.JoinExpr(arg1, arg2=Undef, on=Undef)

Bases: storm.expr.FromExpr

class storm.expr.Join(arg1, arg2=Undef, on=Undef)

Bases: storm.expr.JoinExpr

class storm.expr.LeftJoin(arg1, arg2=Undef, on=Undef)

Bases: storm.expr.JoinExpr

class storm.expr.RightJoin(arg1, arg2=Undef, on=Undef)

Bases: storm.expr.JoinExpr

class storm.expr.NaturalJoin(arg1, arg2=Undef, on=Undef)

Bases: storm.expr.JoinExpr

class storm.expr.NaturalLeftJoin(arg1, arg2=Undef, on=Undef)

Bases: storm.expr.JoinExpr

class storm.expr.NaturalRightJoin(arg1, arg2=Undef, on=Undef)

Bases: storm.expr.JoinExpr

class storm.expr.Distinct(expr)

Bases: storm.expr.Expr

Add the ‘DISTINCT’ prefix to an expression.

class storm.expr.BinaryOper(expr1, expr2)

Bases: storm.expr.BinaryExpr

class storm.expr.NonAssocBinaryOper(expr1, expr2)

Bases: storm.expr.BinaryOper

class storm.expr.CompoundOper(*exprs)

Bases: storm.expr.CompoundExpr

class storm.expr.Eq(expr1, expr2)

Bases: storm.expr.BinaryOper

class storm.expr.Ne(expr1, expr2)

Bases: storm.expr.BinaryOper

class storm.expr.Gt(expr1, expr2)

Bases: storm.expr.BinaryOper

class storm.expr.Ge(expr1, expr2)

Bases: storm.expr.BinaryOper

class storm.expr.Lt(expr1, expr2)

Bases: storm.expr.BinaryOper

class storm.expr.Le(expr1, expr2)

Bases: storm.expr.BinaryOper

class storm.expr.RShift(expr1, expr2)

Bases: storm.expr.BinaryOper

class storm.expr.LShift(expr1, expr2)

Bases: storm.expr.BinaryOper

class storm.expr.Like(expr1, expr2, escape=Undef, case_sensitive=None)

Bases: storm.expr.BinaryOper

class storm.expr.In(expr1, expr2)

Bases: storm.expr.BinaryOper

class storm.expr.Add(*exprs)

Bases: storm.expr.CompoundOper

class storm.expr.Sub(expr1, expr2)

Bases: storm.expr.NonAssocBinaryOper

class storm.expr.Mul(*exprs)

Bases: storm.expr.CompoundOper

class storm.expr.Div(expr1, expr2)

Bases: storm.expr.NonAssocBinaryOper

class storm.expr.Mod(expr1, expr2)

Bases: storm.expr.NonAssocBinaryOper

class storm.expr.And(*exprs)

Bases: storm.expr.CompoundOper

class storm.expr.Or(*exprs)

Bases: storm.expr.CompoundOper

class storm.expr.SetExpr(*exprs, **kwargs)

Bases: storm.expr.Expr

class storm.expr.Union(*exprs, **kwargs)

Bases: storm.expr.SetExpr

class storm.expr.Except(*exprs, **kwargs)

Bases: storm.expr.SetExpr

class storm.expr.Intersect(*exprs, **kwargs)

Bases: storm.expr.SetExpr

class storm.expr.FuncExpr

Bases: storm.expr.ComparableExpr

class storm.expr.Count(column=Undef, distinct=False)

Bases: storm.expr.FuncExpr

class storm.expr.Func(name, *args)

Bases: storm.expr.FuncExpr

name

str(object=’‘) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

class storm.expr.NamedFunc(*args)

Bases: storm.expr.FuncExpr

class storm.expr.Max(*args)

Bases: storm.expr.NamedFunc

class storm.expr.Min(*args)

Bases: storm.expr.NamedFunc

class storm.expr.Avg(*args)

Bases: storm.expr.NamedFunc

class storm.expr.Sum(*args)

Bases: storm.expr.NamedFunc

class storm.expr.Lower(*args)

Bases: storm.expr.NamedFunc

class storm.expr.Upper(*args)

Bases: storm.expr.NamedFunc

class storm.expr.Coalesce(*args)

Bases: storm.expr.NamedFunc

class storm.expr.Row(*args)

Bases: storm.expr.NamedFunc

class storm.expr.Cast(column, type)

Bases: storm.expr.FuncExpr

A representation of CAST clauses. e.g., CAST(bar AS TEXT).

Create a cast of column as type.

storm.expr.compile_cast(compile, cast, state)

Compile Cast expressions.

class storm.expr.PrefixExpr(expr)

Bases: storm.expr.Expr

class storm.expr.SuffixExpr(expr)

Bases: storm.expr.Expr

class storm.expr.Not(expr)

Bases: storm.expr.PrefixExpr

class storm.expr.Exists(expr)

Bases: storm.expr.PrefixExpr

class storm.expr.Neg(expr)

Bases: storm.expr.PrefixExpr

class storm.expr.Asc(expr)

Bases: storm.expr.SuffixExpr

class storm.expr.Desc(expr)

Bases: storm.expr.SuffixExpr

class storm.expr.SQLRaw

Bases: str

Subtype to mark a string as something that shouldn’t be compiled.

This is handled internally by the compiler.

class storm.expr.SQLToken

Bases: str

Marker for strings that should be considered as a single SQL token.

These strings will be quoted, when needed.

storm.expr.is_safe_token()

Matches zero or more characters at the beginning of the string.

class storm.expr.SQL(expr, params=Undef, tables=Undef)

Bases: storm.expr.ComparableExpr

class storm.expr.Sequence(name)

Bases: storm.expr.Expr

Expression representing auto-incrementing support from the database.

This should be translated into the next value of the named auto-incrementing sequence. There’s no standard way to compile a sequence, since it’s very database-dependent.

This may be used as follows:

class Class(object):
    (...)
    id = Int(default=Sequence("my_sequence_name"))
class storm.expr.AutoTables(expr, tables, replace=False)

Bases: storm.expr.Expr

This class will inject one or more entries in state.auto_tables.

If the constructor is passed replace=True, it will also discard any auto_table entries injected by compiling the given expression.

Databases

Basic database interfacing mechanisms for Storm.

This is the common code for database support; specific databases are supported in modules in storm.databases.

class storm.database.Result(connection, raw_cursor)

Bases: object

A representation of the results from a single SQL statement.

close()

Close the underlying raw cursor, if it hasn’t already been closed.

get_one()

Fetch one result from the cursor.

The result will be converted to an appropriate format via from_database.

Raises:DisconnectionError – Raised when the connection is lost. Reconnection happens automatically on rollback.
Returns:A converted row or None, if no data is left.
get_all()

Fetch all results from the cursor.

The results will be converted to an appropriate format via from_database.

Raises:DisconnectionError – Raised when the connection is lost. Reconnection happens automatically on rollback.
rowcount

See PEP 249 for further details on rowcount.

Returns:the number of affected rows, or None if the database backend does not provide this information. Return value is undefined if all results have not yet been retrieved.
get_insert_identity(primary_columns, primary_variables)

Get a query which will return the row that was just inserted.

This must be overridden in database-specific subclasses.

Return type:storm.expr.Expr
static set_variable(variable, value)

Set the given variable’s value from the database.

static from_database(row)

Convert a row fetched from the database to an agnostic format.

This method is intended to be overridden in subclasses, but not called externally.

If there are any peculiarities in the datatypes returned from a database backend, this method should be overridden in the backend subclass to convert them.

class storm.database.Connection(database, event=None)

Bases: object

A connection to a database.

Variables:
  • result_factory – A callable which takes this Connection and the backend cursor and returns an instance of Result.
  • param_mark – The dbapi paramstyle that the database backend expects.
  • compile – The compiler to use for connections of this type.
result_factory

alias of Result

block_access()

Block access to the connection.

Attempts to execute statements or commit a transaction will result in a ConnectionBlockedError exception. Rollbacks are permitted as that operation is often used in case of failures.

unblock_access()

Unblock access to the connection.

execute(statement, params=None, noresult=False)

Execute a statement with the given parameters.

Parameters:
  • statement (Expr or str) – The statement to execute. It will be compiled if necessary.
  • noresult – If True, no result will be returned.
Raises:
Returns:

The result of self.result_factory, or None if noresult is True.

close()

Close the connection if it is not already closed.

begin(xid)

Begin a two-phase transaction.

prepare()

Run the prepare phase of a two-phase transaction.

commit(xid=None)

Commit the connection.

Parameters:

xid – Optionally the Xid of a previously prepared transaction to commit. This form should be called outside of a transaction, and is intended for use in recovery.

Raises:
recover()

Return a list of Xids representing pending transactions.

rollback(xid=None)

Rollback the connection.

Parameters:xid – Optionally the Xid of a previously prepared transaction to rollback. This form should be called outside of a transaction, and is intended for use in recovery.
static to_database(params)

Convert some parameters into values acceptable to a database backend.

It is acceptable to override this method in subclasses, but it is not intended to be used externally.

This delegates conversion to any Variables in the parameter list, and passes through all other values untouched.

build_raw_cursor()

Get a new dbapi cursor object.

It is acceptable to override this method in subclasses, but it is not intended to be called externally.

raw_execute(statement, params=None)

Execute a raw statement with the given parameters.

It’s acceptable to override this method in subclasses, but it is not intended to be called externally.

If the global DEBUG is True, the statement will be printed to standard out.

Returns:The dbapi cursor object, as fetched from build_raw_cursor.
is_disconnection_error(exc, extra_disconnection_errors=())

Check whether an exception represents a database disconnection.

This should be overridden by backends to detect whichever exception values are used to represent this condition.

preset_primary_key(primary_columns, primary_variables)

Process primary variables before an insert happens.

This method may be overwritten by backends to implement custom changes in primary variables before an insert happens.

class storm.database.Database(uri=None)

Bases: object

A database that can be connected to.

This should be subclassed for individual database backends.

Variables:connection_factory – A callable which will take this database and should return an instance of Connection.
connection_factory

alias of Connection

get_uri()

Return the URI object this database was created with.

connect(event=None)

Create a connection to the database.

It calls self.connection_factory to allow for ease of customization.

Parameters:event – The event system to broadcast messages with. If not specified, then no events will be broadcast.
Returns:An instance of Connection.
raw_connect()

Create a raw database connection.

This is used by Connection objects to connect to the database. It should be overriden in subclasses to do any database-specific connection setup.

Returns:A DB-API connection object.
storm.database.register_scheme(scheme, factory)

Register a handler for a new database URI scheme.

Parameters:
  • scheme – the database URI scheme
  • factory – a function taking a URI instance and returning a database.
storm.database.create_database(uri)

Create a database instance.

Parameters:uri – An URI instance, or a string describing the URI. Some examples:
“sqlite:”
An in memory sqlite database.
“sqlite:example.db”
A SQLite database called example.db
“postgres:test”
The database ‘test’ from the local postgres server.
“postgres://user:password@host/test”
The database test on machine host with supplied user credentials, using postgres.
“anything:…”
Where ‘anything’ has previously been registered with register_scheme.

PostgreSQL

class storm.databases.postgres.Returning(expr, columns=None)

Bases: storm.expr.Expr

Appends the “RETURNING <columns>” suffix to an INSERT or UPDATE.

Parameters:
  • expr – an Insert or Update expression.
  • columns – The columns to return, if None then expr.primary_columns will be used.

This is only supported in PostgreSQL 8.2+.

class storm.databases.postgres.Case(cases, expression=Undef, default=Undef)

Bases: storm.expr.Expr

A CASE statement.

Params cases:

a list of tuples of (condition, result) or (value, result), if an expression is passed too.

Parameters:
  • expression – the expression to compare (if the simple form is used).
  • default – an optional default condition if no other case matches.
class storm.databases.postgres.currval(column)

Bases: storm.expr.FuncExpr

storm.databases.postgres.compile_currval(compile, expr, state)

Compile a currval.

This is a bit involved because we have to get escaping right. Here are a few cases to keep in mind:

currval('thetable_thecolumn_seq')
currval('theschema.thetable_thecolumn_seq')
currval('"the schema".thetable_thecolumn_seq')
currval('theschema."the table_thecolumn_seq"')
currval('theschema."thetable_the column_seq"')
currval('"thetable_the column_seq"')
currval('"the schema"."the table_the column_seq"')
class storm.databases.postgres.PostgresResult(connection, raw_cursor)

Bases: storm.database.Result

get_insert_identity(primary_key, primary_variables)

Get a query which will return the row that was just inserted.

This must be overridden in database-specific subclasses.

Return type:storm.expr.Expr
class storm.databases.postgres.PostgresConnection(database, event=None)

Bases: storm.database.Connection

result_factory

alias of PostgresResult

execute(statement, params=None, noresult=False)

Execute a statement with the given parameters.

This extends the Connection.execute method to add support for automatic retrieval of inserted primary keys to link in-memory objects with their specific rows.

to_database(params)

Like Connection.to_database, but this converts datetime types to strings, and bytes to psycopg2.Binary instances.

is_disconnection_error(exc, extra_disconnection_errors=())

Check whether an exception represents a database disconnection.

This should be overridden by backends to detect whichever exception values are used to represent this condition.

class storm.databases.postgres.Postgres(uri)

Bases: storm.database.Database

connection_factory

alias of PostgresConnection

raw_connect()

Create a raw database connection.

This is used by Connection objects to connect to the database. It should be overriden in subclasses to do any database-specific connection setup.

Returns:A DB-API connection object.
storm.databases.postgres.create_from_uri

alias of storm.databases.postgres.Postgres

storm.databases.postgres.make_dsn(uri)

Convert a URI object to a PostgreSQL DSN string.

class storm.databases.postgres.PostgresTimeoutTracer(granularity=5)

Bases: storm.tracer.TimeoutTracer

set_statement_timeout(raw_cursor, remaining_time)

Perform the timeout setup in the raw cursor.

The database should raise an error if the next statement takes more than the number of seconds provided in remaining_time.

Must be specialized in the backend.

connection_raw_execute_error(connection, raw_cursor, statement, params, error)

Raise TimeoutError if the given error was a timeout issue.

Must be specialized in the backend.

class storm.databases.postgres.JSONElement(expr1, expr2)

Bases: storm.expr.BinaryOper

Return an element of a JSON value (by index or field name).

class storm.databases.postgres.JSONTextElement(expr1, expr2)

Bases: storm.expr.BinaryOper

Return an element of a JSON value (by index or field name) as text.

class storm.databases.postgres.JSONVariable(*args, **kwargs)

Bases: storm.variables.JSONVariable

class storm.databases.postgres.JSON(name=None, primary=False, **kwargs)

Bases: storm.properties.SimpleProperty

Parameters:
  • name – The name of this property.
  • primary – A boolean indicating whether this property is a primary key.
  • default – The initial value of this variable. The default behavior is for the value to stay undefined until it is set with set.
  • default_factory – If specified, this will immediately be called to get the initial value.
  • allow_none – A boolean indicating whether None should be allowed to be set as the value of this variable.
  • validator – Validation function called whenever trying to set the variable to a non-db value. The function should look like validator(object, attr, value), where the first and second arguments are the result of validator_object_factory() (or None, if this parameter isn’t provided) and the value of validator_attribute, respectively. When called, the function should raise an error if the value is unacceptable, or return the value to be used in place of the original value otherwise.
  • kwargs – Other keyword arguments passed through when constructing the underlying variable.
variable_class

alias of JSONVariable

SQLite

class storm.databases.sqlite.SQLiteResult(connection, raw_cursor)

Bases: storm.database.Result

get_insert_identity(primary_key, primary_variables)

Get a query which will return the row that was just inserted.

This must be overridden in database-specific subclasses.

Return type:storm.expr.Expr
static set_variable(variable, value)

Set the given variable’s value from the database.

static from_database(row)

Convert SQLite-specific datatypes to “normal” Python types.

On Python 2, if there are any buffer instances in the row, convert them to bytes. On Python 3, BLOB types are converted to bytes, which is already what we want.

class storm.databases.sqlite.SQLiteConnection(database, event=None)

Bases: storm.database.Connection

result_factory

alias of SQLiteResult

static to_database(params)

Like Connection.to_database, but this also converts instances of datetime types to strings, and (on Python 2) bytes instances to buffer instances.

commit()

Commit the connection.

Parameters:

xid – Optionally the Xid of a previously prepared transaction to commit. This form should be called outside of a transaction, and is intended for use in recovery.

Raises:
  • ConnectionBlockedError – Raised if access to the connection has been blocked with block_access.
  • DisconnectionError – Raised when the connection is lost. Reconnection happens automatically on rollback.
rollback()

Rollback the connection.

Parameters:xid – Optionally the Xid of a previously prepared transaction to rollback. This form should be called outside of a transaction, and is intended for use in recovery.
raw_execute(statement, params=None, _end=False)

Execute a raw statement with the given parameters.

This method will automatically retry on locked database errors. This should be done by pysqlite, but it doesn’t work with versions < 2.3.4, so we make sure the timeout is respected here.

class storm.databases.sqlite.SQLite(uri)

Bases: storm.database.Database

connection_factory

alias of SQLiteConnection

raw_connect()

Create a raw database connection.

This is used by Connection objects to connect to the database. It should be overriden in subclasses to do any database-specific connection setup.

Returns:A DB-API connection object.
storm.databases.sqlite.create_from_uri

alias of storm.databases.sqlite.SQLite

Transaction identifiers

class storm.xid.Xid(format_id, global_transaction_id, branch_qualifier)

Bases: object

Represent a transaction identifier compliant with the XA specification.

Hooks and events

Event

class storm.event.EventSystem(owner)

Bases: object

A system for managing hooks that are called when events are emitted.

Hooks are callables that take the event system owner as their first argument, followed by the arguments passed when emitting the event, followed by any additional data arguments given when registering the hook.

Hooks registered for a given event name are stored without ordering: no particular call order may be assumed when an event is emitted.

Parameters:owner – The object that owns this event system. It is passed as the first argument to each hook function.
hook(name, callback, *data)

Register a hook.

Parameters:
  • name – The name of the event for which this hook should be called.
  • callback – A callable which should be called when the event is emitted.
  • data – Additional arguments to pass to the callable, after the owner and any arguments passed when emitting the event.
unhook(name, callback, *data)

Unregister a hook.

This ignores attempts to unregister hooks that were not already registered.

Parameters:
  • name – The name of the event for which this hook should no longer be called.
  • callback – The callable to unregister.
  • data – Additional arguments that were passed when registering the callable.
emit(name, *args)

Emit an event, calling any registered hooks.

Parameters:
  • name – The name of the event.
  • args – Additional arguments to pass to hooks.

Tracer

class storm.tracer.TimeoutTracer(granularity=5)

Bases: object

Provide a timeout facility for connections to prevent rogue operations.

This tracer must be subclassed by backend-specific implementations that override connection_raw_execute_error, set_statement_timeout and get_remaining_time methods.

connection_raw_execute(connection, raw_cursor, statement, params)

Check timeout conditions before a statement is executed.

Parameters:
  • connection – The Connection to the database.
  • raw_cursor – A cursor object, specific to the backend being used.
  • statement – The SQL statement to execute.
  • params – The parameters to use with statement.
Raises:

TimeoutError – Raised if there isn’t enough time left to execute statement.

connection_raw_execute_error(connection, raw_cursor, statement, params, error)

Raise TimeoutError if the given error was a timeout issue.

Must be specialized in the backend.

connection_commit(connection, xid=None)

Reset Connection._timeout_tracer_remaining_time.

Parameters:
  • connection – The Connection to the database.
  • xid – Optionally the Xid of a previously prepared transaction to commit.
connection_rollback(connection, xid=None)

Reset Connection._timeout_tracer_remaining_time.

Parameters:
  • connection – The Connection to the database.
  • xid – Optionally the Xid of a previously prepared transaction to rollback.
set_statement_timeout(raw_cursor, remaining_time)

Perform the timeout setup in the raw cursor.

The database should raise an error if the next statement takes more than the number of seconds provided in remaining_time.

Must be specialized in the backend.

get_remaining_time()

Tells how much time the current context (HTTP request, etc) has.

Must be specialized with application logic.

Returns:Number of seconds allowed for the next statement.
class storm.tracer.BaseStatementTracer

Bases: object

Storm tracer base class that does query interpolation.

class storm.tracer.TimelineTracer(timeline_factory, prefix='SQL-')

Bases: storm.tracer.BaseStatementTracer

Storm tracer class to insert executed statements into a Timeline.

For more information on timelines see the module at https://pypi.org/project/timeline/.

The timeline to use is obtained by calling the timeline_factory supplied to the constructor. This simple function takes no parameters and returns a timeline to use. If it returns None, the tracer is bypassed.

Create a TimelineTracer.

Parameters:
  • timeline_factory – A factory function to produce the timeline to record a query against.
  • prefix – A prefix to give the connection name when starting an action. Connection names are found by trying a getattr for ‘name’ on the connection object. If no name has been assigned, ‘<unknown>’ is used instead.

Miscellaneous

Cache

class storm.cache.Cache(size=1000)

Bases: object

Prevents recently used objects from being deallocated.

This prevents recently used objects from being deallocated by Python even if the user isn’t holding any strong references to it. It does that by holding strong references to the objects referenced by the last N obj_infos added to it (where N is the cache size).

clear()

Clear the entire cache at once.

add(obj_info)

Add obj_info as the most recent entry in the cache.

If the obj_info is already in the cache, it remains in the cache and has its order changed to become the most recent entry (IOW, will be the last to leave).

remove(obj_info)

Remove obj_info from the cache, if present.

Returns:True if obj_info was cached, False otherwise.
set_size(size)

Set the maximum number of objects that may be held in this cache.

If the size is reduced, older obj_infos may be dropped from the cache to respect the new size.

get_cached()

Return an ordered list of the currently cached obj_infos.

The most recently added objects come first in the list.

class storm.cache.GenerationalCache(size=1000)

Bases: object

Generational replacement for Storm’s LRU cache.

This cache approximates LRU without keeping exact track. Instead, it keeps a primary dict of “recently used” objects plus a similar, secondary dict of objects used in a previous timeframe.

When the “most recently used” dict reaches its size limit, it is demoted to secondary dict and a fresh primary dict is set up. The previous secondary dict is evicted in its entirety.

Use this to replace the LRU cache for sizes where LRU tracking overhead becomes too large (e.g. 100,000 objects) or the StupidCache when it eats up too much memory.

Create a generational cache with the given size limit.

The size limit applies not to the overall cache, but to the primary one only. When this reaches the size limit, the real number of cached objects will be somewhere between size and 2*size depending on how much overlap there is between the primary and secondary caches.

clear()

See Cache.clear.

Clears both the primary and the secondary caches.

add(obj_info)

See Cache.add.

remove(obj_info)

See Cache.remove.

set_size(size)

See Cache.set_size.

After calling this, the cache may still contain more than size objects, but no more than twice that number.

get_cached()

See Cache.get_cached.

The result is a loosely-ordered list. Any object in the primary generation comes before any object that is only in the secondary generation, but objects within a generation are not ordered and there is no indication of the boundary between the two.

Objects that are in both the primary and the secondary generation are listed only as part of the primary generation.

Exceptions

exception storm.exceptions.StormError

Bases: Exception

exception storm.exceptions.CompileError

Bases: storm.exceptions.StormError

exception storm.exceptions.NoTableError

Bases: storm.exceptions.CompileError

exception storm.exceptions.ExprError

Bases: storm.exceptions.StormError

exception storm.exceptions.NoneError

Bases: storm.exceptions.StormError

exception storm.exceptions.PropertyPathError

Bases: storm.exceptions.StormError

exception storm.exceptions.ClassInfoError

Bases: storm.exceptions.StormError

exception storm.exceptions.URIError

Bases: storm.exceptions.StormError

exception storm.exceptions.ClosedError

Bases: storm.exceptions.StormError

exception storm.exceptions.FeatureError

Bases: storm.exceptions.StormError

exception storm.exceptions.DatabaseModuleError

Bases: storm.exceptions.StormError

exception storm.exceptions.StoreError

Bases: storm.exceptions.StormError

exception storm.exceptions.NoStoreError

Bases: storm.exceptions.StormError

exception storm.exceptions.WrongStoreError

Bases: storm.exceptions.StoreError

exception storm.exceptions.NotFlushedError

Bases: storm.exceptions.StoreError

exception storm.exceptions.OrderLoopError

Bases: storm.exceptions.StoreError

exception storm.exceptions.NotOneError

Bases: storm.exceptions.StoreError

exception storm.exceptions.UnorderedError

Bases: storm.exceptions.StoreError

exception storm.exceptions.LostObjectError

Bases: storm.exceptions.StoreError

exception storm.exceptions.Error

Bases: storm.exceptions.StormError

exception storm.exceptions.Warning

Bases: storm.exceptions.StormError

exception storm.exceptions.InterfaceError

Bases: storm.exceptions.Error

exception storm.exceptions.DatabaseError

Bases: storm.exceptions.Error

exception storm.exceptions.InternalError

Bases: storm.exceptions.DatabaseError

exception storm.exceptions.OperationalError

Bases: storm.exceptions.DatabaseError

exception storm.exceptions.ProgrammingError

Bases: storm.exceptions.DatabaseError

exception storm.exceptions.IntegrityError

Bases: storm.exceptions.DatabaseError

exception storm.exceptions.DataError

Bases: storm.exceptions.DatabaseError

exception storm.exceptions.NotSupportedError

Bases: storm.exceptions.DatabaseError

exception storm.exceptions.DisconnectionError

Bases: storm.exceptions.OperationalError

exception storm.exceptions.TimeoutError(statement, params, message=None)

Bases: storm.exceptions.StormError

Raised by timeout tracers when remining time is over.

exception storm.exceptions.ConnectionBlockedError

Bases: storm.exceptions.StormError

Raised when an attempt is made to use a blocked connection.

storm.exceptions.wrap_exceptions(database)

Context manager that re-raises DB exceptions as StormError instances.

Info

class storm.info.ClassInfo(cls)

Bases: dict

Persistent Storm-related information of a class.

The following attributes are defined:

Variables:
  • table – Expression from where columns will be looked up.
  • cls – Class which should be used to build objects.
  • columns – Tuple of column properties found in the class.
  • primary_key – Tuple of column properties used to form the primary key
  • primary_key_pos – Position of primary_key items in the columns tuple.
class storm.info.ObjectInfo(obj)

Bases: dict

class storm.info.ClassAlias

Bases: object

Create a named alias for a Storm class for use in queries.

This is useful basically when the SQL ‘AS’ feature is desired in code using Storm queries.

ClassAliases which are explicitly named (i.e., when ‘name’ is passed) are cached for as long as the class exists, such that the alias returned from ClassAlias(Foo, 'foo_alias') will be the same object no matter how many times it’s called.

Parameters:
  • cls – The class to create the alias of.
  • name – If provided, specify the name of the alias to create.

Testing

class storm.testing.CaptureTracer

Bases: storm.tracer.BaseStatementTracer, fixtures.fixture.Fixture

Trace SQL statements appending them to a list.

Example:

with CaptureTracer() as tracer:
    # Run queries
print(tracer.queries)  # Print the queries that have been run
Note:This class requires the fixtures package to be available.

Timezone

This module offers extensions to the standard python 2.3+ datetime module.

class storm.tz.tzutc

Bases: datetime.tzinfo

utcoffset(dt)

datetime -> timedelta showing offset from UTC, negative values indicating West of UTC

dst(dt)

datetime -> DST offset as timedelta positive east of UTC.

tzname(dt)

datetime -> string name of time zone.

class storm.tz.tzoffset(name, offset)

Bases: datetime.tzinfo

utcoffset(dt)

datetime -> timedelta showing offset from UTC, negative values indicating West of UTC

dst(dt)

datetime -> DST offset as timedelta positive east of UTC.

tzname(dt)

datetime -> string name of time zone.

class storm.tz.tzlocal

Bases: datetime.tzinfo

utcoffset(dt)

datetime -> timedelta showing offset from UTC, negative values indicating West of UTC

dst(dt)

datetime -> DST offset as timedelta positive east of UTC.

tzname(dt)

datetime -> string name of time zone.

class storm.tz.tzfile(fileobj)

Bases: datetime.tzinfo

utcoffset(dt)

datetime -> timedelta showing offset from UTC, negative values indicating West of UTC

dst(dt)

datetime -> DST offset as timedelta positive east of UTC.

tzname(dt)

datetime -> string name of time zone.

class storm.tz.tzrange(stdabbr, stdoffset=None, dstabbr=None, dstoffset=None, start=None, end=None)

Bases: datetime.tzinfo

utcoffset(dt)

datetime -> timedelta showing offset from UTC, negative values indicating West of UTC

dst(dt)

datetime -> DST offset as timedelta positive east of UTC.

tzname(dt)

datetime -> string name of time zone.

class storm.tz.tzstr(s)

Bases: storm.tz.tzrange

URIs

class storm.uri.URI(uri_str)

Bases: object

A representation of a Uniform Resource Identifier (URI).

This is intended exclusively for database connection URIs.

Variables:
  • username – The username part of the URI, or None.
  • password – The password part of the URI, or None.
  • host – The host part of the URI, or None.
  • port – The port part of the URI, or None.
  • database – The part of the URI representing the database name, or None.

WSGI

Glue to wire a storm timeline tracer up to a WSGI app.

storm.wsgi.make_app(app)

Capture the per-request timeline object needed for Storm tracing.

To use firstly make your app and then wrap it with this make_app:

>>> app, find_timeline = make_app(app)

Then wrap the returned app with the timeline app (or anything that sets environ['timeline.timeline']):

>>> app = timeline.wsgi.make_app(app)

Finally install a timeline tracer to capture Storm queries:

>>> install_tracer(TimelineTracer(find_timeline))
Returns:A wrapped WSGI app and a timeline factory function for use with TimelineTracer.