API

Locals

This is the complete list of classes, functions and methods exported from storm.locals:

• storm.base.Storm

• storm.database.create_database()

• storm.exceptions.StormError

• storm.expr.And

• storm.expr.Asc

• storm.expr.Count

• storm.expr.Delete

• storm.expr.Desc

• storm.expr.In

• storm.expr.Insert

• storm.expr.Join

• storm.expr.Like

• storm.expr.Max

• storm.expr.Min

• storm.expr.Not

• storm.expr.Or

• storm.expr.SQL

• storm.expr.Select

• storm.expr.Update

• storm.info.ClassAlias

• storm.properties.Bool

• storm.properties.DateTime

• storm.properties.Date

• storm.properties.Decimal

• storm.properties.Enum

• storm.properties.Float

• storm.properties.Int

• storm.properties.JSON

• storm.properties.List

• storm.properties.RawStr

• storm.properties.TimeDelta

• storm.properties.Time

• storm.properties.UUID

• storm.store.AutoReload

• storm.store.Store

• storm.xid.Xid

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.

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.

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.

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.

begin(xid)

Start a new two-phase transaction.

Parameters

xid – A Xid instance holding identification data for the new transaction.

block_access()

Block access to the underlying database connection.

block_implicit_flushes()

Block implicit flushes from operations like execute().

close()

Close the connection.

commit()

Commit all changes to the database.

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

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

Execute a basic query.

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

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.

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.

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.

get_database()

Return this Store’s Database object.

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.

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.

prepare()

Prepare a two-phase transaction for the final commit.

Note

It must be call inside a two-phase transaction started with begin().

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.

remove(obj)

Remove the given object from the store.

The associated row will be deleted from the database.

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.

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.

rollback()

Roll back all outstanding changes, reverting to database state.

unblock_access()

Unblock access to the underlying database connection.

unblock_implicit_flushes()

Unblock implicit flushes from operations like execute().

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.

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.

any()

avg(column)

cached()

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

copy()

count(expr=Undef, distinct=False)

difference(other)

find(*args, **kwargs)

first()

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.

group_by(*expr)

intersection(other)

is_empty()

last()

max(column)

min(column)

one()

order_by(*args)

remove()

set(*args, **kwargs)

sum(column)

union(other)

values(*columns)

Columns and types

Properties

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

Bases: object

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

Bases: storm.properties.Property

variable_class = None

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

Bases: storm.properties.SimpleProperty

variable_class

alias of storm.variables.BoolVariable

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

Bases: storm.properties.SimpleProperty

variable_class

alias of storm.variables.IntVariable

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

Bases: storm.properties.SimpleProperty

variable_class

alias of storm.variables.FloatVariable

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

Bases: storm.properties.SimpleProperty

variable_class

alias of storm.variables.DecimalVariable

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

Bases: storm.properties.SimpleProperty

variable_class

alias of storm.variables.RawStrVariable

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

Bases: storm.properties.SimpleProperty

variable_class

alias of storm.variables.UnicodeVariable

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

Bases: storm.properties.SimpleProperty

variable_class

alias of storm.variables.DateTimeVariable

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

Bases: storm.properties.SimpleProperty

variable_class

alias of storm.variables.DateVariable

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

Bases: storm.properties.SimpleProperty

variable_class

alias of storm.variables.TimeVariable

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

Bases: storm.properties.SimpleProperty

variable_class

alias of storm.variables.TimeDeltaVariable

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

Bases: storm.properties.SimpleProperty

variable_class

alias of storm.variables.UUIDVariable

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.JSON(name=None, primary=False, **kwargs)

Bases: storm.properties.SimpleProperty

variable_class

alias of storm.variables.JSONVariable

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

Bases: storm.properties.SimpleProperty

variable_class

alias of storm.variables.ListVariable

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.

add_class(cls)

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

This method may also be used as a class decorator.

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.

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.

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.

class storm.references.ReferenceSet(local_key1, remote_key1, remote_key2=None, local_key2=None, order_by=None)

