py-app-runner 0.5.49.dev0__tar.gz

py_app_runner-0.5.49.dev0/.version

@@ -0,0 +1 @@
+0.5.49.dev0

py_app_runner-0.5.49.dev0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Gints Murāns
+
+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.

py_app_runner-0.5.49.dev0/MANIFEST.in

@@ -0,0 +1 @@
+include .version

py_app_runner-0.5.49.dev0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: py_app_runner
+Version: 0.5.49.dev0
+Summary: Async service framework: Tornado HTTP/WS bridge, service loader, Redis WS connection manager
+Author-email: Gints Murans <gm@gm.lv>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/4Apps/py_app_runner
+Project-URL: Documentation, https://github.com/4Apps/py_app_runner/blob/master/AGENTS.md
+Project-URL: Code, https://github.com/4Apps/py_app_runner
+Project-URL: Issue Tracker, https://github.com/4Apps/py_app_runner/issues
+Project-URL: Download, https://pypi.org/project/py-app-runner/
+Keywords: async,tornado,websocket,framework,service,redis,postgresql,migrations,queue
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+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 :: Implementation :: CPython
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sentry-sdk
+Requires-Dist: python-dotenv
+Requires-Dist: uvloop
+Requires-Dist: msgspec
+Requires-Dist: msgpack
+Requires-Dist: tornado
+Requires-Dist: database_wrapper[pgsql,redis]==0.3.146
+Requires-Dist: psycopg>=3.2.0
+Requires-Dist: psycopg[pool]>=3.2.0
+Requires-Dist: redis
+Requires-Dist: pyjwt
+Requires-Dist: cryptography>=44
+Requires-Dist: bcrypt
+Provides-Extra: dev
+Requires-Dist: pyrefly; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Dynamic: license-file
+
+# py_app_runner
+
+Async Python service framework: Tornado HTTP/WS bridge, PyBridge service loader, Redis WebSocket connection manager.
+
+## Install
+
+```bash
+pip install py_app_runner
+```
+
+Every push to `develop` publishes a pre-release, `X.Y.<commit count>.dev0`. pip hides those
+unless you ask for them:
+
+```bash
+pip install --pre py_app_runner        # newest, including dev builds
+pip install py_app_runner==0.4.50.dev0 # a specific dev build
+```
+
+## Development
+
+```bash
+docker-compose up develop
+```
+
+## Migrations
+
+Built-in service that applies tracked SQL files to one or more configured databases. Add
+`migrations` to `SERVICES` to enable it.
+
+```bash
+python3 src/app.py migrations status   [--check] [--target NAME]
+python3 src/app.py migrations apply    [--dry-run] [--to PREFIX] [--target NAME]
+python3 src/app.py migrations baseline [--to PREFIX] [--yes] [--target NAME]
+python3 src/app.py migrations new      <name> [--target NAME]
+python3 src/app.py migrations repair   <filename> [--target NAME]
+```
+
+By default there is a single target, `main`, against `config["db"]["main"]`: files live in
+`config["migrations"]["dir"]` (default `data/migrations`) and are tracked in
+`config["migrations"]["table"]` (default `migrations`). **No project needs to change
+anything to keep this working** - an absent `migrations` key, an empty one, and this flat
+shape all resolve to that same single target.
+
+To migrate more than one database, opt in with `config["migrations"]["targets"]`:
+
+```python
+"migrations": {
+    "targets": {
+        "main": {"db": "main", "dir": "data/migrations", "table": "migrations"},
+        "gis": {"db": "gis", "dir": "data/migrations_gis", "table": "gis_migrations"},
+    }
+}
+```
+
+Each target's `db` names a key under `config["db"]` and defaults to the target's own name;
+`dir` and `table` default as above. `status` and `apply` with no `--target` run every
+target in declared order (`apply` stops at the first one that fails; `status --check`
+reports each target rather than stopping at the first with pending work, and exits 1 if any
+is pending or blocked). `new`, `repair` and `baseline` require `--target` once more than one
+target is configured, and an unknown `--target` exits 1 - both name the configured targets.
+Output gets a `[name] ` prefix only when more than one target is processed, so single-target
+output is unchanged.
+
+Targets may share a database, but not a database *and* a tracking table - each would then
+report the other's migrations as missing, so that config is refused up front, naming both
+targets. `table` defaults to `migrations` for every target, so two targets on one database
+need an explicit `table` on at least one of them.
+
+- Migrations no longer need to be idempotent - each file runs in its own transaction with
+  its tracking row written inside it, so what already ran is always known.
+- `-- migrations:no-transaction` on line 1 runs a file outside a transaction (for
+  `CREATE INDEX CONCURRENTLY` and friends). Such a file must contain **exactly one
+  statement**: Postgres wraps a multi-statement send in an implicit transaction, which would
+  defeat the directive, so `apply` refuses it up front. A no-transaction file that fails
+  cannot roll back and is not recorded - `apply` says so and tells you to inspect the
+  database before re-running.
+- Editing an applied file is detected as drift, and a tracked file that has since been
+  deleted shows as missing; both block `apply` until resolved. `repair` fixes drift only;
+  a missing file is fixed by restoring it, or by deleting its tracking row by hand
+  (`apply` prints the exact `DELETE` when it blocks).
+- Files must not contain psql meta-commands (`\restrict` / `\unrestrict`, as emitted by
+  `pg_dump`) - psycopg cannot execute them, and `apply` refuses such a file up front.
+- `baseline` adopts an existing database into the system: it writes tracking rows without
+  executing anything.
+- Every subcommand exits non-zero on failure, including a misconfigured `targets` block.
+  `status --check` exits 1 if anything is pending, drifted or missing, so a deploy script
+  can halt before restarting services against a half-migrated database.

