aflib 0.0.1__tar.gz

aflib-0.0.1/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/

aflib-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 English Connection
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aflib-0.0.1/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: aflib
+Version: 0.0.1
+Summary: Helper library for business logic inside Airflows plpython function bodies
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# aflib
+
+Helper library for business logic inside [Airflows](https://flows.ninja) `plpython3u`
+function bodies.
+
+An Airflows function body is a bare Python snippet with a `plpy` global. It cannot import
+another function body, cannot see the HTTP request, and cannot shape the HTTP response — so
+every body ends up re-implementing the same parameter parsing, the same row reading and the
+same result envelope. aflib is that plumbing, written once.
+
+**Status: early, and deliberately so.** Nothing enters this library until it has run on a
+real Airflows instance — written first as a plain function body, deployed, called, and
+observed. One version corresponds to one proven capability, which is why the numbers start
+so low.
+
+## Install
+
+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`:
+
+```
+pythonPackage aflib==0.0.1
+```
+
+Then import it from a function body.
+
+## What 0.0.1 gives you
+
+```python
+from aflib import BadParameter, Db, fail, ok, params
+
+db = Db(plpy)
+
+try:
+    receipt_id = params.as_int(p_id_receipt, name="p_id_receipt", required=True)
+except BadParameter as exc:
+    return fail("invalid_param", str(exc))
+
+row = db.query(
+    'SELECT id, amount FROM "Economic"."Receipt" WHERE id = $1',
+    [receipt_id], ["integer"],
+).one()
+
+if row is None:
+    return fail("not_found", "No receipt with that id")
+
+return ok(row)
+```
+
+- **`Db(plpy)`** — `plpy` is injected, never imported, because the function body is the only
+  composition root available. `db.query(...)` returns a `Rows` you narrow with `.one()`
+  (`None` for no row, and it refuses more than one rather than silently taking the first),
+  `.rows()` for all of them, or `.scalar(column)` for a single named value.
+- **`params.as_int` / `as_bool` / `as_decimal` / `as_date` / `as_json`** — every HTTP
+  parameter arrives as text and must be *declared* `text`, so every body converts. These
+  raise `BadParameter`, which is the caller's fault and should become a 4xx-shaped failure
+  rather than an uncaught exception.
+- **`ok(data)` / `fail(code, message)`** — a body's only output is its return value, which
+  the platform wraps as `[{"result": …}]`. There is no status code and no header, so success
+  and failure both have to be expressed *inside* the value.
+- **`codec.dumps` / `loads`** — JSON that raises on anything it cannot serialize instead of
+  stringifying it. `numeric` columns arrive as `decimal.Decimal` and are encoded as strings,
+  never floats, so exactness survives the round trip.
+
+## Platform constraints worth knowing before you build on it
+
+These are observed on a live instance, not inferred from documentation. They are the reason
+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 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.
+- **A body cannot see the request or shape the response.** Its globals are exactly `GD`,
+  `SD`, `args`, its declared parameters and `plpy`: no request object, no undeclared query
+  parameters, no body, no headers. It cannot set a status code, a header or a redirect.
+- **`jsonb` is never decoded** — it always arrives as `str`, even through `plpy.prepare`.
+  `numeric` arrives as `decimal.Decimal` and `bytea` as `bytes`; neither is JSON-serializable
+  by default, and `numeric` is every money column.
+- **Never cache request-scoped state in `GD` or `SD`.** Consecutive calls land on different
+  pooled backends, and the connection role varies per caller.
+
+## Tests
+
+```
+uv run pytest
+```
+
+The unit tests run against a fake `plpy`, which verifies control flow and nothing
+transactional. Anything involving a savepoint is proven on the platform, not here.
+
+## License
+
+MIT — see `LICENSE`.

aflib-0.0.1/README.md

@@ -0,0 +1,98 @@
+# aflib
+
+Helper library for business logic inside [Airflows](https://flows.ninja) `plpython3u`
+function bodies.
+
+An Airflows function body is a bare Python snippet with a `plpy` global. It cannot import
+another function body, cannot see the HTTP request, and cannot shape the HTTP response — so
+every body ends up re-implementing the same parameter parsing, the same row reading and the
+same result envelope. aflib is that plumbing, written once.
+
+**Status: early, and deliberately so.** Nothing enters this library until it has run on a
+real Airflows instance — written first as a plain function body, deployed, called, and
+observed. One version corresponds to one proven capability, which is why the numbers start
+so low.
+
+## Install
+
+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`:
+
+```
+pythonPackage aflib==0.0.1
+```
+
+Then import it from a function body.
+
+## What 0.0.1 gives you
+
+```python
+from aflib import BadParameter, Db, fail, ok, params
+
+db = Db(plpy)
+
+try:
+    receipt_id = params.as_int(p_id_receipt, name="p_id_receipt", required=True)
+except BadParameter as exc:
+    return fail("invalid_param", str(exc))
+
+row = db.query(
+    'SELECT id, amount FROM "Economic"."Receipt" WHERE id = $1',
+    [receipt_id], ["integer"],
+).one()
+
+if row is None:
+    return fail("not_found", "No receipt with that id")
+
+return ok(row)
+```
+
+- **`Db(plpy)`** — `plpy` is injected, never imported, because the function body is the only
+  composition root available. `db.query(...)` returns a `Rows` you narrow with `.one()`
+  (`None` for no row, and it refuses more than one rather than silently taking the first),
+  `.rows()` for all of them, or `.scalar(column)` for a single named value.
+- **`params.as_int` / `as_bool` / `as_decimal` / `as_date` / `as_json`** — every HTTP
+  parameter arrives as text and must be *declared* `text`, so every body converts. These
+  raise `BadParameter`, which is the caller's fault and should become a 4xx-shaped failure
+  rather than an uncaught exception.
+- **`ok(data)` / `fail(code, message)`** — a body's only output is its return value, which
+  the platform wraps as `[{"result": …}]`. There is no status code and no header, so success
+  and failure both have to be expressed *inside* the value.
+- **`codec.dumps` / `loads`** — JSON that raises on anything it cannot serialize instead of
+  stringifying it. `numeric` columns arrive as `decimal.Decimal` and are encoded as strings,
+  never floats, so exactness survives the round trip.
+
+## Platform constraints worth knowing before you build on it
+
+These are observed on a live instance, not inferred from documentation. They are the reason
+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 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.
+- **A body cannot see the request or shape the response.** Its globals are exactly `GD`,
+  `SD`, `args`, its declared parameters and `plpy`: no request object, no undeclared query
+  parameters, no body, no headers. It cannot set a status code, a header or a redirect.
+- **`jsonb` is never decoded** — it always arrives as `str`, even through `plpy.prepare`.
+  `numeric` arrives as `decimal.Decimal` and `bytea` as `bytes`; neither is JSON-serializable
+  by default, and `numeric` is every money column.
+- **Never cache request-scoped state in `GD` or `SD`.** Consecutive calls land on different
+  pooled backends, and the connection role varies per caller.
+
+## Tests
+
+```
+uv run pytest
+```
+
+The unit tests run against a fake `plpy`, which verifies control flow and nothing
+transactional. Anything involving a savepoint is proven on the platform, not here.
+
+## License
+
+MIT — see `LICENSE`.

aflib-0.0.1/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "aflib"
+version = "0.0.1"
+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).
+# There is no reason to support anything older: nothing else will ever import this.
+requires-python = ">=3.11"
+license = { text = "MIT" }
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aflib"]
+
+# An ALLOWLIST, deliberately — not an exclude list. The default sdist ships every tracked
+# file, which swept up internal working notes that were never meant for distribution. A
+# PyPI release cannot be withdrawn — a deleted release stays downloadable — so what gets
+# published must not depend on anyone remembering to exclude something. With an allowlist,
+# a new file is absent from the sdist until someone adds it here on purpose.
+#
+# Note this file is itself published: nothing in these comments should be anything you
+# would not put on a public page.
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/aflib",
+    "tests",
+    "README.md",
+    "LICENSE",
+]

