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

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

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

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyoq-sql
-Version: 1.0.1
+Version: 1.0.2
 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/
@@ -128,7 +128,14 @@ selected-profile = "default"
 
 [tool.pyoq.profiles.default]
 dialect = "postgres"
-dsn = "${DATABASE_URL}"
+host = "localhost"
+port = 5432
+database = "${POSTGRES_DATABASE}"
+username = "${POSTGRES_USERNAME}"
+password = "${POSTGRES_PASSWORD}"
+minimum-pool-size = 1
+maximum-pool-size = 8
+pool-checkout-timeout = 3.0
 
 [tool.pyoq.profiles.testing]
 dialect = "sqlite"
@@ -139,26 +146,25 @@ Open the selected profile through the fully typed lifecycle API:
 
 ```python
 from pyoq import connect
-from pyoq.query.execution import PoolPolicy
 from application.database.tables import ACCOUNT
 
 
-with connect(
-    profile="default",
-    pool_policy=PoolPolicy(maximum_size=8),
-) as database:
+with connect(profile="default") as database:
     rows = database.select_from(ACCOUNT).limit(10).fetch_all()
 ```
 
 Omit `profile` to use `selected-profile`. The context creates one process-owned
-pool and closes it on exit. A framework-free application can instead pass a
-data source directly with `connect(dsn, dialect=Dialect.MYSQL)`.
+pool from the profile limits and closes it on exit. A framework-free
+application can instead pass a data source directly with
+`connect(dsn, dialect=Dialect.MYSQL)`. An explicit `pool_policy` replaces the
+complete profile pool policy for one call.
 
 SQLite file paths use `database-path`. They are resolved relative to the project
 root, must remain inside it, and are opened read-only during inspection. An
-environment reference in the exact `${VARIABLE_NAME}` form may be used instead
-when the database location should be supplied by the process environment. Any
-other `dsn` value is literal. A profile cannot define both settings.
+environment reference in the exact `${VARIABLE_NAME}` form may be used for any
+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.
 
 `SecretValue` renders as `[REDACTED]`; access to its underlying value is always
 explicit. An explicit `Configuration` object takes precedence over the file,

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

@@ -84,7 +84,14 @@ selected-profile = "default"
 
 [tool.pyoq.profiles.default]
 dialect = "postgres"
-dsn = "${DATABASE_URL}"
+host = "localhost"
+port = 5432
+database = "${POSTGRES_DATABASE}"
+username = "${POSTGRES_USERNAME}"
+password = "${POSTGRES_PASSWORD}"
+minimum-pool-size = 1
+maximum-pool-size = 8
+pool-checkout-timeout = 3.0
 
 [tool.pyoq.profiles.testing]
 dialect = "sqlite"
@@ -95,26 +102,25 @@ Open the selected profile through the fully typed lifecycle API:
 
 ```python
 from pyoq import connect
-from pyoq.query.execution import PoolPolicy
 from application.database.tables import ACCOUNT
 
 
-with connect(
-    profile="default",
-    pool_policy=PoolPolicy(maximum_size=8),
-) as database:
+with connect(profile="default") as database:
     rows = database.select_from(ACCOUNT).limit(10).fetch_all()
 ```
 
 Omit `profile` to use `selected-profile`. The context creates one process-owned
-pool and closes it on exit. A framework-free application can instead pass a
-data source directly with `connect(dsn, dialect=Dialect.MYSQL)`.
+pool from the profile limits and closes it on exit. A framework-free
+application can instead pass a data source directly with
+`connect(dsn, dialect=Dialect.MYSQL)`. An explicit `pool_policy` replaces the
+complete profile pool policy for one call.
 
 SQLite file paths use `database-path`. They are resolved relative to the project
 root, must remain inside it, and are opened read-only during inspection. An
