xtr-orm 5.2.1__tar.gz → 6.0.0__tar.gz

{xtr_orm-5.2.1 → xtr_orm-6.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtr-orm
-Version: 5.2.1
+Version: 6.0.0
 Summary: Databases for async applications: engines, sessions and versioned schema migrations, configured once per connection.
 Keywords: orm,database,migrations,sqlalchemy,alembic,asyncio
 Author: Xterr
@@ -20,7 +20,7 @@ Requires-Dist: advanced-alchemy>=1.11
 Requires-Dist: alembic>=1.20
 Requires-Dist: sqlalchemy[asyncio]>=2.0.41
 Requires-Dist: typing-extensions>=4.4
-Requires-Dist: xtr-logging-contracts>=5.0,<6
+Requires-Dist: xtr-logging-contracts>=6.0,<7
 Requires-Dist: asyncmy>=0.2.9 ; extra == 'mysql'
 Requires-Dist: asyncpg>=0.29 ; extra == 'postgres'
 Requires-Dist: aiosqlite>=0.20 ; extra == 'sqlite'
@@ -75,6 +75,7 @@ uv add "xtr-orm[postgres]"                            # asyncpg
 uv add "xtr-orm[postgres]" xtr-dependency-injection   # + the container, for the OrmBundle
 uv add xtr-console                                    # beside it: the orm:* commands
 uv add xtr-messenger                                  # beside it: the message bus middleware
+uv add "xtr-messenger[orm]"                           # beside it: the orm:// transport too
 ```
 
 | Extra | Brings | For |
@@ -86,7 +87,8 @@ sessions, migrators from one configuration — is used when
 [xtr-dependency-injection](../xtr-dependency-injection) is installed beside the package, and a
 `Migrator` works without it, as the [Quick start](#quick-start) shows. Installed beside it too,
 [xtr-console](../xtr-console) brings the `orm:*` commands and [xtr-messenger](../xtr-messenger)
-the [message bus middleware](#message-bus-middleware).
+the [message bus middleware](#message-bus-middleware); with
+[xtr-orm-messenger](../xtr-orm-messenger) as well, the [`orm://` transport](#message-bus-transport).
 
 ## Quick start
 
@@ -201,7 +203,8 @@ removing it undoes.
 - **Install** — `uv add "xtr-orm[postgres]" xtr-dependency-injection`: the bundle needs the
   container installed beside it, never as an extra; `mysql` or `sqlite` instead of `postgres` for
   those databases. Install xtr-console beside it for the `orm:*` commands, and xtr-messenger for
-  the [message bus middleware](#message-bus-middleware).
+  the [message bus middleware](#message-bus-middleware) — and xtr-orm-messenger, or
+  `xtr-messenger[orm]`, for the [`orm://` transport](#message-bus-transport).
 - **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate*, *Configure* and
   *Environment* steps below: it lists `OrmBundle`, writes a starting `<app>/config/packages/orm.py` with the
   `default` connection, and `DATABASE_URL` in `.env`, and adds a PostgreSQL `database` service to
@@ -211,7 +214,8 @@ removing it undoes.
   `xtr_orm.bundle`.
 - **Brings along** — the logging and console bundles, when those packages are installed.
   With the messenger bundle active too, the [middleware](#message-bus-middleware) are
-  registered for a bus to list.
+  registered for a bus to list, and with xtr-orm-messenger installed the
+  [`orm://` transport](#message-bus-transport) too.
 - **Configure** — the recipe writes a starting `<app>/config/packages/orm.py` with the `default`
   connection reading `DATABASE_URL`, its revisions in `migrations` in the project directory and
   diffs against the models advanced-alchemy registers. Add connections, replicas and table
@@ -532,6 +536,34 @@ Without a container, build them with a `ConnectionRegistry` whose connections ar
 with a `session` — what returns the session the handlers use — and put the instances in the
 configuration.
 
+## Message bus transport
+
+With the messenger bundle active and [xtr-orm-messenger](../xtr-orm-messenger) installed —
+`uv add "xtr-messenger[orm]"` — a bus can keep its messages in a table on one of these
+connections. There is no bundle to list: this one registers the transport factory with the
+messenger, built on the connections, once it finds the package installed.
+
+```python
+# app/config/packages/messenger.py
+MessageBusConfig(
+    transports={"jobs": TransportConfig("orm://default", queue="jobs")},
+    routing={IngestDocument: "jobs"},
+)
+```
+
+- **The DSN names a connection.** `orm://default` is the `default` connection, `orm://` the
+  default one, whatever it is called; its URL stays in `OrmConfig`.
+- **Migrations write the table.** Each connection's migrator adds the messages table of every
+  `orm://` transport on it to its table definitions, so `orm:migrations:diff` writes it like
+  one of the application's own tables. The bus configuration is read for that when a migrator
+  is first built, so the environment variables its DSNs name must be set then. A connection
+  keeping several sets of table definitions is refused, naming it.
+- **Until the revision is applied**, the transport creates its table the first time it runs;
+  `auto_setup=false` on the DSN leaves it to the migrations alone.
+
+Options, workers and notifications are the transport's: see
+[xtr-orm-messenger](../xtr-orm-messenger).
+
 ## Creating and dropping databases
 
 `DatabaseManager(url)` creates and drops the database a URL names. A database cannot be

{xtr_orm-5.2.1 → xtr_orm-6.0.0}/README.md

@@ -43,6 +43,7 @@ uv add "xtr-orm[postgres]"                            # asyncpg
 uv add "xtr-orm[postgres]" xtr-dependency-injection   # + the container, for the OrmBundle
 uv add xtr-console                                    # beside it: the orm:* commands
 uv add xtr-messenger                                  # beside it: the message bus middleware
+uv add "xtr-messenger[orm]"                           # beside it: the orm:// transport too
 ```
 
 | Extra | Brings | For |
@@ -54,7 +55,8 @@ sessions, migrators from one configuration — is used when
 [xtr-dependency-injection](../xtr-dependency-injection) is installed beside the package, and a
 `Migrator` works without it, as the [Quick start](#quick-start) shows. Installed beside it too,
 [xtr-console](../xtr-console) brings the `orm:*` commands and [xtr-messenger](../xtr-messenger)
-the [message bus middleware](#message-bus-middleware).
+the [message bus middleware](#message-bus-middleware); with
+[xtr-orm-messenger](../xtr-orm-messenger) as well, the [`orm://` transport](#message-bus-transport).
 
 ## Quick start
 
@@ -169,7 +171,8 @@ removing it undoes.
 - **Install** — `uv add "xtr-orm[postgres]" xtr-dependency-injection`: the bundle needs the
   container installed beside it, never as an extra; `mysql` or `sqlite` instead of `postgres` for
   those databases. Install xtr-console beside it for the `orm:*` commands, and xtr-messenger for
-  the [message bus middleware](#message-bus-middleware).
+  the [message bus middleware](#message-bus-middleware) — and xtr-orm-messenger, or
+  `xtr-messenger[orm]`, for the [`orm://` transport](#message-bus-transport).
 - **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate*, *Configure* and
   *Environment* steps below: it lists `OrmBundle`, writes a starting `<app>/config/packages/orm.py` with the
   `default` connection, and `DATABASE_URL` in `.env`, and adds a PostgreSQL `database` service to
@@ -179,7 +182,8 @@ removing it undoes.
   `xtr_orm.bundle`.
 - **Brings along** — the logging and console bundles, when those packages are installed.
   With the messenger bundle active too, the [middleware](#message-bus-middleware) are
-  registered for a bus to list.
+  registered for a bus to list, and with xtr-orm-messenger installed the
+  [`orm://` transport](#message-bus-transport) too.
 - **Configure** — the recipe writes a starting `<app>/config/packages/orm.py` with the `default`
   connection reading `DATABASE_URL`, its revisions in `migrations` in the project directory and
   diffs against the models advanced-alchemy registers. Add connections, replicas and table
@@ -500,6 +504,34 @@ Without a container, build them with a `ConnectionRegistry` whose connections ar
 with a `session` — what returns the session the handlers use — and put the instances in the
 configuration.
 
+## Message bus transport
+
+With the messenger bundle active and [xtr-orm-messenger](../xtr-orm-messenger) installed —
+`uv add "xtr-messenger[orm]"` — a bus can keep its messages in a table on one of these
+connections. There is no bundle to list: this one registers the transport factory with the
+messenger, built on the connections, once it finds the package installed.
+
+```python
+# app/config/packages/messenger.py
+MessageBusConfig(
+    transports={"jobs": TransportConfig("orm://default", queue="jobs")},
+    routing={IngestDocument: "jobs"},
+)
+```
+
+- **The DSN names a connection.** `orm://default` is the `default` connection, `orm://` the
+  default one, whatever it is called; its URL stays in `OrmConfig`.
+- **Migrations write the table.** Each connection's migrator adds the messages table of every
+  `orm://` transport on it to its table definitions, so `orm:migrations:diff` writes it like
+  one of the application's own tables. The bus configuration is read for that when a migrator
+  is first built, so the environment variables its DSNs name must be set then. A connection
+  keeping several sets of table definitions is refused, naming it.
+- **Until the revision is applied**, the transport creates its table the first time it runs;
+  `auto_setup=false` on the DSN leaves it to the migrations alone.
+
+Options, workers and notifications are the transport's: see
+[xtr-orm-messenger](../xtr-orm-messenger).
+
 ## Creating and dropping databases
 
 `DatabaseManager(url)` creates and drops the database a URL names. A database cannot be

{xtr_orm-5.2.1 → xtr_orm-6.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-orm"
-version = "5.2.1"
+version = "6.0.0"
 description = "Databases for async applications: engines, sessions and versioned schema migrations, configured once per connection."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -30,7 +30,7 @@ dependencies = [
     "alembic>=1.20",
     "sqlalchemy[asyncio]>=2.0.41",
     "typing-extensions>=4.4",
-    "xtr-logging-contracts>=5.0,<6",
+    "xtr-logging-contracts>=6.0,<7",
 ]
 
 [[project.authors]]
@@ -57,11 +57,12 @@ dev = [
     "anyio>=4.0",
     "ty>=0.0.83",
     "aiosqlite>=0.20",
-    "xtr-console>=5.0,<6",
-    "xtr-dependency-injection>=5.0,<6",
-    "xtr-logging>=5.0,<6",
-    "xtr-messenger>=5.0,<6",
-    "xtr-service-contracts>=5.0,<6",
+    "xtr-console>=6.0,<7",
+    "xtr-dependency-injection>=6.0,<7",
+    "xtr-logging>=6.0,<7",
+    "xtr-messenger>=6.0,<7",
+    "xtr-orm-messenger>=6.0,<7",
+    "xtr-service-contracts>=6.0,<7",
 ]
 
 [build-system]
@@ -143,6 +144,11 @@ unfixable = []
     "TC002",
     "TC003",
 ]
+"src/xtr_orm/messenger_transport.py" = [
+    "TC001",
+    "TC002",
+    "TC003",
+]
 "tests/**/*.py" = [
     "S101",
     "ARG",

{xtr_orm-5.2.1 → xtr_orm-6.0.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-orm"
-version = "5.2.1"
+version = "6.0.0"
 description = "Databases for async applications: engines, sessions and versioned schema migrations, configured once per connection."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -26,7 +26,7 @@ dependencies = [
     "alembic>=1.20",
     "sqlalchemy[asyncio]>=2.0.41",
     "typing-extensions>=4.4",
-    "xtr-logging-contracts>=5.0,<6",
+    "xtr-logging-contracts>=6.0,<7",
 ]
 
 [project.optional-dependencies]
@@ -59,11 +59,12 @@ dev = [
     "ty>=0.0.83",
     # Every test runs on SQLite files under the test's own directory: no server.
     "aiosqlite>=0.20",
-    "xtr-console>=5.0,<6",
-    "xtr-dependency-injection>=5.0,<6",
-    "xtr-logging>=5.0,<6",
-    "xtr-messenger>=5.0,<6",
-    "xtr-service-contracts>=5.0,<6",
+    "xtr-console>=6.0,<7",
+    "xtr-dependency-injection>=6.0,<7",
+    "xtr-logging>=6.0,<7",
+    "xtr-messenger>=6.0,<7",
+    "xtr-orm-messenger>=6.0,<7",
+    "xtr-service-contracts>=6.0,<7",
 ]
 
 [build-system]
@@ -147,6 +148,8 @@ unfixable = []
 # runtime, and the container resolves its config's fields; deferring these
 # would register the factories under nothing.
 "src/xtr_orm/bundle/*.py" = ["TC001", "TC002", "TC003"]
+# The same for the orm:// transport factory the bundle registers.
+"src/xtr_orm/messenger_transport.py" = ["TC001", "TC002", "TC003"]
 "tests/**/*.py" = [
     "S101",    # assert is the point of pytest
     "ARG",     # fixtures look unused

{xtr_orm-5.2.1 → xtr_orm-6.0.0}/src/xtr_orm/.agents/skills/xtr-orm/SKILL.md

@@ -317,6 +317,23 @@ A handler asks for `Injected[AsyncSession]` like any service and adds rows; it n
 More, including building the middleware without a container:
 [references/messenger.md](references/messenger.md).
 
+## A queue in a table
+
+With the messenger bundle active and xtr-orm-messenger installed (`uv add "xtr-messenger[orm]"`),
+this bundle registers the `orm://` transport on its connections — no other bundle to list.
+
+```python
+# <app>/config/packages/messenger.py
+MessageBusConfig(
+    transports={"jobs": TransportConfig("orm://default", queue="jobs")},
+    routing={IngestDocument: "jobs"},
+)
+```
+
+Each connection's migrator adds the messages table of every `orm://` transport on it, so
+`orm:migrations:diff` writes it. The transport itself — options, workers, notifications — is
+the `xtr-orm-messenger` skill's.
+
 ## Creating and dropping a database
 
 ```python

{xtr_orm-5.2.1 → xtr_orm-6.0.0}/src/xtr_orm/bundle/orm_bundle.py

@@ -21,14 +21,20 @@ disposed when the container closes. When the console bundle is active, the
 ``orm_open_transaction_logger`` middleware are, for a bus to list; when the
 logging bundle is, an ``orm`` channel is added and every migrator logs there.
 
+With the messenger bundle active and xtr-orm-messenger installed, the
+``orm://`` transport is registered with the messenger too, built on these
+connections, and each connection's migrator writes the messages tables of the
+``orm://`` transports on it.
+
 Nothing connects until a service is first used, and a URL given as
 ``env(...)`` is read only then.
 """
 
 from __future__ import annotations
 
-from collections.abc import AsyncIterator, Awaitable, Callable
+from collections.abc import AsyncIterator, Awaitable, Callable, Sequence
 from functools import partial
+from importlib.util import find_spec
 from operator import contains
 from typing import Final, TypeVar, cast, final
 
@@ -37,6 +43,7 @@ from advanced_alchemy.config import AsyncSessionConfig, EngineConfig, SQLAlchemy
 from advanced_alchemy.config.routing import EngineConfig as ReplicaEngine
 from advanced_alchemy.config.routing import RoutingConfig, RoutingStrategy
 from advanced_alchemy.routing import RoutingAsyncSessionMaker, stick_to_primary_var
+from sqlalchemy import MetaData
 from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker
 from typing_extensions import override
 from xtr_dependency_injection import (
@@ -48,6 +55,7 @@ from xtr_dependency_injection import (
     current_unit_of_work,
     named_factory,
     optional_service,
+    qualified_name,
     required_bundle,
 )
 from xtr_logging_contracts import LoggerInterface
@@ -55,7 +63,7 @@ from xtr_service_contracts import ContainerInterface
 
 from xtr_orm.connection_registry import ConnectionRegistry
 from xtr_orm.database import DatabaseManager
-from xtr_orm.exception import SessionUnavailableError
+from xtr_orm.exception import InvalidArgumentError, SessionUnavailableError
 from xtr_orm.migrations import MigrationsConfig, Migrator
 
 from .connection_config import ConnectionConfig
@@ -71,6 +79,9 @@ _SessionMaker = type[async_sessionmaker[AsyncSession]] | type[RoutingAsyncSessio
 ORM_CHANNEL: Final = "orm"
 """The logging channel migrators write to."""
 
+_MESSENGER_TRANSPORT: Final = "xtr_orm_messenger"
+"""The package of the ``orm://`` transport, registered with the messenger when installed."""
+
 _PER_CONNECTION: Final[tuple[type, ...]] = (
     SQLAlchemyAsyncConfig,
     AsyncEngine,
@@ -108,6 +119,8 @@ class OrmBundle(Bundle[OrmConfig]):
         builder: ContainerBuilder,
     ) -> None:
         """Register every connection's services under its name, the registry, the commands."""
+        messenger = bundle_active(builder, "messenger")
+        transport = messenger and find_spec(_MESSENGER_TRANSPORT) is not None
         for name, connection in config.connections.items():
             maker_type: _SessionMaker = (
                 RoutingAsyncSessionMaker
@@ -123,7 +136,15 @@ class OrmBundle(Bundle[OrmConfig]):
                     else _session_maker_factory(name),
                     "session_maker",
                 ),
-                (_migrator_factory(name, connection), "migrator"),
+                (
+                    _migrator_factory(
+                        name,
+                        connection,
+                        default=config.default_connection,
+                        messages_tables=transport,
+                    ),
+                    "migrator",
+                ),
                 (_database_factory(connection), "database"),
             )
             for factory, kind in factories:
@@ -148,8 +169,37 @@ class OrmBundle(Bundle[OrmConfig]):
 
         if bundle_active(builder, "console"):
             services.load("xtr_orm.command")
-        if bundle_active(builder, "messenger"):
+        if messenger:
             services.load("xtr_orm.messenger")
+        if transport:
+            _register_orm_transport(services)
+
+
+def _register_orm_transport(services: ServiceConfigurator) -> None:
+    """Register the ``orm://`` transport factory with the messenger, built on these connections.
+
+    Registered under the messenger's transport factory interface and tagged
+    with its transport factory tag, which is how the messenger consults a
+    factory built from services ahead of the ones it discovers by DSN scheme.
+    """
+    # Optional peers: importable only once the messenger bundle is active and
+    # the transport installed, which the caller checked.
+    from xtr_messenger import TransportFactoryInterface  # noqa: PLC0415 — optional peer
+    from xtr_messenger.bundle import TRANSPORT_FACTORY_TAG  # noqa: PLC0415 — optional peer
+
+    from xtr_orm.messenger_transport import (  # noqa: PLC0415 — needs the optional peers
+        OrmTransportFactory,
+        orm_transport_factory,
+    )
+
+    qualifier = qualified_name(OrmTransportFactory)
+    _ = services.set(orm_transport_factory, qualifier=qualifier).add_tag(TRANSPORT_FACTORY_TAG)
+    services.alias(
+        TransportFactoryInterface,
+        OrmTransportFactory,
+        alias_qualifier=qualifier,
+        target_qualifier=qualifier,
+    )
 
 
 @final
@@ -291,9 +341,14 @@ def _session_factory(
 
 
 def _migrator_factory(
-    name: str, connection: ConnectionConfig
+    name: str, connection: ConnectionConfig, *, default: str, messages_tables: bool
 ) -> Callable[[ContainerInterface], Awaitable[Migrator]]:
-    """Build the factory of the connection ``name``'s migrator, logging to ``orm`` when it can."""
+    """Build the factory of the connection ``name``'s migrator, logging to ``orm`` when it can.
+
+    With ``messages_tables``, the messages tables of the ``orm://`` transports
+    on this connection join its table definitions first, so a diff writes them
+    like any of the application's own tables.
+    """
 
     async def migrator(container: ContainerInterface) -> Migrator:
         resolved = connection.with_url_options()
@@ -302,6 +357,8 @@ def _migrator_factory(
             if resolved.metadata is not None
             else metadata_registry.get(resolved.bind_key)
         )
+        if messages_tables:
+            await _map_messages_tables(container, name, default, metadata)
         built = Migrator(
             await container.get(AsyncEngine, name),
             resolved.migrations or MigrationsConfig(),
@@ -316,6 +373,44 @@ def _migrator_factory(
     return migrator
 
 
+async def _map_messages_tables(
+    container: ContainerInterface,
+    name: str,
+    default: str,
+    metadata: MetaData | Sequence[MetaData],
+) -> None:
+    """Add the messages table of every ``orm://`` transport on the connection ``name``.
+
+    The transports are read from the bus configuration as the application
+    resolved it, so a DSN given as ``env(...)`` is read here — when a migrator
+    is first built.
+
+    Raises:
+        InvalidArgumentError: When a transport keeps a table on a connection
+            that keeps several sets of table definitions.
+    """
+    # Optional peers: importable only once the messenger bundle is active and
+    # the transport installed, which the bundle checked.
+    from xtr_messenger import MessageBusConfig  # noqa: PLC0415 — optional peer
+    from xtr_orm_messenger import (  # noqa: PLC0415 — optional peer
+        MessagesTableDriver,
+        messages_tables,
+    )
+
+    bus = await optional_service(container, MessageBusConfig)
+    tables = messages_tables(bus, name, default) if bus is not None else ()
+    if not tables:
+        return
+    if not isinstance(metadata, MetaData):
+        raise InvalidArgumentError(
+            f'The "{name}" connection keeps several sets of table definitions; the messages '
+            f"tables of its orm:// transports need the one they belong to. Give that connection "
+            f"a single MetaData.",
+        )
+    for table in tables:
+        _ = MessagesTableDriver(table).load_metadata(metadata)
+
+
 def _database_factory(connection: ConnectionConfig) -> Callable[[], DatabaseManager]:
     """Build the factory of ``connection``'s database manager."""
 

xtr_orm-6.0.0/src/xtr_orm/messenger_transport.py

@@ -0,0 +1,24 @@
+"""Building the ``orm://`` transport factory from the container's services.
+
+The orm bundle registers it when the messenger bundle is active and
+xtr-orm-messenger is installed: the factory needs this package's connections,
+which only this package's bundle holds. Importing this module therefore needs
+both xtr-messenger and xtr-orm-messenger; the bundle imports it only once it
+has found them, and nothing scans it.
+"""
+
+from __future__ import annotations
+
+from xtr_messenger import SerializerInterface
+from xtr_orm_messenger import OrmTransportFactory
+
+from xtr_orm.connection_registry import ConnectionRegistry
+
+__all__ = ["OrmTransportFactory", "orm_transport_factory"]
+
+
+def orm_transport_factory(
+    registry: ConnectionRegistry, serializer: SerializerInterface
+) -> OrmTransportFactory:
+    """Build the factory on the application's connections, with the messenger's serializer."""
+    return OrmTransportFactory(registry, serializer)