aflib-0.0.1/src/aflib/__init__.py

@@ -0,0 +1,42 @@
+"""Helper library for business logic inside Airflows `plpython3u` function bodies.
+
+Nothing enters this package until it has run on a real Airflows instance. See
+`docs/02-roadmap.md` for what exists and what is still only a plan.
+
+`src/aflib/` imports the standard library, `plpy` and `airflows` — nothing else. See
+`docs/adr/0001-stdlib-only-no-third-party-dependencies.md`.
+
+A function body's whole import line, and the shape of a body:
+
+    from aflib import Db, ok, fail, params
+
+    db = Db(plpy)
+    tid = params.as_int(p_id_receipt, name="p_id_receipt", required=True)
+
+    row = db.query("SELECT * FROM t WHERE id = $1", [tid], ["integer"]).one()
+    if row is None:
+        return fail("not_found", "No receipt with that id")
+    return ok(row)
+"""
+
+from aflib import codec, db, params, result
+from aflib.db import Db
+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.1"
+
+__all__ = [
+    "BadParameter",
+    "Db",
+    "codec",
+    "db",
+    "fail",
+    "ok",
+    "params",
+    "result",
+    "__version__",
+]

aflib-0.0.1/src/aflib/codec.py

@@ -0,0 +1,36 @@
+"""JSON encoding for values that came out of Postgres.
+
+The standard library cannot serialise everything plpython hands you. `numeric` columns
+arrive as `decimal.Decimal`, and `json.dumps` raises `TypeError` on them — which, since
+`numeric` is every money column, means the first real amount crashes the response.
+"""
+
+import json
+from decimal import Decimal
+
+
+def _default(value):
+    """Called by `json.dumps` only for values it cannot serialise itself."""
+    if isinstance(value, Decimal):
+        # A string, not a float. `float(Decimal("1.50"))` is not exactly 1.50, and it
+        # drops the trailing zero that makes a price a price.
+        return str(value)
+    # Refuse rather than guess. A `default` that falls off the end returns None, which
+    # `json.dumps` happily writes as `null` — so a `bytea` column would vanish from the
+    # response with no error anywhere. Naming the type is the whole value of the message:
+    # it surfaces inside a response envelope, where nothing else identifies the culprit.
+    raise TypeError("aflib.codec cannot serialise " + type(value).__name__)
+
+
+def dumps(obj):
+    """Serialise `obj` to a JSON string."""
+    return json.dumps(obj, default=_default)
+
+
+def loads(text):
+    """Decode a JSON string — typically the contents of a `jsonb` column.
+
+    Raises `ValueError` on malformed input rather than returning None, so a corrupt
+    column cannot be mistaken for an empty one.
+    """
+    return json.loads(text)

