supython 0.1.7__tar.gz → 0.1.9__tar.gz

{supython-0.1.7 → supython-0.1.9}/CHANGELOG.md

@@ -31,6 +31,39 @@ Each entry links the relevant `PROJECT.md` section and decision-log row
 
 ---
 
+## [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 +234,5 @@ v0.1–v0.7 plus a v1.1.x admin track; see §19 decision log
 ---
 
 
+[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.7 → supython-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: supython
-Version: 0.1.7
+Version: 0.1.9
 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
@@ -58,7 +58,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 +69,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 +106,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 +393,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 +436,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 +472,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 +818,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 +829,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.7 → supython-0.1.9}/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.7 → supython-0.1.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "supython"
-version = "0.1.7"
+version = "0.1.9"
 description = "A lightweight Postgres-first BaaS framework for Python"
 readme = "README.md"
 requires-python = ">=3.11"

{supython-0.1.7 → supython-0.1.9}/src/supython/cli.py

@@ -115,6 +115,22 @@ 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
+
+    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`)."),
@@ -418,6 +434,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 +444,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()
 
@@ -1355,14 +1384,22 @@ def up(
     timeout: int = typer.Option(30, help="Seconds to wait for Postgres."),
     prod: bool = typer.Option(False, "--prod", help="Use docker-compose.prod.yml."),
     worker: bool = typer.Option(False, "--worker", help="Also start the worker (prod only)."),
+    profile: list[str] = typer.Option(
+        [],
+        "--profile",
+        help="Compose profile(s) to enable. Repeatable; user-defined extension services gated by a profile come up via a final sweep.",
+    ),
 ) -> None:
     """Start Postgres + PostgREST and apply migrations.
 
     Brings the DB up first, runs migrations (which create the roles
     PostgREST needs), rotates the authenticator password, then starts PostgREST.
+    Any user-added services gated behind a compose profile come up after the
+    core services when `--profile <name>` is passed.
     """
     compose_file = _resolve_compose_file(prod)
     is_prod = compose_file == "docker-compose.prod.yml"
+    user_profiles = tuple(profile)
     configure_logging("INFO", json_format=False)
     _compose_with(compose_file, "up", "-d", "db")
     typer.echo("waiting for Postgres ...")
@@ -1379,6 +1416,8 @@ def up(
         _compose_with(compose_file, "up", "-d", "postgrest", "supython")
         if worker:
             _compose_with(compose_file, "--profile", "worker", "up", "-d", "worker")
+        if user_profiles:
+            _compose_with(compose_file, "up", "-d", profiles=user_profiles)
         typer.echo("")
         typer.echo("ready.")
         typer.echo("  postgres   localhost:54322  (bind 127.0.0.1 only)")
@@ -1386,12 +1425,18 @@ def up(
         typer.echo("  supython   http://localhost:8000")
         if worker:
             typer.echo("  worker     running (profile=worker)")
+        for p in user_profiles:
+            typer.echo(f"  profile    {p}   # user-defined services")
     else:
         _compose_with(compose_file, "up", "-d", "postgrest")
+        if user_profiles:
+            _compose_with(compose_file, "up", "-d", profiles=user_profiles)
         typer.echo("")
         typer.echo("ready.")
         typer.echo("  postgres   localhost:54322  (user/db: supython)")
         typer.echo(f"  postgrest  {s.postgrest_url}")
+        for p in user_profiles:
+            typer.echo(f"  profile    {p}   # user-defined services")
         typer.echo("  next       supython dev   # start the auth/API service")
 
 
@@ -1610,11 +1655,15 @@ def _compose(*args: str) -> None:
     _compose_with(None, *args)
 
 
-def _compose_with(file: str | None, *args: str) -> None:
-    """Run `docker compose [-f <file>] <args...>`, surfacing common errors."""
+def _compose_with(
+    file: str | None, *args: str, profiles: tuple[str, ...] = ()
+) -> None:
+    """Run `docker compose [-f <file>] [--profile <p>]... <args...>`, surfacing common errors."""
     cmd = ["docker", "compose"]
     if file:
         cmd += ["-f", file]
+    for p in profiles:
+        cmd += ["--profile", p]
     cmd += list(args)
     try:
         subprocess.run(cmd, check=True)

{supython-0.1.7 → supython-0.1.9}/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.7 → supython-0.1.9}/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