pyoq-sql 1.0.2__tar.gz → 1.0.3__tar.gz

{pyoq_sql-1.0.2 → pyoq_sql-1.0.3}/Cargo.lock

@@ -94,7 +94,7 @@ dependencies = [
 
 [[package]]
 name = "pyoq-native"
-version = "1.0.2"
+version = "1.0.3"
 dependencies = [
  "pyo3",
 ]

{pyoq_sql-1.0.2 → pyoq_sql-1.0.3}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pyoq-native"
-version = "1.0.2"
+version = "1.0.3"
 edition = "2024"
 description = "Native runtime for the PyOQ SQL toolkit"
 license = "MPL-2.0"

{pyoq_sql-1.0.2 → pyoq_sql-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyoq-sql
-Version: 1.0.2
+Version: 1.0.3
 Summary: A fully typed, database-first SQL toolkit for Python.
 Project-URL: Homepage, https://teqpod.com/pyoq-sql/
 Project-URL: Documentation, https://teqpod.com/pyoq-sql/overview/
@@ -166,6 +166,14 @@ structured server or pool value. Any other string is literal. Server profiles
 may alternatively define one `dsn`, but cannot combine it with structured
 connection fields.
 
+The default generation layout is flat and preserves the directory and import
+name above. An application with several databases can set
+`codegen-layout = "profiles"`, use the root output settings as bases, and put a
+`codegen-name` and `schema-snapshot` on each profile. With both output bases set
+to `generated`, a profile named `default` with `codegen-name = "database"`
+produces `generated.database`, while an `analytics` profile produces
+`generated.analytics` by default.
+
 `SecretValue` renders as `[REDACTED]`; access to its underlying value is always
 explicit. An explicit `Configuration` object takes precedence over the file,
 and the `selected_profile` argument can override profile selection. Unknown
@@ -1055,6 +1063,27 @@ dsl.select(TITLE_ID, TITLE_NAME, TITLE_PRICE) \
    .to_list()
 ```
 
+The same bound chain can show what it would send without running it:
+
+```python
+query = (
+    dsl.select(TITLE_ID, TITLE_NAME)
+    .from_(table_source(TITLES))
+    .where(TITLE_PRICE.gt(Decimal("10.00")))
+)
+
+print(query.sql())
+compiled = query.compile()
+print(compiled.parameters)
+```
+
+`sql()` uses the active database's quoting and placeholder style. It never
+interpolates values. `compile()` returns the same SQL together with its bound
+parameters, sensitive-parameter indexes, statement kind, and declared result
+types. Neither method executes, checks out a connection, records a query-budget
+use, or emits an execution event. The asynchronous DSL exposes the same two
+synchronous methods because compilation performs no I/O.
+
 A generated table names its own columns, so a query over all of them does not
 have to list them:
 
@@ -1282,12 +1311,41 @@ python manage.py pyoq_codegen --dry-run
 python manage.py pyoq_codegen --check
 ```
 
+For multiple Django aliases, use profile layout:
+
+```python
+PYOQ = {
+    "codegen_layout": "profiles",
+    "codegen_directory": "app/generated",
+    "codegen_package": "app.generated",
+    "databases": {
+        "default": {"codegen_name": "database"},
+        "reporting": {},
+    },
+}
+```
+
+```bash
+python manage.py pyoq_codegen --database reporting
+python manage.py pyoq_codegen --all-databases
+python manage.py pyoq_codegen --all-databases --check
+python manage.py pyoq_codegen --all-databases --dry-run
+```
+
+A single-alias run owns only that alias package. An all-database run loads and
+validates every configured alias before publishing the generated package base
+once, so one failure leaves every existing alias package unchanged.
+
 The schema comes from the migration files, not from a database. Migrations are
 what the schema is going to be, and a developer generating types has usually
 not applied them yet. Nothing connects: Django answers what column a field
 takes on a backend without consulting a server, so the alias selects the
 dialect rather than opening a socket.
 
+The selected alias also passes each historical model through Django's
+`allow_migrate` routers. Profile layout therefore produces a package for the
+tables eligible for each database, as well as using that alias's dialect.
+
 What that yields is the schema the database will really have, which is not
 always the one the models appear to describe:
 
@@ -1352,6 +1410,12 @@ def open_notes() -> SyncDatabase:
 app = FastAPI(lifespan=database_lifespan(synchronous={"default": open_notes}))
 ```
 
+For several databases, use profile-organized generation through the shared
+CLI and give the lifespan mapping the same names as those profiles. Each route
+then selects the matching alias, such as `database("reporting")`, while imports
+come from separate packages such as `generated.reporting.tables`. Generation
+does not run during application startup.
+
 A database that fails to open takes the application down, and the ones already
 open are given back first. Starting up halfway and serving requests against a
 partly opened application is worse than not starting.
@@ -1441,6 +1505,12 @@ async def open_notes() -> AsyncDatabase:
 attach_databases(app, asynchronous={"default": open_notes})
 ```
 
+For several databases, use profile-organized generation through the shared
+CLI and give the attachment mapping the same names as those profiles. A handler
+can then pair `database_of(request, "reporting")` with descriptors imported
+from `generated.reporting.tables`. Generation happens before server startup,
+never inside a worker.
+
 A database that fails to open takes the worker down, and the ones already open
 are given back first. Every one a worker opened is closed when it stops.
 
@@ -2954,6 +3024,8 @@ pyoq --version
 pyoq generate --project-root .
 pyoq generate --project-root . --check
 pyoq generate --project-root . --dry-run
+pyoq generate --project-root . --profile reporting
+pyoq generate --project-root . --all-profiles
 pyoq inspect --project-root .
 ```
 
@@ -2961,6 +3033,12 @@ Both database commands accept `--config` for a configuration file below the
 project root and `--profile` for explicit profile selection. `--check` and
 `--dry-run` are mutually exclusive.
 
+Generation defaults to one flat package. Set `codegen-layout = "profiles"` to
+treat `codegen-directory` and `codegen-package` as bases, then give any profile
+a `codegen-name` when its profile name is not the desired Python package
+segment. `--all-profiles` prepares every schema first and atomically publishes
+all changed profile packages. It cannot be combined with `--profile`.
+
 Command exit codes are stable:
 
 - `0`: success
@@ -2975,7 +3053,7 @@ primary and unique keys, indexes, CHECK constraints, and foreign-key
 relationships. Metadata is normalized before rendering, and the connection is
 closed before generated files are checked or written.
 
-Generation writes six deterministic, fully typed modules and an ownership
+Generation writes eight deterministic, fully typed modules and an ownership
 manifest into `codegen-directory`. Repeating a write against an unchanged
 database leaves the generated directory untouched. `--check` fails on drift,
 while `--dry-run` reports planned creation, update, removal, and conflict counts

{pyoq_sql-1.0.2 → pyoq_sql-1.0.3}/README.md

@@ -122,6 +122,14 @@ structured server or pool value. Any other string is literal. Server profiles
 may alternatively define one `dsn`, but cannot combine it with structured
 connection fields.
 
+The default generation layout is flat and preserves the directory and import
+name above. An application with several databases can set
+`codegen-layout = "profiles"`, use the root output settings as bases, and put a
+`codegen-name` and `schema-snapshot` on each profile. With both output bases set
+to `generated`, a profile named `default` with `codegen-name = "database"`
+produces `generated.database`, while an `analytics` profile produces
+`generated.analytics` by default.
+
 `SecretValue` renders as `[REDACTED]`; access to its underlying value is always
 explicit. An explicit `Configuration` object takes precedence over the file,
 and the `selected_profile` argument can override profile selection. Unknown
@@ -1011,6 +1019,27 @@ dsl.select(TITLE_ID, TITLE_NAME, TITLE_PRICE) \
    .to_list()
 ```
 
+The same bound chain can show what it would send without running it:
+
+```python
+query = (
+    dsl.select(TITLE_ID, TITLE_NAME)
+    .from_(table_source(TITLES))
+    .where(TITLE_PRICE.gt(Decimal("10.00")))
+)
+
+print(query.sql())
+compiled = query.compile()
+print(compiled.parameters)
+```
+
+`sql()` uses the active database's quoting and placeholder style. It never
+interpolates values. `compile()` returns the same SQL together with its bound
+parameters, sensitive-parameter indexes, statement kind, and declared result
+types. Neither method executes, checks out a connection, records a query-budget
+use, or emits an execution event. The asynchronous DSL exposes the same two
+synchronous methods because compilation performs no I/O.
+
 A generated table names its own columns, so a query over all of them does not
 have to list them:
 
@@ -1238,12 +1267,41 @@ python manage.py pyoq_codegen --dry-run
 python manage.py pyoq_codegen --check
 ```
 
+For multiple Django aliases, use profile layout:
+
+```python
+PYOQ = {
+    "codegen_layout": "profiles",
+    "codegen_directory": "app/generated",
+    "codegen_package": "app.generated",
+    "databases": {
+        "default": {"codegen_name": "database"},
+        "reporting": {},
+    },
+}
+```
+
+```bash
+python manage.py pyoq_codegen --database reporting
+python manage.py pyoq_codegen --all-databases
+python manage.py pyoq_codegen --all-databases --check
+python manage.py pyoq_codegen --all-databases --dry-run
+```
+
+A single-alias run owns only that alias package. An all-database run loads and
+validates every configured alias before publishing the generated package base
+once, so one failure leaves every existing alias package unchanged.
+
 The schema comes from the migration files, not from a database. Migrations are
 what the schema is going to be, and a developer generating types has usually
 not applied them yet. Nothing connects: Django answers what column a field
 takes on a backend without consulting a server, so the alias selects the
 dialect rather than opening a socket.
 
+The selected alias also passes each historical model through Django's
+`allow_migrate` routers. Profile layout therefore produces a package for the
+tables eligible for each database, as well as using that alias's dialect.
+
 What that yields is the schema the database will really have, which is not
 always the one the models appear to describe:
 
@@ -1308,6 +1366,12 @@ def open_notes() -> SyncDatabase:
 app = FastAPI(lifespan=database_lifespan(synchronous={"default": open_notes}))
 ```
 
+For several databases, use profile-organized generation through the shared
+CLI and give the lifespan mapping the same names as those profiles. Each route
+then selects the matching alias, such as `database("reporting")`, while imports
+come from separate packages such as `generated.reporting.tables`. Generation
+does not run during application startup.
+
 A database that fails to open takes the application down, and the ones already
 open are given back first. Starting up halfway and serving requests against a
 partly opened application is worse than not starting.
@@ -1397,6 +1461,12 @@ async def open_notes() -> AsyncDatabase:
 attach_databases(app, asynchronous={"default": open_notes})
 ```
 
+For several databases, use profile-organized generation through the shared
+CLI and give the attachment mapping the same names as those profiles. A handler
+can then pair `database_of(request, "reporting")` with descriptors imported
+from `generated.reporting.tables`. Generation happens before server startup,
+never inside a worker.
+
 A database that fails to open takes the worker down, and the ones already open
 are given back first. Every one a worker opened is closed when it stops.
 
@@ -2910,6 +2980,8 @@ pyoq --version
 pyoq generate --project-root .
 pyoq generate --project-root . --check
 pyoq generate --project-root . --dry-run
+pyoq generate --project-root . --profile reporting
+pyoq generate --project-root . --all-profiles
 pyoq inspect --project-root .
 ```
 
@@ -2917,6 +2989,12 @@ Both database commands accept `--config` for a configuration file below the
 project root and `--profile` for explicit profile selection. `--check` and
 `--dry-run` are mutually exclusive.
 
+Generation defaults to one flat package. Set `codegen-layout = "profiles"` to
+treat `codegen-directory` and `codegen-package` as bases, then give any profile
+a `codegen-name` when its profile name is not the desired Python package
+segment. `--all-profiles` prepares every schema first and atomically publishes
+all changed profile packages. It cannot be combined with `--profile`.
+
 Command exit codes are stable:
 
 - `0`: success
@@ -2931,7 +3009,7 @@ primary and unique keys, indexes, CHECK constraints, and foreign-key
 relationships. Metadata is normalized before rendering, and the connection is
 closed before generated files are checked or written.
 
-Generation writes six deterministic, fully typed modules and an ownership
+Generation writes eight deterministic, fully typed modules and an ownership
 manifest into `codegen-directory`. Repeating a write against an unchanged
 database leaves the generated directory untouched. `--check` fails on drift,
 while `--dry-run` reports planned creation, update, removal, and conflict counts

{pyoq_sql-1.0.2 → pyoq_sql-1.0.3}/docs/web/astro.config.mjs

@@ -8,6 +8,15 @@ import { remarkLicence } from "./src/remark-licence.mjs";
 import { remarkMermaid } from "./src/remark-mermaid.mjs";
 import { remarkPairs } from "./src/remark-pairs.mjs";
 
+const base = process.env.DOCS_BASE ?? "/";
+
+/** Astro puts the base in front of where a redirect comes from, not where it
+ * goes, so the destination is built from the same value the rest of the site
+ * is. Written plainly it would send a reader to a path the host does not
+ * serve. */
+/** @param {string} path */
+const under = (path) => `${base}/${path}`.replace(/\/{2,}/g, "/");
+
 // The site is a directory of files when it is built, so it works from a
 // bucket, a static host, or a laptop without anything running behind it.
 export default defineConfig({
@@ -19,6 +28,10 @@ export default defineConfig({
   site: process.env.DOCS_SITE,
   base: process.env.DOCS_BASE ?? "/",
   build: { format: "directory" },
+  // The reference index was published at its old address before it moved into
+  // the API section. A link that already exists is not a link that can be
+  // corrected, so the old address still leads somewhere.
+  redirects: { "/reference": under("api/references") },
   vite: {
     // The package metadata sits above this directory, and src/project.ts reads
     // the licence straight out of it.

{pyoq_sql-1.0.2 → pyoq_sql-1.0.3}/docs/web/package.json

@@ -2,7 +2,7 @@
   "name": "pyoq-docs",
   "private": true,
   "type": "module",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "scripts": {
     "dev": "astro dev",
     "build": "astro build && pagefind --site dist",

{pyoq_sql-1.0.2 → pyoq_sql-1.0.3}/docs/web/src/content/docs/agents.md

@@ -73,7 +73,7 @@ for every task.
 | Query limits and observability | `src/pyoq/policies`, `src/pyoq/diagnostics` | [Policies](../policies/) |
 | Framework lifecycle | `src/pyoq/django`, `src/pyoq/fastapi`, `src/pyoq/sanic` | [Framework routing](#framework-routing) |
 | Native runtime selection | `src/pyoq/runtime` | [Performance](../performance/) |
-| Supported public names | Package `__init__.py` files | [API reference](../reference/) |
+| Supported public names | Package `__init__.py` files | [API reference](../api/references/) |
 
 Tests mirror the source layout. Start with the matching directory under
 `tests`, then inspect `tests/contracts` when behavior must be identical across
@@ -106,6 +106,11 @@ only when the required values have been supplied. Generated files must be
 changed through the schema model and renderer, never by editing generated
 output.
 
+Generation has two layouts. Flat layout writes one package and is the default.
+Profile layout writes one package per database below a shared base. Each has an
+isolated manifest. An all-profile run prepares every schema and publishes the
+base once, so no profile may write before every plan has validated.
+
 See [Generating your types](../generating/), [Inserting rows](../inserting/),
 and [Updating and deleting](../updating/) for complete application examples.
 
@@ -184,6 +189,11 @@ Shared reflection, generation, compilation, decoding, pooling, and transaction
 behavior belongs in the core package. An adapter should translate framework
 lifecycle and configuration into those shared services.
 
+Django profile generation maps configured database aliases to core generation
+profiles. One alias owns one generated package and manifest. An all-database
+run must use the shared atomic profile publication path rather than looping
+over single-profile writes.
+
 ## Invariants an agent must preserve
 
 - Query trees and schema value objects remain immutable.

pyoq_sql-1.0.3/docs/web/src/content/docs/alembic.md

@@ -0,0 +1,136 @@
+---
+title: "Alembic"
+summary: "Keeping the snapshot and the generated package in step with your migrations."
+---
+
+Alembic owns the schema. PyOQ reads it. Nothing about that changes when you use
+both: Alembic writes and applies migrations exactly as it did, and PyOQ needs
+one thing from you, which is to be told when the database has moved.
+
+There is no extra to install and no adapter to configure. PyOQ never opens a
+connection through Alembic and never takes part in a migration.
+
+## What has to happen, and in what order
+
+After a migration is applied, two things are behind:
+
+1. The recorded schema snapshot, which still describes the old database.
+2. The generated package, which was generated from that snapshot.
+
+They have to catch up in that order, because generation reads the snapshot.
+Doing it the other way regenerates the old package and makes the update look
+complete when it is not.
+
+`after_migration_at` does both, in order.
+
+## Where to put it
+
+### In `env.py`, once the migrations have run
+
+The project owns `env.py`, so this is the place with the most context.
+
+```python
+from pathlib import Path
+
+from alembic import context
+from pyoq.migrations import after_migration_at
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+
+
+def run_migrations_online() -> None:
+    connectable = engine_from_config(
+        config.get_section(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()
+
+    # The database has moved. Bring the snapshot and the package back in step.
+    after_migration_at(PROJECT_ROOT)
+```
+
+Put it after the `with` block, not inside it. Inside, the migration has not
+committed yet, and reflection would read a schema no other connection can see.
+
+### Or as a step of its own
+
+```bash
+alembic upgrade head && pyoq-after-migration
+```
+
+The command takes a project directory, or nothing and uses the working
+directory. `&&` matters: if the upgrade fails there is nothing to catch up to.
+
+## Not as a post-write hook
+
+This is the one thing that looks right and is not.
+
+```toml
+# Do not do this.
+[post_write_hooks]
+hooks = pyoq
+pyoq.type = console_scripts
+pyoq.entrypoint = pyoq-after-migration
+```
+
+A post-write hook runs inside `alembic revision`, which **writes a revision
+file**. It does not apply one. The database at that moment is still whatever it
+was, so recording the schema there records the schema the migration is about to
+replace, and generates from it. The package would then describe the old
+database while the migration sits unapplied.
+
+Alembic hands a hook the file it has just written, and that is how PyOQ notices:
+being given a file rather than a directory is refused, with a message saying
+so, rather than quietly recording the wrong schema.
+
+## What you get back
+
+```python
+outcome = after_migration_at(PROJECT_ROOT)
+print(outcome.describe())
+```
+
+`MigrationOutcome` carries what each step reported, as `recorded` and
+`generated`, and `describe()` puts both on one line worth logging.
+
+If your project has more than one profile, name the one the migration touched:
+
+```python
+after_migration_at(PROJECT_ROOT, selected_profile="primary")
+```
+
+A caller that already holds a `Configuration` can use
+[`after_migration`](../api/migrations/) instead, which takes it directly.
+
+## In a pipeline
+
+Where production has no credentials and no code generation, make the snapshot
+and the generated package build artifacts instead:
+
+1. Apply the migration in an integration environment.
+2. Run `pyoq-after-migration`, or the hook from `env.py`.
+3. Run `pyoq drift` and `pyoq generate --check`.
+4. Run the type checks and the tests.
+5. Ship the reviewed package and snapshot.
+
+Steps 3 and 4 are what catch a migration that changed something the code did
+not expect: `--check` fails when the generated package is not what the schema
+now implies, and the type checker fails where code still reads a column that
+moved.
+
+## What can go wrong
+
+| Symptom | Cause |
+| --- | --- |
+| The hook refuses, saying it was given a file | It is wired as a post-write hook. Move it after `alembic upgrade`. |
+| The snapshot records the pre-migration schema | The call sits inside the `begin_transaction()` block, before the commit. |
+| `pyoq generate --check` fails in CI after a migration | The catch-up step did not run, or ran before the upgrade. |
+| The package regenerated but is unchanged | Generation ran before the snapshot was re-recorded. `after_migration_at` does both in the right order. |
+
+See [Migration lifecycle](../migrations/) for the same ground without Alembic,
+and [pyoq commands](../api/commands/) for what `pyoq-after-migration` exits
+with.

pyoq_sql-1.0.3/docs/web/src/content/docs/api/cli.md

@@ -0,0 +1,79 @@
+---
+title: "pyoq.cli"
+summary: "Running the command line from Python, and what each exit code means."
+---
+
+The command line as a Python entry point. [Command line](../../cli/) covers the
+commands themselves and their arguments; this is how to invoke them from code,
+which is what a test or a wrapper script wants.
+
+The package installs two commands, `pyoq` and `pyoq-after-migration`, and
+`python -m pyoq` runs the same thing through `pyoq.__main__`.
+
+## `main`
+
+```python
+main(
+    arguments: Sequence[str] | None = None,
+    *,
+    services: CommandServices | None = None,
+    output: IO[str] | None = None,
+    error: IO[str] | None = None,
+) -> int
+```
+
+Runs one command and **returns** its exit code rather than exiting, which is
+what makes it usable from a test.
+
+| Argument | What it is for |
+| --- | --- |
+| `arguments` | The words after `pyoq`. Omitted, it reads `sys.argv`. |
+| `services` | The services the command runs against, so a test can supply its own. |
+| `output` | Where ordinary output goes. Defaults to standard output. |
+| `error` | Where errors go. Defaults to standard error. |
+
+```python
+from pyoq.cli import ExitCode, main
+
+assert main(["generate", "--check"]) == ExitCode.SUCCESS
+```
+
+## `run`
+
+```python
+run(arguments: Sequence[str] | None = None) -> NoReturn
+```
+
+The same, but exits the process with that code rather than returning it. This
+is what the installed `pyoq` command calls, and it never returns.
+
+## `CommandServices`
+
+*dataclass* — what a command runs against, in `pyoq.cli.services`. Passing your
+own is how a test drives a command without a database.
+
+| Field | What it does |
+| --- | --- |
+| `generation` | Runs `generate`. |
+| `inspection` | Runs `inspect`. |
+| `snapshot` | Runs `snapshot`. |
+| `drift` | Runs `drift`. |
+
+The same type is accepted by [`after_migration`](../migrations/), which runs
+two of those steps.
+
+## `ExitCode`
+
+*enum of `int`* — what the process exits with, so a shell can tell one failure
+from another.
+
+| Member | Value | Means |
+| --- | --- | --- |
+| `SUCCESS` | `0` | The command did what was asked. |
+| `COMMAND_FAILED` | `1` | It ran and reported a failure, such as generated output being out of date. |
+| `USAGE` | `2` | The arguments were wrong. |
+| `CONFIGURATION` | `3` | Configuration was missing, unreadable, or invalid. |
+| `UNAVAILABLE` | `4` | The command is not available for this dialect or this build. |
+
+Because the members are integers, `main(...) == 0` works, and a shell reading
+`$?` sees the same numbers.