aflib-0.0.1/src/aflib/db.py

@@ -0,0 +1,126 @@
+"""Reads over `plpy`.
+
+`plpy` is **injected**, never imported at module scope. That is what makes this testable
+off-platform, and it matches the constraint that the function body is the composition
+root: bodies cannot import each other or any shared local module, so there is nowhere
+else for wiring to live.
+
+    from aflib.db import Db
+
+    db = Db(plpy)
+
+    row   = db.query("SELECT * FROM t WHERE id = $1", [tid], ["integer"]).one()
+    total = db.query("SELECT count(*) AS c FROM t").scalar("c")
+    all_t = db.query("SELECT * FROM t").rows()
+
+`query()` runs the statement and hands back a `Rows`; the method you call on it chooses
+how to read what came back. The SQL and its bindings are stated once, and `.scalar()` can
+name its column without wedging it in among the query's own arguments.
+
+**This layer does not transform values.** `numeric` arrives as `decimal.Decimal` and
+`jsonb` as an undecoded `str`, and both are handed on exactly as they came. Decoding a
+jsonb column is the caller's decision — a helpful decode here would make it impossible to
+pass one straight through — and `Decimal` belongs to `codec` at the serialisation edge.
+"""
+
+
+class Rows(object):
+    """The answers one executed query can give.
+
+    Wraps the result object `plpy` returned. This is the single place where that object's
+    API is used, so the fake in `tests/conftest.py` has exactly one thing to be faithful
+    about.
+
+    Read it through the named methods and no other way — it is deliberately not
+    list-like. See `TestRowsIsTerminalOnly` for why.
+    """
+
+    def __init__(self, result):
+        self._result = result
+
+    def rows(self):
+        """Every matching row, as a list of dicts. `[]` when nothing matched."""
+        return [dict(row) for row in self._result]
+
+    def one(self):
+        """The single matching row, or `None`. Raises if more than one matched.
+
+        The row count is checked against `len()`, because indexing an empty result raises
+        `IndexError` rather than returning `None`. Two rows where one was expected is a
+        broken query, not a data outcome, so it raises rather than quietly returning the
+        first — which would turn a bug into plausible-looking data.
+        """
+        rows = self.rows()
+        if not rows:
+            return None
+        self._refuse_more_than_one(len(rows))
+        return rows[0]
+
+    def scalar(self, column):
+        """One **named** column of the single matching row, or `None` if nothing matched.
+
+        The column is named rather than taken positionally. The obvious
+        `next(iter(row.values()))` bets that the first value is the wanted one; naming it
+        removes the bet, and makes the call read as what it selects.
+
+        A column the result does not have raises, and — because the result reports its
+        column list even with zero rows — that check works on the empty path too.
+        Without it, one typo would return `None` for every query that matched nothing:
+        indistinguishable from "not found", and breaking only once data exists.
+        """
+        # Checked before the row count, deliberately. A misnamed column is a programmer
+        # error and should be reported whatever the query happened to return.
+        names = self._result.colnames()
+        if column not in names:
+            raise ValueError(
+                "no column {!r} in this result; it has: {}".format(
+                    column, ", ".join(repr(name) for name in names) or "<none>"
+                )
+            )
+
+        self._refuse_more_than_one(len(self._result))
+        if len(self._result) == 0:
+            return None
+        # A row holding NULL also gives None. A caller who must tell that apart from
+        # "no row at all" uses one().
+        return self._result[0][column]
+
+    @staticmethod
+    def _refuse_more_than_one(count):
+        if count > 1:
+            raise ValueError("expected at most one row, got {} rows".format(count))
+
+
+class Db(object):
+    def __init__(self, plpy):
+        self._plpy = plpy
+
+    def query(self, sql, args=None, argtypes=None):
+        """Run `sql` and return a `Rows`.
+
+        Executes **now**, not when a method is called on the result. A handle that only
+        ran once someone remembered to read it would make an unread statement a silent
+        no-op, and running first is what makes `one()` an assertion about the query rather
+        than something that could have rewritten it.
+        """
+        if not args:
+            # None and [] both mean "no parameters". Preparing a plan for zero arguments
+            # would cost a round trip and buy nothing.
+            return Rows(self._plpy.execute(sql))
+
+        if not argtypes:
+            raise ValueError(
+                "args were given without argtypes: every bind type must be stated. "
+                "Binding the wrong Postgres type does not raise — it makes the call fail "
+                "to resolve, and inferring types from Python values is how that trap "
+                "gets set."
+            )
+        if len(args) != len(argtypes):
+            raise ValueError(
+                "a query with {} args needs {} argtypes, got {}".format(
+                    len(args), len(args), len(argtypes)
+                )
+            )
+
+        plan = self._plpy.prepare(sql, argtypes)
+        return Rows(self._plpy.execute(plan, args))

