continuo-python-runtime 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

continuo_python_runtime/contract/kinds.py

@@ -0,0 +1,109 @@
+"""Per-kind contract rules: which fields a node of each kind must carry.
+
+Each kind is one ``KindRules`` entry composed of a script policy and a reads
+rule. Adding a kind means adding one entry to ``RULES``; nothing that parses a
+contract branches on the kind's name.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any
+
+from continuo_engine_contract.sql import ensure_single_read  # type: ignore[import-untyped]
+from sqlglot.errors import TokenError
+
+from continuo_python_runtime.contract.model import KINDS
+from continuo_python_runtime.csv_source import parse_csv_uri
+from continuo_python_runtime.errors import ContractError
+
+
+class ReadsRule(ABC):
+    """Validates a node's ``reads`` mapping and returns it unchanged."""
+
+    @abstractmethod
+    def validate(
+        self, reads: Any, label: str, *, dialect: str | None, check_reads: bool
+    ) -> dict[str, str]: ...
+
+
+class SqlReads(ReadsRule):
+    """A non-empty mapping of read name -> single SELECT."""
+
+    def validate(
+        self, reads: Any, label: str, *, dialect: str | None, check_reads: bool
+    ) -> dict[str, str]:
+        if not isinstance(reads, dict) or not reads:
+            raise ContractError(
+                f"{label}: 'reads' must be a non-empty mapping of name -> SQL"
+            )
+        for name, sql in reads.items():
+            if not isinstance(name, str) or not name.strip():
+                raise ContractError(
+                    f"{label}: 'reads' name {name!r} must be a non-empty string"
+                )
+            if not isinstance(sql, str) or not sql.strip():
+                raise ContractError(
+                    f"{label}: 'reads.{name}' must be a non-empty SQL string"
+                )
+            if not check_reads:
+                continue
+            try:
+                ensure_single_read(sql, dialect)
+            except (ValueError, TokenError) as exc:
+                # ensure_single_read's own message is phrased for check_binds
+                # (its only other caller today), so it's wrapped rather than
+                # surfaced bare here. TokenError is also caught: an unterminated
+                # string literal or comment fails sqlglot's tokenizer with a
+                # TokenError, a SqlglotError sibling of ParseError and not a
+                # subclass of ValueError -- despite ensure_single_read's
+                # docstring promising every rejection is a ValueError. Only
+                # TokenError, not the broader SqlglotError, is caught here: by
+                # the time control reaches this point `dialect` has already
+                # been validated once in load_contract_dir, so any other
+                # SqlglotError a future sqlglot version might raise from this
+                # call should surface as itself, not get relabeled as a
+                # rejected read.
+                raise ContractError(
+                    f"{label}: 'reads.{name}' must be a single read query ({exc})"
+                ) from exc
+        return dict(reads)
+
+
+class CsvRead(ReadsRule):
+    """Exactly ``{csv: <uri>}``, the uri in the grammar ``parse_csv_uri`` accepts."""
+
+    def validate(
+        self, reads: Any, label: str, *, dialect: str | None, check_reads: bool
+    ) -> dict[str, str]:
+        if not isinstance(reads, dict) or set(reads) != {"csv"}:
+            raise ContractError(
+                f"{label}: a python-csv node's 'reads' must be exactly {{csv: <uri>}}"
+            )
+        try:
+            parse_csv_uri(reads["csv"])
+        except (ValueError, TypeError) as exc:
+            raise ContractError(f"{label}: invalid csv uri: {exc}") from exc
+        return dict(reads)
+
+
+@dataclass(frozen=True)
+class KindRules:
+    """What a node of one kind must declare."""
+
+    script_required: bool
+    reads: ReadsRule
+
+
+RULES: dict[str, KindRules] = {
+    "python-node": KindRules(script_required=True, reads=SqlReads()),
+    "python-csv": KindRules(script_required=False, reads=CsvRead()),
+}
+
+
+def rules_for(kind: object, label: str) -> KindRules:
+    """Return the rules for ``kind``; raise ``ContractError`` for any other value."""
+    if isinstance(kind, str) and kind in RULES:
+        return RULES[kind]
+    raise ContractError(f"{label}: 'kind' must be one of {sorted(KINDS)}, got {kind!r}")

continuo_python_runtime/contract/loader.py

@@ -11,18 +11,16 @@ from pathlib import Path
 from typing import Any
 
 import yaml
-from continuo_engine_contract.sql import ensure_single_read  # type: ignore[import-untyped]
 from sqlglot import Dialect
-from sqlglot.errors import TokenError
 
