API Reference

The BaseModel class

class alchemical.core.BaseModel

This is the base model class from where all models inherit from.

classmethod select()

Create a select statement on this model.

Example:

User.select().order_by(User.username)

classmethod update()

Create an update statement on this model.

Example:

User.select().order_by(User.username)

classmethod delete()

Create a delete statement on this model.

Example:

User.delete().where(User.username == 'susan')

The Alchemical class

class alchemical.Alchemical(url=None, binds=None, engine_options=None, session_options=None, model_class=None, naming_convention=None)

Create a database instance.

Parameters:

• url – the database URL.

• binds – a dictionary with additional databases to manage with this instance. The keys are the names, and the values are the database URLs. A model is then assigned to a specific bind with the __bind_key__ class attribute.

• engine_options – a dictionary with additional engine options to pass to SQLAlchemy.

• session_options – a dictionary with additional session options to use when creating sessions.

• model_class – a custom declarative base class to use instead of the default one. This class, extended with Alchemical functionality, can be accessed as db.Model.

• naming_convention – a dictionary with naming conventions to pass to SQLAlchemy. The naming convention recommended in the SQLAlchemy documentation is used by default. Pass an empty dictionary to disable naming conventions.

The database instances can be initialized in two phases, in which case the Alchemical.initialize() method must be called later to complete the initialization. Note that the model_class and naming_convention arguments can only be passed in this first phase, while the remaining arguments can be passed in either phase.

create_all()

Create the database tables.

Only tables that do not already exist are created. Existing tables are not modified.

drop_all()

Drop all the database tables.

Note that this is a destructive operation; data stored in the database will be deleted when this method is called.

property Session

Return a database session.

The recommended way to use the SQLAlchemy session is as a context manager:

with db.Session() as session:
    # work with the session here

The context manager automatically closes the session at the end. A session can also be created without a context manager:

session = db.Session()

When the session is created in this way, session.close() must be called when the session isn’t needed anymore.

begin()

Context manager for a database transaction.

Upon entering the context manager block, a new session is created and a transaction started on it. If any errors occur inside the context manager block, then the transation is rolled back. If no errors occur, the transaction is committed. In both cases the session is then closed.

Example usage:

with db.begin() as session:
    # work with the session here
    # a commit (on success) or rollback (on error) is automatic

The aio.Alchemical class

class alchemical.aio.Alchemical(url=None, binds=None, engine_options=None, session_options=None, model_class=None, naming_convention=None)

Create a database instance.

Parameters:

• url – the database URL.

• binds – a dictionary with additional databases to manage with this instance. The keys are the names, and the values are the database URLs. A model is then assigned to a specific bind with the __bind_key__ class attribute.

• engine_options – a dictionary with additional engine options to pass to SQLAlchemy.

• session_options – a dictionary with additional session options to use when creating sessions.

• model_class – a custom declarative base class to use instead of the default one. This class, extended with Alchemical functionality, can be accessed as db.Model.

• naming_convention – a dictionary with naming conventions to pass to SQLAlchemy. The naming convention recommended in the SQLAlchemy documentation is used by default. Pass an empty dictionary to disable naming conventions.

The database instances can be initialized in two phases, in which case the Alchemical.initialize() method must be called later to complete the initialization. Note that the model_class and naming_convention arguments can only be passed in this first phase, while the remaining arguments can be passed in either phase.

initialize(url=None, binds=None, engine_options=None, session_options=None)

Initialize the database instance.

Parameters:

• url – the database URL.

• binds – a dictionary with additional databases to manage with this instance. The keys are the names, and the values are the database URLs. A model is then assigned to a specific bind with the __bind_key__ class attribute.

• engine_options – a dictionary with additional engine options to pass to SQLAlchemy.

• session_options – a dictionary with additional session options to use when creating sessions.

This method must be called explicitly to complete the initialization of the instance the two-phase initialization method is used.

async create_all()

Create the database tables.

Only tables that do not already exist are created. Existing tables are not modified.

Note: this method is a coroutine.

async drop_all()

Drop all the database tables.

Note that this is a destructive operation; data stored in the database will be deleted when this method is called.

Note: this method is a coroutine.

property Session

Return a database session.

The recommended way to use the SQLAlchemy session is as a context manager:

async with db.Session() as session:
    # work with the session here

The context manager automatically closes the session at the end. A session can also be created without a context manager:

session = db.Session()

When the session is created in this way, await session.close() must be called when the session isn’t needed anymore.

begin()

Context manager for a database transaction.

Upon entering the context manager block, a new session is created and a transaction started on it. If any errors occur inside the context manager block, then the transaction is rolled back. If no errors occur, the transaction is committed. In both cases the session is then closed.

Example usage:

async with db.begin() as session:
    # work with the session here
    # a commit (on success) or rollback (on error) is automatic

async run_sync(f, *args, **kwargs)

Run a function using a synchronous version of this object.

This method can be used to start a synchronous function under the SQLALchemy sync/async compatibility layer based on greenlets. The function receives a sync version of the Alchemical object as first argument.

Applications would not normally need to use this method directly, as it is used internally to support some operations that do not currently have an awaitable interface. For more information, search for run_sync in the SQLAlchemy documentation.

Note: this method is a coroutine.

is_async()

Return True if this database instance is asynchronous.

get_engine(bind=None)

Return the SQLAlchemy engine object.

Parameters:

bind – when binds are used, this argument selects which of the binds to return an engine for.

The flask.Alchemical class