Bases: object

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.

property variable_factory

Variables

storm.variables.VariableFactory

alias of functools.partial

class storm.variables.Variable

Bases: object

checkpoint()

column

copy()

delete()

event

get()

get_lazy()

get_state()

has_changed()

is_defined()

parse_get()

parse_set()

set()

set_state()

class storm.variables.LazyValue

Bases: object

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

class storm.variables.BoolVariable

Bases: storm.variables.Variable

parse_set(value, from_db)

class storm.variables.IntVariable

Bases: storm.variables.Variable

parse_set(value, from_db)

class storm.variables.FloatVariable

Bases: storm.variables.Variable

parse_set(value, from_db)

class storm.variables.DecimalVariable

Bases: storm.variables.Variable

static parse_get(value, to_db)

static parse_set(value, from_db)

class storm.variables.RawStrVariable

Bases: storm.variables.Variable

parse_set(value, from_db)

class storm.variables.UnicodeVariable

Bases: storm.variables.Variable

parse_set(value, from_db)

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

Bases: storm.variables.Variable

parse_set(value, from_db)

class storm.variables.DateVariable

Bases: storm.variables.Variable

parse_set(value, from_db)

class storm.variables.TimeVariable

Bases: storm.variables.Variable

parse_set(value, from_db)

class storm.variables.TimeDeltaVariable

Bases: storm.variables.Variable

parse_set(value, from_db)

class storm.variables.EnumVariable(get_map, set_map, *args, **kwargs)

Bases: storm.variables.Variable

parse_get(value, to_db)

parse_set(value, from_db)

class storm.variables.UUIDVariable

Bases: storm.variables.Variable

parse_get(value, to_db)

parse_set(value, from_db)

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

Bases: storm.variables.EncodedValueVariable

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

Bases: storm.variables.MutableValueVariable

get_state()

parse_get(value, to_db)

parse_set(value, from_db)

set_state(state)

Expressions

class storm.expr.Add(*exprs)

Bases: storm.expr.CompoundOper

oper = '+'

class storm.expr.Alias(expr, name=Undef)

Bases: storm.expr.ComparableExpr

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

auto_counter = 0

expr

name

class storm.expr.And(*exprs)

Bases: storm.expr.CompoundOper

oper = ' AND '

class storm.expr.Asc(expr)

Bases: storm.expr.SuffixExpr

suffix = 'ASC'

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.

expr

replace

tables

class storm.expr.Avg(*args)

Bases: storm.expr.NamedFunc

name = 'AVG'

class storm.expr.BinaryExpr(expr1, expr2)

Bases: storm.expr.ComparableExpr

expr1

expr2

class storm.expr.BinaryOper(expr1, expr2)

Bases: storm.expr.BinaryExpr

oper = ' (unknown) '

class storm.expr.Cast(column, type)

Bases: storm.expr.FuncExpr

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

column

name = 'CAST'

type

class storm.expr.Coalesce(*args)

Bases: storm.expr.NamedFunc

name = 'COALESCE'

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.

compile_cache

compile_id

name

primary

table

variable_factory

class storm.expr.Comparable

Bases: object

contains_string(substring)

endswith(suffix)

is_in(others)

like(other, escape=Undef, case_sensitive=None)

lower()

startswith(prefix)

upper()

class storm.expr.ComparableExpr

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

class storm.expr.CompilePython

Bases: storm.variables.Compile

get_matcher(expr)

class storm.expr.CompoundExpr(*exprs)

Bases: storm.expr.ComparableExpr

exprs

class storm.expr.CompoundOper(*exprs)

Bases: storm.expr.CompoundExpr

oper = ' (unknown) '

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.Count(column=Undef, distinct=False)

Bases: storm.expr.FuncExpr

column

distinct

name = 'COUNT'

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

Bases: storm.expr.Expr

default_table

table

where

class storm.expr.Desc(expr)

Bases: storm.expr.SuffixExpr

suffix = 'DESC'

class storm.expr.Distinct(expr)

Bases: storm.expr.Expr

