continuo-python-runtime 0.1.0__py3-none-any.whl

continuo_python_runtime/types.py

@@ -0,0 +1,208 @@
+"""SQL type parsing and Arrow type mapping.
+
+Parses SQL type strings into a canonical representation and provides mapping
+to PyArrow types for schema generation.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+import pyarrow as pa  # type: ignore[import-untyped]
+
+from continuo_python_runtime.errors import ContractError
+
+
+@dataclass(frozen=True)
+class SqlType:
+    """Canonical SQL type representation.
+
+    Attributes:
+        base: Canonicalized base type name (one of BIGINT, INTEGER,
+            DOUBLE_PRECISION, NUMERIC, VARCHAR, CHAR, TEXT, TIMESTAMP,
+            DATE, BOOLEAN).
+        precision: For NUMERIC types, the total number of digits.
+        scale: For NUMERIC types, the number of digits after the decimal.
+        length: For VARCHAR and CHAR types, the maximum length in characters.
+    """
+
+    base: str
+    precision: int | None = None
+    scale: int | None = None
+    length: int | None = None
+
+
+def parse_sql_type(raw: str) -> SqlType:
+    """Parse a SQL type string into a canonical SqlType.
+
+    Args:
+        raw: A SQL type string (case-insensitive).
+
+    Returns:
+        A SqlType with canonicalized base and parsed parameters.
+
+    Raises:
+        ContractError: If the type is unsupported or malformed.
+    """
+    raw = raw.strip()
+    if not raw:
+        raise ContractError("type: empty string is not a valid SQL type")
+
+    # Normalize to uppercase for parsing
+    normalized = raw.upper()
+
+    # Handle DOUBLE PRECISION specially (has a space). Only the authored
+    # spelling with a space is part of the contract grammar; the internal
+    # canonical spelling (with an underscore) is not accepted as input even
+    # though it is the SqlType.base value produced above.
+    if normalized == "DOUBLE PRECISION":
+        return SqlType("DOUBLE_PRECISION")
+
+    # Try to match parametrized types: TYPE(args)
+    match = re.match(r"^([A-Z_]+)\s*\((.*)\)$", normalized)
+    if match:
+        base_name = match.group(1).strip()
+        params_str = match.group(2).strip()
+
+        # Alias handling
+        if base_name == "INT":
+            base_name = "INTEGER"
+        elif base_name == "DECIMAL":
+            base_name = "NUMERIC"
+
+        if base_name == "NUMERIC":
+            # Parse NUMERIC(precision, scale) - strict format: \d+,\s*\d+ (spaces only after comma)
+            numeric_match = re.match(r"^(\d+),\s*(\d+)$", params_str)
+            if not numeric_match:
+                raise ContractError(
+                    f"type: NUMERIC requires precision and scale as unsigned integers, "
+                    f"got ({params_str})"
+                )
+            precision = int(numeric_match.group(1))
+            scale = int(numeric_match.group(2))
+            if not (1 <= precision <= 38):
+                raise ContractError(
+                    f"type: NUMERIC precision must be between 1 and 38, got {precision}"
+                )
+            if not (0 <= scale <= precision):
+                raise ContractError(
+                    f"type: NUMERIC scale must be between 0 and precision ({precision}), "
+                    f"got {scale}"
+                )
+            return SqlType("NUMERIC", precision=precision, scale=scale)
+
+        elif base_name == "VARCHAR":
+            # Parse VARCHAR(length) - strict format: \d+ only
+            if "," in params_str:
+                raise ContractError(
+                    f"type: VARCHAR takes a single parameter (length), "
+                    f"got {params_str!r}"
+                )
+            varchar_match = re.match(r"^(\d+)$", params_str)
+            if not varchar_match:
+                raise ContractError(
+                    f"type: VARCHAR length must be an unsigned integer, "
+                    f"got {params_str!r}"
+                )
+            length = int(varchar_match.group(1))
+            return SqlType("VARCHAR", length=length)
+
+        elif base_name == "CHAR":
+            # Parse CHAR(length) - strict format: \d+ only
+            if "," in params_str:
+                raise ContractError(
+                    f"type: CHAR takes a single parameter (length), "
+                    f"got {params_str!r}"
+                )
+            char_match = re.match(r"^(\d+)$", params_str)
+            if not char_match:
+                raise ContractError(
+                    f"type: CHAR length must be an unsigned integer, "
+                    f"got {params_str!r}"
+                )
+            length = int(char_match.group(1))
+            return SqlType("CHAR", length=length)
+
+        else:
+            # No other types accept parameters
+            raise ContractError(
+                f"type: {base_name} does not accept parameters, got ({params_str})"
+            )
+
+    # No parameters - must be a bare base type
+    normalized_base = normalized
+
+    # Alias handling
+    if normalized_base == "INT":
+        normalized_base = "INTEGER"
+    elif normalized_base == "DECIMAL":
+        normalized_base = "NUMERIC"
+
+    # List of supported bare types
+    # Note: "DOUBLE_PRECISION" (underscored) is deliberately excluded here.
+    # It is the canonical SqlType.base value, but only the authored spelling
+    # "DOUBLE PRECISION" (with a space) is part of the contract grammar and
+    # is handled above.
+    supported_bare = {
+        "BIGINT",
+        "INTEGER",
+        "TEXT",
+        "TIMESTAMP",
+        "DATE",
+        "BOOLEAN",
+    }
+
+    if normalized_base in supported_bare:
+        return SqlType(normalized_base)
+
+    # Bare VARCHAR and CHAR require a length parameter
+    if normalized_base == "VARCHAR":
+        raise ContractError(f"type: VARCHAR requires a length parameter, got {raw!r}")
+    if normalized_base == "CHAR":
+        raise ContractError(f"type: CHAR requires a length parameter, got {raw!r}")
+
+    # Bare NUMERIC and DECIMAL require parameters
+    if normalized_base == "NUMERIC":
+        raise ContractError(f"type: NUMERIC requires precision and scale parameters, got {raw!r}")
+
+    # Unknown type
+    raise ContractError(f"type: unknown SQL type {raw!r}")
+
+
+def arrow_type(t: SqlType) -> pa.DataType:
+    """Map a SqlType to a PyArrow DataType.
+
+    Args:
+        t: A SqlType instance.
+
+    Returns:
+        A PyArrow DataType corresponding to the SQL type.
+
+    Raises:
+        ValueError: If the SqlType is invalid or incomplete.
+    """
+    if t.base == "BIGINT":
+        return pa.int64()
+    elif t.base == "INTEGER":
+        return pa.int32()
+    elif t.base == "DOUBLE_PRECISION":
+        return pa.float64()
+    elif t.base == "NUMERIC":
+        if t.precision is None or t.scale is None:
+            raise ValueError(f"NUMERIC requires precision and scale, got {t}")
+        return pa.decimal128(t.precision, t.scale)
+    elif t.base == "VARCHAR":
+        return pa.string()
+    elif t.base == "CHAR":
+        return pa.string()
+    elif t.base == "TEXT":
+        return pa.string()
+    elif t.base == "TIMESTAMP":
+        return pa.timestamp("us")
+    elif t.base == "DATE":
+        return pa.date32()
+    elif t.base == "BOOLEAN":
+        return pa.bool_()
+    else:
+        raise ValueError(f"unknown SQL type base: {t.base}")

continuo_python_runtime-0.1.0.dist-info/METADATA

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: continuo-python-runtime
+Version: 0.1.0
+Summary: Runtime harness, contract tooling, and CI lint for Continuo python nodes.
+Author: Simone Carolini
+Maintainer: Simone Carolini
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.14
+Requires-Dist: continuo-validation-contract==0.3.0
+Requires-Dist: pyarrow==25.0.0
+Requires-Dist: pyyaml==6.0.3
+Description-Content-Type: text/markdown
+
+# Continuo Python Runtime
+
+Runtime harness, contract tooling, and CI lint for Continuo python nodes.
+This repo is what domain data teams (marketing, finance, …) template from to
+ship a python node into Continuo: write a contract + a `run(ctx)` script,
+push to `main`, and CI does the rest — lint, validate, merge, build, publish,
+and register the release with Continuo.
+
+## What this repo is
+
+Three artifacts come out of this repository:
+
+- **The `continuo-python-runtime` PyPI package** — the `continuo-runtime` CLI
+  (`validate` / `merge` / `hash` / `lint` / `run`) and the harness library
+  (`conform()`, `RunContext`, the error taxonomy) that domain repos install.
+- **Per-engine base images**, one per warehouse engine (`...-postgres`,
+  `...-trino`), that domain repos build `FROM`. Each image bakes in the
+  runtime, a single `RuntimeAdapter` for that engine, and the
+  `continuo-runtime run` entrypoint.
+- **`template/`** — a copy-ready domain repo: `Dockerfile`, `contracts/`,
+  `scripts/`, and the `release.yml` CI/CD workflow.
+
+Base images and the PyPI publication of this package land with this repo's
+PR 9 (the image pipeline); until then, install the runtime from git as noted
+in `template/.github/workflows/release.yml`.
+
+### Package map
+
+Each per-engine base image bakes together three PyPI packages: the harness,
+the engine adapter, and the published contract. The harness and both engine
+adapters live in *this* repo (`continuo-python-runtime`) as a uv workspace;
+`continuo-validation-runners` owns the *validation-side* (offline lint/merge)
+counterparts of the same engines, which is a separate concern from the
+data-plane adapters here.
+
+| Package (distribution name) | Module | Lives in | Role |
+| --- | --- | --- | --- |
+| `continuo-python-runtime` | `continuo_python_runtime` | this repo (root) | Harness: CLI, `conform()`, `RunContext`, error taxonomy. |
+| `continuo-python-runtime-postgres` | `continuo_python_runtime_postgres` | this repo, `python-runtime-postgres/` | Data-plane `RuntimeAdapter` for Postgres (`fetch`/`ensure_table`/`load`). |
+| `continuo-python-runtime-trino` | `continuo_python_runtime_trino` | this repo, `python-runtime-trino/` | Data-plane `RuntimeAdapter` for Trino/Iceberg. |
+| `continuo-validation-contract` | `continuo_validation_contract` | `continuo-validation-runners` | The published contract (schema, `RuntimeAdapter` port, result-block format) both sides depend on. |
+| `continuo-validation-postgres` / `continuo-validation-trino` | `continuo_validation_postgres` / `continuo_validation_trino` | `continuo-validation-runners` | Validation-side (lint/merge, no live warehouse I/O) adapters — not to be confused with the data-plane adapters above. |
+
+All three packages built in this repo resolve `continuo-validation-contract`
+from PyPI (`==0.3.0`); the two adapter packages are uv workspace members
+(`[tool.uv.workspace]` in the root `pyproject.toml`), so `uv sync
+--all-packages --all-groups` at the repo root installs everything for local
+development.
+
+## Quickstart for domain teams
+
+1. Copy `template/` into a new repository.
+2. Edit `template/.github/workflows/release.yml` and set `SERVICE` to your
+   service name (one service name per domain repo).
+3. Configure repository variables in GitHub (Settings → Secrets and
+   variables → Actions): `REGISTRY` (your Docker registry), `BUCKET` (your
+   S3 bucket for contract artifacts), `RELEASE_ENDPOINT` (the release
+   webhook endpoint). `RELEASE_ENDPOINT` is the **base URL** of the Continuo
+   API (no `/releases` suffix) — the workflow appends `/releases` itself.
+4. Configure repository secrets: `AWS_ACCESS_KEY_ID` and
+   `AWS_SECRET_ACCESS_KEY` for the S3 upload. The template workflow pushes
+   the built image to GHCR using the workflow's own `GITHUB_TOKEN` (granted
+   `packages: write`) — no registry secret is needed for that. If you point
+   `REGISTRY` at a different or private registry, add your own `docker
+   login` step to `release.yml`.
+5. Write a contract file under `contracts/` (see
+   `template/contracts/example.yml`) and a script under `scripts/` that
+   implements `run(ctx)` (see `template/scripts/example.py`).
+6. Push to `main`. The `release.yml` workflow lints the scripts, validates
+   and merges the contracts, builds and pushes the image, uploads the merged
+   contract to S3, and POSTs the release.
+
+## The script API
+
+A node script is a Python file with exactly one required entry point:
+
+```python
+def run(ctx):
+    ...
+```
+
+- `ctx` is a `RunContext` (`continuo_python_runtime.context.RunContext`).
+  Its only method is `ctx.read(name)`, where `name` is one of the read
+  names declared under the node's `reads:` map in the contract — reading
+  anything else raises `ReadError`. Each declared read is fetched once and
+  memoized; `ctx.read(name)` returns a `pyarrow.Table`.
+- `run(ctx)` can return anything Arrow-convertible: a `pyarrow.Table`
+  as-is, a pandas `DataFrame` (converted via
+  `pa.Table.from_pandas(..., preserve_index=False)`), or any object
+  implementing the Arrow C stream protocol (`__arrow_c_stream__`) — for
+  example a polars DataFrame. Returning anything else raises `ScriptError`.
+- The dataframe library is your choice. No dataframe library is baked into
+  the base image — the package's own runtime dependencies are `pyarrow`,
+  `PyYAML`, and `continuo-validation-contract`. Add whatever you script
+  against (pandas, polars, …) as a `RUN pip install` line in your own
+  `Dockerfile`, on top of the base image.
+- Scripts do not import warehouse drivers, write raw SQL literals, or call
+  data-access methods directly — `continuo-runtime lint` rejects those:
+  - forbidden driver imports (`psycopg2`/`sqlalchemy`/`trino`/etc.),
+  - SQL string literals (in plain strings, f-strings, and `+` concatenation),
+  - forbidden data-access calls (`execute`/`read_sql`/etc.), including ones
+    reached via a `from ... import` alias (e.g. `from pandas import
+    read_sql as rs` then calling `rs(...)`),
+  - private/protected attribute access (`obj._x`) — except on `self`/`cls`,
+    so a script's own class-private helpers (`self._helper()`) aren't
+    flagged.
+
+  The SQL-literal rule is best-effort: docstrings are exempt, but other
+  prose may still occasionally match. The hard guarantees enforced by lint
+  are the driver-import and data-access-call rules, together with the fact
+  that `RunContext` only exposes `ctx.read()` — all warehouse access goes
+  through it.
+- The harness — not the script — performs the write. It calls `conform()`
+  on whatever `run()` returned and issues the only INSERT; the script never
+  writes directly.
+
+## Conform rules
+
+`conform()` (`continuo_python_runtime/conform.py`) enforces the node's
+declared `output_columns` on the table `run()` returned, in this order:
+
+| Check | Behavior |
+| --- | --- |
+| Duplicate columns | Any duplicate column name in the returned table always raises `ConformError`. |
+| Extra columns | Governed by the node's `extra_columns` policy: `raise` (default) fails the run; `warn` drops the undeclared column(s) and logs a warning. |
+| Missing columns | Any declared column absent from the returned table always raises `ConformError`. |
+| Column order | The table is reselected into the declared column order. |
+| Strict cast | Each column is cast to its declared Arrow type with `safe=True`. Casts pyarrow's `safe=True` would silently accept but that are not value-lossless are rejected before the cast even runs: floating → decimal (rounds to scale), non-boolean → boolean (coerces truthiness), timestamp → date (drops time-of-day). Any other cast failure also raises `ConformError`. |
+| Not-null | A column declared `nullable: false` that contains any null raises `ConformError`. |
+| VARCHAR/CHAR length | A column declared `VARCHAR(n)`/`CHAR(n)` whose longest value exceeds `n` raises `ConformError`. |
+
+## Error taxonomy
+
+Every runtime failure is one of five `HarnessError` subclasses
+(`continuo_python_runtime/errors.py`). The sentinel result block's message
+is prefixed `<ErrorClass>: ` so failures can be triaged without parsing free
+text.
+
+| Class | Meaning | Typical fix target |
+| --- | --- | --- |
+| `ContractError` | Contract missing or invalid, node not found for `NODE_ID`, or the declared script is missing/unreachable. | The contract yaml or the `script:` path. |
+| `ReadError` | `ctx.read()` was called with an undeclared name, or a declared read failed at the warehouse. | The `reads:` map, or the upstream query/warehouse access. |
+| `ScriptError` | `run()` raised, has no callable `run`, or returned a value that isn't Arrow-convertible. | The node script. |
+| `ConformError` | Structural mismatch (extra/missing/duplicate columns), a strict-cast failure, a not-null violation, or a VARCHAR/CHAR overflow. | The script's output shape, or the `output_columns` declaration. |
+| `LoadError` | Adapter construction failed, or the DDL/INSERT failed at the warehouse during the write. | Warehouse connectivity/permissions, or the target table. |
+
+## Engine selection
+
+A domain repo picks its warehouse engine by which base image it builds
+`FROM`:
+
+```dockerfile
+FROM ghcr.io/carolsimone/continuo-python-runtime:v0.1.0-postgres
+# or
+FROM ghcr.io/carolsimone/continuo-python-runtime:v0.1.0-trino
+```
+
+Each image bakes in exactly one `RuntimeAdapter` for that engine — installed
+from this repo's `python-runtime-postgres/` or `python-runtime-trino/`
+package (see the package map above; both adapters live in this repo, not
+`continuo-validation-runners`) — registered under the
+`continuo_runtime.adapters` entry-point group (entry names `postgres` /
+`trino`). The harness discovers it via `discover_runtime_adapter()` at run
+time, so a single image serves every node in the service. The executor
+injects the
+warehouse connection as environment variables (engine-native, e.g.
+`POSTGRES_HOST`/`POSTGRES_DB`/`POSTGRES_USER`) plus the node-selection
+environment (`NODE_ID`, `TABLE_NAME`, `TARGET_SCHEMA`, and optionally
+`CONTRACT_DIR`/`APP_ROOT`) that `continuo-runtime run` reads to dispatch the
+right node's script.
+
+## Further reading
+
+- `docs/superpowers/specs/2026-07-31-python-runtime-design.md` — this
+  repo's design.
+- `docs/boundary-contract.md` — the parent design's boundary contract (§13):
+  the five surfaces (S3 artifact, `content_hash`, the release call, the
+  runtime image, and the domain repo's CI/CD) that this repo implements.

continuo_python_runtime-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+continuo_python_runtime/__init__.py,sha256=otNaXEPsTtRXJV5FLtDUsFO8VD4OC-MLAzwhtimHfOE,70
+continuo_python_runtime/cli.py,sha256=Qki4Mfoab74D0DvguZd5yzSfI-FRQDmtvwC0OacxrAc,4860
+continuo_python_runtime/conform.py,sha256=a9CKCA-gT9Zerzr6c5H8aByTFOUd6uBMo02sNKSDnXg,9199
+continuo_python_runtime/context.py,sha256=ZyeN_dA2DihQbegBiiqHj1_EKk79GsxS-tATPVymUPg,1856
+continuo_python_runtime/errors.py,sha256=nfZzfBhQ2ajm7USAWKKaGY2uUlh8eNjNPNYYuaOJgZE,1032
+continuo_python_runtime/harness.py,sha256=YcWy4ummKY3HQYQ4JQ3-UI5jxDgYwJDQlWT88_GRPH4,7504
+continuo_python_runtime/hashing.py,sha256=6D4MntcjaHTEC55IQBBX2Pq9K59D0TWlxTSXGJ5Jsro,1159
+continuo_python_runtime/lint.py,sha256=HgB0BAuiQuS3DgT6BsOoB2M5A-_OKcFsGbaTWhuM7XU,11897
+continuo_python_runtime/types.py,sha256=z1qnBbbaP6nFN2mmRySXM4ZAesv5N6_4E9vZ4kv74HU,7138
+continuo_python_runtime/contract/__init__.py,sha256=S79x6j_P0CmaSuCGzeWoK1U0507KvD2MZXwQl9DFWMM,37
+continuo_python_runtime/contract/loader.py,sha256=wlxI6XZIoUZ4z9rDe1G8s26jbL0tGXnAHPGajTAM0ag,12828
+continuo_python_runtime/contract/merge.py,sha256=WFde9lzrojlMNjuEU7YW8FWOs6VPSrWPY2_Sri0ljZE,2567
+continuo_python_runtime/contract/model.py,sha256=6luq3SJcgshKoG0QsQhJPZ5fzLa8AcGAev9D4jiGgxA,849
+continuo_python_runtime/contract/paths.py,sha256=SRn70pJkDAIpXw0IcMU2iNKPKvct8w_SZP2ec-lV91M,1458
+continuo_python_runtime-0.1.0.dist-info/METADATA,sha256=YQWMZaYiS3gpRnIutzgKhT3KeB5BtUpeMrwi0qKLRUU,10953
+continuo_python_runtime-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+continuo_python_runtime-0.1.0.dist-info/entry_points.txt,sha256=ZvIwSm9f9B9ZmZMf6CyF5Zt4QONn8rqaIk-u-B1CF2Y,70
+continuo_python_runtime-0.1.0.dist-info/RECORD,,

continuo_python_runtime-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

continuo_python_runtime-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+continuo-runtime = continuo_python_runtime.cli:main