aflib-0.0.1/src/aflib/params.py

@@ -0,0 +1,123 @@
+"""Convert the text an HTTP caller sent into the value a body needs.
+
+Every parameter of an `httpEnabled` function must be declared `text`: a typed declaration
+makes the endpoint uncallable, because the platform binds every query-string argument as
+`character varying` and Postgres cannot match that to an `integer` or `jsonb` parameter. So
+every value arriving from HTTP is a `str`, and every body has to convert it.
+
+Hand-rolled, `int(p_id_receipt)` raises `ValueError`, which escapes as a 500 — telling the
+caller the server broke when in fact they sent a bad id. These converters raise
+`BadParameter` instead, which the edge can turn into a 400.
+
+This is an edge concern only. A function called from SQL by another function receives
+properly typed arguments, because there the caller chooses the bind types.
+"""
+
+from datetime import date
+from decimal import Decimal, InvalidOperation
+
+from aflib import codec
+
+
+class BadParameter(Exception):
+    """A caller-supplied parameter is missing when required, or cannot be converted."""
+
+
+def _blank(value):
+    """Is this "the user left it empty"?
+
+    Exactly `None` (never sent) and `''` (sent with no value) — those are different at the
+    platform level, but neither converts to anything, so both mean blank here. A
+    whitespace-only string is NOT blank: trimming first would let `?p_id=%20` masquerade as
+    an absent parameter and hide the caller's mistake.
+    """
+    return value is None or value == ""
+
+
+def _fail(name, message):
+    raise BadParameter(name + ": " + message if name else message)
+
+
+def as_int(value, name=None, required=False):
+    """Convert `value` to an `int`, or `None` when it was left blank."""
+    if _blank(value):
+        if required:
+            _fail(name, "a value is required")
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        _fail(name, "expected a whole number, got " + repr(value))
+
+
+# Postgres renders booleans as 't'/'f', so a value that made a round trip through the
+# database converts back without surprise. 'yes'/'on'/'sí' are left out on purpose: one
+# vocabulary, and a rejected value tells the caller exactly what to send.
+_TRUE = frozenset(("true", "1", "t"))
+_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."""
+    if _blank(value):
+        if required:
+            _fail(name, "a value is required")
+        return None
+    folded = value.strip().lower() if isinstance(value, str) else value
+    if folded in _TRUE:
+        return True
+    if folded in _FALSE:
+        return False
+    _fail(name, "expected true/false, 1/0 or t/f, got " + repr(value))
+
+
+def as_decimal(value, name=None, required=False):
+    """Convert `value` to a `Decimal`, or `None` when it was left blank."""
+    if _blank(value):
+        if required:
+            _fail(name, "a value is required")
+        return None
+    try:
+        number = Decimal(value)
+    except (TypeError, ValueError, InvalidOperation):
+        _fail(name, "expected a number, got " + repr(value))
+    # Decimal accepts "nan" and "Infinity". A NaN is not equal to itself, so letting one
+    # through would quietly corrupt every comparison and total downstream.
+    if not number.is_finite():
+        _fail(name, "expected a finite number, got " + repr(value))
+    return number
+
+
+def as_date(value, name=None, required=False):
+    """Convert `value` to a `date`, or `None` when it was left blank.
+
+    ISO `YYYY-MM-DD` only. `01/02/2026` is 1 February in Spain and 2 January in the United
+    States, so a permissive parser would silently produce the wrong day for half of all
+    ambiguous dates. Postgres emits dates in ISO form, so round trips are exact.
+    """
+    if _blank(value):
+        if required:
+            _fail(name, "a value is required")
+        return None
+    try:
+        return date.fromisoformat(value)
+    except (TypeError, ValueError):
+        _fail(name, "expected a date as YYYY-MM-DD, got " + repr(value))
+
+
+def as_json(value, name=None, required=False):
+    """Decode `value` as JSON, or `None` when it was left blank."""
+    if _blank(value):
+        if required:
+            _fail(name, "a value is required")
+        return None
+    try:
+        decoded = codec.loads(value)
+    except (TypeError, ValueError):
+        _fail(name, "expected valid JSON, got " + repr(value))
+    # 'null' is valid JSON and decodes to None, so a non-blank input can still yield
+    # nothing. `required` promises a non-None RESULT, so it has to be checked here too —
+    # this is the only converter where that can happen.
+    if decoded is None and required:
+        _fail(name, "a value is required")
+    return decoded

aflib-0.0.1/src/aflib/result.py

@@ -0,0 +1,34 @@
+"""The envelope a function body returns.
+
+A plpython body's only output is its return value, which the platform wraps as
+`[{"result": <value>}]`. It cannot set a status code and cannot set a response header —
+both are JavaScript-only — so **success and failure are expressed inside the value**.
+An HTTP caller sees 200 either way; `ok` is what tells them which happened.
+
+    from aflib import ok, fail
+
+    row = db.query("SELECT * FROM t WHERE id = $1", [tid], ["integer"]).one()
+    if row is None:
+        return fail("not_found", "No receipt with that id")
+    return ok(row)
+
+Both go through `codec`, so a `Decimal` money column renders exactly and an
+unserialisable value raises instead of being quietly stringified — an envelope that
+mangled its payload would ship a wrong answer under `ok: true`.
+"""
+
+from aflib import codec
+
+
+def ok(data=None):
+    """Success. `data` may be any JSON-serialisable value, including a falsy one."""
+    return codec.dumps({"ok": True, "data": data})
+
+
+def fail(code, message):
+    """Failure, with a short stable `code` and a human-readable `message`.
+
+    No `data` key: a caller reading data on a failure path is a bug waiting to happen,
+    and emitting `"data": null` alongside the error invites exactly that.
+    """
+    return codec.dumps({"ok": False, "error": {"code": code, "message": message}})