Add the ‘DISTINCT’ prefix to an expression.

e

expr

p

r

x

class storm.expr.Div(expr1, expr2)

Bases: storm.expr.NonAssocBinaryOper

oper = '/'

class storm.expr.Eq(expr1, expr2)

Bases: storm.expr.BinaryOper

oper = ' = '

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

Bases: storm.expr.SetExpr

oper = ' EXCEPT '

class storm.expr.Exists(expr)

Bases: storm.expr.PrefixExpr

prefix = 'EXISTS'

class storm.expr.Expr

Bases: storm.variables.LazyValue

class storm.expr.FromExpr

Bases: storm.expr.Expr

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

Bases: storm.expr.FuncExpr

args

name

class storm.expr.FuncExpr

Bases: storm.expr.ComparableExpr

name = '(unknown)'

class storm.expr.Ge(expr1, expr2)

Bases: storm.expr.BinaryOper

oper = ' >= '

class storm.expr.Gt(expr1, expr2)

Bases: storm.expr.BinaryOper

oper = ' > '

class storm.expr.In(expr1, expr2)

Bases: storm.expr.BinaryOper

oper = ' IN '

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.

default_table

map

primary_columns

primary_variables

table

values

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

Bases: storm.expr.SetExpr

oper = ' INTERSECT '

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

Bases: storm.expr.JoinExpr

oper = 'JOIN'

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

Bases: storm.expr.FromExpr

left

on

oper = '(unknown)'

right

class storm.expr.LShift(expr1, expr2)

Bases: storm.expr.BinaryOper

oper = '<<'

class storm.expr.Le(expr1, expr2)

Bases: storm.expr.BinaryOper

oper = ' <= '

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

Bases: storm.expr.JoinExpr

oper = 'LEFT JOIN'

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

Bases: storm.expr.BinaryOper

case_sensitive

escape

oper = ' LIKE '

class storm.expr.Lower(*args)

Bases: storm.expr.NamedFunc

name = 'LOWER'

class storm.expr.Lt(expr1, expr2)

Bases: storm.expr.BinaryOper

oper = ' < '

class storm.expr.Max(*args)

Bases: storm.expr.NamedFunc

name = 'MAX'

class storm.expr.Min(*args)

Bases: storm.expr.NamedFunc

name = 'MIN'

class storm.expr.Mod(expr1, expr2)

Bases: storm.expr.NonAssocBinaryOper

oper = '%'

class storm.expr.Mul(*exprs)

Bases: storm.expr.CompoundOper

oper = '*'

class storm.expr.NamedFunc(*args)

Bases: storm.expr.FuncExpr

args

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

Bases: storm.expr.JoinExpr

oper = 'NATURAL JOIN'

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

Bases: storm.expr.JoinExpr

oper = 'NATURAL LEFT JOIN'

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

Bases: storm.expr.JoinExpr

oper = 'NATURAL RIGHT JOIN'

class storm.expr.Ne(expr1, expr2)

Bases: storm.expr.BinaryOper

oper = ' != '

class storm.expr.Neg(expr)

Bases: storm.expr.PrefixExpr

prefix = '-'

class storm.expr.NonAssocBinaryOper(expr1, expr2)

Bases: storm.expr.BinaryOper

oper = ' (unknown) '

class storm.expr.Not(expr)

Bases: storm.expr.PrefixExpr

prefix = 'NOT'

class storm.expr.Or(*exprs)

Bases: storm.expr.CompoundOper

oper = ' OR '

class storm.expr.PrefixExpr(expr)

Bases: storm.expr.Expr

expr

prefix = '(unknown)'

class storm.expr.RShift(expr1, expr2)

Bases: storm.expr.BinaryOper

oper = '>>'

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

Bases: storm.expr.JoinExpr

oper = 'RIGHT JOIN'

class storm.expr.Row(*args)

Bases: storm.expr.NamedFunc

name = 'ROW'

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

Bases: storm.expr.ComparableExpr

expr

params

tables

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.

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

columns

default_tables

distinct

