xtr-orm 5.0.1__tar.gz → 5.2.0__tar.gz

{xtr_orm-5.0.1 → xtr_orm-5.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtr-orm
-Version: 5.0.1
+Version: 5.2.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
@@ -203,25 +203,30 @@ removing it undoes.
   those databases. Install xtr-console beside it for the `orm:*` commands, and xtr-messenger for
   the [message bus middleware](#message-bus-middleware).
 - **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate*, *Configure* and
-  *Environment* steps below: it lists `OrmBundle`, writes a starting `<app>/config/orm.py` with the
-  `default` connection, and `DATABASE_URL` in `.env`. It prints the middleware step, which a recipe
-  cannot make for you.
-- **Activate** — `OrmBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`, imported from
+  *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
+  `compose.yaml`, published on `5432` in `compose.override.yaml`. It prints the middleware step,
+  which a recipe cannot make for you.
+- **Activate** — `OrmBundle: {"all": True}` in `BUNDLES` in `<app>/config/bundles.py`, imported from
   `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.
-- **Configure** — the recipe writes a starting `<app>/config/orm.py` with the `default`
+- **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
   definitions to that `@configure` function returning `OrmConfig` — see
   [Kernel / bundle](#kernel--bundle).
 - **Environment** — `DATABASE_URL`, read when a connection is first used — engine, session,
   migrator or command — not when the application boots. Its query may carry options; see
-  [Options in the URL](#options-in-the-url).
+  [Options in the URL](#options-in-the-url). The recipe's value reaches the `database` service
+  `docker compose up -d database` starts; the `POSTGRES_*` variables that service reads, set in
+  the shell or `.env`, change its version, database, user and password — keep `DATABASE_URL` in
+  step with them.
 - **Ignore** — nothing: commit `migrations/`.
 - **Remove** — take the `orm_*` entries out of every bus's `middleware`, drop the `BUNDLES`
-  entry, delete `<app>/config/orm.py`, then `uv remove xtr-orm`.
+  entry, delete `<app>/config/packages/orm.py` and the `xtr-orm` blocks in `compose.yaml` and
+  `compose.override.yaml`, then `uv remove xtr-orm`.
 - **Check** — `debug:bundles` shows `orm` as `listed` and `active`, and
   `orm:migrations:status` reaches the database.
 
@@ -232,14 +237,14 @@ not a dependency, and nothing outside `xtr_orm.bundle` needs it — list the bun
 connections:
 
 ```python
-# app/bundles.py
+# app/config/bundles.py
 from xtr_orm.bundle import OrmBundle
 
 BUNDLES = {OrmBundle: {"all": True}}
 ```
 
 ```python
-# app/config/orm.py
+# app/config/packages/orm.py
 from xtr_dependency_injection import configure, env
 from xtr_orm.bundle import ConnectionConfig, OrmConfig
 
@@ -479,7 +484,7 @@ class NotifyAccounting:
 ```
 
 ```python
-# app/config/messenger.py
+# app/config/packages/messenger.py
 MessageBusConfig(
     middleware=[
         "orm_close_connection",

{xtr_orm-5.0.1 → xtr_orm-5.2.0}/README.md

@@ -171,25 +171,30 @@ removing it undoes.
   those databases. Install xtr-console beside it for the `orm:*` commands, and xtr-messenger for
   the [message bus middleware](#message-bus-middleware).
 - **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate*, *Configure* and
-  *Environment* steps below: it lists `OrmBundle`, writes a starting `<app>/config/orm.py` with the
-  `default` connection, and `DATABASE_URL` in `.env`. It prints the middleware step, which a recipe
-  cannot make for you.
-- **Activate** — `OrmBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`, imported from
+  *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
+  `compose.yaml`, published on `5432` in `compose.override.yaml`. It prints the middleware step,
+  which a recipe cannot make for you.
+- **Activate** — `OrmBundle: {"all": True}` in `BUNDLES` in `<app>/config/bundles.py`, imported from
   `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.
-- **Configure** — the recipe writes a starting `<app>/config/orm.py` with the `default`
+- **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
   definitions to that `@configure` function returning `OrmConfig` — see
   [Kernel / bundle](#kernel--bundle).
 - **Environment** — `DATABASE_URL`, read when a connection is first used — engine, session,
   migrator or command — not when the application boots. Its query may carry options; see
-  [Options in the URL](#options-in-the-url).
+  [Options in the URL](#options-in-the-url). The recipe's value reaches the `database` service
+  `docker compose up -d database` starts; the `POSTGRES_*` variables that service reads, set in
+  the shell or `.env`, change its version, database, user and password — keep `DATABASE_URL` in
+  step with them.
 - **Ignore** — nothing: commit `migrations/`.
 - **Remove** — take the `orm_*` entries out of every bus's `middleware`, drop the `BUNDLES`
-  entry, delete `<app>/config/orm.py`, then `uv remove xtr-orm`.
+  entry, delete `<app>/config/packages/orm.py` and the `xtr-orm` blocks in `compose.yaml` and
+  `compose.override.yaml`, then `uv remove xtr-orm`.
 - **Check** — `debug:bundles` shows `orm` as `listed` and `active`, and
   `orm:migrations:status` reaches the database.
 
@@ -200,14 +205,14 @@ not a dependency, and nothing outside `xtr_orm.bundle` needs it — list the bun
 connections:
 
 ```python
-# app/bundles.py
+# app/config/bundles.py
 from xtr_orm.bundle import OrmBundle
 
 BUNDLES = {OrmBundle: {"all": True}}
 ```
 
 ```python
-# app/config/orm.py
+# app/config/packages/orm.py
 from xtr_dependency_injection import configure, env
 from xtr_orm.bundle import ConnectionConfig, OrmConfig
 
@@ -447,7 +452,7 @@ class NotifyAccounting:
 ```
 
 ```python
-# app/config/messenger.py
+# app/config/packages/messenger.py
 MessageBusConfig(
     middleware=[
         "orm_close_connection",

{xtr_orm-5.0.1 → xtr_orm-5.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-orm"
-version = "5.0.1"
+version = "5.2.0"
 description = "Databases for async applications: engines, sessions and versioned schema migrations, configured once per connection."
 readme = "README.md"
 requires-python = ">=3.11"

{xtr_orm-5.0.1 → xtr_orm-5.2.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-orm"
-version = "5.0.1"
+version = "5.2.0"
 description = "Databases for async applications: engines, sessions and versioned schema migrations, configured once per connection."
 readme = "README.md"
 requires-python = ">=3.11"

{xtr_orm-5.0.1 → xtr_orm-5.2.0}/src/xtr_orm/.agents/skills/xtr-orm/SKILL.md

@@ -14,7 +14,7 @@ connection's name. Everything is async; there is no sync counterpart.
 
 - Inject `Injected[AsyncSession]` for the default connection;
   `Annotated[AsyncSession, Target("reports")]` for another. Never build a session yourself.
-- Name databases in `<app>/config/orm.py` with a `@configure` function returning `OrmConfig`.
+- Name databases in `<app>/config/packages/orm.py` with a `@configure` function returning `OrmConfig`.
 - Set `DATABASE_URL` with an async driver: `postgresql+asyncpg://`, `mysql+asyncmy://`,
   `sqlite+aiosqlite:///`. Engine and session options may ride on its query.
 - Write a revision from your models: `orm:migrations:diff --message "add invoices"`. Apply:
@@ -225,14 +225,14 @@ migrate = MigrationsMigrateCommand(registry)
 ## Use in an application
 
 `uv run xtr-recipes recipes:sync` applies the recipe shipped with this package: it lists `OrmBundle`,
-writes a starting `config/orm.py` with the `default` connection, and `DATABASE_URL` in `.env`. That
+writes a starting `config/packages/orm.py` with the `default` connection, and `DATABASE_URL` in `.env`. That
 is the steps below a recipe can do; the middleware it prints for you to add.
 
 1. **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`.
    Install xtr-console beside it for the `orm:*` commands, and xtr-messenger for the bus
    middleware.
-2. **Activate** — `OrmBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`
+2. **Activate** — `OrmBundle: {"all": True}` in `BUNDLES` in `<app>/config/bundles.py`
    (`from xtr_orm.bundle import OrmBundle`).
 3. **Brings along** — the logging and console bundles when those packages are installed, each
    optional. With the logging bundle active an `orm` channel is added and every migrator logs the
@@ -242,7 +242,7 @@ is the steps below a recipe can do; the middleware it prints for you to add.
    advanced-alchemy registers.
 
    ```python
-   # <app>/config/orm.py
+   # <app>/config/packages/orm.py
    from xtr_dependency_injection import configure, env
    from xtr_orm.bundle import ConnectionConfig, MigrationsConfig, OrmConfig
 
@@ -274,7 +274,7 @@ is the steps below a recipe can do; the middleware it prints for you to add.
 8. **Check** — `debug:bundles` shows `orm` as `listed` and `active`, and
    `orm:migrations:status` reaches the database.
 9. **Remove** — take the `orm_*` entries out of every bus's `middleware`, drop the `BUNDLES`
-   entry, delete `<app>/config/orm.py`, then `uv remove xtr-orm`.
+   entry, delete `<app>/config/packages/orm.py`, then `uv remove xtr-orm`.
 
 `OrmConfig` has two fields: `default_connection` (`"default"`) and `connections`
 (`{"default": ConnectionConfig()}`). Two connections may not keep their revisions in one
@@ -287,7 +287,7 @@ With xtr-messenger installed beside it and both bundles active, three middleware
 by name. Nothing is added to a bus by itself — the bus lists what it wants, and order matters.
 
 ```python
-# <app>/config/messenger.py
+# <app>/config/packages/messenger.py
 MessageBusConfig(
     middleware=[
         "orm_close_connection",  # outermost: closes after the transaction ended

{xtr_orm-5.0.1 → xtr_orm-5.2.0}/src/xtr_orm/.agents/skills/xtr-orm/references/messenger.md

@@ -16,7 +16,7 @@ configuration, so an untouched connection is left alone.
 ## Order
 
 ```python
-# <app>/config/messenger.py
+# <app>/config/packages/messenger.py
 MessageBusConfig(
     middleware=[
         "orm_close_connection",

xtr_orm-5.2.0/src/xtr_orm/recipe/manifest.toml

@@ -0,0 +1,66 @@
+# The recipe for xtr-orm: what *Use in an application* in the README takes, as
+# data. Keep the two in step — the README is the source.
+
+[bundles]
+# "<module>:<class>" = the environments it is listed with, exactly as in BUNDLES.
+"xtr_orm.bundle:OrmBundle" = { all = true }
+
+[files]
+# Destination under the application package = template under this recipe.
+# The default connection on DATABASE_URL, written out so the application has
+# one place to add replicas, connections and its models' metadata.
+"config/packages/orm.py" = "files/config/orm.py.tmpl"
+
+[env]
+# Read when a connection is first used — engine, session, migrator or command —
+# not when the application boots. The PostgreSQL compose.yaml runs, for the
+# postgres extra the README installs; change it, or put the real one in
+# .env.local.
+DATABASE_URL = "postgresql+asyncpg://app:!ChangeMe!@127.0.0.1:5432/app"
+
+[gitignore]
+# Nothing: migrations/ is committed.
+lines = []
+
+# A PostgreSQL for DATABASE_URL to reach: `docker compose up -d database`.
+# Kept verbatim: ${...} is Compose's own interpolation, read from the shell or .env.
+[compose."compose.yaml"]
+services = '''
+  database:
+    image: postgres:${POSTGRES_VERSION:-16}-alpine
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB:-app}
+      # You should definitely change the password in production
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-!ChangeMe!}
+      POSTGRES_USER: ${POSTGRES_USER:-app}
+    healthcheck:
+      test: ["CMD", "pg_isready", "-d", "${POSTGRES_DB:-app}", "-U", "${POSTGRES_USER:-app}"]
+      timeout: 5s
+      retries: 5
+      start_period: 60s
+    volumes:
+      - database_data:/var/lib/postgresql/data:rw
+      # You may use a bind-mounted host directory instead, so that it is harder to accidentally remove the volume and lose all your data!
+      # - ./docker/db/data:/var/lib/postgresql/data:rw
+'''
+volumes = '''
+  database_data:
+'''
+
+# Development only: the database published on the port DATABASE_URL names.
+[compose."compose.override.yaml"]
+services = '''
+  database:
+    ports:
+      - "5432:5432"
+'''
+
+[notes]
+steps = [
+  "With the messenger bundle active, list the orm_* middleware in every bus's middleware: every message is then a unit of work.",
+]
+check = [
+  "<script> debug:bundles — orm is listed and active",
+  "<script> orm:migrations:status — it reaches the database",
+]
+run = ["docker compose up -d database — the PostgreSQL DATABASE_URL points at"]

xtr_orm-5.0.1/src/xtr_orm/recipe/manifest.toml

@@ -1,32 +0,0 @@
-# The recipe for xtr-orm: what *Use in an application* in the README takes, as
-# data. Keep the two in step — the README is the source.
-
-[bundles]
-# "<module>:<class>" = the environments it is listed with, exactly as in BUNDLES.
-"xtr_orm.bundle:OrmBundle" = { all = true }
-
-[files]
-# Destination under the application package = template under this recipe.
-# The default connection on DATABASE_URL, written out so the application has
-# one place to add replicas, connections and its models' metadata.
-"config/orm.py" = "files/config/orm.py.tmpl"
-
-[env]
-# Read when a connection is first used — engine, session, migrator or command —
-# not when the application boots. A local PostgreSQL to start from, for the
-# postgres extra the README installs; change it, or put the real one in
-# .env.local.
-DATABASE_URL = "postgresql+asyncpg://app:change-me@127.0.0.1:5432/app"
-
-[gitignore]
-# Nothing: migrations/ is committed.
-lines = []
-
-[notes]
-steps = [
-  "With the messenger bundle active, list the orm_* middleware in every bus's middleware: every message is then a unit of work.",
-]
-check = [
-  "<script> debug:bundles — orm is listed and active",
-  "<script> orm:migrations:status — it reaches the database",
-]