+from continuo_python_runtime.contract.kinds import rules_for
 from continuo_python_runtime.contract.model import (
     CRITICALITIES,
+    DEFAULT_KIND,
     EXTRA_COLUMNS_POLICIES,
-    KINDS,
     Column,
     Node,
 )
-from continuo_python_runtime.csv_source import parse_csv_uri
 from continuo_python_runtime.errors import ContractError
 from continuo_python_runtime.types import parse_sql_type
 
@@ -173,11 +171,8 @@ def parse_node(
     if unknown:
         raise ContractError(f"{label}: unknown key(s) {sorted(unknown)}")
 
-    kind = raw.get("kind", "python-model")
-    if not isinstance(kind, str) or kind not in KINDS:
-        raise ContractError(
-            f"{label}: 'kind' must be one of {sorted(KINDS)}, got {kind!r}"
-        )
+    kind = raw.get("kind", DEFAULT_KIND)
+    rules = rules_for(kind, label)
 
     for field in _REQUIRED_STRING_FIELDS:
         value = raw.get(field)
@@ -191,20 +186,20 @@ def parse_node(
     owner = raw["owner"]
     schedule = raw["schedule"]
 
-    if kind == "python-csv":
-        if "script" in raw:
-            raise ContractError(
-                f"{label}: 'script' is forbidden for kind python-csv "
-                "(csv nodes are contract-only)"
-            )
-        script = ""
-    else:
+    if rules.script_required:
         raw_script = raw.get("script")
         if not isinstance(raw_script, str) or not raw_script.strip():
             raise ContractError(
                 f"{label}: required field 'script' must be a non-empty string"
             )
         script = raw_script
+    else:
+        if "script" in raw:
+            raise ContractError(
+                f"{label}: 'script' is forbidden for kind {kind} "
+                "(it is a contract-only kind)"
+            )
+        script = ""
 
     criticality = raw.get("criticality")
     if not isinstance(criticality, str) or criticality not in CRITICALITIES:
@@ -222,51 +217,9 @@ def parse_node(
             f"got {extra_columns!r}"
         )
 
-    reads = raw.get("reads")
-    if kind == "python-csv":
-        if not isinstance(reads, dict) or set(reads) != {"csv"}:
-            raise ContractError(
-                f"{label}: a python-csv node's 'reads' must be exactly {{csv: <uri>}}"
-            )
-        try:
-            parse_csv_uri(reads["csv"])
-        except (ValueError, TypeError) as exc:
-            raise ContractError(f"{label}: invalid csv uri: {exc}") from exc
-    else:
-        if not isinstance(reads, dict) or not reads:
-            raise ContractError(
-                f"{label}: 'reads' must be a non-empty mapping of name -> SQL"
-            )
-        for name, sql in reads.items():
-            if not isinstance(name, str) or not name.strip():
-                raise ContractError(
-                    f"{label}: 'reads' name {name!r} must be a non-empty string"
-                )
-            if not isinstance(sql, str) or not sql.strip():
-                raise ContractError(
-                    f"{label}: 'reads.{name}' must be a non-empty SQL string"
-                )
-            if not check_reads:
-                continue
-            try:
-                ensure_single_read(sql, dialect)
-            except (ValueError, TokenError) as exc:
-                # ensure_single_read's own message is phrased for check_binds
-                # (its only other caller today), so it's wrapped rather than
-                # surfaced bare here. TokenError is also caught: an unterminated
-                # string literal or comment fails sqlglot's tokenizer with a
-                # TokenError, a SqlglotError sibling of ParseError and not a
-                # subclass of ValueError -- despite ensure_single_read's
-                # docstring promising every rejection is a ValueError. Only
-                # TokenError, not the broader SqlglotError, is caught here: by
-                # the time control reaches this point `dialect` has already
-                # been validated once in load_contract_dir, so any other
-                # SqlglotError a future sqlglot version might raise from this
-                # call should surface as itself, not get relabeled as a
-                # rejected read.
-                raise ContractError(
-                    f"{label}: 'reads.{name}' must be a single read query ({exc})"
-                ) from exc
+    reads = rules.reads.validate(
+        raw.get("reads"), label, dialect=dialect, check_reads=check_reads
+    )
 
     raw_columns = raw.get("output_columns")
     if not isinstance(raw_columns, list) or not raw_columns:
@@ -325,7 +278,7 @@ def parse_node(
         schedule=schedule,
         criticality=criticality,
         script=script,
-        reads=dict(reads),
+        reads=reads,
         output_columns=tuple(columns),
         description=description,
         extra_columns=extra_columns,

continuo_python_runtime/contract/merge.py

@@ -1,5 +1,6 @@
 """Contract v1 merger: wire contract builder."""
 
+from collections.abc import Callable
 from pathlib import Path
 
 import yaml
@@ -110,6 +111,29 @@ def _lint_node_closure(
         )
 
 
+def _script_hash_inputs(node: Node, repo_root: Path) -> tuple[bytes, list[bytes]]:
+    """A script node's source is its script plus its in-repo import closure,
+    every file of which is held to the closure lint."""
+    script_path = resolve_script_path(node.script, repo_root, context=node.relation)
+    script_bytes = script_path.read_bytes()
+    closure = resolve_closure(script_path, repo_root)
+    member_bytes = [member.read_bytes() for member in closure]
+    _lint_node_closure(node, repo_root, script_path, script_bytes, closure, member_bytes)
+    return script_bytes, member_bytes
+
+
+def _csv_hash_inputs(node: Node, repo_root: Path) -> tuple[bytes, list[bytes]]:
+    """A csv node has no script and no import closure: its source is the uri.
+    New file content at the same uri is new data, not a new node version."""
+    return node.reads["csv"].encode(), []
+
+
+_HASH_INPUTS: dict[str, Callable[[Node, Path], tuple[bytes, list[bytes]]]] = {
+    "python-node": _script_hash_inputs,
+    "python-csv": _csv_hash_inputs,
+}
+
+
 def build_wire_contract(
     contract_dir: Path, repo_root: Path, service: str, *, dialect: str | None = None
 ) -> dict:
@@ -129,19 +153,8 @@ def build_wire_contract(
     for node in nodes:
         entry = node_entry(node)
 
-        if node.kind == "python-csv":
-            # A csv node has no script and no import closure: its source IS
-            # the uri -- new file content at the same uri is new data, not a
-            # new node version.
-            uri_bytes = node.reads["csv"].encode()
-            entry.update(hash_parts(entry, uri_bytes, []))
-        else:
-            script_path = resolve_script_path(node.script, repo_root, context=node.relation)
-            script_bytes = script_path.read_bytes()
-            closure = resolve_closure(script_path, repo_root)
-            member_bytes = [member.read_bytes() for member in closure]
-            _lint_node_closure(node, repo_root, script_path, script_bytes, closure, member_bytes)
-            entry.update(hash_parts(entry, script_bytes, member_bytes))
+        primary_bytes, member_bytes = _HASH_INPUTS[node.kind](node, repo_root)
+        entry.update(hash_parts(entry, primary_bytes, member_bytes))
 
         wire_nodes.append(entry)
 

continuo_python_runtime/contract/model.py

@@ -6,7 +6,8 @@ from typing import Any
 # Module-level constants
 CRITICALITIES = frozenset({"REGULATORY", "CORE", "SECONDARY"})
 EXTRA_COLUMNS_POLICIES = frozenset({"raise", "warn"})
-KINDS = frozenset({"python-model", "python-csv"})
+KINDS = frozenset({"python-node", "python-csv"})
+DEFAULT_KIND = "python-node"
 CONTRACT_VERSION = 1
 
 
@@ -35,7 +36,7 @@ class Node:
     extra_columns: str = "raise"
     config: dict[str, Any] = field(default_factory=dict)
     content_hash: str | None = None
-    kind: str = "python-model"
+    kind: str = DEFAULT_KIND
 
     @property
     def relation(self) -> str:

continuo_python_runtime/harness.py

@@ -1,6 +1,6 @@
 """Container entrypoint: dispatches a single node's script and writes its output.
 
-``run_node`` is the sole write sink for a python-model node. It resolves the
+``run_node`` is the sole write sink for a python-node node. It resolves the
 node from the contract, loads and executes its script inside a
 :class:`~continuo_python_runtime.context.RunContext`, conforms the result to
 the declared schema, and writes it through the runtime adapter. Exactly one
@@ -16,7 +16,7 @@ import logging
 import os
 import sys
 import uuid
-from collections.abc import Mapping
+from collections.abc import Callable, Mapping
 from pathlib import Path
 from types import ModuleType
 from typing import Any
@@ -208,15 +208,36 @@ def _validate_config_early(adapter: Any, node: Node) -> None:
         ) from exc
 
 
+def _produce_from_script(
+    node: Node, adapter: Any, app_root: Path, reader: CsvSourceReader | None
+) -> Any:
+    """Import the node's script and return its ``run(ctx)`` result as Arrow."""
+    with contextlib.redirect_stdout(sys.stderr):
+        module = load_script(node, app_root)
+    ctx = RunContext(node, adapter)
+    return to_arrow(_execute_script(module, ctx))
+
+
+def _produce_from_csv(
+    node: Node, adapter: Any, app_root: Path, reader: CsvSourceReader | None
+) -> Any:
+    """Load the node's declared csv source."""
+    return produce_csv(node, reader=reader)
+
+
+_PRODUCERS: dict[str, Callable[[Node, Any, Path, CsvSourceReader | None], Any]] = {
+    "python-node": _produce_from_script,
+    "python-csv": _produce_from_csv,
+}
+
+
 def run_node(
     env: Mapping[str, str], adapter: Any = None, reader: CsvSourceReader | None = None
 ) -> int:
     """Run a single node end-to-end and print exactly one sentinel result block.
 
-    ``reader`` mirrors the ``adapter`` injection seam: when given, it is
-    threaded into :func:`produce_csv` for a python-csv node instead of
-    letting that function pick a reader via ``reader_for``. Ignored for a
-    python-model node.
+    ``reader`` is threaded into the python-csv producer instead of letting
+    it pick a reader via ``reader_for``; the script producer ignores it.
 
     Returns 0 on success, 1 on any :class:`HarnessError`.
     """
@@ -255,14 +276,7 @@ def run_node(
 
         _validate_config_early(active_adapter, node)
 
-        if node.kind == "python-csv":
-            table = produce_csv(node, reader=reader)
-        else:
-            with contextlib.redirect_stdout(sys.stderr):
-                module = load_script(node, app_root)
-            ctx = RunContext(node, active_adapter)
-            raw_result = _execute_script(module, ctx)
-            table = to_arrow(raw_result)
+        table = _PRODUCERS[node.kind](node, active_adapter, app_root, reader)
 
         conformed = conform(table, node.output_columns, node.extra_columns)
 

{continuo_python_runtime-0.5.0.dist-info → continuo_python_runtime-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: continuo-python-runtime
-Version: 0.5.0
+Version: 0.6.0
 Summary: Runtime harness, contract tooling, and CI lint for Continuo python nodes.
 Author: Simone Carolini
 Maintainer: Simone Carolini
@@ -163,7 +163,7 @@ Every rule below (`extra_columns`, `output_columns`, "Conform rules") applies
 to both kinds identically — `kind` only changes how the pre-conform table is
 produced, never how it is checked or written.
 
-- **`python-model`** (the default; the field may be omitted) — a script node.
+- **`python-node`** (the default; the field may be omitted) — a script node.
   It requires `script:` and a `reads:` map of one or more named SQL queries,
   as described in "The script API" below.
 - **`python-csv`** — a contract-only node: it has no script and its `reads:`
@@ -275,9 +275,9 @@ A domain repo picks its warehouse engine by which base image it builds
 `FROM`:
 
 ```dockerfile
-FROM ghcr.io/carolsimone/continuo-python-runtime-postgres:v0.5.0
+FROM ghcr.io/carolsimone/continuo-python-runtime-postgres:v0.6.0
 # or
-FROM ghcr.io/carolsimone/continuo-python-runtime-trino:v0.5.0
+FROM ghcr.io/carolsimone/continuo-python-runtime-trino:v0.6.0
 ```
 
 The engine is part of the image **name**; the tag is the bare version, so

{continuo_python_runtime-0.5.0.dist-info → continuo_python_runtime-0.6.0.dist-info}/RECORD

@@ -6,14 +6,15 @@ continuo_python_runtime/context.py,sha256=K-9XXYlQ4OZ250rCOq6EJNq7fg_D5sK6tOcu7D
 continuo_python_runtime/csv_loader.py,sha256=a5Hwu-YIzIiko8X1_vqShsnzjs2-OsKEUSCHLXg_dio,3346
 continuo_python_runtime/csv_source.py,sha256=7g8Tu6ieiJLvWH4Ep4nwYlOdGkjeePr12K5UHuO8TNc,4136
 continuo_python_runtime/errors.py,sha256=nfZzfBhQ2ajm7USAWKKaGY2uUlh8eNjNPNYYuaOJgZE,1032
-continuo_python_runtime/harness.py,sha256=BBJBmmiQ922WVmPi0Xh7CFnXjNxKefPey0YOEHercjs,12634
+continuo_python_runtime/harness.py,sha256=1NDlhHVoDF9Q1jg3LQmhA56XgRZCBUHzcknntgOwqV0,13011
 continuo_python_runtime/hashing.py,sha256=70iXQb0CmjGqniTPofXY6WapydQ7aK2XOk5dzpEf-zk,3354
 continuo_python_runtime/lint.py,sha256=M59UtCHHVQnJKNolIkvkRk_AgGAFvxD9zkKAMMK-7GI,12984
 continuo_python_runtime/types.py,sha256=_ssxNE2Lq5782n9_Ihs-u_6ybCCy8XaL6iYbE35tBug,5057
 continuo_python_runtime/contract/__init__.py,sha256=S79x6j_P0CmaSuCGzeWoK1U0507KvD2MZXwQl9DFWMM,37
-continuo_python_runtime/contract/loader.py,sha256=oUer1sbaxhUMNQVUuqO5j5vbQCrgwuHOWJzGe0MHSLg,16973
-continuo_python_runtime/contract/merge.py,sha256=36awQV8cHGcQJv6XJGC_mC5MuyRS5-7XTVTLw0sjMgE,6903
-continuo_python_runtime/contract/model.py,sha256=L7GwSYKrh6Z0J1c1zWFHQw8GzYUUzzWycuBw5Qq5Dfg,1017
+continuo_python_runtime/contract/kinds.py,sha256=nFyCZplwpxYK8AKzKRfJp0-V49jFVZcJAW8Q4-3ezHE,4338
+continuo_python_runtime/contract/loader.py,sha256=1JARlZJSgadN0h_wvvhFV9q5nqwoDbtvwVsAGDSiXg8,14491
+continuo_python_runtime/contract/merge.py,sha256=QjHavaFe_HviR3vPtAmF5-4_3XdmgNbhl-JmrpVM8iI,7323
+continuo_python_runtime/contract/model.py,sha256=-tf5DFqRidMx_Pt8NWyJZ9i8Yystg9-YqBjqHAeX4Xg,1043
 continuo_python_runtime/contract/paths.py,sha256=SRn70pJkDAIpXw0IcMU2iNKPKvct8w_SZP2ec-lV91M,1458
 continuo_python_runtime/csv_readers/__init__.py,sha256=9TKvjC37C77uRaJQZuO0--zVj2OvuNwpJE6nWx7j2S8,806
 continuo_python_runtime/csv_readers/https.py,sha256=tMJ9k5F0b9SAydpon0ZlOznfjvjhF2BBLltyVmvRneE,4998
@@ -21,9 +22,9 @@ continuo_python_runtime/csv_readers/s3.py,sha256=zmvHs3TxlN2alPKrdaHzPyREmkve2nB
 continuo_python_runtime/validation/__init__.py,sha256=hz5oGXsoaUoygR0_pBby9PS6cEfrre518EE0HGB58eE,79
 continuo_python_runtime/validation/runner.py,sha256=7pbksf7MXfTNcdklCOkOXg9qfRiJtyI_dbgbL3a9LWk,14072
 continuo_python_runtime/validation/s3.py,sha256=q8nRrT9R7L1-M4dSlDnkL7CUJMPmq86MHY_UKYFlEf8,1785
-continuo_python_runtime-0.5.0.dist-info/METADATA,sha256=vQisnCASgreJNhw4ryPWuyQvo4dmw6mWEMJH3zZxHx4,18811
-continuo_python_runtime-0.5.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-continuo_python_runtime-0.5.0.dist-info/entry_points.txt,sha256=ZvIwSm9f9B9ZmZMf6CyF5Zt4QONn8rqaIk-u-B1CF2Y,70
-continuo_python_runtime-0.5.0.dist-info/licenses/LICENSE,sha256=hfXfFCk-8gnps4YvHA6bjCNaSYqOrq2gAdqkXYycAQc,11345
-continuo_python_runtime-0.5.0.dist-info/licenses/NOTICE,sha256=ykgYyQkAMx3uas90FZHzt0aTca9IgJQCLpZ4d74Pl3U,465
-continuo_python_runtime-0.5.0.dist-info/RECORD,,
+continuo_python_runtime-0.6.0.dist-info/METADATA,sha256=kX73HGlQoFnSWLVicVKPNyVo-ou6HDH4360MHrcduaM,18810
+continuo_python_runtime-0.6.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+continuo_python_runtime-0.6.0.dist-info/entry_points.txt,sha256=ZvIwSm9f9B9ZmZMf6CyF5Zt4QONn8rqaIk-u-B1CF2Y,70
+continuo_python_runtime-0.6.0.dist-info/licenses/LICENSE,sha256=hfXfFCk-8gnps4YvHA6bjCNaSYqOrq2gAdqkXYycAQc,11345
+continuo_python_runtime-0.6.0.dist-info/licenses/NOTICE,sha256=ykgYyQkAMx3uas90FZHzt0aTca9IgJQCLpZ4d74Pl3U,465
+continuo_python_runtime-0.6.0.dist-info/RECORD,,

{continuo_python_runtime-0.5.0.dist-info → continuo_python_runtime-0.6.0.dist-info}/WHEEL

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