API Reference

Mixins

class mortar_sqlalchemy.Common

This mixin provides a common set of functionality that is slightly opinionated.

__tablename__

The table name is, by default, the snake-case version of the class name.

__eq__(other) → bool

Instances of this class are considered equal if values of all the mapped attributes are equal. Relationships are excluded from this, but the attributes that are used to form them are included.

__hash__() → int

The Python identity of instances of this class is used as its hash.

__repr__() → str

The repr() of instances of this class shows the values of all mapped attributes.

__str__() → str

The repr() of instances of this class shows the values of all mapped attributes.

class mortar_sqlalchemy.Temporal(**kw)

This mixin takes advantage of the Postgres range types in order to help store tabular information that changes over time.

__init__(period: Range[datetime] = None, value_from: datetime = None, value_to: datetime = None, ...)

This behaves the same as the normal constructor for a mapped object, but the period may alternatively be set by passing either or both of value_from and value_to.

key_columns: List[str]

The names of the columns that uniquely identify this row. In a non-temporal model, this would be the table’s primary key columns.

value_columns: List[str] = None

The columns to consider as “values” for this type of object, by default this is all columns that are not key_columns excluding id and period.

exclude_constraint: bool = True

Controls whether an exclude constraint is generated for this table, such that accidental overlaps of data are prevented.

id: Mapped[int] = Column(None, Integer(), table=None, primary_key=True, nullable=False)

The identifier for this row, which is an automatically generated integer that is unique throughout the whole table.

period: Mapped[Range[datetime]] = Column(None, TSRANGE(), table=None, nullable=False)

The Column specifying the period represented by this row. When being set, this should be a Range[datetime]. When being retrieved, it will likewise be a Range[datetime].

classmethod value_at(timestamp: datetime)

Returns a clause element that returns the current value

property value_from: datetime

A helper for retrieving or setting the lower bound of the period.

property value_to: datetime

A helper for retrieving or setting the upper bound of the period.

property value_tuple: tuple[..., ...]

Return the tuple representing the value of this object. By default, this is constructed from the attributes for all value_columns.

period_str() → str

Return a human-readable version of the period this object is valid.

property pretty_key: str

Return a human-readable version of the key for this object.

property pretty_value: str

Return a human-readable version of the value of this object.

overlaps(session)

Returns a query for all objects that overlap with this one. This means that they are valid for the an overlapping period and share the same key.

set_for_period(session, coalesce=True, set_logging=20, change_logging=30, unchanged_logging=10)

Set the temporal value using the values in self for the keys specified in self over the period specified in self.

self should not be attached to any session; the session to the database in which changes should be made should be passed as session.

It is assumed that the bounds of periods in the table are [).

If coalesce is True, then where values are the same over a period affected by this operation, they will be merged into one database row.

The case where period is open ended going forwards is special cased such that if it would replace future records that have a different value, it is instead closed at the point in time where the period of the earliest overlapping record ends.

Testing

mortar_sqlalchemy.testing.drop_tables(connection: Connection) → None

Drop all tables that can be reflected from the supplied connection.

mortar_sqlalchemy.testing.connection_in_transaction(url: str = None) → Iterable[Connection]

Create an engine using the supplied url or, in not specified, the contents of the DB_URL environment variable.

The context return is a Connection that is in an active transaction that will be rolled back when exiting the context.

mortar_sqlalchemy.testing.create_tables_and_session(connection: Connection, base: DeclarativeBase) → Iterable[Session]

Create all the tables found in the MetaData of the supplied DeclarativeBase.

The context returned is a Session joined to the transaction open on the supplied connection using the create_savepoint mode as described in the pattern Joining a Session into an External Transaction (such as for test suites).