bump: version 0.2.2 → 0.3.0

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to Wutta-Continuum will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## v0.3.0 (2025-12-20)
+
+### Feat
+
+- add TransactionMetaPlugin to save comments when applicable
+
 ## v0.2.2 (2025-10-29)
 
 ### Fix

docs/index.rst

@@ -5,7 +5,7 @@ Wutta-Continuum
 This package adds data versioning/history for `WuttJamaican`_, using
 `SQLAlchemy-Continuum`_.
 
-.. _WuttJamaican: https://rattailproject.org/docs/wuttjamaican/
+.. _WuttJamaican: https://docs.wuttaproject.org/wuttjamaican/
 
 .. _SQLAlchemy-Continuum: https://sqlalchemy-continuum.readthedocs.io/en/latest/
 
@@ -20,7 +20,9 @@ This package adds data versioning/history for `WuttJamaican`_, using
    :maxdepth: 2
    :caption: Documentation
 
+   narr/features
    narr/install
+   narr/usage
 
 .. toctree::
    :maxdepth: 1

docs/narr/features.rst

@@ -0,0 +1,26 @@
+
+Features
+========
+
+The general idea is to provide an audit/versioning trail for important
+data tables.
+
+Each table defined in the :term:`app model` can either be versioned,
+or not.  Nothing changes for a non-versioned table.
+
+For a "versioned" table, a secondary "versions" table is created,
+schema for which is a superset of the original "versioned" table.
+When records change in the original table, new "version" records are
+added to the versions table.
+
+Therefore you can see how a record has changed over time, by
+inspecting its corresponding versions.
+
+When any record changes (for any versioned table), a new "transaction"
+record is also created.  This identifies the user responsible, and
+timestamp etc.  Any new version records will tie back to this
+transaction record.
+
+All this is made possible by SQLAlchemy-Continuum; the Wutta-Continuum
+package mostly just adds config glue.  See also
+:doc:`sqlalchemy-continuum:index`.

docs/narr/install.rst

@@ -31,7 +31,7 @@ this package for database migrations.  You should already have an
 
    [alembic]
    script_location = wuttjamaican.db:alembic
-   version_locations = wuttjamaican.db:alembic/versions wutta_continuum.db:alembic/versions
+   version_locations = wutta_continuum.db:alembic/versions poser.db:alembic/versions wuttjamaican.db:alembic/versions
 
 Then (as you would have done previously in
 :ref:`wuttjamaican:db-setup`) you can migrate your database to add the

docs/narr/usage.rst

@@ -0,0 +1,41 @@
+
+Usage
+=====
+
+You can check the feature status with
+:meth:`~wutta_continuum.app.WuttaContinuumAppProvider.continuum_is_enabled()`::
+
+   app = config.get_app()
+
+   if not app.continuum_is_enabled():
+       print("Oh no!  Continuum is not enabled.")
+
+The rest of this will assume the feature is enabled.
+
+
+Built-In Models
+---------------
+
+The following built-in models are versioned.  So, when records are
+added / modified / removed via the ORM, new version records are
+automatically created for each of these:
+
+* :class:`~wuttjamaican:wuttjamaican.db.model.auth.Permission`
+* :class:`~wuttjamaican:wuttjamaican.db.model.base.Person`
+* :class:`~wuttjamaican:wuttjamaican.db.model.auth.Role`
+* :class:`~wuttjamaican:wuttjamaican.db.model.auth.User`
+* :class:`~wuttjamaican:wuttjamaican.db.model.auth.UserRole`
+
+
+Object Versions
+---------------
+
+A versioned model works normally but also has a ``versions``
+attribute, which reflects the list of version records::
+
+    user = session.query(model.User).first()
+
+    for version in user.versions:
+        print(version)
+
+See also :doc:`sqlalchemy-continuum:version_objects`.

pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "Wutta-Continuum"
-version = "0.2.2"
+version = "0.3.0"
 description = "SQLAlchemy-Continuum versioning for Wutta Framework"
 readme = "README.md"
 authors = [{name = "Lance Edgar", email = "lance@wuttaproject.org"}]
