diff --git a/docs/conf.py b/docs/conf.py index 5ce3986..eb61e17 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -9,7 +9,7 @@ from importlib.metadata import version as get_version project = "WuttJamaican" -copyright = "2023-2024, Lance Edgar" +copyright = "2023-2025, Lance Edgar" author = "Lance Edgar" release = get_version("WuttJamaican") diff --git a/docs/narr/db/app.rst b/docs/narr/db/app.rst index 1a45483..83d1ccc 100644 --- a/docs/narr/db/app.rst +++ b/docs/narr/db/app.rst @@ -181,6 +181,32 @@ config. But if the migration went okay then you now have a complete app database. +Notes on DateTime +~~~~~~~~~~~~~~~~~ + +Most data types are straightforward, but ``DateTime`` deserves some +explanation: + +All built-in model definitions use a "simple" +:class:`sqlalchemy:sqlalchemy.types.DateTime` column type, where +relevant +(e.g. :attr:`wuttjamaican.db.model.upgrades.Upgrade.created`). + +Logic expects all values for such columns to be naive +:class:`python:datetime.datetime` instances, i.e. with no +:attr:`~python:datetime.datetime.tzinfo` set. However the values are +*assumed* to be local to the UTC timezone (as though ``tzinfo`` was +set to :attr:`~python:datetime.timezone.utc`). + +Auto-populating such columns when writing records is done via the +:func:`~wuttjamaican.util.make_utc()` function. + +It is further assumed that custom app / extension models will follow +similar conventions. You should also use +:func:`~wuttjamaican.util.make_utc()` as needed, to coerce values for +ad-hoc writing to the DB. + + Multiple Databases ------------------