group_by

having

limit

offset

order_by

tables

where

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"))

name

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

Bases: storm.expr.Expr

all

exprs

limit

offset

oper = ' (unknown) '

order_by

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.

pop()

Revert the topmost push.

push(attr, new_value=Undef)

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

class storm.expr.Sub(expr1, expr2)

Bases: storm.expr.NonAssocBinaryOper

oper = '-'

class storm.expr.SuffixExpr(expr)

Bases: storm.expr.Expr

expr

suffix = '(unknown)'

class storm.expr.Sum(*args)

Bases: storm.expr.NamedFunc

name = 'SUM'

class storm.expr.Table(name)

Bases: storm.expr.FromExpr

compile_cache

compile_id

name

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

Bases: storm.expr.SetExpr

oper = ' UNION '

class storm.expr.Update(map, where=Undef, table=Undef, default_table=Undef, primary_columns=Undef)

Bases: storm.expr.Expr

default_table

map

primary_columns

table

where

class storm.expr.Upper(*args)

Bases: storm.expr.NamedFunc

name = 'UPPER'

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.

storm.expr.compare_columns(columns, values)

storm.expr.compile_alias(compile, alias, state)

storm.expr.compile_auto_tables(compile, expr, state)

storm.expr.compile_binary_oper(compile, expr, state)

storm.expr.compile_bool(compile, expr, state)

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

Compile Cast expressions.

storm.expr.compile_column(compile, column, state)

storm.expr.compile_compound_oper(compile, expr, state)

storm.expr.compile_count(compile, count, state)

storm.expr.compile_date(compile, expr, state)

storm.expr.compile_datetime(compile, expr, state)

storm.expr.compile_decimal(compile, expr, state)

storm.expr.compile_delete(compile, delete, state)

storm.expr.compile_distinct(compile, distinct, state)

storm.expr.compile_eq(compile, eq, state)

storm.expr.compile_float(compile, expr, state)

storm.expr.compile_func(compile, func, state)

storm.expr.compile_in(compile, expr, state)

storm.expr.compile_insert(compile, insert, state)

storm.expr.compile_int(compile, expr, state)

storm.expr.compile_join(compile, join, state)

storm.expr.compile_like(compile, like, state, oper=None)

storm.expr.compile_ne(compile, ne, state)

storm.expr.compile_neg_expr(compile, expr, state)

storm.expr.compile_non_assoc_binary_oper(compile, expr, state)

storm.expr.compile_none(compile, expr, state)

storm.expr.compile_prefix_expr(compile, expr, state)

storm.expr.compile_python_bool_and_dates(compile, expr, state)

storm.expr.compile_python_builtin(compile, expr, state)

storm.expr.compile_python_column(compile, column, state)

storm.expr.compile_python_sql_token(compile, expr, state)

storm.expr.compile_python_unsupported(compile, expr, state)

storm.expr.compile_python_variable(compile, variable, state)

storm.expr.compile_select(compile, select, state)

storm.expr.compile_set_expr(compile, expr, state)

storm.expr.compile_sql(compile, expr, state)

storm.expr.compile_sql_token(compile, expr, state)

storm.expr.compile_str(compile, expr, state)

storm.expr.compile_suffix_expr(compile, expr, state)

storm.expr.compile_table(compile, table, state)

storm.expr.compile_time(compile, expr, state)

storm.expr.compile_timedelta(compile, expr, state)

storm.expr.compile_unicode(compile, expr, state)

storm.expr.compile_update(compile, update, state)

storm.expr.compile_variable(compile, variable, state)

storm.expr.has_tables(state, expr)

storm.expr.is_safe_token()

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

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

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.

connection_factory

alias of Connection

get_uri()

Return the URI object this database was created with.

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.

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.

begin(xid)

Begin a two-phase transaction.

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.

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.

close()

Close the connection if it is not already closed.

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.

compile = <storm.variables.Compile object>

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.

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.

param_mark = '?'

prepare()

Run the prepare phase of a two-phase transaction.

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.

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.

recover()

