API¶

Locals ¶

The following names are re-exported from storm.locals for convenience:

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:	FeatureError – Raised if the result set has a `LIMIT` set. UnorderedError – Raised if the result set isn’t ordered.
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:	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.
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:	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.

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

API¶

Locals ¶

Store ¶

Defining tables and columns ¶

Base ¶

Properties ¶

References ¶

Variables ¶

SQLObject emulation ¶

Expressions ¶

Databases ¶

PostgreSQL ¶

SQLite ¶

Transaction identifiers ¶

Hooks and events ¶

Event ¶

Tracer ¶

Miscellaneous ¶

Cache ¶

Exceptions ¶

Info ¶

Testing ¶

Timezone ¶

URIs ¶

WSGI ¶

Storm

Navigation

Related Topics