py_app_runner-0.5.49.dev0/README.md

@@ -0,0 +1,87 @@
+# py_app_runner
+
+Async Python service framework: Tornado HTTP/WS bridge, PyBridge service loader, Redis WebSocket connection manager.
+
+## Install
+
+```bash
+pip install py_app_runner
+```
+
+Every push to `develop` publishes a pre-release, `X.Y.<commit count>.dev0`. pip hides those
+unless you ask for them:
+
+```bash
+pip install --pre py_app_runner        # newest, including dev builds
+pip install py_app_runner==0.4.50.dev0 # a specific dev build
+```
+
+## Development
+
+```bash
+docker-compose up develop
+```
+
+## Migrations
+
+Built-in service that applies tracked SQL files to one or more configured databases. Add
+`migrations` to `SERVICES` to enable it.
+
+```bash
+python3 src/app.py migrations status   [--check] [--target NAME]
+python3 src/app.py migrations apply    [--dry-run] [--to PREFIX] [--target NAME]
+python3 src/app.py migrations baseline [--to PREFIX] [--yes] [--target NAME]
+python3 src/app.py migrations new      <name> [--target NAME]
+python3 src/app.py migrations repair   <filename> [--target NAME]
+```
+
+By default there is a single target, `main`, against `config["db"]["main"]`: files live in
+`config["migrations"]["dir"]` (default `data/migrations`) and are tracked in
+`config["migrations"]["table"]` (default `migrations`). **No project needs to change
+anything to keep this working** - an absent `migrations` key, an empty one, and this flat
+shape all resolve to that same single target.
+
+To migrate more than one database, opt in with `config["migrations"]["targets"]`:
+
+```python
+"migrations": {
+    "targets": {
+        "main": {"db": "main", "dir": "data/migrations", "table": "migrations"},
+        "gis": {"db": "gis", "dir": "data/migrations_gis", "table": "gis_migrations"},
+    }
+}
+```
+
+Each target's `db` names a key under `config["db"]` and defaults to the target's own name;
+`dir` and `table` default as above. `status` and `apply` with no `--target` run every
+target in declared order (`apply` stops at the first one that fails; `status --check`
+reports each target rather than stopping at the first with pending work, and exits 1 if any
+is pending or blocked). `new`, `repair` and `baseline` require `--target` once more than one
+target is configured, and an unknown `--target` exits 1 - both name the configured targets.
+Output gets a `[name] ` prefix only when more than one target is processed, so single-target
+output is unchanged.
+
+Targets may share a database, but not a database *and* a tracking table - each would then
+report the other's migrations as missing, so that config is refused up front, naming both
+targets. `table` defaults to `migrations` for every target, so two targets on one database
+need an explicit `table` on at least one of them.
+
+- Migrations no longer need to be idempotent - each file runs in its own transaction with
+  its tracking row written inside it, so what already ran is always known.
+- `-- migrations:no-transaction` on line 1 runs a file outside a transaction (for
+  `CREATE INDEX CONCURRENTLY` and friends). Such a file must contain **exactly one
+  statement**: Postgres wraps a multi-statement send in an implicit transaction, which would
+  defeat the directive, so `apply` refuses it up front. A no-transaction file that fails
+  cannot roll back and is not recorded - `apply` says so and tells you to inspect the
+  database before re-running.
+- Editing an applied file is detected as drift, and a tracked file that has since been
+  deleted shows as missing; both block `apply` until resolved. `repair` fixes drift only;
+  a missing file is fixed by restoring it, or by deleting its tracking row by hand
+  (`apply` prints the exact `DELETE` when it blocks).
+- Files must not contain psql meta-commands (`\restrict` / `\unrestrict`, as emitted by
+  `pg_dump`) - psycopg cannot execute them, and `apply` refuses such a file up front.
+- `baseline` adopts an existing database into the system: it writes tracking rows without
+  executing anything.
+- Every subcommand exits non-zero on failure, including a misconfigured `targets` block.
+  `status --check` exits 1 if anything is pending, drifted or missing, so a deploy script
+  can halt before restarting services against a half-migrated database.