Return a list of Xid representing pending transactions.

result_factory

alias of Result

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 Variable in the parameter list, and passes through all other values untouched.

unblock_access()

Unblock access to the connection.

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.

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.

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.

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

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.

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

static set_variable(variable, value)

Set the given variable’s value from the database.

storm.database.convert_param_marks(statement, from_param_mark, to_param_mark)

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.

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.

PostgreSQL

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.JSON(name=None, primary=False, **kwargs)

Bases: storm.properties.SimpleProperty

variable_class

alias of JSONVariable

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

Bases: storm.expr.BinaryOper

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

oper = '->'

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.

oper = '->>'

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

Bases: storm.variables.JSONVariable

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.

class storm.databases.postgres.PostgresConnection(database, event=None)

Bases: storm.database.Connection

compile = <storm.variables.Compile object>

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.

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.

param_mark = '%s'

result_factory

alias of PostgresResult

to_database(params)

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

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

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

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"')

storm.databases.postgres.compile_insert_postgres(compile, insert, state)

storm.databases.postgres.compile_like_postgres(compile, like, state)

storm.databases.postgres.compile_list_variable(compile, list_variable, state)

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

storm.databases.postgres.compile_sequence_postgres(compile, sequence, state)

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

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

storm.databases.postgres.create_from_uri

alias of storm.databases.postgres.Postgres

class storm.databases.postgres.currval(column)

Bases: storm.expr.FuncExpr

name = 'currval'

storm.databases.postgres.make_dsn(uri)

Convert a URI object to a PostgreSQL DSN string.

SQLite

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.

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

Bases: storm.database.Connection

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.

compile = <storm.variables.Compile object>

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.

result_factory

alias of SQLiteResult

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.

static to_database(params)

Like Connection.to_database, but this also converts instances of datetime types to strings, and strings instances to buffer instances.

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

Bases: storm.database.Result

static from_database(row)

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

If there are anny buffer instances in the row, convert them to strings.

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.

storm.databases.sqlite.compile_insert_sqlite(compile, insert, state)

storm.databases.sqlite.compile_select_sqlite(compile, select, state)

storm.databases.sqlite.create_from_uri

alias of storm.databases.sqlite.SQLite

Xid

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

Bases: object

emit()

hook()

unhook()

Tracer

class storm.tracer.BaseStatementTracer

Bases: object

Storm tracer base class that does query interpolation.

connection_raw_execute(connection, raw_cursor, statement, params)

class storm.tracer.DebugTracer(stream=None)

Bases: object

connection_commit(connection, xid=None)

connection_raw_execute(connection, raw_cursor, statement, params)

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

connection_raw_execute_success(connection, raw_cursor, statement, params)

connection_rollback(connection, xid=None)

storm.tracer.debug(flag, stream=None)

storm.tracer.get_tracers()

storm.tracer.install_tracer(tracer)

storm.tracer.remove_all_tracers()

storm.tracer.remove_tracer(tracer)

storm.tracer.remove_tracer_type(tracer_type)

storm.tracer.trace(name, *args, **kwargs)

Miscellaneous

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.

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_info added to it (where N is the cache size).

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

clear()

Clear the entire cache at once.

get_cached()

Return an ordered list of the currently cached obj_info.

The most recently added objects come first in the list.

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_info may be dropped from the cache to respect the new size.

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.

add(obj_info)

See storm.store.Cache.add.

clear()

See storm.store.Cache.clear.

Clears both the primary and the secondary caches.

get_cached()

See storm.store.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.

remove(obj_info)

See storm.store.Cache.remove.

set_size(size)

See storm.store.Cache.set_size.

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

Exceptions

exception storm.exceptions.ClassInfoError

Bases: storm.exceptions.StormError

exception storm.exceptions.ClosedError

Bases: storm.exceptions.StormError

exception storm.exceptions.CompileError

Bases: storm.exceptions.StormError

exception storm.exceptions.ConnectionBlockedError

Bases: storm.exceptions.StormError

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

exception storm.exceptions.DataError

