API Reference

mortar_rdb

mortar_rdb.declarative_base(**kw)

Return a Base as would be returned by declarative_base().

Only one Base will exist for each combination of parameters that this function is called with. If it is called with the same combination of parameters more than once, subsequent calls will return the existing Base.

This method should be used so that even if more than one package used by a project defines models, they will all end up in the same MetaData instance and all have the same declarative registry.

mortar_rdb.drop_tables(engine)

Drop all the tables in the database attached to by the supplied engine.

As many foreign key constraints as possible will be dropped first making this quite brutal!

mortar_rdb.get_session(name='')

Return a Session instance from the current registry as registered with the supplied name.

mortar_rdb.register_session(url=None, name='', engine=None, echo=None, transactional=True, scoped=True, extension=None, twophase=True)

Create a Session class and register it for later use.

Generally, you’ll only need to pass in a SQLAlchemy connection URL. If you want to register multiple sessions for a particular application, then you should name them. If you want to provide specific engine configuration, then you can pass in an Engine instance. In that case, you must not pass in a URL.

Parameters:

• echo – If True, then all SQL will be echoed to the python logging framework. This option cannot be specified if you pass in an engine.
• scoped – If True, then get_session() will return a distinct session for each thread that it is called from but, within that thread, it will always return the same session. If it is False, every call to get_session() will return a new session.
• transactional –

  If True, a SQLAlchemy extension will be used that that enables the transaction package to manage the lifecycle of the SQLAlchemy session (eg: begin()/commit()/rollback()). This can only be done when scoped sessions are used.

  If False, you will need to make sure you call begin()/commit()/rollback(), as appropriate, yourself.

• extension – An optional SessionExtension or sequence of SessionExtension objects to be used with the session that is registered.
• twophase – By default two-phase transactions are used where supported by the underlying database. Where this causes problems, single-phase transactions can be used for all engines by passing this parameter as False.

mortar_rdb.controlled

class mortar_rdb.controlled.Config(*sources)

A configuration for a particular database to allow control of the schema of that database.

Parameters:sources – The Source instances from which to create this configuration.

class mortar_rdb.controlled.Scripts(url, config, failsafe)

A command-line harness for performing schema control functions on a database. You should instantiate this in a small python script and call it when the script is run as a command, eg:

from mortar_rdb.controlled import Scripts
from sample.model import config

scripts = Scripts('sqlite://', config, True)

if __name__=='__main__':
    script()

Writing the script in this style also allows scripts to be used as a :mod:setuptools entry point.

Parameters:

• url – The SQLAlchemy url to connect to the database to be managed. If this isn’t known at the time when this class is instantiated, then use None.
• config – A Config instance describing the schema of the database to be managed.
• failsafe – A boolean value that should be True if it’s okay for the database being managed to have all its tables dropped. For obvious reasons, this should be False when managing your production database.

create()

Create all the tables in the configuration in the database

drop()

Drop all tables in the database

class mortar_rdb.controlled.Source(*tables)

A collection of tables that should have their versioning managed together. This usually means they originate from one package.

Parameters:tables – A sequence of Table objects that contain all the tables that will be managed by the repository in this Source.

mortar_rdb.controlled.scan(package, tables=())

Scan a package or module and return a Source containing the tables from any declaratively mapped models found, any Table objects explicitly passed in and the sqlalchemy-migrate repository contained within the package.

Note

While the package parameter is passed as a string, this will be resolved into a module or package object. It is not a distribution name, although the two are often very similar.

Parameters:

• package – A dotted path to the package to be scanned for Table objects.
• tables – A sequence of Table objects to be added to the returned Source. Any tables not created as part of declaratively mapping a class will need to be passed in using this sequence as scan() cannot sensibly scan for these objects.

mortar_rdb.testing

Helpers for unit testing when using mortar_rdb

class mortar_rdb.testing.TestingBase

This is a helper class that can either be used to make declarative_base() return a new, empty Base for testing purposes.

If writing a suite of unit tests, this can be done as follows:

from mortar_rdb.testing import TestingBase
from unittest import TestCase

class YourTestCase(TestCase):

    def setUp(self):
        self.tb = TestingBase()

    def tearDown(self):
        self.tb.restore()

If you need a fresh Base for a short section of Python code, TestingBase can also be used as a context manager:

with TestingBase():
    base = declarative_base()
    # your test code here

mortar_rdb.testing.register_session(url=None, name='', engine=None, echo=False, transactional=True, scoped=True, config=None, metadata=None, extension=None)

This will create a Session class for testing purposes and register it for later use.

The calling parameters mirror those of mortar_rdb.register_session() but if neither url nor engine is specified then:

• The environment will be consulted for a variable called DB_URL. If found, that will be used for the url parameter.
• If url is still None, an implicit url of sqlite:// will be used.

If a Config is passed in then, once any existing content in the database has been removed, any tables controlled by that config will be created.

If a MetaData instance is passed in, then all tables within it will be created.

Unlike the non-testing register_session, this will also return an instance of the registered session.

Warning

No matter where the url or engine come from, the entire contents of the database they point at will be destroyed!

mortar_rdb.sequence

Database independent provision of non-repeating, always-incrementing sequences of integers.

mortar_rdb.sequence.get_sequence(name)

Obtain a previously registered sequence. Once obtained, the next() method should be called as many times as necessary.

Each call will return one system-wide unique integer that will be greater than any integers previously returned.

mortar_rdb.sequence.register_sequence(name, session, impl=<class 'mortar_rdb.sequence.generic.SequenceImplementation'>)

Register a sequence for later user.

Parameters:

• name – A string containing the name of the sequence.
• session – A Session instance that will be used to set up anything needed in the database for the sequence to be functional. It will not be retained and may be closed and discarded once this function has returned.
• impl – A class whose instances implement ISequence. Defaults to mortar_rdb.sequence.generic.SequenceImplementation.

class mortar_rdb.sequence.generic.SequenceImplementation(name, session)

A sequence implementation that uses a table in the database with one row for each named sequence.

next(session)

Return the next integer in the sequence using the Session provided.

Warning

The current implementation will lock the row (or table, depending on which database you use) for the sequence in question. This could conceivably cause contention problems if more than one connection is trying to generate integers from the sequence at one time.

mortar_rdb.interfaces

Internal interface definitions. Unless you’re doing something pretty special, you don’t need to know about these.

interface mortar_rdb.interfaces.ISession

A marker interface for SQLAlchemy Sessions. This is so that we can register factories that return them.

interface mortar_rdb.interfaces.ISequence

An interface for sequence utility impementations. A sequence is a non-repeating, always-incrementing sequence of integers.

Implementations of this interface will be instantiated once and then have their next() method called often.