sqlalchemy-declarative-extensions 0.18.0__tar.gz → 0.19.0__tar.gz

{sqlalchemy_declarative_extensions-0.18.0 → sqlalchemy_declarative_extensions-0.19.0}/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.19
+
+### 0.19.0
+
+- feat: Accept a `Function` as a trigger's `execute`, creating it alongside the trigger.
+
 ## 0.18
 
 

{sqlalchemy_declarative_extensions-0.18.0 → sqlalchemy_declarative_extensions-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlalchemy-declarative-extensions
-Version: 0.18.0
+Version: 0.19.0
 Summary: Library to declare additional kinds of objects not natively supported by SQLAlchemy/Alembic.
 Project-URL: documentation, https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/
 Project-URL: homepage, https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/

{sqlalchemy_declarative_extensions-0.18.0 → sqlalchemy_declarative_extensions-0.19.0}/docs/source/triggers.md

@@ -91,6 +91,61 @@ the natural ordering, but it does mean that doing so afterwards will discard any
 already-attached table-level triggers.
 ```
 
+## Executing a function
+
+For dialects whose triggers execute a function (PostgreSQL), `execute` may be a
+`Function` rather than the name of one. The function is then created automatically
+alongside the trigger, so it need not be separately registered through `Functions`.
+
+```python
+from sqlalchemy_declarative_extensions.dialects.postgresql import Trigger, trigger_function
+
+audit = trigger_function(
+    "audit",
+    """
+    BEGIN
+    INSERT INTO log (message) VALUES (TG_TABLE_NAME);
+    RETURN NULL;
+    END
+    """,
+)
+
+
+class Foo(Base):
+    __tablename__ = "foo"
+    __table_args__ = (
+        Trigger.after("insert", execute=audit).named("on_insert_foo").for_each_row(),
+    )
+
+    id = Column(types.Integer(), primary_key=True)
+```
+
+This works however the trigger is declared (`Triggers`, `register_trigger` or
+`__table_args__`). Any number of triggers may share the same function, as with the generic
+audit function above, and it is created once. Declaring two *different* functions with the
+same qualified name is an error.
+
+`trigger_function` returns a PostgreSQL `Function` fixed to `RETURNS trigger LANGUAGE plpgsql`,
+and accepts neither `parameters` nor `returns`. A plain `Function` may be used in the
+same way when more control is needed.
+
+```{note}
+Trigger functions are collected when `register_sqlalchemy_events` is called, so call it
+after the models which declare triggers.
+```
+
+```{note}
+When a function is only declared through a trigger, only that function is managed:
+other functions in the database are left alone. If you also declare `Functions`, its
+`ignore_unspecified` and `include`/`ignore` settings apply to the combined set (with
+trigger functions added to `include`, if set).
+```
+
+```{note}
+MySQL triggers execute a raw statement, so passing a `Function` to a MySQL `Trigger`
+raises a `TypeError`.
+```
+
 ```{eval-rst}
 .. autoapimodule:: sqlalchemy_declarative_extensions.trigger.base
    :members: Trigger, Triggers, register_trigger

{sqlalchemy_declarative_extensions-0.18.0 → sqlalchemy_declarative_extensions-0.19.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlalchemy-declarative-extensions"
-version = "0.18.0"
+version = "0.19.0"
 authors = [{ name = "Dan Cardin", email = "ddcardin@gmail.com" }]
 description = "Library to declare additional kinds of objects not natively supported by SQLAlchemy/Alembic."
 license = { file = "LICENSE" }

{sqlalchemy_declarative_extensions-0.18.0 → sqlalchemy_declarative_extensions-0.19.0}/src/sqlalchemy_declarative_extensions/api.py

@@ -229,7 +229,7 @@ def register_create_events(
     concrete_grants = metadata.info.get("grants") or Grants()
     concrete_views = Views.extract(metadata) or Views()
     concrete_procedures = metadata.info.get("procedures") or Procedures()
-    concrete_functions = metadata.info.get("functions") or Functions()
+    concrete_functions = Functions.extract(metadata) or Functions()
     concrete_triggers = metadata.info.get("triggers") or Triggers()
     concrete_databases = metadata.info.get("databases") or Databases()
     concrete_rows = metadata.info.get("rows") or Rows()
@@ -333,7 +333,7 @@ def register_drop_events(
     concrete_roles = metadata.info.get("roles")
     concrete_views = metadata.info.get("views")
     concrete_procedures = metadata.info.get("procedures")
-    concrete_functions = metadata.info.get("functions")
+    concrete_functions = Functions.extract(metadata)
     concrete_triggers = metadata.info.get("triggers")
     concrete_databases = metadata.info.get("databases")
 

{sqlalchemy_declarative_extensions-0.18.0 → sqlalchemy_declarative_extensions-0.19.0}/src/sqlalchemy_declarative_extensions/dialects/mysql/trigger.py

@@ -48,6 +48,11 @@ class Trigger(base.Trigger):
     order: TriggerOrder | None = None
 
     def __post_init__(self):
+        if not isinstance(self.execute, str):
+            raise TypeError(
+                f"MySQL trigger '{self.name}' must execute a statement string,"
+                " not a `Function`."
+            )
         self.time = TriggerTimes.from_string(self.time)
         self.event = TriggerEvents.from_string(self.event)
 
@@ -118,6 +123,7 @@ class Trigger(base.Trigger):
         if self.order:
             components.append(self.order.order.value)
             components.append(self.order.other_trigger_name)
+        assert isinstance(self.execute, str)
         components.append(self.execute)
 
         return " ".join(components) + ";"

{sqlalchemy_declarative_extensions-0.18.0 → sqlalchemy_declarative_extensions-0.19.0}/src/sqlalchemy_declarative_extensions/dialects/postgresql/__init__.py

@@ -5,6 +5,7 @@ from sqlalchemy_declarative_extensions.dialects.postgresql.function import (
     FunctionReturn,
     FunctionSecurity,
     FunctionVolatility,
+    trigger_function,
 )
 from sqlalchemy_declarative_extensions.dialects.postgresql.grant import (
     DefaultGrant,
@@ -70,4 +71,5 @@ __all__ = [
     "TypeGrants",
     "View",
     "ViewIndex",
+    "trigger_function",
 ]

{sqlalchemy_declarative_extensions-0.18.0 → sqlalchemy_declarative_extensions-0.19.0}/src/sqlalchemy_declarative_extensions/dialects/postgresql/function.py

@@ -363,3 +363,21 @@ type_map = {
     "bool[]": "_bool",
     "boolean[]": "_bool",
 }
+
+
+def trigger_function(
+    name: str,
+    definition: str,
+    *,
+    schema: str | None = None,
+    security: FunctionSecurity = FunctionSecurity.invoker,
+) -> Function:
+    """Create a plpgsql `Function` returning `trigger`, suitable for `Trigger(execute=...)`."""
+    return Function(
+        name=name,
+        definition=definition,
+        schema=schema,
+        security=security,
+        returns="trigger",
+        language="plpgsql",
+    )

{sqlalchemy_declarative_extensions-0.18.0 → sqlalchemy_declarative_extensions-0.19.0}/src/sqlalchemy_declarative_extensions/dialects/postgresql/trigger.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass, replace
 from sqlalchemy.engine import Connection
 
 from sqlalchemy_declarative_extensions.dialects.from_string import FromStrings
+from sqlalchemy_declarative_extensions.function.base import Function
 from sqlalchemy_declarative_extensions.sql import quote_name
 from sqlalchemy_declarative_extensions.trigger import base
 
@@ -105,7 +106,11 @@ class Trigger(base.Trigger):
 
     @classmethod
     def before(
-        cls, *events: TriggerEvents | str, execute: str, on: str = "", name: str = ""
+        cls,
+        *events: TriggerEvents | str,
+        execute: str | Function,
+        on: str = "",
+        name: str = "",
     ):
         return cls(
             time=TriggerTimes.before,
@@ -117,7 +122,11 @@ class Trigger(base.Trigger):
 
     @classmethod
     def after(
-        cls, *events: TriggerEvents | str, execute: str, on: str = "", name: str = ""
+        cls,
+        *events: TriggerEvents | str,
+        execute: str | Function,
+        on: str = "",
+        name: str = "",
     ):
         return cls(
             time=TriggerTimes.after,
@@ -129,7 +138,11 @@ class Trigger(base.Trigger):
 
     @classmethod
     def instead_of(
-        cls, *events: TriggerEvents | str, execute: str, on: str = "", name: str = ""
+        cls,
+        *events: TriggerEvents | str,
+        execute: str | Function,
+        on: str = "",
+        name: str = "",
     ):
         return cls(
             time=TriggerTimes.instead_of,
@@ -203,7 +216,7 @@ class Trigger(base.Trigger):
         args_quoted = (
             tuple(f"'{arg}'" for arg in self.arguments) if self.arguments else ()
         )
-        components.append(quote_name(self.execute) + f"({','.join(args_quoted)})")
+        components.append(quote_name(self.execute_name) + f"({','.join(args_quoted)})")
         return " ".join(components) + ";"
 
     def to_sql_drop(self):

{sqlalchemy_declarative_extensions-0.18.0 → sqlalchemy_declarative_extensions-0.19.0}/src/sqlalchemy_declarative_extensions/function/base.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import glob
 from dataclasses import dataclass, field, replace
 from typing import Iterable, Sequence
 
@@ -109,9 +110,35 @@ class Functions:
 
     @classmethod
     def extract(cls, metadata: MetaData | list[MetaData | None] | None) -> Self | None:
+        """Extract the declared functions, including those executed by declared triggers.
+
+        When a trigger function is not otherwise declared, only that function is managed
+        (through `include`), so unrelated functions in the database are left alone.
+        """
         if not isinstance(metadata, Sequence):
             metadata = [metadata]
 
+        declared = cls._extract_declared(metadata)
+        trigger_functions = [
+            function
+            for m in metadata
+            if m and m.info.get("triggers")
+            for function in m.info["triggers"].functions
+        ]
+        if not trigger_functions:
+            return declared
+
+        if declared is None:
+            result = cls(include=[])
+        else:
+            result = replace(declared, functions=list(declared.functions))
+
+        for function in trigger_functions:
+            result.append_managed(function)
+        return result
+
+    @classmethod
+    def _extract_declared(cls, metadata: Sequence[MetaData | None]) -> Self | None:
         instances: list[Self] = [
             m.info["functions"] for m in metadata if m and m.info.get("functions")
         ]
@@ -146,8 +173,35 @@ class Functions:
         )
 
     def append(self, function: Function):
+        """Add the function, unless an identical one is already present.
+
+        Raises a `ValueError` if a different function has the same qualified name.
+        """
+        qualified_name = function.qualified_name
+        existing = next(
+            (f for f in self.functions if f.qualified_name == qualified_name), None
+        )
+        if existing is not None:
+            if existing != function:
+                raise ValueError(
+                    f"Function '{qualified_name}' is declared more than once"
+                    " with differing definitions."
+                )
+            return
+
         self.functions.append(function)
 
+    def append_managed(self, function: Function):
+        """Append the function, and add it to `include` if this collection is restricted by it."""
+        self.append(function)
+
+        if self.include is None:
+            return
+
+        pattern = glob.escape(function.qualified_name)
+        if pattern not in self.include:
+            self.include = [*self.include, pattern]
+
     def __iter__(self):
         yield from self.functions
 

{sqlalchemy_declarative_extensions-0.18.0 → sqlalchemy_declarative_extensions-0.19.0}/src/sqlalchemy_declarative_extensions/trigger/base.py

@@ -8,23 +8,40 @@ from sqlalchemy.engine import Connection
 from sqlalchemy.sql.schema import SchemaItem
 from typing_extensions import Self
 
+from sqlalchemy_declarative_extensions.function.base import Function, Functions
 from sqlalchemy_declarative_extensions.sql import qualify_name
 from sqlalchemy_declarative_extensions.sqlalchemy import HasMetaData
 
 
 @dataclass
 class Trigger(SchemaItem):
-    """Describes a generic trigger."""
+    """Describes a generic trigger.
+
+    `execute` is either the statement/name to execute, or (for dialects whose triggers
+    execute a function) a `Function`, which is then created alongside the trigger.
+    """
 
     name: str
     on: str
-    execute: str
+    execute: str | Function
 
     @property
     def identity(self) -> Hashable:
         """Return the dialect-specific identity used to compare triggers."""
         return self.name
 
+    @property
+    def execute_name(self) -> str:
+        if isinstance(self.execute, Function):
+            return self.execute.qualified_name
+        return self.execute
+
+    def normalize(self) -> Self:
+        """Return the trigger with any `Function` replaced by its qualified name."""
+        if isinstance(self.execute, Function):
+            return replace(self, execute=self.execute_name)
+        return self
+
     def named(self, name: str):
         return replace(self, name=name)
 
@@ -118,6 +135,11 @@ class Triggers:
             include=include,
         )
 
+    @property
+    def functions(self) -> list[Function]:
+        """The functions referenced as `execute` by the triggers."""
+        return [t.execute for t in self.triggers if isinstance(t.execute, Function)]
+
     def append(self, trigger: Trigger):
         self.triggers.append(trigger)
 
@@ -133,12 +155,20 @@ def register_trigger(base_or_metadata: HasMetaData | MetaData, trigger: Trigger)
 
     This can be used instead of the static registration through `Triggers` on a declarative base or
     `MetaData`, to imperitively register triggers.
+
+    If the trigger executes a `Function`, that function is registered as well.
     """
     if isinstance(base_or_metadata, MetaData):
         metadata = base_or_metadata
     else:
         metadata = base_or_metadata.metadata
 
+    if isinstance(trigger.execute, Function):
+        functions = metadata.info.get("functions")
+        if not functions:
+            functions = metadata.info["functions"] = Functions(include=[])
+        functions.append_managed(trigger.execute)
+
     if not metadata.info.get("triggers"):
         metadata.info["triggers"] = Triggers()
     metadata.info["triggers"].append(trigger)

{sqlalchemy_declarative_extensions-0.18.0 → sqlalchemy_declarative_extensions-0.19.0}/src/sqlalchemy_declarative_extensions/trigger/compare.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from typing import Union
 
 from sqlalchemy.engine import Connection
@@ -51,6 +51,7 @@ Operation = Union[CreateTriggerOp, UpdateTriggerOp, DropTriggerOp]
 def compare_triggers(connection: Connection, triggers: Triggers) -> list[Operation]:
     result: list[Operation] = []
 
+    triggers = replace(triggers, triggers=[t.normalize() for t in triggers])
     triggers_by_identity = {r.identity: r for r in triggers.triggers}
     expected_trigger_identities = set(triggers_by_identity)
 

sqlalchemy_declarative_extensions-0.19.0/tests/examples/test_trigger_function_execute/models.py

@@ -0,0 +1,49 @@
+from sqlalchemy import Column, types
+
+from sqlalchemy_declarative_extensions import declarative_database
+from sqlalchemy_declarative_extensions.dialects.postgresql import (
+    Trigger,
+    trigger_function,
+)
+from sqlalchemy_declarative_extensions.sqlalchemy import declarative_base
+
+_Base = declarative_base()
+
+gimme = trigger_function(
+    "gimme",
+    """
+    BEGIN
+    INSERT INTO log (id) select NEW.id + 1;
+    RETURN NULL;
+    END
+    """,
+)
+
+
+@declarative_database
+class Base(_Base):  # type: ignore
+    __abstract__ = True
+
+
+class Log(Base):
+    __tablename__ = "log"
+
+    id = Column(types.Integer(), primary_key=True)
+
+
+class Foo(Base):
+    __tablename__ = "foo"
+    __table_args__ = (
+        Trigger.after("insert", execute=gimme).named("on_insert_foo").for_each_row(),
+    )
+
+    id = Column(types.Integer(), primary_key=True)
+
+
+class Bar(Base):
+    __tablename__ = "bar"
+    __table_args__ = (
+        Trigger.after("insert", execute=gimme).named("on_insert_bar").for_each_row(),
+    )
+
+    id = Column(types.Integer(), primary_key=True)

sqlalchemy_declarative_extensions-0.19.0/tests/examples/test_trigger_function_execute/test_migrations.py

@@ -0,0 +1,38 @@
+from pathlib import Path
+
+import pytest
+from pytest_alembic import MigrationContext
+from pytest_mock_resources import PostgresConfig, create_postgres_fixture
+from sqlalchemy import text
+
+alembic_engine = create_postgres_fixture(scope="function", engine_kwargs={"echo": True})
+
+
+@pytest.fixture(scope="session")
+def pmr_postgres_config():
+    return PostgresConfig(image="postgres:13", port=None, ci_port=None)
+
+
+def test_function_is_created_before_triggers_and_dropped_after(
+    alembic_runner: MigrationContext, alembic_engine
+):
+    alembic_runner.generate_revision(autogenerate=True, prevent_file_generation=False)
+
+    (revision,) = Path("migrations/versions").glob("*.py")
+    source = revision.read_text()
+    upgrade, downgrade = source.split("def downgrade")
+    assert upgrade.count("CREATE FUNCTION") == 1
+    assert upgrade.index("CREATE FUNCTION") < upgrade.index("CREATE TRIGGER")
+    assert downgrade.index("DROP TRIGGER") < downgrade.index("DROP FUNCTION")
+
+    alembic_runner.migrate_up_one()
+
+    with alembic_engine.connect() as conn:
+        conn.execute(text("insert into foo (id) values (1)"))
+        conn.execute(text("insert into bar (id) values (10)"))
+        conn.commit()
+        result = [r for r, *_ in conn.execute(text("select id from log")).fetchall()]
+
+    assert sorted(result) == [2, 11]
+
+    alembic_runner.migrate_down_one()

sqlalchemy_declarative_extensions-0.19.0/tests/examples/test_view_update_pg/alembic.ini

@@ -0,0 +1,36 @@
+[alembic]
+script_location = migrations
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

sqlalchemy_declarative_extensions-0.19.0/tests/examples/test_view_update_pg/migrations/env.py

@@ -0,0 +1,26 @@
+from alembic import context
+
+# isort: split
+from models import Base
+from sqlalchemy import engine_from_config, pool
+
+from sqlalchemy_declarative_extensions import register_alembic_events
+
+target_metadata = Base.metadata
+
+register_alembic_events(views=True, rows=True)
+
+connectable = context.config.attributes.get("connection", None)
+
+if connectable is None:
+    connectable = engine_from_config(
+        context.config.get_section(context.config.config_ini_section),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+with connectable.connect() as connection:
+    context.configure(connection=connection, target_metadata=target_metadata)
+
+    with context.begin_transaction():
+        context.run_migrations()

sqlalchemy_declarative_extensions-0.19.0/tests/examples/test_view_update_pg/migrations/script.py.mako

@@ -0,0 +1,24 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade():
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade():
+    ${downgrades if downgrades else "pass"}

{sqlalchemy_declarative_extensions-0.18.0 → sqlalchemy_declarative_extensions-0.19.0}/tests/trigger/test_alembic.py

@@ -26,3 +26,8 @@ def test_trigger_rewriter(pytester):
 @pytest.mark.alembic
 def test_trigger_table_args(pytester):
     successful_test_run(pytester, count=1)
+
+
+@pytest.mark.alembic
+def test_trigger_function_execute(pytester):
+    successful_test_run(pytester, count=1)

sqlalchemy_declarative_extensions-0.19.0/tests/trigger/test_function_execute_conflict.py

@@ -0,0 +1,34 @@
+import pytest
+from sqlalchemy import MetaData
+
+from sqlalchemy_declarative_extensions.dialects.postgresql import (
+    Trigger,
+    trigger_function,
+)
+from sqlalchemy_declarative_extensions.trigger.base import register_trigger
+
+
+def test_different_functions_with_the_same_name_raise():
+    metadata = MetaData()
+    register_trigger(
+        metadata,
+        Trigger.after(
+            "insert",
+            on="a",
+            name="a",
+            execute=trigger_function("audit", "BEGIN RETURN NULL; END"),
+        ),
+    )
+
+    with pytest.raises(ValueError, match="'audit'"):
+        register_trigger(
+            metadata,
+            Trigger.after(
+                "insert",
+                on="b",
+                name="b",
+                execute=trigger_function("audit", "BEGIN RETURN NEW; END"),
+            ),
+        )
+
+    assert [t.name for t in metadata.info["triggers"]] == ["a"]

sqlalchemy_declarative_extensions-0.19.0/tests/trigger/test_function_execute_mysql.py

@@ -0,0 +1,11 @@
+import pytest
+
+from sqlalchemy_declarative_extensions.dialects import mysql
+from sqlalchemy_declarative_extensions.dialects.postgresql import trigger_function
+
+
+def test_function_is_rejected():
+    audit = trigger_function("audit", "BEGIN RETURN NULL; END")
+
+    with pytest.raises(TypeError, match="Function"):
+        mysql.Trigger.after("insert", execute=audit, on="a", name="a")  # type: ignore