-environment reference in the exact `${VARIABLE_NAME}` form may be used instead
-when the database location should be supplied by the process environment. Any
-other `dsn` value is literal. A profile cannot define both settings.
+environment reference in the exact `${VARIABLE_NAME}` form may be used for any
+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.
 
 `SecretValue` renders as `[REDACTED]`; access to its underlying value is always
 explicit. An explicit `Configuration` object takes precedence over the file,

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

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

{pyoq_sql-1.0.1 → pyoq_sql-1.0.2}/docs/web/src/code-head.mjs

@@ -22,7 +22,15 @@ const COPY_ICON =
 const DONE_ICON =
   '<svg class="i-done" viewBox="0 0 16 16" aria-hidden="true"><path d="m3.5 8.4 3 3 6-6.4" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/></svg>';
 
+/** Languages that are a session at a prompt rather than a file of code. */
+const TERMINALS = new Set(["bash", "sh", "shell", "zsh", "console"]);
+
+export function isTerminal(language) {
+  return TERMINALS.has((language ?? "").toLowerCase());
+}
+
 export function label(language) {
+  if (isTerminal(language)) return "Terminal";
   if (!language) return "Text";
   return LABELS[language] ?? language.toUpperCase();
 }

{pyoq_sql-1.0.1 → pyoq_sql-1.0.2}/docs/web/src/components/CodeEditors.astro

