l3io-wordpress-database 0.3.5__tar.gz

l3io_wordpress_database-0.3.5/.gitignore

@@ -0,0 +1,23 @@
+__pycache__
+.coverage
+.DS_Store
+.vscode
+build
+dist
+htmlcov
+*.egg-info
+coverage.xml
+.pytest_cache
+.mypy_cache
+.ruff_cache
+.venv
+dist-verify
+# Local age ≥1.3 + batchpass binaries for CLI passphrase tests (not shipped).
+.tools/
+
+# BMad agent definitions: tool output, regenerated by the installer.
+.github/agents/
+
+# Subagent-driven-development scratch: ledgers, briefs, review packages.
+.superpowers/
+.cache/

l3io_wordpress_database-0.3.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shawn Anderson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

l3io_wordpress_database-0.3.5/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.5
+Name: l3io-wordpress-database
+Version: 0.3.5
+Summary: Create and inspect WordPress MySQL databases and their users, idempotently.
+Project-URL: Homepage, https://github.com/LiquidLogicLabs/l3io-wordpress-database
+Project-URL: Source, https://github.com/LiquidLogicLabs/l3io-wordpress-database
+Author: Shawn Anderson
+License-Expression: MIT
+License-File: LICENSE
+Keywords: database,mariadb,mysql,provisioning,wordpress
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: opentelemetry-api<2,>=1.30
+Requires-Dist: pymysql[rsa]<2,>=1.2
+Requires-Dist: structlog<27,>=26.1
+Provides-Extra: aws
+Requires-Dist: boto3<2,>=1.34; extra == 'aws'
+Provides-Extra: encryption
+Requires-Dist: l3io-age-passphrase<0.2,>=0.1.1; extra == 'encryption'
+Requires-Dist: pyrage<2,>=1.4; extra == 'encryption'
+Provides-Extra: wpconfig
+Requires-Dist: l3io-wordpress-config<0.2,>=0.1.2; extra == 'wpconfig'
+Description-Content-Type: text/markdown
+
+# l3io-wordpress-database
+
+The operations a WordPress site performs against its MySQL or MariaDB database:
+inspecting it, provisioning it, changing its accounts, destroying it, and exporting
+and importing it. Every operation acts with credentials the caller supplies, and
+every operation that changes or moves something can be checked before it runs.
+
+It imports as `l3io.wp.database`, in the `l3io.wp` namespace shared with
+`l3io-wordpress-config` and `l3io-wordpress-backup`.
+
+> **Status:** 0.x — documented and typed, with no stability promise until 1.0.0.
+> Not yet on PyPI; releases are on
+> [GitHub](https://github.com/LiquidLogicLabs/l3io-wordpress-database/releases).
+
+## Installing
+
+```shell
+pip install l3io-wordpress-database                # core: PyMySQL, structlog, opentelemetry-api
+pip install 'l3io-wordpress-database[aws]'         # credentials from AWS Secrets Manager
+pip install 'l3io-wordpress-database[wpconfig]'    # credentials and location from wp-config.php
+pip install 'l3io-wordpress-database[encryption]'  # age-encrypted dumps
+```
+
+An optional dependency is an optional import: a base install never imports
+`boto3`, the config reader or `pyrage`, and asking for a feature whose extra is
+absent raises `MissingDependencyError` naming the extra.
+
+## Two accounts
+
+WordPress's own account — the one in `wp-config.php` — is the account that is
+created and granted. A separate administrative account does the creating, and is
+never defaulted to the WordPress account. Whether a database exists is answered
+by the administrator: a server authenticates before it resolves the database, so a
+failed login by the WordPress account says nothing about the database.
+
+## Check, then run
+
+```python
+from l3io.wp.database import Connection, Database, Environment, Explicit
+
+db = Database(Connection("127.0.0.1", "wp_site"))
+admin = Environment("DB_ADMIN_USER", "DB_ADMIN_PASSWORD")
+wordpress = Explicit("wpuser", "wp-pass")
+
+verdict = db.check_ensure(admin, wordpress)
+for finding in verdict.findings:
+    print(finding.severity, finding.code, finding.message)
+
+if verdict.ok:
+    result = db.ensure(admin, wordpress)
+    print(result.created_database, result.created_user, result.granted, result.changed)
+```
+
+`ensure` runs the same check itself and raises `RefusedError`, carrying the
+`Verdict`, on any blocker. It creates only what is missing, and a second run
+against a converged server changes nothing. Grants are scoped to the one database,
+with the `_` and `%` wildcards in its name escaped.
+
+Destructive operations — `revoke`, `drop_user`, `drop_database` — take
+`confirm=`, which must repeat the target's name.
+
+## From wp-config.php
+
+```python
+from l3io.wp.database import Database, Environment, WpConfigFile
+
+site = WpConfigFile("/var/www/html/wp-config.php")
+db = Database(site.connection())
+survey = db.survey(
+    Environment("DB_ADMIN_USER", "DB_ADMIN_PASSWORD"),
+    wordpress_user=site.resolve().username,
+    table_prefix=site.table_prefix,
+)
+print(survey.database_exists, survey.table_count, survey.is_wordpress, survey.schema_version)
+```
+
+`inspect` asks the WordPress account itself what it can do, and never raises
+for an ordinary failure:
+
+| State | Meaning |
+|---|---|
+| `ready` | connected, authenticated, and the database is usable |
+| `database_absent` | authenticated, but the database does not exist |
+| `access_denied` | authenticated, but may not use this database |
+| `authentication_failed` | the server rejected the account |
+| `unreachable` | the server could not be reached |
+| `credentials_unobtainable` | the credentials could not be obtained; nothing was attempted |
+
+## Export and import
+
+```python
+from l3io.wp.database import (
+    Connection,
+    Database,
+    Environment,
+    WpConfigFile,
+    encrypt,
+    generate_identity,
+)
+
+site = WpConfigFile("/var/www/html/wp-config.php")
+identity, recipient = generate_identity()
+Database(site.connection()).dump(site, "/backups/wp_site.sql.age", recipients=[recipient])
+# Or passphrase mode (mutually exclusive with recipients= / identities=):
+# Database(site.connection()).dump(site, "/backups/wp_site.sql.age", passphrase=secret)
+
+admin = Environment("DB_ADMIN_USER", "DB_ADMIN_PASSWORD")
+staging = Database(Connection("127.0.0.1", "wp_site_staging"))
+staging.ensure(admin, site)
+staging.load(site, "/backups/wp_site.sql.age", identities=[identity])
+```
+
+Dumps are made by the server's own client tools (`mysqldump` or `mariadb-dump`),
+and loads by `mysql` or `mariadb`. The password reaches them only through an
+anonymous pipe: never an argument, an environment variable or a file. A dump to
+a path is written under a temporary name and renamed only on success. `iter_dump`
+yields the dump as chunks, and raises at the end if the tool failed, so a
+truncated dump is never mistaken for a whole one.
+
+Loading into a database that holds tables requires `replace=` naming it. A damaged
+source is discovered mid-load, after the statements before the damage have run,
+so load into a staging database and switch to it once the load succeeds.
+
+Encryption is standard [age](https://age-encryption.org): recipient keys or a
+passphrase (scrypt sole recipient). Either streams; any dump can be decrypted
+with the stock `age` command line. Passphrase mode uses the
+`l3io-age-passphrase` binder by default, or `age` + `age-plugin-batchpass` when
+`L3IO_AGE_PASSPHRASE_BACKEND=cli` (or when the binder is absent under `auto`).
+Archive callers can also
+`from l3io.wp.database import encrypt, decrypt, check_passphrase`.
+
+## Command line
+
+```shell
+l3io-wordpress-database survey --wp-config /var/www/html/wp-config.php \
+    --admin-user root --admin-password-env DB_ADMIN_PASSWORD
+l3io-wordpress-database check ensure --wp-config /var/www/html/wp-config.php \
+    --admin-user root --admin-password-env DB_ADMIN_PASSWORD
+l3io-wordpress-database ensure --wp-config /var/www/html/wp-config.php \
+    --admin-user root --admin-password-env DB_ADMIN_PASSWORD
+l3io-wordpress-database dump --wp-config /var/www/html/wp-config.php \
+    --output wp_site.sql.age --recipient age1examplerecipient
+l3io-wordpress-database dump --wp-config /var/www/html/wp-config.php \
+    --output wp_site.sql.age --passphrase-file /run/secrets/age-passphrase
+l3io-wordpress-database load --db-host 127.0.0.1 --db-name wp_site_staging \
+    --db-user wpuser --db-password-env DB_PASSWORD \
+    --input wp_site.sql.age --identity key.txt
+l3io-wordpress-database load --db-host 127.0.0.1 --db-name wp_site_staging \
+    --db-user wpuser --db-password-env DB_PASSWORD \
+    --input wp_site.sql.age --ask-passphrase
+l3io-wordpress-database drop-database --db-host 127.0.0.1 --db-name wp_site_staging \
+    --admin-user root --admin-password-env DB_ADMIN_PASSWORD --confirm wp_site_staging
+```
+
+No password or age passphrase is accepted as an argument value, because an
+argument vector is visible to every user on the machine: a password comes from
+`--wp-config`, from the environment variable named by a `--*-password-env`
+option, from AWS Secrets Manager, or from a prompt; an age passphrase comes from
+`--passphrase-file` or `--ask-passphrase` (mutually exclusive with
+`--recipient` / `--identity`). Results are printed as JSON on stdout; with
+`dump --output -` the dump is on stdout and the result on stderr.
+
+| Exit code | Meaning |
+|---|---|
+| `0` | success |
+| `1` | the operation started and failed |
+| `2` | usage |
+| `3` | refused: the check found a blocker, and nothing ran |
+| `4` | credentials could not be obtained |
+| `5` | the server could not be reached |
+| `7` | not ready: `inspect` found the account cannot use the database |
+
+## Supported
+
+- Python 3.11, 3.12, 3.13 and 3.14.
+- MySQL 8.0 and later, MariaDB 10.2 and later. CI runs MySQL 8.0, 8.4 and 9.7 and
+  MariaDB 10.2 and 11.4.
+- Export and import need `/dev/fd` (Linux or macOS) and the client tools on `PATH`.
+  Everything else is pure Python.
+
+The package logs through `structlog` and never configures logging, and opens one
+OpenTelemetry span per operation through `opentelemetry-api`, inert until the host
+configures an SDK.
+
+## Design records
+
+This package's decisions are in [docs/adr](docs/adr/README.md). The rules the
+`l3io.wp` family shares (cited as AD-n) are in `l3io-wordpress-backup`'s
+architecture spine.
+
+## Development
+
+```shell
+make sync                                # locked environment, all extras
+make check                               # lint, format, types, tests, contracts
+make test-db DB_HOST=127.0.0.1           # integration tests against a server
+make test-transfer ENGINE=mysql:8.4      # export/import with that image's own client tools
+make verify-wheel                        # install the built wheel, bare and with each extra
+make ci                                  # replay the CI pipeline under act
+```
+
+## Licence
+
+MIT.

l3io_wordpress_database-0.3.5/README.md

@@ -0,0 +1,204 @@
+# l3io-wordpress-database
+
+The operations a WordPress site performs against its MySQL or MariaDB database:
+inspecting it, provisioning it, changing its accounts, destroying it, and exporting
+and importing it. Every operation acts with credentials the caller supplies, and
+every operation that changes or moves something can be checked before it runs.
+
+It imports as `l3io.wp.database`, in the `l3io.wp` namespace shared with
+`l3io-wordpress-config` and `l3io-wordpress-backup`.
+
+> **Status:** 0.x — documented and typed, with no stability promise until 1.0.0.
+> Not yet on PyPI; releases are on
+> [GitHub](https://github.com/LiquidLogicLabs/l3io-wordpress-database/releases).
+
+## Installing
+
+```shell
+pip install l3io-wordpress-database                # core: PyMySQL, structlog, opentelemetry-api
+pip install 'l3io-wordpress-database[aws]'         # credentials from AWS Secrets Manager
+pip install 'l3io-wordpress-database[wpconfig]'    # credentials and location from wp-config.php
+pip install 'l3io-wordpress-database[encryption]'  # age-encrypted dumps
+```
+
+An optional dependency is an optional import: a base install never imports
+`boto3`, the config reader or `pyrage`, and asking for a feature whose extra is
+absent raises `MissingDependencyError` naming the extra.
+
+## Two accounts
+
+WordPress's own account — the one in `wp-config.php` — is the account that is
+created and granted. A separate administrative account does the creating, and is
+never defaulted to the WordPress account. Whether a database exists is answered
+by the administrator: a server authenticates before it resolves the database, so a
+failed login by the WordPress account says nothing about the database.
+
+## Check, then run
+
+```python
+from l3io.wp.database import Connection, Database, Environment, Explicit
+
+db = Database(Connection("127.0.0.1", "wp_site"))
+admin = Environment("DB_ADMIN_USER", "DB_ADMIN_PASSWORD")
+wordpress = Explicit("wpuser", "wp-pass")
+
+verdict = db.check_ensure(admin, wordpress)
+for finding in verdict.findings:
+    print(finding.severity, finding.code, finding.message)
+
+if verdict.ok:
+    result = db.ensure(admin, wordpress)
+    print(result.created_database, result.created_user, result.granted, result.changed)
+```
+
+`ensure` runs the same check itself and raises `RefusedError`, carrying the
+`Verdict`, on any blocker. It creates only what is missing, and a second run
+against a converged server changes nothing. Grants are scoped to the one database,
+with the `_` and `%` wildcards in its name escaped.
+
+Destructive operations — `revoke`, `drop_user`, `drop_database` — take
+`confirm=`, which must repeat the target's name.
+
+## From wp-config.php
+
+```python
+from l3io.wp.database import Database, Environment, WpConfigFile
+
+site = WpConfigFile("/var/www/html/wp-config.php")
+db = Database(site.connection())
+survey = db.survey(
+    Environment("DB_ADMIN_USER", "DB_ADMIN_PASSWORD"),
+    wordpress_user=site.resolve().username,
+    table_prefix=site.table_prefix,
+)
+print(survey.database_exists, survey.table_count, survey.is_wordpress, survey.schema_version)
+```
+
+`inspect` asks the WordPress account itself what it can do, and never raises
+for an ordinary failure:
+
+| State | Meaning |
+|---|---|
+| `ready` | connected, authenticated, and the database is usable |
+| `database_absent` | authenticated, but the database does not exist |
+| `access_denied` | authenticated, but may not use this database |
+| `authentication_failed` | the server rejected the account |
+| `unreachable` | the server could not be reached |
+| `credentials_unobtainable` | the credentials could not be obtained; nothing was attempted |
+
+## Export and import
+
+```python
+from l3io.wp.database import (
+    Connection,
+    Database,
+    Environment,
+    WpConfigFile,
+    encrypt,
+    generate_identity,
+)
+
+site = WpConfigFile("/var/www/html/wp-config.php")
+identity, recipient = generate_identity()
+Database(site.connection()).dump(site, "/backups/wp_site.sql.age", recipients=[recipient])
+# Or passphrase mode (mutually exclusive with recipients= / identities=):
+# Database(site.connection()).dump(site, "/backups/wp_site.sql.age", passphrase=secret)
+
+admin = Environment("DB_ADMIN_USER", "DB_ADMIN_PASSWORD")
+staging = Database(Connection("127.0.0.1", "wp_site_staging"))
+staging.ensure(admin, site)
+staging.load(site, "/backups/wp_site.sql.age", identities=[identity])
+```
+
+Dumps are made by the server's own client tools (`mysqldump` or `mariadb-dump`),
+and loads by `mysql` or `mariadb`. The password reaches them only through an
+anonymous pipe: never an argument, an environment variable or a file. A dump to
+a path is written under a temporary name and renamed only on success. `iter_dump`
+yields the dump as chunks, and raises at the end if the tool failed, so a
+truncated dump is never mistaken for a whole one.
+
+Loading into a database that holds tables requires `replace=` naming it. A damaged
+source is discovered mid-load, after the statements before the damage have run,
+so load into a staging database and switch to it once the load succeeds.
+
+Encryption is standard [age](https://age-encryption.org): recipient keys or a
+passphrase (scrypt sole recipient). Either streams; any dump can be decrypted
+with the stock `age` command line. Passphrase mode uses the
+`l3io-age-passphrase` binder by default, or `age` + `age-plugin-batchpass` when
+`L3IO_AGE_PASSPHRASE_BACKEND=cli` (or when the binder is absent under `auto`).
+Archive callers can also
+`from l3io.wp.database import encrypt, decrypt, check_passphrase`.
+
+## Command line
+
+```shell
+l3io-wordpress-database survey --wp-config /var/www/html/wp-config.php \
+    --admin-user root --admin-password-env DB_ADMIN_PASSWORD
+l3io-wordpress-database check ensure --wp-config /var/www/html/wp-config.php \
+    --admin-user root --admin-password-env DB_ADMIN_PASSWORD
+l3io-wordpress-database ensure --wp-config /var/www/html/wp-config.php \
+    --admin-user root --admin-password-env DB_ADMIN_PASSWORD
+l3io-wordpress-database dump --wp-config /var/www/html/wp-config.php \
+    --output wp_site.sql.age --recipient age1examplerecipient
+l3io-wordpress-database dump --wp-config /var/www/html/wp-config.php \
+    --output wp_site.sql.age --passphrase-file /run/secrets/age-passphrase
+l3io-wordpress-database load --db-host 127.0.0.1 --db-name wp_site_staging \
+    --db-user wpuser --db-password-env DB_PASSWORD \
+    --input wp_site.sql.age --identity key.txt
+l3io-wordpress-database load --db-host 127.0.0.1 --db-name wp_site_staging \
+    --db-user wpuser --db-password-env DB_PASSWORD \
+    --input wp_site.sql.age --ask-passphrase
+l3io-wordpress-database drop-database --db-host 127.0.0.1 --db-name wp_site_staging \
+    --admin-user root --admin-password-env DB_ADMIN_PASSWORD --confirm wp_site_staging
+```
+
+No password or age passphrase is accepted as an argument value, because an
+argument vector is visible to every user on the machine: a password comes from
+`--wp-config`, from the environment variable named by a `--*-password-env`
+option, from AWS Secrets Manager, or from a prompt; an age passphrase comes from
+`--passphrase-file` or `--ask-passphrase` (mutually exclusive with
+`--recipient` / `--identity`). Results are printed as JSON on stdout; with
+`dump --output -` the dump is on stdout and the result on stderr.
+
+| Exit code | Meaning |
+|---|---|
+| `0` | success |
+| `1` | the operation started and failed |
+| `2` | usage |
+| `3` | refused: the check found a blocker, and nothing ran |
+| `4` | credentials could not be obtained |
+| `5` | the server could not be reached |
+| `7` | not ready: `inspect` found the account cannot use the database |
+
+## Supported
+
+- Python 3.11, 3.12, 3.13 and 3.14.
+- MySQL 8.0 and later, MariaDB 10.2 and later. CI runs MySQL 8.0, 8.4 and 9.7 and
+  MariaDB 10.2 and 11.4.
+- Export and import need `/dev/fd` (Linux or macOS) and the client tools on `PATH`.
+  Everything else is pure Python.
+
+The package logs through `structlog` and never configures logging, and opens one
+OpenTelemetry span per operation through `opentelemetry-api`, inert until the host
+configures an SDK.
+
+## Design records
+
+This package's decisions are in [docs/adr](docs/adr/README.md). The rules the
+`l3io.wp` family shares (cited as AD-n) are in `l3io-wordpress-backup`'s
+architecture spine.
+
+## Development
+
+```shell
+make sync                                # locked environment, all extras
+make check                               # lint, format, types, tests, contracts
+make test-db DB_HOST=127.0.0.1           # integration tests against a server
+make test-transfer ENGINE=mysql:8.4      # export/import with that image's own client tools
+make verify-wheel                        # install the built wheel, bare and with each extra
+make ci                                  # replay the CI pipeline under act
+```
+
+## Licence
+
+MIT.

l3io_wordpress_database-0.3.5/pyproject.toml

@@ -0,0 +1,191 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "l3io-wordpress-database"
+dynamic = ["version"]
+description = "Create and inspect WordPress MySQL databases and their users, idempotently."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Shawn Anderson" }]
+keywords = ["wordpress", "mysql", "mariadb", "database", "provisioning"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Operating System :: OS Independent",
+  "Topic :: Internet :: WWW/HTTP :: Site Management",
+  "Typing :: Typed",
+]
+
+# Core stays deliberately small. opentelemetry-api is a hard dependency on purpose:
+# it is ~58KB with one dependency and already ships the no-op NonRecordingSpan /
+# ProxyTracer, so putting it behind an extra would oblige us to hand-roll a shim.
+dependencies = [
+  "PyMySQL[rsa]>=1.2,<2",
+  "structlog>=26.1,<27",
+  "opentelemetry-api>=1.30,<2",
+]
+
+[project.optional-dependencies]
+aws = ["boto3>=1.34,<2"]
+wpconfig = ["l3io-wordpress-config>=0.1.2,<0.2"]
+encryption = [
+  "pyrage>=1.4,<2",
+  "l3io-age-passphrase>=0.1.1,<0.2",
+]
+
+# Mechanical enforcement of the family's uv version, matching l3io-wordpress-config.
+# A lock generated by a different uv version can make `uv sync --locked` fail in
+# CI while passing locally; pinning here makes that impossible rather than
+# remembered. Bump deliberately and across all three repositories together.
+[tool.uv]
+required-version = "==0.11.6"
+
+[tool.uv.sources]
+# Development and CI only. Both packages are on TestPyPI and the family Gitea
+# index, but a clean public clone still has no default index for them, so we
+# keep git tags until consumers (and this package) resolve from an index by
+# default. `uv build --no-sources` strips these; check_dist_metadata fails a
+# build that carries a VCS dependency. Delete this block once public PyPI (or
+# a documented default index) carries both.
+l3io-wordpress-config = { git = "https://github.com/LiquidLogicLabs/l3io-wordpress-config.git", tag = "v0.1.3" }
+l3io-age-passphrase = { git = "https://github.com/LiquidLogicLabs/l3io-age-passphrase.git", tag = "v0.1.1" }
+
+[project.scripts]
+l3io-wordpress-database = "l3io.wp.database.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/LiquidLogicLabs/l3io-wordpress-database"
+Source = "https://github.com/LiquidLogicLabs/l3io-wordpress-database"
+
+[dependency-groups]
+dev = [
+  "ruff==0.16.7",
+  "mypy==2.3.1",
+  "pytest==9.1.1",
+  "pytest-cov==7.1.0",
+  "types-pymysql>=1.2.0.20260807",
+  # The contract tests read the workflow files. A maintained parser, because the
+  # one thing this repo's rules will not tolerate is a hand-written YAML parser.
+  "pyyaml==6.0.3",
+  "types-pyyaml==6.0.12.20260906",
+  # tests/test_declared_facts.py compares requirement names, specifiers and
+  # versions. Declared directly rather than relied on through pytest's own
+  # dependency on it.
+  "packaging==26.3",
+  # Span assertions need a real SDK; the package itself depends on the API only.
+  "opentelemetry-sdk==1.45.1",
+  # The encryption extra, also here because `uv run` prunes extras.
+  "pyrage==1.4.0",
+  "l3io-age-passphrase>=0.1.1,<0.2",
+  # The optional extras are dev dependencies too, so a bare `uv run` can
+  # exercise the code paths behind them. `uv run` syncs the default groups
+  # only, which PRUNES extras -- without this, every `uv run` silently
+  # uninstalled the wpconfig extra and its tests began skipping.
+  #
+  # This does not weaken the optionality guarantee. That is enforced against
+  # the BUILT WHEEL in an isolated environment, by the verify-install job and
+  # `make verify-wheel`, not by whatever happens to be in the dev environment.
+  "boto3>=1.34,<2",
+  "l3io-wordpress-config>=0.1.2,<0.2",
+]
+
+# AD-27: l3io.wp is a PEP 420 native namespace. Ship no __init__.py at
+# src/l3io/ or src/l3io/wp/ -- doing so shadows the namespace and makes the
+# sibling distributions unimportable, while this package's own tests still pass.
+[tool.hatch.version]
+# AD-30: the git tag IS the version. There is no literal anywhere in this repo
+# to drift from it -- not in pyproject, not in the package -- so "keep the tag
+# and the package in sync" is not a rule anyone can break.
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+# PyPI rejects local version labels, so a dev build must not carry +g<sha>.
+local_scheme = "no-local-version"
+# Only three-component tags count. Without this the abandoned 2018 `v1.0` tag
+# is the nearest ancestor of every commit on main, and setuptools-scm reads its
+# two components and guesses the next MINOR: builds came out as 1.1.dev39, which
+# sorts ABOVE 1.0.0 in PEP 440, so publishing one would have permanently
+# outranked the release.
+#
+# The match also needs a three-component ancestor to find, which is what the
+# v0.0.0 BASELINE tag provides. Without it the fallback was 0.1.devN, and
+# 0.1.dev1 > 0.0.1 in PEP 440 -- verified, not assumed -- so a dev build published
+# before the first release would have outranked it permanently. From the baseline
+# an untagged tree derives 0.0.1.devN, which sorts below 0.0.1.
+#
+# v0.0.0 is not a release and is excluded from publish.yml's tag trigger.
+git_describe_command = "git describe --dirty --tags --long --match v[0-9]*.[0-9]*.[0-9]*"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/l3io"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/l3io", "README.md", "LICENSE"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+# Installed tooling and generated artifacts, not this project's source. CI lints
+# `.` rather than a hand-listed set of directories so a new package directory is
+# covered automatically -- which means the exclusions, not the inclusions, are
+# what has to be maintained.
+extend-exclude = ["_bmad", "_bmad-output", ".claude", ".agents", ".github"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "A", "C4", "SIM", "RET", "ARG", "PTH", "BLE", "TRY", "EM", "S"]
+# BLE001 (blind except): a bare `except Exception` silently turns distinct failures
+# into one benign-looking result.
+ignore = []
+
+[tool.ruff.lint.per-file-ignores]
+# S101 asserts are the point of a test; S105-S107 flag the fake
+# credentials every credential test must construct.
+"tests/*" = ["S101", "S105", "S106", "S107", "ARG"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src", "tests"]
+# AD-27: l3io/ and l3io/wp/ have no __init__.py by design, so mypy needs to be
+# told where package roots begin. The fix for "source file found twice" here is
+# this setting -- never adding an __init__.py, which would break the siblings.
+mypy_path = "src"
+namespace_packages = true
+explicit_package_bases = true
+
+[[tool.mypy.overrides]]
+# boto3 lives behind the `aws` extra and is absent from a base install, which
+# is the point of AD-8.
+module = ["boto3", "boto3.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+# pyrage lives behind the `encryption` extra and ships no type information.
+module = ["pyrage", "pyrage.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+# l3io-age-passphrase is a compiled extension behind the encryption extra.
+module = ["l3io_age_passphrase", "l3io_age_passphrase.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+markers = ["slow: builds a wheel or talks to a real database server", "transfer: export/import tests run by make test-transfer inside a server image"]
+
+# Just under the line coverage the integration legs measure (89% on MySQL 8.4), so
+# a deleted test file fails CI instead of passing quietly. pytest-cov applies it to
+# every run that measures coverage; `make test` measures none.
+[tool.coverage.report]
+fail_under = 87