@@ -27,7 +27,7 @@ classifiers = [
 requires-python = ">= 3.8"
 dependencies = [
         "SQLAlchemy-Continuum",
-        "WuttJamaican[db]>=0.24.1",
+        "WuttJamaican[db]>=0.27.0",
 ]
 
 

src/wutta_continuum/conf.py

@@ -28,7 +28,7 @@ import socket
 
 from sqlalchemy.orm import configure_mappers
 from sqlalchemy_continuum import make_versioned
-from sqlalchemy_continuum.plugins import Plugin
+from sqlalchemy_continuum.plugins import Plugin, TransactionMetaPlugin
 
 from wuttjamaican.conf import WuttaConfigExtension
 from wuttjamaican.util import load_object
@@ -66,6 +66,20 @@ class WuttaContinuumConfigExtension(WuttaConfigExtension):
 
         For more about SQLAlchemy-Continuum see
         :doc:`sqlalchemy-continuum:intro`.
+
+        Two plugins are provided to ``make_versioned()``:
+
+        The first is ``TransactionMetaPlugin`` for sake of adding
+        comments (see
+        :mod:`~sqlalchemy-continuum:sqlalchemy_continuum.plugins.transaction_meta`).
+
+        The second by default is :class:`WuttaContinuumPlugin` but you
+        can override with config:
+
+        .. code-block:: ini
+
+           [wutta_continuum]
+           wutta_plugin_spec = poser.db.continuum:PoserContinuumPlugin
         """
         # only do this if config enables it
         if not config.get_bool(
@@ -86,7 +100,7 @@ class WuttaContinuumConfigExtension(WuttaConfigExtension):
             raise RuntimeError("something not right, app already has model")
 
         # let sqlalchemy-continuum do its thing
-        make_versioned(plugins=[plugin()])
+        make_versioned(plugins=[TransactionMetaPlugin(), plugin()])
 
         # must load model *between* prev and next calls
         app.get_model()
@@ -148,3 +162,16 @@ class WuttaContinuumPlugin(Plugin):
             kwargs["user_id"] = user_id
 
         return kwargs
+
+    def before_flush(self, uow, session):
+        """
+        We use this hook to inject the "comment" for current
+        transaction, if applicable.
+
+        This checks the session for the comment; so any session can
+        specify one like so::
+
+           session.info["continuum_comment"] = "hello world"
+        """
+        if comment := session.info.get("continuum_comment"):
+            uow.current_transaction.meta["comment"] = comment

src/wutta_continuum/db/alembic/versions/46fb4711411d_add_transaction_meta.py

@@ -0,0 +1,40 @@
+"""add transaction_meta
+
+Revision ID: 46fb4711411d
+Revises: 989392cc191d
+Create Date: 2025-12-18 21:22:33.382628
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import wuttjamaican.db.util
+
+
+# revision identifiers, used by Alembic.
+revision: str = "46fb4711411d"
+down_revision: Union[str, None] = "989392cc191d"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+
+    # transaction_meta
+    op.create_table(
+        "transaction_meta",
+        sa.Column("transaction_id", sa.BigInteger(), nullable=False),
+        sa.Column("key", sa.Unicode(length=255), nullable=False),
+        sa.Column("value", sa.UnicodeText(), nullable=True),
+        sa.PrimaryKeyConstraint(
+            "transaction_id", "key", name=op.f("pk_transaction_meta")
+        ),
+    )
+
+
+def downgrade() -> None:
+
+    # transaction_meta
+    op.drop_table("transaction_meta")

tests/test_conf.py

@@ -2,7 +2,7 @@
 
 import socket
 
-from unittest.mock import patch
+from unittest.mock import patch, Mock
 
 from wuttjamaican.testing import ConfigTestCase, DataTestCase
 
@@ -71,3 +71,20 @@ class TestWuttaContinuumPlugin(DataTestCase):
                     plugin.transaction_args(None, self.session),
                     {"remote_addr": "127.0.0.1", "user_id": "some-random-uuid"},
                 )
+
+    def test_before_flush(self):
+        plugin = self.make_plugin()
+
+        meta = {}
+        txn = Mock(meta=meta)
+        uow = Mock(current_transaction=txn)
+
+        # no comment in session or transaction
+        plugin.before_flush(uow, self.session)
+        self.assertNotIn("comment", meta)
+
+        # transaction comment matches session
+        self.session.info["continuum_comment"] = "whaddyaknow"
+        plugin.before_flush(uow, self.session)
+        self.assertIn("comment", meta)
+        self.assertEqual(meta["comment"], "whaddyaknow")