aflib 0.0.2__tar.gz → 0.0.7__tar.gz

{aflib-0.0.2 → aflib-0.0.7}/.gitignore

@@ -5,3 +5,4 @@ build/
 dist/
 .venv/
 .pytest_cache/
+.env

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: aflib
-Version: 0.0.2
+Version: 0.0.7
 Summary: Helper library for business logic inside Airflows plpython function bodies
 License: MIT
 License-File: LICENSE
@@ -26,15 +26,75 @@ 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.7` 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.7
 ```
 
 Then import it from a function body.
 
-## What 0.0.2 gives you
+## What 0.0.7 gives you
+
+Everything in 0.0.6, plus three capabilities that ran on a real instance on
+2026-10-01 before they were extracted:
+
+- **`Batch(plpy).run(...)`** — one committed chunk. The pending predicate is
+  placed in the outer `WHERE` and in the subquery, and the result carries
+  `done`, `remaining` and `seconds`.
+- **`workflow.start` / `status` / `stuck`** — insert a `PENDING` workflow
+  instance and its variables, read the newest instance for a business key, and
+  list instances that are still `PENDING` or `IN_PROGRESS` after an interval.
+- **`Outbox(plpy, outbox=..., delivery=..., subscription=...).emit` / `pump`** —
+  one event plus a pending delivery per active subscriber, then a chunk of
+  deliveries. Each subscriber runs inside `plpy.subtransaction()`. Failures
+  retry with `attempts`, `next_attempt_at` and `last_error`, and dead-letter
+  after 3 attempts.
+
+```python
+from aflib import workflow
+from aflib.events import Outbox
+
+workflow.start(plpy, "WFP_cadena", "case-58", {
+    "SomeSchema.some_function.p_id": ("INTEGER", 42),
+})
+
+box = Outbox(plpy, outbox="app.outbox", delivery="app.delivery", subscription="app.sub")
+box.emit("order.placed", {"id": 42}, 42)
+box.pump(deliver, limit=50)
+```
+
+`deliver(subscriber, outbox_id, attempt)` does the work and raises to fail the
+attempt. Table names are identifiers you wrote, not request data.
+
+## 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.7`), not
+`aflib==0.0.7` as one string.
+
+## Core API (0.0.1–0.0.3, still in 0.0.7)
 
 ```python
 from aflib import Db, errors, fail, logging, ok, params
@@ -85,6 +145,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 +156,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 +201,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.7}/README.md

@@ -17,15 +17,75 @@ 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.7` 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.7
 ```
 
 Then import it from a function body.
 
-## What 0.0.2 gives you
+## What 0.0.7 gives you
+
+Everything in 0.0.6, plus three capabilities that ran on a real instance on
+2026-10-01 before they were extracted:
+
+- **`Batch(plpy).run(...)`** — one committed chunk. The pending predicate is
+  placed in the outer `WHERE` and in the subquery, and the result carries
+  `done`, `remaining` and `seconds`.
+- **`workflow.start` / `status` / `stuck`** — insert a `PENDING` workflow
+  instance and its variables, read the newest instance for a business key, and
+  list instances that are still `PENDING` or `IN_PROGRESS` after an interval.
+- **`Outbox(plpy, outbox=..., delivery=..., subscription=...).emit` / `pump`** —
+  one event plus a pending delivery per active subscriber, then a chunk of
+  deliveries. Each subscriber runs inside `plpy.subtransaction()`. Failures
+  retry with `attempts`, `next_attempt_at` and `last_error`, and dead-letter
+  after 3 attempts.
+
+```python
+from aflib import workflow
+from aflib.events import Outbox
+
+workflow.start(plpy, "WFP_cadena", "case-58", {
+    "SomeSchema.some_function.p_id": ("INTEGER", 42),
+})
+
+box = Outbox(plpy, outbox="app.outbox", delivery="app.delivery", subscription="app.sub")
+box.emit("order.placed", {"id": 42}, 42)
+box.pump(deliver, limit=50)
+```
+
+`deliver(subscriber, outbox_id, attempt)` does the work and raises to fail the
+attempt. Table names are identifiers you wrote, not request data.
+
+## 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.7`), not
+`aflib==0.0.7` as one string.
+
+## Core API (0.0.1–0.0.3, still in 0.0.7)
 
 ```python
 from aflib import Db, errors, fail, logging, ok, params
@@ -76,6 +136,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 +147,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 +192,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.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "aflib"
-version = "0.0.2"
+version = "0.0.7"
 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.7}/src/aflib/__init__.py

@@ -24,33 +24,60 @@ 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,
+    batch,
+    codec,
+    db,
+    errors,
+    events,
+    functions,
+    identity,
+    logging,
+    params,
+    result,
+    transaction,
+    trigger,
+    workflow,
+)
+from aflib.batch import Batch
 from aflib.db import Db
+from aflib.events import Outbox
 from aflib.params import BadParameter
 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.7"
 
 __all__ = [
     "BadParameter",
+    "Batch",
     "Db",
+    "Outbox",
+    "authz",
+    "batch",
     "codec",
     "db",
     "errors",
+    "events",
     "fail",
+    "functions",
+    "identity",
     "logging",
     "ok",
     "params",
     "result",
+    "transaction",
+    "trigger",
+    "workflow",
     "__version__",
 ]

aflib-0.0.7/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.7/src/aflib/batch.py

@@ -0,0 +1,141 @@
+"""Work through a backlog one committed chunk at a time.
+
+    from aflib.batch import Batch
+
+    batch = Batch(plpy)
+
+    progress = batch.run(
+        table="\\"Economic\\".\\"Receipt\\"",
+        set_clause='id_status = $1',
+        pending='id_status = $2 AND (period_from IS NULL OR period_from <= CURRENT_DATE + 5)',
+        args=[pending_id, planned_id],
+        types=["integer", "integer"],
+        limit=1000,
+    )
+
+    return ok({"done": progress.done, "remaining": progress.remaining})
+
+One call is one chunk. The caller decides what drives the next one — a `pg_cron` job, the
+next step of a workflow, a human pressing a button again — and each call is its own
+transaction, so each chunk is **kept** whether or not the next one happens.
+
+**Why a function and not a loop.** A plpgsql or plpython function cannot commit: it runs
+inside a transaction it does not own, and `plpy.commit()` fails with *invalid transaction
+termination*. There are no `PROCEDURE`s on the platform either (401 functions, zero
+procedures, measured 2026-10-01), so the usual `LOOP … COMMIT` shape has nowhere to live.
+A chunk per invocation is not a stylistic choice; it is the only way to commit progress.
+
+**The one rule this exists to enforce: the pending predicate goes in two places.** It
+selects the ids *and* it guards the update. Written the obvious way, with the predicate
+only in the subquery, this is wrong:
+
+    UPDATE t SET … WHERE id IN (SELECT id FROM t WHERE pending LIMIT 1000)   -- BROKEN
+
+Under `READ COMMITTED` the subquery runs against the statement's snapshot, but when the
+update reaches a row another transaction has since changed, Postgres re-reads the latest
+committed version and applies the update to **that**. A row that was pending when selected
+and is now cancelled gets updated anyway. On 2026-10-01 that aborted a production run on
+its second chunk: a receipt was cancelled by a user mid-batch and the trigger refused the
+`Cancelled → Pending` transition. Repeating the predicate in the outer `WHERE` makes
+Postgres re-evaluate it against the new version and skip the row.
+
+`run()` takes the predicate once and places it twice, so getting this wrong requires
+bypassing the helper.
+
+**`table`, `set_clause` and `pending` are SQL, and are interpolated.** They are code
+written by the caller, not values — values go in `args` and are bound. Never build them
+from anything a request supplied.
+
+**Chunk size is measured, not chosen.** Cost per row depends on the triggers the write
+fires, and the figure is not guessable: the same 1.000-row chunk took 19 s on
+`Economic.Receipt`, whose triggers recalculate and audit, and 0.07 ms per row on a bare
+table. Run one chunk, read `progress.seconds`, and size the rest so a chunk finishes well
+inside the environment's `statement_timeout` — 180 s on PRO, no limit on PRE, so **PRE
+cannot tell you whether a chunk fits**.
+"""
+
+import time
+
+from aflib.db import Db
+
+
+class Progress(object):
+    """What one chunk did, and whether there is more.
+
+    `remaining` is counted **after** the update, in the same transaction, so it already
+    reflects this chunk. A caller that loops until `complete` therefore terminates without
+    needing to subtract anything itself.
+    """
+
+    __slots__ = ("done", "remaining", "seconds")
+
+    def __init__(self, done, remaining, seconds):
+        self.done = done
+        self.remaining = remaining
+        self.seconds = seconds
+
+    @property
+    def complete(self):
+        """True when nothing is left to do."""
+        return self.remaining == 0
+
+    def as_dict(self):
+        return {"done": self.done, "remaining": self.remaining,
+                "seconds": round(self.seconds, 3), "complete": self.complete}
+
+    def __repr__(self):
+        return "Progress(done=%r, remaining=%r, complete=%r)" % (
+            self.done, self.remaining, self.complete)
+
+
+class Batch(object):
+    """One committed chunk per call. `plpy` is injected, as everywhere in aflib."""
+
+    def __init__(self, plpy):
+        self._db = Db(plpy)
+
+    ALIAS = "_t"
+
+    def run(self, table, set_clause, pending, args=None, types=None,
+            limit=1000, key="id", order=None):
+        """Update at most `limit` rows matching `pending`, and report what is left.
+
+        `pending` must be **unqualified** — write `id_status = $1`, not
+        `"Receipt".id_status = $1`. That is not a style rule: the same text is placed in
+        the outer `WHERE`, where Postgres resolves it against the update target, and
+        inside the subquery, where it resolves against the subquery's own `FROM`. Both
+        resolutions are what we want, and either qualification breaks one of them. A
+        predicate mentioning the alias is rejected rather than silently misplaced.
+
+        `order` defaults to `key`, which makes the work deterministic and the chunks
+        disjoint. Ordering by something non-unique would let two concurrent callers pick
+        overlapping sets; the row-level guard still keeps them correct, but they would
+        waste each other's work.
+        """
+        if self.ALIAS in pending:
+            raise ValueError(
+                "`pending` must be unqualified: it is placed both in the outer WHERE and "
+                "inside the subquery, and %r resolves in only one of them." % self.ALIAS)
+
+        args = list(args or [])
+        types = list(types or [])
+        order = order or key
+
+        started = time.time()
+        updated = self._db.query(
+            "UPDATE {table} AS {alias} SET {set_clause} "
+            "WHERE {pending} "
+            "  AND {alias}.{key} IN (SELECT {key} FROM {table} WHERE {pending} "
+            "                        ORDER BY {order} LIMIT {limit}) "
+            "RETURNING {alias}.{key}".format(
+                table=table, alias=self.ALIAS, set_clause=set_clause,
+                pending=pending, key=key, order=order, limit=int(limit)),
+            args, types).rows()
+        elapsed = time.time() - started
+
+        remaining = self._db.query(
+            "SELECT count(*)::int AS n FROM {table} WHERE {pending}".format(
+                table=table, pending=pending),
+            args, types).scalar("n")
+
+        return Progress(len(updated), remaining, elapsed)

{aflib-0.0.2 → aflib-0.0.7}/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)