py_app_runner-0.5.49.dev0/pyproject.toml

@@ -0,0 +1,117 @@
+[build-system]
+# PEP 639 license expressions (the "license"/"license-files" keys below) need 77+
+requires = ["setuptools >= 77.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "py_app_runner"
+dynamic = ["version"]
+description = "Async service framework: Tornado HTTP/WS bridge, service loader, Redis WS connection manager"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Gints Murans", email = "gm@gm.lv" }]
+keywords = [
+    "async",
+    "tornado",
+    "websocket",
+    "framework",
+    "service",
+    "redis",
+    "postgresql",
+    "migrations",
+    "queue",
+]
+# No "License ::" classifier: it is deprecated alongside Metadata 2.4, and setuptools
+# refuses one next to the license expression above
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    # uvloop is a hard dependency and does not build on Windows
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "sentry-sdk",
+    "python-dotenv",
+    "uvloop",
+    "msgspec",
+    "msgpack",
+    "tornado",
+    # The extras pull the base package in, so one pin rather than three that must be kept
+    # in lockstep. 0.3.146 is the first MIT release - 0.2.38 and earlier are GPL-3.0.
+    "database_wrapper[pgsql,redis] == 0.3.146",
+    # Used directly by py_app_runner.migrations, not only through database_wrapper, so the
+    # floor is declared here rather than inherited. Matches database_wrapper_pgsql 0.3.146's
+    # own psycopg[binary]/psycopg[pool] >= 3.2.0.
+    "psycopg >= 3.2.0",
+    "psycopg[pool] >= 3.2.0",
+    "redis",
+    "pyjwt",
+    # Used directly by py_app_runner.crypto for AES-256-GCM. The floor is 44 because that
+    # is where XChaCha20Poly1305 appears, which is the obvious alternative if AES-GCM's
+    # 96-bit nonce ever becomes uncomfortable for a high-volume column.
+    "cryptography >= 44",
+    "bcrypt",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pyrefly",
+    "ruff",
+    "pytest",
+    "pytest-asyncio",
+]
+
+[project.urls]
+Homepage = "https://github.com/4Apps/py_app_runner"
+Documentation = "https://github.com/4Apps/py_app_runner/blob/master/AGENTS.md"
+Code = "https://github.com/4Apps/py_app_runner"
+"Issue Tracker" = "https://github.com/4Apps/py_app_runner/issues"
+Download = "https://pypi.org/project/py-app-runner/"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# Without the marker file in the wheel, a downstream type checker ignores every
+# annotation in this package (PEP 561)
+[tool.setuptools.package-data]
+"py_app_runner" = ["py.typed"]
+
+# Manual major.minor in .version; CI appends the git commit count as the patch part.
+# A local build therefore reports a bare "0.4" - scripts/version.bash prints what a
+# release of this commit would actually publish as.
+[tool.setuptools.dynamic]
+version = { file = ".version" }
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+fixable = ["ALL"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+# For some reason this needs to be here to show errors in VSCode
+[tool.pyrefly]
+site-package-path = ["/srv/venv/lib64/python3.13/site-packages"]

py_app_runner-0.5.49.dev0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

py_app_runner-0.5.49.dev0/src/py_app_runner/__init__.py

@@ -0,0 +1,11 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from py_app_runner.registry import AppRegistry
+
+__all__ = ["AppRegistry"]
+
+try:
+    __version__ = version("py_app_runner")
+except PackageNotFoundError:
+    # Running straight from a source tree that was never installed
+    __version__ = "0.0.dev0"

py_app_runner-0.5.49.dev0/src/py_app_runner/audit/__init__.py

@@ -0,0 +1,29 @@
+"""An append-only trail of who changed what, written explicitly at the call site."""
+
+from py_app_runner.audit.audit import Audit
+from py_app_runner.audit.errors import AuditError
+from py_app_runner.audit.event import (
+    CREATED,
+    DELETED,
+    UPDATED,
+    Actor,
+    AuditEvent,
+    RequestContext,
+    current_context,
+    new_request_id,
+    request_context,
+)
+
+__all__ = [
+    "CREATED",
+    "DELETED",
+    "UPDATED",
+    "Actor",
+    "Audit",
+    "AuditError",
+    "AuditEvent",
+    "RequestContext",
+    "current_context",
+    "new_request_id",
+    "request_context",
+]

py_app_runner-0.5.49.dev0/src/py_app_runner/audit/_service.py

@@ -0,0 +1,91 @@
+import asyncio
+import logging
+import pathlib
+from argparse import Namespace
+from datetime import UTC, datetime
+
+import psycopg
+
+from py_app_runner.audit.commands import Out, cmd_install, cmd_prune
+from py_app_runner.audit.errors import AuditError
+from py_app_runner.migrations._service import connect_kwargs, resolve_targets
+from py_app_runner.pybridge import PyBridge
+from py_app_runner.registry import AppRegistry
+
+_DEFAULT_DB = "main"
+_DEFAULT_TABLE = "audit_log"
+
+
+def _migrations_dir(args: Namespace, config: dict) -> pathlib.Path:
+    """Where `install` writes.
+
+    The file it produces is a migration and belongs wherever the rest of them are, so the
+    default comes from the migrations config rather than from an audit key of its own.
+    """
+
+    raw = getattr(args, "dir", None)
+    if raw:
+        directory = pathlib.Path(raw)
+        if directory.is_absolute():
+            return directory
+
+        return pathlib.Path(config.get("current_path") or ".") / directory
+
+    targets = resolve_targets(config)
+    return next(iter(targets.values())).directory
+
+
+async def init_service(args: Namespace, _pybridge: PyBridge, logger: logging.Logger) -> None:
+    out: Out = print
+
+    # Same reasoning as migrations: runner.py catches Exception around init_service and
+    # returns normally, which exits 0. A prune that could not reach the database must not
+    # report success to a retention job.
+    code = 1
+    try:
+        config = AppRegistry.config()
+        settings = config.get("audit") or {}
+        table = getattr(args, "table", None) or settings.get("table") or _DEFAULT_TABLE
+
+        if args.step == "install":
+            raise SystemExit(cmd_install(_migrations_dir(args, config), table, datetime.now(UTC), out))
+
+        db_name = getattr(args, "db", None) or settings.get("db") or _DEFAULT_DB
+        db_config = config.get("db") or {}
+        if db_name not in db_config:
+            out(
+                f'error: no database {db_name!r} in config["db"]; '
+                f"configured are: {', '.join(sorted(db_config)) or 'none'}."
+            )
+            raise SystemExit(2)
+
+        if args.step == "prune":
+            async with await psycopg.AsyncConnection.connect(**connect_kwargs(db_config[db_name])) as conn:
+                code = await cmd_prune(
+                    conn,
+                    table,
+                    args.before,
+                    args.batch,
+                    getattr(args, "dry_run", False),
+                    out,
+                )
+        else:
+            out(f"error: unknown audit command {args.step!r}")
+            code = 1
+
+    except AuditError as e:
+        # Configuration and refusal messages already say what to do; a stack trace above
+        # them would bury it.
+        out(f"error: {e}")
+        raise SystemExit(1) from None
+    except (KeyboardInterrupt, asyncio.CancelledError):
+        # Above `except Exception` because both derive from BaseException. An interrupted
+        # prune has deleted some batches and not others - safe to resume, but it must not
+        # be reported as complete.
+        logger.error("audit: interrupted; the prune is partially done")
+        raise SystemExit(1) from None
+    except Exception:
+        logger.exception("audit: unhandled failure")
+        raise SystemExit(1) from None
+
+    raise SystemExit(code)

py_app_runner-0.5.49.dev0/src/py_app_runner/audit/_service_args.py

@@ -0,0 +1,44 @@
+"""CLI subparsers for the built-in audit service.
+
+    python3 src/app.py audit install [--dir PATH] [--table NAME]
+    python3 src/app.py audit prune --before YYYY-MM-DD [--batch N] [--dry-run] [--db NAME]
+
+`--dry-run` shadows a real top-level flag on runner.py's parser and needs
+`default=SUPPRESS`, the same collision migrations' `apply` has.
+"""
+
+import logging
+from argparse import SUPPRESS, ArgumentParser, _SubParsersAction  # type: ignore
+
+from py_app_runner.pybridge import PyBridge
+
+
+def reg_subparsers(
+    subparsers: "_SubParsersAction[ArgumentParser]",
+    _pybridge: PyBridge,
+    _base_logger: logging.Logger,
+) -> None:
+    """Command line subparsers"""
+
+    parser = subparsers.add_parser(
+        "audit",
+        description="Install the audit trail schema and prune old rows",
+        help="Audit trail",
+    )
+    group = parser.add_subparsers(title="command", dest="step", required=True)
+
+    install_parser = group.add_parser("install", help="Write the audit schema into the migrations directory")
+    install_parser.add_argument("--dir", default=None, help="Migrations directory to write into")
+    install_parser.add_argument("--table", default=None, help="Audit table (default: from config)")
+
+    prune_parser = group.add_parser("prune", help="Delete trail rows older than a date")
+    prune_parser.add_argument("--before", required=True, help="Delete rows older than this, YYYY-MM-DD")
+    prune_parser.add_argument("--batch", type=int, default=10000, help="Rows per statement (default: 10000)")
+    prune_parser.add_argument("--table", default=None, help="Audit table (default: from config)")
+    prune_parser.add_argument("--db", default=None, help='Entry of config["db"] to prune in (default: main)')
+    prune_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        default=SUPPRESS,
+        help="Count what would go, delete nothing",
+    )