@@ -145,7 +145,12 @@
 
   async function enhance() {
     const shells = [
-      ...document.querySelectorAll<HTMLElement>(".code-shell:not([data-ready])"),
+      // A terminal keeps the block it was built with. An editor would give a
+      // typed command line numbers and a folding margin, which is a file's
+      // furniture, not a prompt's.
+      ...document.querySelectorAll<HTMLElement>(
+        ".code-shell:not([data-ready]):not([data-terminal])",
+      ),
     ];
     if (!shells.length) return;
 

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

@@ -121,7 +121,10 @@ Framework-free synchronous applications should enter `connect()` once at their
 composition root. It can load the selected `pyproject.toml` profile or accept a
 direct data source with `Dialect`. The yielded `Database` is a `DslContext` with
 transactions, streaming, and pool statistics. The context owns and closes its
-pool. Do not enter it for every repository operation.
+pool. Structured server profiles keep host, port, database, username, password,
+and pool limits in one configuration source. A complete `${VARIABLE_NAME}`
+value resolves from the process environment; every other string is literal.
+Do not enter the context for every repository operation.
 
 Use the pure query API for reusable statements, compilation tests, advanced
 features, and code that should not know how connections are owned. Use the

pyoq_sql-1.0.2/docs/web/src/content/docs/configuration.md

@@ -0,0 +1,262 @@
+---
+title: "Configuration"
+summary: "Every setting PyOQ reads, and where it reads it from."
+---
+
+Configuration lives in `pyproject.toml`, under `[tool.pyoq]`. A server profile
+can keep its connection and pool settings as separate values. Each value is
+literal unless the entire value has the `${VARIABLE_NAME}` form.
+
+```toml
+[tool.pyoq]
+codegen-directory = "generated/database"
+codegen-package = "application.database"
+selected-profile = "default"
+
+[tool.pyoq.profiles.default]
+dialect = "postgres"
+host = "database.internal"
+port = 5432
+database = "${POSTGRES_DATABASE}"
+username = "${POSTGRES_USERNAME}"
+password = "${POSTGRES_PASSWORD}"
+minimum-pool-size = 1
+maximum-pool-size = 8
+pool-checkout-timeout = 3.0
+
+[tool.pyoq.profiles.testing]
+dialect = "sqlite"
+database-path = "database/testing.sqlite"
+```
+
+## Top level
+
+| Setting | Means |
+| --- | --- |
+| `codegen-directory` | where the generated package is written, relative to the project root |
+| `codegen-package` | its importable name |
+| `selected-profile` | which profile a command uses when none is named |
+| `schema-snapshot` | where the recorded schema is kept, relative to the project root, and inside it |
+| `profiles` | the profiles themselves |
+
+When omitted, `codegen-directory` and `codegen-package` both default to
+`pyoq_generated`, and `selected-profile` defaults to `default`. Profiles are
+never invented; at least one must be configured.
+
+`codegen-directory` must stay inside the project root. A path that escapes it
+is refused, because generation replaces what is there and a path that walks
+out of the project is a way to replace something else.
+
+## A profile
+
+| Setting | Means |
+| --- | --- |
+| `dialect` | `sqlite`, `postgres`, or `mysql` |
+| `dsn` | a literal connection string, or a complete `${VARIABLE_NAME}` environment reference |
+| `dsn-environment` | the legacy form containing only an environment variable name |
+| `database-path` | a SQLite file, relative to the project root |
+| `host` | server host, defaulting to `localhost` |
+| `port` | server port, defaulting to `5432` for PostgreSQL or `3306` for MySQL |
+| `database` | server database name |
+| `username` | server user name |
+| `password` | optional server password |
+| `minimum-pool-size` | connections opened with the pool, defaulting to `0` |
+| `maximum-pool-size` | maximum connections in this process, defaulting to `5` |
+| `pool-checkout-timeout` | seconds to wait for a connection, defaulting to `30.0` |
+
+### Every way to name a database
+
+A profile names its database in exactly one of the ways below. They cannot be
+combined: a profile that mixes them is refused rather than resolved in some
+order you would have to know.
+
+**Every part named separately.** What a deployment that already holds its parts
+separately can use directly.
+
+```toml
+[tool.pyoq.profiles.default]
+dialect = "postgres"
+host = "database.internal"
+port = 5432
+database = "shop"
+username = "shop_service"
+password = "${POSTGRES_PASSWORD}"
+```
+
+`database` and `username` are required once any structured field is present.
+`host` defaults to `localhost`, and `port` to `5432` for PostgreSQL or `3306`
+for MySQL. PyOQ percent-encodes the credentials and the database name while
+building the connection, so a password containing `@`, `#` or `/` needs no
+escaping from you.
+
+**One connection string.**
+
+```toml
+[tool.pyoq.profiles.default]
+dialect = "mysql"
+dsn = "mysql://shop_service:p%40ssw0rd@localhost:3306/shop"
+```
+
+Here the escaping is yours: those same characters divide a URL, so a password
+containing one has to be percent-encoded before it goes in.
+
+**A connection string kept out of the file.** The same thing, with nothing
+secret committed:
+
+```toml
+[tool.pyoq.profiles.default]
+dialect = "mysql"
+dsn = "${MYSQL_DATABASE_URL}"
+```
+
+**A variable name, the older form.** `dsn-environment` holds the *name* of a
+variable and never a connection string:
+
+```toml
+[tool.pyoq.profiles.default]
+dialect = "mysql"
+dsn-environment = "MYSQL_DATABASE_URL"
+```
+
+It stays accepted for projects already using it. `dsn = "${MYSQL_DATABASE_URL}"`
+says the same thing in the form every other setting uses.
+
+**A SQLite file.**
+
+```toml
+[tool.pyoq.profiles.testing]
+dialect = "sqlite"
+database-path = "database/testing.sqlite"
+```
+
+The path is resolved against the project root, must stay inside it, and is
+opened read-only while inspecting. A SQLite profile can use `dsn` instead, and
+cannot use the structured fields. A schema source provided by an integration,
+such as Django migration state, can use a profile that names no database at
+all, because it never inspects a live one.
+
+### Literal, or read from the environment
+
+Every profile setting is a literal unless the whole value has the
+`${VARIABLE_NAME}` form. Nothing is looked up unless it asks to be.
+
+| Written | Used as |
+| --- | --- |
+| `"shop_service"` | that text |
+| `"PATH"` | that text, not the variable of that name |
+| `"${DB_USER}"` | the value of `DB_USER` |
+| `"$DB_USER"` | that text, because there are no braces |
+| `"pre${DB_USER}"` | refused |
+
+A value that is part reference and part text is refused rather than read as a
+literal. Read as a literal it would be used as typed, so a password meant to
+come from the environment would be sent as the text that asks for it, and the
+first sign of the mistake would be a server refusing the connection.
+
+A reference to a variable that is not set is an error, not an empty value.
+PyOQ does not load `.env` files: export the variables before running a command.
+Do not commit a literal that carries credentials.
+
+### Pool settings
+
+Pool settings are per profile, and take a number or a reference resolving to
+one. They apply to whichever way the database was named.
+
+```toml
+[tool.pyoq.profiles.default]
+dialect = "postgres"
+dsn = "${POSTGRES_DATABASE_URL}"
+minimum-pool-size = 1
+maximum-pool-size = "${POSTGRES_POOL_SIZE}"
+pool-checkout-timeout = 3.0
+```
+
+The [framework-free MySQL application](../mysql-application/) follows this
+profile through generation, runtime settings, pool ownership, repositories,
+transactions, and process shutdown.
+
+## Opening the selected profile
+
+The same profile can own the application database lifecycle:
+
+```python
+from pathlib import Path
+
+from pyoq import connect
+with connect(
+    profile="default",
+    project_root=Path.cwd(),
+) as database:
+    run_application(database)
+```
+
+Omit `profile` to use `selected-profile`. Pool settings from that profile are
+used automatically. An explicit `pool_policy=PoolPolicy(...)` replaces all
+profile pool settings for that call. This synchronous convenience API supports
+all three dialects. Framework integrations and asynchronous applications use
+their dedicated lifecycle APIs.
+
+## The project root
+
+The project root is the containment boundary, not a search result. PyOQ does
+not walk upward looking for configuration. Commands default it to the current
+working directory and read `pyproject.toml` there unless `--config` names
+another file inside the same root.
+
+Configured output, snapshots, SQLite database paths, and relative configuration
+paths must stay inside this directory. This prevents a mistaken command from
+replacing files in a parent or unrelated project.
+
+## Selecting a profile
+
+`selected-profile` is the default for every command. Override it for one run:
+
+```bash
+pyoq inspect --project-root . --profile testing
+```
+
+The override does not edit configuration. It only selects one of the profiles
+already declared in the file.
+
+## Reading it yourself
+
+```python
+from pathlib import Path
+from pyoq.config import load_configuration
+
+configuration = load_configuration(Path.cwd())
+database_url = configuration.active_profile.resolve_dsn()
+if database_url is not None:
+    connect_value = database_url.reveal()
+```
+
+A resolved secret is a value you have to ask to see. `reveal()` is a
+deliberate call, so a connection string never lands in a log through an
+ordinary `repr`.
+
+## Unknown settings are refused
+
+A setting PyOQ does not recognise raises
+`UnknownConfigurationSettingError` rather than being ignored. A misspelled
+key that is quietly skipped is a setting that silently does nothing, and the
+usual way to find out is in production.
+
+## Under Django
+
+There is no TOML. Django settings hold the same facts:
+
+```python
+PYOQ = {
+    "codegen_directory": "app/schema",
+    "codegen_package": "app.schema",
+}
+```
+
+See [Django](/django/) for the full list.
+
+## What is deliberately not configurable
+
+Generated output is not formatted to taste, and the generated directory is
+owned entirely by the generator. Both are so that regenerating is safe: a
+directory PyOQ shares with hand-written files is a directory it cannot
+replace.

{pyoq_sql-1.0.1 → pyoq_sql-1.0.2}/docs/web/src/content/docs/connections.md

@@ -9,21 +9,25 @@ application process, then leave its context during application shutdown.
 
 ## Connect from a profile
 
-With a profile in the current project's `pyproject.toml`, connection ownership
-is one context:
+With a profile in the current project's `pyproject.toml`, connection and pool
+ownership are one context:
+
+```toml
+[tool.pyoq.profiles.default]
+dialect = "mysql"
+host = "localhost"
+port = 3306
+database = "${MYSQL_DATABASE}"
+username = "${MYSQL_USERNAME}"
+password = "${MYSQL_PASSWORD}"
+minimum-pool-size = 1
+maximum-pool-size = 8
+pool-checkout-timeout = 2.0
+```
 
 ```python
 from pyoq import connect
-from pyoq.query.execution import PoolPolicy
-
-
-policy = PoolPolicy(
-    minimum_size=1,
-    maximum_size=8,
-    checkout_timeout=2.0,
-)
-
-with connect(profile="default", pool_policy=policy) as database:
+with connect(profile="default") as database:
     rows = database.select_from(TITLES).fetch_all()
 ```
 
@@ -32,8 +36,10 @@ Omit `profile` to use `selected-profile`. Configuration is read from
 the application starts elsewhere, or `config=Path("config/database.toml")`
 for another file inside that root.
 
-The same profile drives generation and runtime, so its dialect and data source
-are not repeated in application code.
+The same profile drives generation and runtime, so its dialect, connection,
+and pool policy are not repeated in application code. Pass an explicit
+`pool_policy=PoolPolicy(...)` only when one process needs to replace the entire
+profile policy.
 
 ## Connect directly
 
@@ -42,8 +48,10 @@ Programs that do not have a project configuration can supply both values:
 ```python
 from pyoq import Dialect, connect
 from pyoq.config import DataSourceName
+from pyoq.query.execution import PoolPolicy
 
 
+policy = PoolPolicy(maximum_size=8)
 with connect(
     DataSourceName("${DATABASE_URL}"),
     dialect=Dialect.POSTGRES,
@@ -106,7 +114,7 @@ operations, and where transactions and shutdown belong.
 application run:
 
 ```python
-with connect(profile="default", pool_policy=policy) as database:
+with connect(profile="default") as database:
     rows = database.select_from(TITLES).fetch_all()
 ```
 

{pyoq_sql-1.0.1 → pyoq_sql-1.0.2}/docs/web/src/content/docs/installing.md

@@ -5,10 +5,22 @@ summary: "The distribution, the extras, and what each one pulls in."
 
 PyOQ is published as **`pyoq-sql`** and imported as **`pyoq`**.
 
+With uv:
+
+```bash
+uv add pyoq-sql
+```
+
+With pip:
+
 ```bash
 pip install pyoq-sql
 ```
 
+`uv add` records it in `pyproject.toml` and the lockfile. To install into an
+environment without recording anything, `uv pip install pyoq-sql` takes the
+same arguments pip does.
+
 A plain install has **no dependencies at all**. SQLite works immediately,
 because Python already ships it.
 
@@ -26,7 +38,16 @@ Everything else is opt in, so a project pulls in only the drivers it uses.
 | `sanic` | `sanic` | the Sanic integration |
 | `tracing` | `opentelemetry-api` | reporting statements to OpenTelemetry |
 
-Combine them as needed:
+Combine them as needed. Quote the name: a shell reads square brackets itself.
+
+With uv:
+
+```bash
+uv add "pyoq-sql[postgres,fastapi]"
+uv add "pyoq-sql[django,mysql]"
+```
+
+With pip:
 
 ```bash
 pip install "pyoq-sql[postgres,fastapi]"
@@ -39,11 +60,27 @@ turns out to speak it.
 
 ## Checking what you have
 
+Inside a uv project:
+
+```bash
+uv run python -c "import pyoq; print(pyoq.__version__)"
+uv run pyoq --version
+```
+
+Or in an activated environment:
+
 ```bash
 python -c "import pyoq; print(pyoq.__version__)"
 pyoq --version
 ```
 
+The command line can also be run without installing PyOQ into the project at
+all, which is enough to read its help or check a version:
+
+```bash
+uvx --from pyoq-sql pyoq --version
+```
+
 ## Python
 
 3.11 and later. The typed builders lean on `TypeVarTuple` and modern union