model
=====

.. py:module:: model


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/model/depot/index
   /autoapi/model/general/index
   /autoapi/model/network/index
   /autoapi/model/schedule/index
   /autoapi/model/util/index


Exceptions
----------

.. autoapisummary::

   model.ConsistencyWarning


Classes
-------

.. autoapisummary::

   model.Base
   model.TimeStampWithTz


Functions
---------

.. autoapisummary::

   model.create_engine
   model.setup_database


Package Contents
----------------

.. py:function:: 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.

   :param url: The database URL to connect to.
   :param kwargs: Additional keyword arguments for the engine creation.
   :return: A SQLAlchemy engine instance.


.. py:class:: Base

   Bases: :py:obj:`sqlalchemy.orm.DeclarativeBase`


.. py:class:: TimeStampWithTz

   Bases: :py:obj:`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))


   .. py:attribute:: impl


   .. py:method:: 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



   .. py:method:: 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



.. py:exception:: ConsistencyWarning

   Bases: :py:obj:`UserWarning`


   A warning that is raised when a consistency check fails.


.. py:function:: 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

   :param engine: The engine to use to connect to the database.

   :return: None