model

Submodules

Exceptions

ConsistencyWarning

A warning that is raised when a consistency check fails.

Classes

Base

TimeStampWithTz

A SQLAlchemy TypeDecorator that handles timezone-aware datetime objects.

Functions

create_engine(url, **kwargs)

Create a SQLAlchemy engine with the given URL and options. This is an overridden version of the

setup_database(engine)

Use this method to create a new database from scratch.

Package Contents

model.create_engine(url, **kwargs)

Create a SQLAlchemy engine with the given URL and options. This is an overridden version of the sqlalchemy.create_engine function that loads the Spatialite extension if sqlite is used.

Parameters:

  • url (str) – The database URL to connect to.

  • kwargs – Additional keyword arguments for the engine creation.

Returns:

A SQLAlchemy engine instance.

Return type:

sqlalchemy.Engine

class model.Base

Bases: sqlalchemy.orm.DeclarativeBase

class model.TimeStampWithTz

Bases: sqlalchemy.types.TypeDecorator

A SQLAlchemy TypeDecorator that handles timezone-aware datetime objects.

This decorator enables storing timezone-aware datetime objects in databases that don’t support timezone information (like SQLite). It works by:

  1. On save: Converting timezone-aware datetimes to UTC and storing them as naive datetimes (without timezone info)

  2. On load: Treating stored naive datetimes as UTC and converting them to the system’s local timezone

Example:
class MyModel(Base):

__tablename__ = ‘my_table’ id = Column(Integer, primary_key=True) created_at = Column(TimeStampWithTz, nullable=False)

# Usage - always use timezone-aware datetimes model = MyModel(created_at=datetime.datetime.now(datetime.timezone.utc))

impl
process_bind_param(value, dialect)

Convert a timezone-aware datetime to a naive UTC datetime for storage.

Args:

value: A timezone-aware datetime object or None dialect: The database dialect (unused but required by interface)

Returns:

A naive datetime in UTC, or None if value is None

Raises:

ValueError: If value is not a datetime object or lacks timezone info

Parameters:

  • value (datetime.datetime | None)

  • dialect (Any)

Return type:

datetime.datetime | None

process_result_value(value, dialect)

Convert a naive UTC datetime from storage to a timezone-aware local datetime.

Args:

value: A naive datetime object (assumed UTC) or None dialect: The database dialect (unused but required by interface)

Returns:

A timezone-aware datetime in the local timezone, or None if value is None

Raises:

ValueError: If value is not a datetime object or has timezone info

Parameters:

  • value (datetime.datetime | None)

  • dialect (Any)

Return type:

datetime.datetime | None

exception model.ConsistencyWarning

Bases: UserWarning

A warning that is raised when a consistency check fails.

model.setup_database(engine)

Use this method to create a new database from scratch.

This method will create all tables and set the alembric version to the latest version, based on this howto: https://alembic.sqlalchemy.org/en/latest/cookbook.html#building-an-up-to-date-database-from-scratch

Parameters:

engine (sqlalchemy.Engine) – The engine to use to connect to the database.

Returns:

None

Return type:

None