Bases: storm.exceptions.DatabaseError

exception storm.exceptions.DatabaseError

Bases: storm.exceptions.Error

exception storm.exceptions.DatabaseModuleError

Bases: storm.exceptions.StormError

exception storm.exceptions.DisconnectionError

Bases: storm.exceptions.OperationalError

exception storm.exceptions.Error

Bases: storm.exceptions.StormError

exception storm.exceptions.ExprError

Bases: storm.exceptions.StormError

exception storm.exceptions.FeatureError

Bases: storm.exceptions.StormError

exception storm.exceptions.IntegrityError

Bases: storm.exceptions.DatabaseError

exception storm.exceptions.InterfaceError

Bases: storm.exceptions.Error

exception storm.exceptions.InternalError

Bases: storm.exceptions.DatabaseError

exception storm.exceptions.LostObjectError

Bases: storm.exceptions.StoreError

exception storm.exceptions.NoStoreError

Bases: storm.exceptions.StormError

exception storm.exceptions.NoTableError

Bases: storm.exceptions.CompileError

exception storm.exceptions.NoneError

Bases: storm.exceptions.StormError

exception storm.exceptions.NotFlushedError

Bases: storm.exceptions.StoreError

exception storm.exceptions.NotOneError

Bases: storm.exceptions.StoreError

exception storm.exceptions.NotSupportedError

Bases: storm.exceptions.DatabaseError

exception storm.exceptions.OperationalError

Bases: storm.exceptions.DatabaseError

exception storm.exceptions.OrderLoopError

Bases: storm.exceptions.StoreError

exception storm.exceptions.ProgrammingError

Bases: storm.exceptions.DatabaseError

exception storm.exceptions.PropertyPathError

Bases: storm.exceptions.StormError

exception storm.exceptions.StoreError

Bases: storm.exceptions.StormError

exception storm.exceptions.StormError

Bases: Exception

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

Bases: storm.exceptions.StormError

Raised by timeout tracers when remining time is over.

exception storm.exceptions.URIError

Bases: storm.exceptions.StormError

exception storm.exceptions.UnorderedError

Bases: storm.exceptions.StoreError

exception storm.exceptions.Warning

Bases: storm.exceptions.StormError

exception storm.exceptions.WrongStoreError

Bases: storm.exceptions.StoreError

storm.exceptions.install_exceptions(module)

Info

storm.info.get_obj_info()

storm.info.set_obj_info(obj, obj_info)

storm.info.get_cls_info(cls)

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

Bases: dict

checkpoint()

cls_info

event

get_obj()

primary_vars

set_obj()

variables

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.

alias_count = 0

Timezone

Copyright (c) 2003-2005 Gustavo Niemeyer <gustavo@niemeyer.net>

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

class storm.tz.tzutc

Bases: datetime.tzinfo

dst(dt)

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

tzname(dt)

datetime -> string name of time zone.

utcoffset(dt)

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

class storm.tz.tzoffset(name, offset)

Bases: datetime.tzinfo

dst(dt)

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

tzname(dt)

datetime -> string name of time zone.

utcoffset(dt)

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

class storm.tz.tzlocal

Bases: datetime.tzinfo

dst(dt)

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

tzname(dt)

datetime -> string name of time zone.

utcoffset(dt)

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

class storm.tz.tzfile(fileobj)

Bases: datetime.tzinfo

dst(dt)

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

tzname(dt)

datetime -> string name of time zone.

utcoffset(dt)

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

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

Bases: datetime.tzinfo

dst(dt)

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

tzname(dt)

datetime -> string name of time zone.

utcoffset(dt)

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

class storm.tz.tzstr(s)

Bases: storm.tz.tzrange

class storm.tz.tzical(fileobj)

Bases: object

get(tzid=None)

keys()

storm.tz.gettz(name=None)

URI

class storm.uri.URI(uri_str)

Bases: object

copy()

database = None

host = None

password = None

port = None

username = None

storm.uri.escape(s, safe='')

storm.uri.unescape(s)