supython 0.1.8__tar.gz → 0.1.10__tar.gz

{supython-0.1.8 → supython-0.1.10}/CHANGELOG.md

@@ -31,6 +31,62 @@ Each entry links the relevant `PROJECT.md` section and decision-log row
 
 ---
 
+## [0.1.10] — 2026-06-12
+
+### Added
+
+- `python-dotenv` is now a direct dependency (previously only transitive via
+  `pydantic-settings`), backing the new boot-time `.env` export.
+
+### Fixed
+
+- `.env` is now exported into `os.environ` at the start of every boot path
+  (`create_app`, `supython worker run`, CLI subcommands) via the shared
+  `settings.export_env_file()` helper, **before** extensions load. Previously
+  pydantic-settings loaded `.env` into the typed `Settings` model only, so
+  dynamically-named secrets read via `os.environ.get(<name>)` (the `secret_ref`
+  convention) resolved to `None` under `supython dev` / `worker run` / CLI —
+  working in containers only because docker-compose's `env_file:` injected
+  `.env` first. The export uses `override=False`, so real environment variables
+  set by an orchestrator always win, and the path is sourced from the same
+  `SettingsConfigDict.env_file`. Downstream apps can delete their ad-hoc
+  `load_dotenv()` boot shims. (#1)
+
+---
+
+## [0.1.9] — 2026-05-29
+
+### Fixed
+
+- `@cron(...)` now also registers the decorated function as the job
+  handler for `job_name`. Previously the decorator only wrote a
+  `CronDefinition`, so when pg_cron fired `jobs.enqueue(p_name :=
+  <job_name>)` the worker rejected the job with `unknown job:
+  <job_name>` on every tick. Pass `register_handler=False` to keep
+  the pre-fix behaviour (schedule fires a handler declared elsewhere
+  with `@job`).
+- `supython cron list` and `supython cron sync` now load the user's
+  settings module and `EXTENSIONS` before reading the registry,
+  mirroring `worker run` and the FastAPI startup path. Without the
+  bootstrap, `cron list` always printed `no crons registered` and a
+  subsequent `cron sync` would silently wipe every row from
+  `jobs.cron_schedules` and unschedule every matching pg_cron entry.
+
+### Added
+
+- `@cron(...)` accepts `register_handler` (default `True`) plus the
+  job kwargs forwarded to the auto-registered `JobDefinition`:
+  `max_attempts`, `backoff`, `backoff_base_s`, `backoff_max_s`,
+  `role`, `claims_from`, `accepts_payload`.
+- `supython cron sync --allow-empty` (and the matching
+  `sync_pg_cron(conn, allow_empty=True)` argument). Without the flag,
+  `sync_pg_cron` now refuses to act when the in-process registry is
+  empty but `jobs.cron_schedules` is non-empty — guards against a
+  forgotten extension bootstrap silently wiping production schedules.
+  The empty-registry-and-empty-table cold-start case stays a no-op.
+
+---
+
 ## [0.1.0] — 2026-05-09
 
 The first public release. Everything currently on `main` collapses
@@ -201,4 +257,6 @@ v0.1–v0.7 plus a v1.1.x admin track; see §19 decision log
 ---
 
 
+[0.1.10]: https://github.com/Tkeby/supython/releases/tag/v0.1.10
+[0.1.9]: https://github.com/Tkeby/supython/releases/tag/v0.1.9
 [0.1.0]: https://github.com/Tkeby/supython/releases/tag/v0.1.0

{supython-0.1.8 → supython-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: supython
-Version: 0.1.8
+Version: 0.1.10
 Summary: A lightweight Postgres-first BaaS framework for Python
 Project-URL: Homepage, https://github.com/Tkeby/supython
 Project-URL: Repository, https://github.com/Tkeby/supython
@@ -35,6 +35,7 @@ Requires-Dist: itsdangerous>=2.2
 Requires-Dist: pydantic-settings>=2.6
 Requires-Dist: pydantic>=2.9
 Requires-Dist: pyjwt[crypto]>=2.10
+Requires-Dist: python-dotenv>=1.0
 Requires-Dist: python-multipart>=0.0.20
 Requires-Dist: typer>=0.15
 Requires-Dist: uvicorn[standard]>=0.32
@@ -58,7 +59,7 @@ Description-Content-Type: text/markdown
 
 # supython
 
-> A lightweight, Postgres-first BaaS framework for Python. **v0.1.4 release**
+> A lightweight, Postgres-first BaaS framework for Python.
 
 **the database owns the schema, Python owns the things SQL is bad at**. 
 It leans on [PostgREST](https://postgrest.org)
@@ -69,7 +70,7 @@ storage, functions, workers, and an optional admin control plane.
 supython is for a specific person with a specific problem:
 > A developer who wants to build a CRUD-heavy web app (most apps are), who thinks in SQL, who wants Postgres to own authorization, and who wants auth + storage + custom logic without assembling the integration themselves.
 
-Shipped [v0.1.2]:
+
 
 **Core platform**
 - **Email/password auth** — signup, login, refresh-token rotation with **reuse detection**
@@ -106,7 +107,7 @@ Shipped [v0.1.2]:
 - **Secret rotation** — JWT keys, symmetric secrets, Postgres passwords; all with zero-downtime runbooks
 - **Multi-arch Docker image** — `linux/amd64` + `linux/arm64`, non-root user, `tini` PID 1, ~64 MB
 
-**Admin control plane** (shipped in v0.1.2)
+**Admin control plane**
 - **Vue 3 + Vite SPA** at `/admin` — no runtime Node deps; pre-built static bundle in the wheel
 - **Database surface** — schema browser, table data with role switcher, SQL workspace (read-only default + write toggle), RLS policy editor with dry-run, migrations panel
 - **Auth surface** — user search, ban/unban/force-logout, refresh-token inspector, audit log, email template editing
@@ -393,7 +394,7 @@ supython dev
 | `JOBS_DRAIN_TIMEOUT_S` | `30.0` | Graceful shutdown drain (seconds) |
 | `JOBS_DEV_INPROCESS` | `false` | Spawn worker in-process during `supython dev` |
 
-## v0.2 auth endpoints
+## Auth endpoints
 
 | Endpoint | Method | Purpose |
 |---|---|---|
@@ -436,7 +437,7 @@ denylist without breaking that contract. The mitigation is a **short
   long-lived (`REFRESH_TOKEN_TTL=30d`) so users don't get prompted to log
   in every few minutes — clients refresh transparently.
 
-### Custom JWT claims [shipped v0.1.3]
+### Custom JWT claims
 
 Register a claims provider to inject application-specific claims into every
 access token minted by the auth endpoints. Each provider is an async callable
@@ -472,7 +473,7 @@ Notes:
 - Refresh re-collects claims, so a token rotated via `/auth/v1/refresh`
   reflects current state.
 
-### Reading the caller in your routes [shipped v0.1.4]
+### Reading the caller in your routes
 
 Application code mounts its own routers alongside supython's. To gate an
 endpoint on a valid bearer token — or to read custom claims out of it —
@@ -818,7 +819,7 @@ unit tests always run in isolation.
 **CI:** runners with Docker run `supython test up && supython test run`;
 runners without Docker run `pytest tests/unit` for a meaningful subset.
 
-## Roadmap [shipped v0.1.2]
+## Roadmap
 
 - ✅ Email/password auth, PostgREST contract, RLS demo
 - ✅ OAuth, password reset, magic link, OTP, reuse detection, email backend, test suite
@@ -829,12 +830,11 @@ runners without Docker run `pytest tests/unit` for a meaningful subset.
 - ✅ Production observable: structured JSON logs, `/livez`/`/readyz`/`/health`, security headers, input size guards, audit log completeness, OAuth PKCE, secret rotation runbooks
 - ✅ (partial) Multi-arch Docker images, admin control plane (Vue 3 SPA — database, auth, storage, functions, realtime, jobs, backups, log tail), CI buildx workflow; benchmarks + security audit pass + dependency budget CI remaining
 - *(deferred)* — Realtime v2 over logical replication
-- v0.1.2 Release — final sweep, tag, publish wheel, production deployment with no patches
 - ✅ **TypeScript SDK** — `@supython/sdk` wrapping `@supabase/postgrest-js` + `@supabase/realtime-js` 
 
-### Post v0.1.2
+### Future
 
-- **v1.1+** — Admin control plane polish (backend + frontend shipped in v0.1.2; tests + remaining DoD items deferred)
+- **Admin control plane** polish (tests + remaining DoD items)
 - **Realtime v2** — logical replication (demand-driven; swap when trigger overhead or >8KB payload data warrants it)
 - **Prometheus `/metrics`** + **OpenTelemetry** — optional extras
 

{supython-0.1.8 → supython-0.1.10}/README.md

@@ -1,6 +1,6 @@
 # supython
 
-> A lightweight, Postgres-first BaaS framework for Python. **v0.1.4 release**
+> A lightweight, Postgres-first BaaS framework for Python.
 
 **the database owns the schema, Python owns the things SQL is bad at**. 
 It leans on [PostgREST](https://postgrest.org)
@@ -11,7 +11,7 @@ storage, functions, workers, and an optional admin control plane.
 supython is for a specific person with a specific problem:
 > A developer who wants to build a CRUD-heavy web app (most apps are), who thinks in SQL, who wants Postgres to own authorization, and who wants auth + storage + custom logic without assembling the integration themselves.
 
-Shipped [v0.1.2]:
+
 
 **Core platform**
 - **Email/password auth** — signup, login, refresh-token rotation with **reuse detection**
@@ -48,7 +48,7 @@ Shipped [v0.1.2]:
 - **Secret rotation** — JWT keys, symmetric secrets, Postgres passwords; all with zero-downtime runbooks
 - **Multi-arch Docker image** — `linux/amd64` + `linux/arm64`, non-root user, `tini` PID 1, ~64 MB
 
-**Admin control plane** (shipped in v0.1.2)
+**Admin control plane**
 - **Vue 3 + Vite SPA** at `/admin` — no runtime Node deps; pre-built static bundle in the wheel
 - **Database surface** — schema browser, table data with role switcher, SQL workspace (read-only default + write toggle), RLS policy editor with dry-run, migrations panel
 - **Auth surface** — user search, ban/unban/force-logout, refresh-token inspector, audit log, email template editing
@@ -335,7 +335,7 @@ supython dev
 | `JOBS_DRAIN_TIMEOUT_S` | `30.0` | Graceful shutdown drain (seconds) |
 | `JOBS_DEV_INPROCESS` | `false` | Spawn worker in-process during `supython dev` |
 
-## v0.2 auth endpoints
+## Auth endpoints
 
 | Endpoint | Method | Purpose |
 |---|---|---|
@@ -378,7 +378,7 @@ denylist without breaking that contract. The mitigation is a **short
   long-lived (`REFRESH_TOKEN_TTL=30d`) so users don't get prompted to log
   in every few minutes — clients refresh transparently.
 
-### Custom JWT claims [shipped v0.1.3]
+### Custom JWT claims
 
 Register a claims provider to inject application-specific claims into every
 access token minted by the auth endpoints. Each provider is an async callable
@@ -414,7 +414,7 @@ Notes:
 - Refresh re-collects claims, so a token rotated via `/auth/v1/refresh`
   reflects current state.
 
-### Reading the caller in your routes [shipped v0.1.4]
+### Reading the caller in your routes
 
 Application code mounts its own routers alongside supython's. To gate an
 endpoint on a valid bearer token — or to read custom claims out of it —
@@ -760,7 +760,7 @@ unit tests always run in isolation.
 **CI:** runners with Docker run `supython test up && supython test run`;
 runners without Docker run `pytest tests/unit` for a meaningful subset.
 
-## Roadmap [shipped v0.1.2]
+## Roadmap
 
 - ✅ Email/password auth, PostgREST contract, RLS demo
 - ✅ OAuth, password reset, magic link, OTP, reuse detection, email backend, test suite
@@ -771,12 +771,11 @@ runners without Docker run `pytest tests/unit` for a meaningful subset.
 - ✅ Production observable: structured JSON logs, `/livez`/`/readyz`/`/health`, security headers, input size guards, audit log completeness, OAuth PKCE, secret rotation runbooks
 - ✅ (partial) Multi-arch Docker images, admin control plane (Vue 3 SPA — database, auth, storage, functions, realtime, jobs, backups, log tail), CI buildx workflow; benchmarks + security audit pass + dependency budget CI remaining
 - *(deferred)* — Realtime v2 over logical replication
-- v0.1.2 Release — final sweep, tag, publish wheel, production deployment with no patches
 - ✅ **TypeScript SDK** — `@supython/sdk` wrapping `@supabase/postgrest-js` + `@supabase/realtime-js` 
 
-### Post v0.1.2
+### Future
 
-- **v1.1+** — Admin control plane polish (backend + frontend shipped in v0.1.2; tests + remaining DoD items deferred)
+- **Admin control plane** polish (tests + remaining DoD items)
 - **Realtime v2** — logical replication (demand-driven; swap when trigger overhead or >8KB payload data warrants it)
 - **Prometheus `/metrics`** + **OpenTelemetry** — optional extras
 

{supython-0.1.8 → supython-0.1.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "supython"
-version = "0.1.8"
+version = "0.1.10"
 description = "A lightweight Postgres-first BaaS framework for Python"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -32,6 +32,7 @@ dependencies = [
     "asyncpg>=0.30",
     "pydantic>=2.9",
     "pydantic-settings>=2.6",
+    "python-dotenv>=1.0",
     "email-validator>=2.2",
     "argon2-cffi>=23.1",
     "pyjwt[crypto]>=2.10",

{supython-0.1.8 → supython-0.1.10}/src/supython/app.py

@@ -27,7 +27,7 @@ from .body_size import BodySizeLimitMiddleware
 from .security_headers import SecurityHeadersMiddleware
 from .realtime import get_broker
 from .realtime.router import router as realtime_router
-from .settings import get_settings
+from .settings import export_env_file, get_settings
 from .storage.router import router as storage_router
 
 logger = logging.getLogger(__name__)
@@ -96,6 +96,7 @@ async def _lifespan(app: FastAPI) -> AsyncIterator[None]:
 
 
 def create_app() -> FastAPI:
+    export_env_file()
     settings = get_settings()
     configure_logging(settings.log_level, json_format=settings.log_json)
 

{supython-0.1.8 → supython-0.1.10}/src/supython/cli.py

@@ -22,7 +22,7 @@ from .db_admin import rotate_role_password
 from .gen import render_types_py, render_types_ts
 from .logging_config import configure_logging
 from .scaffold import scaffold
-from .settings import Settings, get_settings
+from .settings import Settings, export_env_file, get_settings
 
 app = typer.Typer(
     help="supython — lightweight Postgres-first BaaS for Python",
@@ -115,6 +115,23 @@ def _run_async(coro):  # type: ignore[no-untyped-def]
         return asyncio.run(coro)
 
 
+def _bootstrap_user_modules() -> None:
+    """Import the user's settings module + extensions so decorators register.
+
+    Mirrors ``worker_run`` and ``create_app``. CLI subcommands that read the
+    in-process registry (e.g. ``cron list``, ``cron sync``) must call this
+    first, otherwise the registry is empty and a ``cron sync`` would wipe
+    every row from ``jobs.cron_schedules``.
+    """
+    from .extensions import load_extensions
+    from .settings_module import UserSettings, load_user_settings
+
+    export_env_file()
+    s = get_settings()
+    user = load_user_settings(s.settings_module) if s.settings_module else UserSettings()
+    load_extensions([*s.extensions, *user.extensions])
+
+
 @gen_cli.command("types")
 def gen_types(
     lang: str = typer.Option("py", "--lang", help="Target language (`py` or `ts`)."),
@@ -232,6 +249,7 @@ def worker_run(
     from .jobs.worker import Worker
     from .settings_module import UserSettings, load_user_settings
 
+    export_env_file()
     s = get_settings()
     configure_logging(s.log_level, json_format=s.log_json)
     s.jobs_queue_default = queue
@@ -418,6 +436,7 @@ def cron_list() -> None:
     """List registered cron schedules."""
     from .jobs.registry import get_registry
 
+    _bootstrap_user_modules()
     crons = list(get_registry().iter_crons())
     if not crons:
         typer.echo("no crons registered.")
@@ -427,17 +446,29 @@ def cron_list() -> None:
 
 
 @cron_cli.command("sync")
-def cron_sync() -> None:
+def cron_sync(
+    allow_empty: bool = typer.Option(
+        False,
+        "--allow-empty",
+        help=(
+            "Allow sync to proceed when the in-process registry has no @cron "
+            "definitions but `jobs.cron_schedules` has rows. Without this "
+            "flag the sync refuses, because it would otherwise wipe every "
+            "row and unschedule every pg_cron entry."
+        ),
+    ),
+) -> None:
     """Sync registered crons with pg_cron."""
     from .jobs.cron import sync_pg_cron
 
+    _bootstrap_user_modules()
     s = get_settings()
 
     async def _run():
         conn = await asyncpg.connect(s.database_url)
         try:
             await conn.execute("set role service_role")
-            await sync_pg_cron(conn)
+            await sync_pg_cron(conn, allow_empty=allow_empty)
         finally:
             await conn.close()
 

{supython-0.1.8 → supython-0.1.10}/src/supython/jobs/cron.py

@@ -51,7 +51,11 @@ async def _as_login_role(conn: asyncpg.Connection) -> AsyncIterator[None]:
         await conn.execute(f'set {scope}role "{prev_role}"')
 
 
-async def sync_pg_cron(conn: asyncpg.Connection) -> None:
+async def sync_pg_cron(
+    conn: asyncpg.Connection,
+    *,
+    allow_empty: bool = False,
+) -> None:
     """Upsert ``pg_cron`` schedule rows from the registry and remove stale ones.
 
     The caller is expected to have entered ``db.as_service_role()`` (or
@@ -62,18 +66,41 @@ async def sync_pg_cron(conn: asyncpg.Connection) -> None:
     initialise a session at tick time.
 
     When pg_cron is installed, errors from ``cron.schedule`` propagate
-    to the caller. 
+    to the caller.
 
     When pg_cron is NOT installed the metadata row is still upserted so
     the in-process scheduler (or a manual runner) can pick it up, and
     ``cron.schedule`` is skipped entirely.
+
+    Raises ``ValueError`` when the in-process registry has no ``@cron``
+    definitions but ``jobs.cron_schedules`` is non-empty. That mismatch
+    almost always means the caller forgot to import the user's
+    ``EXTENSIONS`` before syncing, and proceeding would wipe every row
+    (and unschedule every pg_cron entry). Pass ``allow_empty=True`` to
+    intentionally clear the table.
     """
     registry = get_registry()
+    cron_defns = list(registry.iter_crons())
+
     has_pg_cron = await conn.fetchval(
         "select exists(select 1 from pg_extension where extname = 'pg_cron')"
     )
 
-    for cron_defn in registry.iter_crons():
+    if not cron_defns and not allow_empty:
+        existing_count = await conn.fetchval(
+            "select count(*) from jobs.cron_schedules"
+        )
+        if existing_count:
+            raise ValueError(
+                f"registry has no @cron definitions but jobs.cron_schedules "
+                f"holds {existing_count} row(s) — refusing to sync, since "
+                f"this would wipe the table and unschedule every pg_cron "
+                f"entry. Pass allow_empty=True to confirm, or check that "
+                f"the module containing your @cron decorators is listed in "
+                f"EXTENSIONS / SUPYTHON_SETTINGS_MODULE."
+            )
+
+    for cron_defn in cron_defns:
         await conn.execute(
             """
             insert into jobs.cron_schedules
@@ -123,7 +150,7 @@ async def sync_pg_cron(conn: asyncpg.Connection) -> None:
                 command,
             )
 
-    registered_names = {c.name for c in registry.iter_crons()}
+    registered_names = {c.name for c in cron_defns}
     existing = await conn.fetch("select name from jobs.cron_schedules")
     for row in existing:
         if row["name"] in registered_names:

{supython-0.1.8 → supython-0.1.10}/src/supython/jobs/decorators.py

@@ -59,18 +59,53 @@ def cron(
     job_version: int = 1,
     payload: dict | None = None,
     queue: str = "default",
+    register_handler: bool = True,
+    max_attempts: int = 3,
+    backoff: Backoff | str = Backoff.EXPONENTIAL,
+    backoff_base_s: float = 5.0,
+    backoff_max_s: float = 300.0,
+    role: str = "service_role",
+    claims_from: str | None = None,
+    accepts_payload: bool = True,
 ) -> Callable[..., Any]:
+    """Schedule the decorated function on a cron expression.
+
+    By default the decorated function is also registered as the handler for
+    ``job_name`` so pg_cron's tick → ``jobs.enqueue`` → worker dispatch
+    round-trip works without a separate ``@job`` declaration. Pass
+    ``register_handler=False`` when the schedule should fire a job whose
+    handler lives elsewhere (declared with ``@job``).
+    """
+    resolved_job_name = job_name or name
+
     def decorator(fn: Handler) -> Handler:
-        get_registry().register_cron(
+        registry = get_registry()
+        registry.register_cron(
             CronDefinition(
                 name=name,
                 cron_expr=cron_expr,
-                job_name=job_name or name,
+                job_name=resolved_job_name,
                 job_version=job_version,
                 payload=payload or {},
                 queue=queue,
             )
         )
+        if register_handler:
+            registry.register_job(
+                JobDefinition(
+                    name=resolved_job_name,
+                    version=job_version,
+                    handler=fn,
+                    max_attempts=max_attempts,
+                    backoff=backoff if isinstance(backoff, str) else backoff.value,
+                    backoff_base_s=backoff_base_s,
+                    backoff_max_s=backoff_max_s,
+                    queue=queue,
+                    role=role,
+                    claims_from=claims_from,
+                    accepts_payload=accepts_payload,
+                )
+            )
         return fn
 
     return decorator

{supython-0.1.8 → supython-0.1.10}/src/supython/settings.py

@@ -2,6 +2,7 @@ from functools import lru_cache
 from pathlib import Path
 from typing import Annotated, Literal
 
+from dotenv import load_dotenv
 from pydantic import Field, field_validator
 from pydantic_settings import BaseSettings, NoDecode, SettingsConfigDict
 
@@ -242,3 +243,33 @@ class Settings(BaseSettings):
 @lru_cache
 def get_settings() -> Settings:
     return Settings()
+
+
+def export_env_file() -> None:
+    """Export the env file ``Settings`` reads into ``os.environ``.
+
+    pydantic-settings loads ``env_file`` into the typed ``Settings`` model only;
+    it never touches ``os.environ``. Code that resolves a *dynamically-named*
+    secret — one whose env var name is not known until runtime (e.g. read from a
+    DB column) and so cannot be a typed ``Settings`` field but must be read via
+    ``os.environ.get(<name>)`` — therefore sees nothing from ``.env`` when the
+    process is launched by supython itself (``supython dev``, ``worker run``, a
+    CLI subcommand). In a container it works only by accident: docker-compose's
+    ``env_file:`` injects ``.env`` into the real process environment first.
+
+    Mirror ``uvicorn --env-file``: load the same file with ``override=False`` so
+    variables already present in the real environment (set by the orchestrator)
+    always win over a checked-in ``.env``. The path is sourced from the same
+    ``SettingsConfigDict.env_file`` ``Settings`` uses, never re-hardcoded.
+    Idempotent — safe to call from every boot path; a missing file is a no-op.
+    """
+    env_file = Settings.model_config.get("env_file")
+    if not env_file:
+        return
+    encoding = Settings.model_config.get("env_file_encoding") or "utf-8"
+    paths = [env_file] if isinstance(env_file, str | Path) else list(env_file)
+    # pydantic gives the *last* listed file precedence; load_dotenv(override=
+    # False) gives the *first*-loaded value precedence — so walk in reverse to
+    # preserve that ordering while still letting the real environment win.
+    for path in reversed(paths):
+        load_dotenv(path, override=False, encoding=encoding)