bag.sqlalchemy.tricks module

Functions that help define SQLAlchemy models.

class bag.sqlalchemy.tricks.AddressBase

Bases: object

Base class for addresses.

In subclasses you can just define __tablename__, id, the foreign key, and maybe indexes.

city = Column('city', Unicode(length=80), table=None, default=ColumnDefault(''))

country_code = Column('country_code', Unicode(length=2), table=None, default=ColumnDefault(''))

district = Column('district', Unicode(length=80), table=None, default=ColumnDefault(''))

postal_code = Column('postal_code', Unicode(length=16), table=None, default=ColumnDefault(''))

province = Column('province', Unicode(length=40), table=None, default=ColumnDefault(''))

street = Column('street', Unicode(length=160), table=None, default=ColumnDefault(''))

class bag.sqlalchemy.tricks.EmailParts

Bases: object

Mixin class that stores an email address in 2 columns.

One column contains the local part, another contains the domain. This makes it easy to find emails from the same domain.

Typical usage:

class Customer(SABase, EmailParts):
    __table_args__ = (UniqueConstraint('email_local', 'email_domain',
                      name='customer_email_key'), {})

email

Get or set the entire email, in Python or in the RDBMS.

email_domain = Column('email_domain', Unicode(length=255), table=None, nullable=False)

email_local = Column('email_local', Unicode(length=160), table=None, nullable=False)

gravatar_image(default='mm', size=80, cacheable=True)

Return the URL for the gravatar image for this email address.

Return type

str

set_email

Get or set the entire email, in Python or in the RDBMS.

class bag.sqlalchemy.tricks.ID

Bases: object

Mixin class that includes a primary key column “id”.

id = Column(None, Integer(), table=None, primary_key=True, nullable=False)

class bag.sqlalchemy.tricks.MinimalBase

Bases: object

Declarative base class that auto-generates __tablename__.

clone(values=None, pk='id', sas=None)

Return a clone of this model.

Optionally update some of its values. Optionally add the clone to the sas session. The name of the primary key column should be given as pk.

Although in general model methods should not use the session, the recursive nature of this one seems to require it.

update(adict, transient=False)

Merge dictionary into this entity.

Optionally check that the keys exist.

update_from_schema(schema, adict)

Validate adict against schema; return updated entity.

Validates the information in the dictionary adict against a Colander schema. If validation fails, colander.Invalid is raised. If happy, returns the updated model instance.

class bag.sqlalchemy.tricks.Names

Bases: object

Mixin class that includes 2 ways to handle a person’s names.

property display_name

property formal_name

full_name = Column(None, Unicode(length=120), table=None, nullable=False)

short_name = Column(None, Unicode(length=16), table=None, nullable=False)

class bag.sqlalchemy.tricks.SubtransactionTrick(engine, sessionmaker)

Bases: object

Encloses your code in a subtransaction. Good for writing tests.

Usage:

trick = SubtransactionTrick(my_engine, sessionmaker)
# Be sure to use the session provided as the ``sas`` variable:
my_session = trick.sas
# Finally, call ``close()`` to roll back the changes:
trick.close()

close()

Roll back everything that happened with the session.

…including calls to commit().

bag.sqlalchemy.tricks.col(attrib)

Return the column that stores an attrib of a model.

Given a sqlalchemy.orm.attributes.InstrumentedAttribute (type of the attributes of model classes), return the corresponding column. E.g.: col(User.email)

bag.sqlalchemy.tricks.commit_session_or_transaction(sas)

Not sure if using the transaction package or not? No problem.

Return type

None

bag.sqlalchemy.tricks.fk(attrib, nullable=False, index=True, primary_key=False, doc=None, ondelete='CASCADE')

Return a ForeignKey column while automatically setting the type.

bag.sqlalchemy.tricks.fk_rel(cls, attrib='id', nullable=False, index=True, primary_key=False, doc=None, ondelete='CASCADE', backref=None, order_by=None, lazy='select')

Return a ForeignKey column and a relationship.

Automatically sets the type of the foreign key.

Usage:

# A relationship in an Address model pointing to a parent Person:
person_id, person = fk_rel(Person, nullable=False,
    index=True, backref='addresses', ondelete='CASCADE')

A backref is created only if you provide its name in the argument. nullable and index are usually ommited, because these are the default values and they are good.

ondelete is “CASCADE” by default, but you can set it to “SET NULL”, or None which translates to “NO ACTION” (less interesting). If provided, order_by is used on the backref.

To load the backref greedily, use lazy='joined' as per http://docs.sqlalchemy.org/en/latest/orm/loading_relationships.html

You may also pass an attrib which is the column name for the foreign key.

bag.sqlalchemy.tricks.foreign_key_from_col(col)

bag.sqlalchemy.tricks.foreign_keys_in(cls)

bag.sqlalchemy.tricks.get_col(model, attribute_name)

Introspect the SQLAlchemy model; return the column object.

…for attribute_name. E.g.: get_col(User, 'email')

bag.sqlalchemy.tricks.get_length(model, field)

Return the length of column field of a SQLAlchemy model.

bag.sqlalchemy.tricks.is_model_class(val)

Return whether the parameter is a SQLAlchemy model class.

Return type

bool

bag.sqlalchemy.tricks.length(attrib)

Return the length of the attrib.

bag.sqlalchemy.tricks.many_to_many(Model1, Model2, pk1='id', pk2='id', metadata=None, backref=None)

Easily set up a many-to-many relationship between 2 existing models.

Return an association table and the relationship itself.

Usage:

customer_user, Customer.users = many_to_many(Customer, User,

pk2=’__id__’)

bag.sqlalchemy.tricks.model_property_names(cls, whitelist=None, blacklist=None, include_relationships=True)

Return the property names in the passed class, maybe filtered.

bag.sqlalchemy.tricks.models_and_tables_in(arg)

Return 2 lists containing the model classes and tables in arg.

arg may be a resource spec, a module or a dictionary:

models, tables = models_and_tables_in(globals())

Return type

Tuple[List, List]

bag.sqlalchemy.tricks.now_column(nullable=False, **k)

Return a DateTime column that defaults to utcnow.

Return type

Column

bag.sqlalchemy.tricks.persistent_attribute_names_of(cls)

Return a list of the names of the persistent attributes of cls.

…except collections.

bag.sqlalchemy.tricks.pk(tablename)

Return a primary key column.

Return type

Column