aflib 0.0.2__tar.gz → 0.0.6__tar.gz

{aflib-0.0.2 → aflib-0.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: aflib
-Version: 0.0.2
+Version: 0.0.6
 Summary: Helper library for business logic inside Airflows plpython function bodies
 License: MIT
 License-File: LICENSE
@@ -26,15 +26,42 @@ so low.
 
 Airflows resolves Python packages from public PyPI by name and version only; there is no
 local-import, git or private-index route. Declare it in
-`models/pythonPackages/pythonPackages.airflows`:
+`models/pythonPackages/pythonPackages.airflows` by pinning **name and version in
+separate fields** — never as a single `aflib==0.0.6` string (that form produced
+malformed `name==ver==ver` entries in a real instance's package list):
 
 ```
-pythonPackage aflib==0.0.2
+name:    aflib
+version: 0.0.6
 ```
 
 Then import it from a function body.
 
-## What 0.0.2 gives you
+## What 0.0.6 gives you
+
+0.0.1–0.0.3 (read/result, errors/logging, `transaction.atomic`) plus what
+the 2026-09 platform probes showed, plus two verified fixes:
+
+- **`params.as_bool`** accepts a genuine Python `bool` as well as the
+  `true`/`false`/`1`/`0`/`t`/`f` text vocabulary. A `boolean` customParameter
+  on the non-HTTP path binds as `True`/`False`; converting that through
+  `as_bool` no longer raises.
+- **`logging`** treats `source` as reserved, the same way it already treats
+  `level` and `event`. Passing `source=` as a field raises rather than
+  silently re-labelling the emitting function.
+- **`authz.can(plpy, "Schema.Entity", "UPDATE")`** and **`authz.snapshot(plpy)`** —
+  table GRANTs via `has_table_privilege`. Not RLS. Snapshot before `SET ROLE`.
+- **`trigger.changed(TD)` / `event` / `when`** — a plpython trigger can
+  write `TD["new"]` and return `"MODIFY"`. Compare OLD/NEW; ignore `search`.
+- **`functions.call(plpy, "Schema.fn", args, argtypes)`** — compose through
+  SQL with **Postgres** bind types. Text binds to a typed signature do not
+  resolve.
+- **`identity.current_user(plpy)`** — `SELECT current_user`. Not a User id.
+
+Pin **name and version in separate fields** (`aflib` / `0.0.6`), not
+`aflib==0.0.6` as one string.
+
+## Core API (0.0.1–0.0.3, still in 0.0.6)
 
 ```python
 from aflib import Db, errors, fail, logging, ok, params
@@ -85,6 +112,9 @@ except Exception as exc:
   present, written through `plpy.log`. It never raises, even when handed a value that cannot
   be encoded: the line is most needed in the error path, so a single exotic field must not be
   able to silence it.
+- **`transaction.atomic(plpy)`** — a savepoint that also rolls back a *returned* failure. See
+  [A returned failure does not roll back](#a-returned-failure-does-not-roll-back) — this is a
+  narrow helper for one specific trap, not a unit of work.
 
 ## Platform constraints worth knowing before you build on it
 
@@ -93,8 +123,9 @@ the library has the shape it does.
 
 - **Every HTTP-facing parameter must be declared `text`.** Declare `integer` and the platform
   binds `varchar` at call time, no candidate signature matches, and the endpoint fails with
-  *function does not exist* — it cannot be invoked at all. This is not a casting
-  inconvenience; the endpoint is simply unreachable. Convert inside the body instead.
+  *function does not exist*. A `boolean` parameter binds `true`/`false`, but `?p_flag=maybe`
+  is HTTP 500 `Cannot cast to boolean` before the body runs. Convert with `params` inside
+  the body.
 - **Function bodies compose only through SQL** — `SELECT "Schema"."fn"(…)`. There is no
   shared module and no package-local import, so a helper another body needs is a database
   function, not a Python one.
@@ -137,6 +168,51 @@ Two related facts worth knowing before you design around logging:
   *type* does not. So a business outcome has to travel as a returned value — `ok`/`fail` — and
   never as an exception, and nothing sensitive may ever go into an exception message.
 
+### A returned failure does not roll back
+
+A function body is **one transaction it does not control.** `plpy.commit()` fails with *invalid
+transaction termination*, because a function invoked inside a query cannot terminate the
+transaction it is running in. What a body *can* do is subdivide that transaction with savepoints
+via `plpy.subtransaction()`, and those work exactly as you would hope: they roll back on any
+exception, Python or SQL alike, the original exception continues unchanged, nesting rolls back
+only the inner block, and a trigger's writes roll back together with the row that fired them.
+
+Two further rules complete the picture: **an uncaught exception discards the whole call**, and
+**a normal return commits the whole call.**
+
+That last one is the trap, because it applies to a returned *failure* too:
+
+```python
+with plpy.subtransaction():
+    db.query("INSERT …")
+    return fail("not_allowed", "…")     # the INSERT is COMMITTED
+```
+
+`plpy.subtransaction()` reacts to exceptions, and a business failure is not an exception — it
+cannot be, since an exception's type does not survive crossing a function boundary. So the most
+natural code silently half-applies the change. `transaction.atomic` exists for exactly this:
+
+```python
+from aflib import errors, transaction
+
+try:
+    with transaction.atomic(plpy) as tx:
+        db.query("INSERT …")
+        if not allowed:
+            tx.reject("not_allowed", "You may not do that")   # rolls back
+        tx.succeed({"id": 7})
+    return tx.outcome
+except Exception as exc:
+    return errors.to_fail(exc, log=log)
+```
+
+`reject()` ends the block and rolls back; `outcome` is read afterwards. A scope that ends
+without `succeed()` or `reject()` raises rather than returning an empty success for work that
+may have half happened.
+
+It is deliberately **not** a unit of work and cannot commit anything — the name describes the
+guarantee it provides (the block is all-or-nothing), not machinery it does not have.
+
 ## Tests
 
 ```

{aflib-0.0.2 → aflib-0.0.6}/README.md

@@ -17,15 +17,42 @@ so low.
 
 Airflows resolves Python packages from public PyPI by name and version only; there is no
 local-import, git or private-index route. Declare it in
-`models/pythonPackages/pythonPackages.airflows`:
+`models/pythonPackages/pythonPackages.airflows` by pinning **name and version in
+separate fields** — never as a single `aflib==0.0.6` string (that form produced
+malformed `name==ver==ver` entries in a real instance's package list):
 
 ```
-pythonPackage aflib==0.0.2
+name:    aflib
+version: 0.0.6
 ```
 
 Then import it from a function body.
 
-## What 0.0.2 gives you
+## What 0.0.6 gives you
+
+0.0.1–0.0.3 (read/result, errors/logging, `transaction.atomic`) plus what
+the 2026-09 platform probes showed, plus two verified fixes:
+
+- **`params.as_bool`** accepts a genuine Python `bool` as well as the
+  `true`/`false`/`1`/`0`/`t`/`f` text vocabulary. A `boolean` customParameter
+  on the non-HTTP path binds as `True`/`False`; converting that through
+  `as_bool` no longer raises.
+- **`logging`** treats `source` as reserved, the same way it already treats
+  `level` and `event`. Passing `source=` as a field raises rather than
+  silently re-labelling the emitting function.
+- **`authz.can(plpy, "Schema.Entity", "UPDATE")`** and **`authz.snapshot(plpy)`** —
+  table GRANTs via `has_table_privilege`. Not RLS. Snapshot before `SET ROLE`.
+- **`trigger.changed(TD)` / `event` / `when`** — a plpython trigger can
+  write `TD["new"]` and return `"MODIFY"`. Compare OLD/NEW; ignore `search`.
+- **`functions.call(plpy, "Schema.fn", args, argtypes)`** — compose through
+  SQL with **Postgres** bind types. Text binds to a typed signature do not
+  resolve.
+- **`identity.current_user(plpy)`** — `SELECT current_user`. Not a User id.
+
+Pin **name and version in separate fields** (`aflib` / `0.0.6`), not
+`aflib==0.0.6` as one string.
+
+## Core API (0.0.1–0.0.3, still in 0.0.6)
 
 ```python
 from aflib import Db, errors, fail, logging, ok, params
@@ -76,6 +103,9 @@ except Exception as exc:
   present, written through `plpy.log`. It never raises, even when handed a value that cannot
   be encoded: the line is most needed in the error path, so a single exotic field must not be
   able to silence it.
+- **`transaction.atomic(plpy)`** — a savepoint that also rolls back a *returned* failure. See
+  [A returned failure does not roll back](#a-returned-failure-does-not-roll-back) — this is a
+  narrow helper for one specific trap, not a unit of work.
 
 ## Platform constraints worth knowing before you build on it
 
@@ -84,8 +114,9 @@ the library has the shape it does.
 
 - **Every HTTP-facing parameter must be declared `text`.** Declare `integer` and the platform
   binds `varchar` at call time, no candidate signature matches, and the endpoint fails with
-  *function does not exist* — it cannot be invoked at all. This is not a casting
-  inconvenience; the endpoint is simply unreachable. Convert inside the body instead.
+  *function does not exist*. A `boolean` parameter binds `true`/`false`, but `?p_flag=maybe`
+  is HTTP 500 `Cannot cast to boolean` before the body runs. Convert with `params` inside
+  the body.
 - **Function bodies compose only through SQL** — `SELECT "Schema"."fn"(…)`. There is no
   shared module and no package-local import, so a helper another body needs is a database
   function, not a Python one.
@@ -128,6 +159,51 @@ Two related facts worth knowing before you design around logging:
   *type* does not. So a business outcome has to travel as a returned value — `ok`/`fail` — and
   never as an exception, and nothing sensitive may ever go into an exception message.
 
+### A returned failure does not roll back
+
+A function body is **one transaction it does not control.** `plpy.commit()` fails with *invalid
+transaction termination*, because a function invoked inside a query cannot terminate the
+transaction it is running in. What a body *can* do is subdivide that transaction with savepoints
+via `plpy.subtransaction()`, and those work exactly as you would hope: they roll back on any
+exception, Python or SQL alike, the original exception continues unchanged, nesting rolls back
+only the inner block, and a trigger's writes roll back together with the row that fired them.
+
+Two further rules complete the picture: **an uncaught exception discards the whole call**, and
+**a normal return commits the whole call.**
+
+That last one is the trap, because it applies to a returned *failure* too:
+
+```python
+with plpy.subtransaction():
+    db.query("INSERT …")
+    return fail("not_allowed", "…")     # the INSERT is COMMITTED
+```
+
+`plpy.subtransaction()` reacts to exceptions, and a business failure is not an exception — it
+cannot be, since an exception's type does not survive crossing a function boundary. So the most
+natural code silently half-applies the change. `transaction.atomic` exists for exactly this:
+
+```python
+from aflib import errors, transaction
+
+try:
+    with transaction.atomic(plpy) as tx:
+        db.query("INSERT …")
+        if not allowed:
+            tx.reject("not_allowed", "You may not do that")   # rolls back
+        tx.succeed({"id": 7})
+    return tx.outcome
+except Exception as exc:
+    return errors.to_fail(exc, log=log)
+```
+
+`reject()` ends the block and rolls back; `outcome` is read afterwards. A scope that ends
+without `succeed()` or `reject()` raises rather than returning an empty success for work that
+may have half happened.
+
+It is deliberately **not** a unit of work and cannot commit anything — the name describes the
+guarantee it provides (the block is all-or-nothing), not machinery it does not have.
+
 ## Tests
 
 ```

{aflib-0.0.2 → aflib-0.0.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "aflib"
-version = "0.0.2"
+version = "0.0.6"
 description = "Helper library for business logic inside Airflows plpython function bodies"
 readme = "README.md"
 # The platform runs Python 3.11.2 (observed, not assumed — see docs/platform-constraints.md).
@@ -26,11 +26,14 @@ packages = ["src/aflib"]
 #
 # Note this file is itself published: nothing in these comments should be anything you
 # would not put on a public page.
+# Patterns are gitignore-style: unanchored names match at ANY depth (a bare
+# "README.md" also swept in docs/README.md — observed in the 0.0.6 build). The
+# leading "/" anchors each entry to the repo root so only the intended files ship.
 [tool.hatch.build.targets.sdist]
 include = [
-    "src/aflib",
-    "tests",
-    "README.md",
-    "LICENSE",
+    "/src/aflib",
+    "/tests",
+    "/README.md",
+    "/LICENSE",
 ]
 

{aflib-0.0.2 → aflib-0.0.6}/src/aflib/__init__.py

@@ -24,14 +24,26 @@ A function body's whole import line, and the shape of a body:
         return errors.to_fail(exc, log=log)
 
 **The `try` is not optional.** An exception that escapes a function body is returned to the
-HTTP caller along with the function's name, the failing line number and the literal source
-line — so catching everything is a security control, not a matter of taste. `except
+HTTP caller carrying internal detail the caller should not see, and a body cannot influence
+that response — so catching everything is a security control, not a matter of taste. `except
 Exception` is also the only clause that works: `plpy.Error` does not inherit from
 `plpy.SPIError`, so the narrower version catches neither `plpy.error()` nor an ordinary
 Python exception.
 """
 
-from aflib import codec, db, errors, logging, params, result
+from aflib import (
+    authz,
+    codec,
+    db,
+    errors,
+    functions,
+    identity,
+    logging,
+    params,
+    result,
+    transaction,
+    trigger,
+)
 from aflib.db import Db
 from aflib.params import BadParameter
 from aflib.result import fail, ok
@@ -39,18 +51,23 @@ from aflib.result import fail, ok
 # Kept in step with `pyproject.toml` by hand. A deployed body returns this so a run can
 # prove which aflib it actually imported — a stale package otherwise looks exactly like a
 # working one.
-__version__ = "0.0.2"
+__version__ = "0.0.6"
 
 __all__ = [
     "BadParameter",
     "Db",
+    "authz",
     "codec",
     "db",
     "errors",
     "fail",
+    "functions",
+    "identity",
     "logging",
     "ok",
     "params",
     "result",
+    "transaction",
+    "trigger",
     "__version__",
 ]

aflib-0.0.6/src/aflib/authz.py

@@ -0,0 +1,86 @@
+"""Table GRANTs for the current caller (`entityPermission`).
+
+Not RLS and not business rules. `can("AdminCentre.Delivery", "UPDATE")` is
+`has_table_privilege` on this connection. A `SELECT` of a missing or
+RLS-hidden id returns **zero rows**, not an error — do not turn that into
+403.
+
+Take a `snapshot` **before** `SET ROLE modelsadmin`. After elevation,
+`has_table_privilege(current_user, …)` is the elevated role. The snapshot
+keeps the caller's answers in a local dict (never `GD`/`SD`).
+
+    from aflib import authz
+
+    az = authz.snapshot(plpy)
+    if not az.can("AdminCentre.Delivery", "INSERT"):
+        return fail("forbidden", "Cannot create a delivery")
+
+A single check with no later SET ROLE can call `authz.can(plpy, entity, verb)`
+and skip the snapshot.
+
+Observed 2026-09-18: `has_table_privilege` is callable from a plpython
+body; SET ROLE modelsadmin changes `current_user` (when the caller is
+allowed to elevate). HTTP `boolean` params are unrelated (G55).
+"""
+
+from __future__ import annotations
+
+import re
+
+from aflib import identity
+
+_IDENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_VERBS = frozenset({"SELECT", "INSERT", "UPDATE", "DELETE"})
+
+
+def _regclass(entity: str) -> str:
+    parts = entity.split(".")
+    if len(parts) != 2:
+        raise ValueError("expected Schema.Entity, got {!r}".format(entity))
+    for part in parts:
+        if not _IDENT.match(part):
+            raise ValueError("invalid identifier {!r} in {!r}".format(part, entity))
+    return '"{}"."{}"'.format(parts[0], parts[1])
+
+
+def _verb(verb: str) -> str:
+    v = (verb or "").upper()
+    if v not in _VERBS:
+        raise ValueError(
+            "verb must be SELECT, INSERT, UPDATE or DELETE, got {!r}".format(verb)
+        )
+    return v
+
+
+def can(plpy, entity, verb, cache=None):
+    """Whether *this connection* has GRANT `verb` on `entity`."""
+    table = _regclass(entity)
+    v = _verb(verb)
+    key = (table, v)
+    if cache is not None and key in cache:
+        return cache[key]
+    plan = plpy.prepare(
+        "SELECT has_table_privilege(current_user, $1, $2) AS ok",
+        ["text", "text"],
+    )
+    row = plpy.execute(plan, [table, v])[0]
+    ok = bool(row["ok"])
+    if cache is not None:
+        cache[key] = ok
+    return ok
+
+
+class Snapshot:
+    """Caller's GRANTs, frozen at construction time."""
+
+    def __init__(self, plpy):
+        self.username = identity.current_user(plpy)
+        self._plpy = plpy
+        self._cache = {}
+
+    def can(self, entity, verb):
+        return can(self._plpy, entity, verb, cache=self._cache)
+
+
+def snapshot(plpy) -> Snapshot:
+    return Snapshot(plpy)

{aflib-0.0.2 → aflib-0.0.6}/src/aflib/errors.py

@@ -10,11 +10,9 @@
         return errors.to_fail(exc, log=log)
 
 **Why a body must catch everything.** An exception that escapes is returned to the HTTP
-caller together with the function's name, the failing line number and the literal source
-line. Every `httpEnabled` endpoint is directly reachable, so an uncaught error is a
-source-disclosure primitive: make a function fail, read one line of it, and repeat. The
-platform produces that response in its own Java handler from the JDBC driver's message —
-there is no setting that suppresses it, and nothing a body can do except not raise.
+caller carrying internal detail that the caller should not see. A body cannot influence that
+response — it is assembled outside the database from the driver's error message, and no
+setting trims it — so the only way to control what a caller receives is to not raise.
 
 **`except Exception` is not laziness here, it is the only sufficient clause.** `plpy.Error`
 does not inherit from `plpy.SPIError`, so the narrower `except plpy.SPIError` catches
@@ -79,7 +77,7 @@ def to_fail(exc, log=None):
     """Log what must stay hidden, and return the failure envelope for the caller.
 
     The envelope is returned even if logging fails. A broken sink must not turn a handled
-    failure back into an escaping exception — that would disclose source at the very moment
+    failure back into an escaping exception — that would expose internal detail at the very moment
     the code was trying to prevent it.
     """
     failure = classify(exc)

aflib-0.0.6/src/aflib/functions.py

@@ -0,0 +1,72 @@
+"""Call another Airflows function with real Postgres types.
+
+Bodies cannot import each other. The only composition channel is SQL:
+`SELECT "Schema"."fn"(…)`. HTTP binds every query argument as `varchar`,
+so a helper that prepared `text` for convenience would make every typed
+callee unreachable — observed 2026-09-17: `aflib_probe_typed(integer,
+numeric, jsonb, text)` succeeded with those binds and failed with four
+`text` binds (`function does not exist`).
+
+    from aflib import functions
+
+    raw = functions.call(
+        plpy,
+        "Master.aflib_probe_typed",
+        [42, "1.50", '{"k": 1}', "hello"],
+        ["integer", "numeric", "jsonb", "text"],
+    )
+
+The return is the first column of the first row (`AS r` in the generated
+SELECT), or `None` if the statement returned nothing. This does not
+decode JSON: if the callee returned an envelope string, the caller
+loads it.
+"""
+
+from __future__ import annotations
+
+import re
+
+_IDENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def _qualified(name: str) -> str:
+    parts = name.split(".")
+    if len(parts) != 2:
+        raise ValueError("expected Schema.function, got {!r}".format(name))
+    for part in parts:
+        if not _IDENT.match(part):
+            raise ValueError("invalid identifier {!r} in {!r}".format(part, name))
+    return '"{}"."{}"'.format(parts[0], parts[1])
+
+
+def call(plpy, name, args, argtypes):
+    """`SELECT "Schema"."fn"($1, …)` with explicit bind types.
+
+    `args` and `argtypes` must be the same length. Types are Postgres
+    names (`integer`, `jsonb`, …), never inferred from Python values.
+    """
+    if args is None:
+        args = []
+        argtypes = []
+    if argtypes is None or len(args) != len(argtypes):
+        raise ValueError(
+            "a call with {} args needs {} argtypes, got {}".format(
+                len(args),
+                len(args),
+                0 if argtypes is None else len(argtypes),
+            )
+        )
+    qualified = _qualified(name)
+    if not args:
+        sql = "SELECT {}() AS r".format(qualified)
+        result = plpy.execute(sql)
+    else:
+        placeholders = ", ".join(
+            "${}".format(i) for i in range(1, len(args) + 1)
+        )
+        sql = "SELECT {}({}) AS r".format(qualified, placeholders)
+        plan = plpy.prepare(sql, list(argtypes))
+        result = plpy.execute(plan, list(args))
+    if not result:
+        return None
+    return result[0]["r"]

aflib-0.0.6/src/aflib/identity.py

@@ -0,0 +1,20 @@
+"""Who is running this body.
+
+A plpython body has no request object. The platform sets the connection
+role to a Postgres role named after the caller's username — observed:
+`current_user` is the caller, not a GUC and not `getUserId()` (that
+name did not exist on the instance, 2026-09-17).
+
+    from aflib import identity
+
+    who = identity.current_user(plpy)
+
+This is the string. Mapping it to `Models.User` is a domain query, not
+this module. Do not cache it in `GD`/`SD`.
+"""
+
+
+def current_user(plpy) -> str:
+    """`SELECT current_user` — the connection role for this call."""
+    row = plpy.execute("SELECT current_user AS u")[0]
+    return row["u"]

{aflib-0.0.2 → aflib-0.0.6}/src/aflib/logging.py

@@ -29,9 +29,11 @@ them cannot reduce that exposure and only makes it look deliberate.
 import json
 from decimal import Decimal
 
-# `level` and `event` are how a line is found in a log that is grepped rather than
-# queried. A field silently overwriting either would break every search built on them.
-_RESERVED = ("level", "event")
+# `level`, `event` and `source` are how a line is found in a log that is grepped
+# rather than queried. A field silently overwriting any of them would break every
+# search built on them. `source` is set on the logger, not per call; letting a
+# field overwrite it would re-label the emitting function.
+_RESERVED = ("level", "event", "source")
 
 
 def _lenient(value):

{aflib-0.0.2 → aflib-0.0.6}/src/aflib/params.py

@@ -58,11 +58,23 @@ _FALSE = frozenset(("false", "0", "f"))
 
 
 def as_bool(value, name=None, required=False):
-    """Convert `value` to a `bool`, or `None` when it was left blank."""
+    """Convert `value` to a `bool`, or `None` when it was left blank.
+
+    Declare the HTTP parameter `text`. A `boolean` customParameter never
+    reaches this converter on a typo: the HTTP layer returns 500
+    `Cannot cast to boolean: "maybe"` before the body runs (observed
+    2026-09-18). `true`/`false` as a boolean parameter do bind as Python
+    `bool`; still use `text` so a bad flag is `BadParameter`, not a 500.
+    """
     if _blank(value):
         if required:
             _fail(name, "a value is required")
         return None
+    # A `boolean` customParameter on the non-HTTP path binds as a real Python
+    # bool. That is never blank, and converting it through as_bool must not
+    # reject a value that is already the right type.
+    if isinstance(value, bool):
+        return value
     folded = value.strip().lower() if isinstance(value, str) else value
     if folded in _TRUE:
         return True