chtypes 0.3.2__tar.gz → 0.4.0__tar.gz

{chtypes-0.3.2 → chtypes-0.4.0}/CHANGELOG.md

@@ -6,6 +6,21 @@ The four bindings in this repository are released together and give one answer,
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-09-30
+
+Speaks ABI revision 6 and refuses revision-5 artifacts. Revision 6 adds the error-code table and the partition key; revision-6 artifacts are published for every ClickHouse line this SDK supports, beside the revision-5 builds that 0.3.x keeps loading.
+
+### Added
+
+- **`Library.error_codes()`** — THIS build's own ClickHouse error-code table (`chs_error_codes`), as an `ErrorCodeTable`: `name(code) -> str | None`, `code(name) -> int | None`, `all()` (ascending) and iteration, over `ErrorCodeEntry(code, name)`. Per `Library` and never package-level, because the table moves between lines — one number names two different errors on 25.8 and 26.2. An unknown or negative code and an unknown name are `None`, never synthesized; names match exactly. Built on the first call and kept on success only: a `NULL` answer raises `ChtypesError` and is never cached; an artifact that predates the symbol raises `UnsupportedError`.
+- **`Schema.set_partition_by(expr)`** — declare the table's partition key; `""` removes it. It follows `set_engine`'s sign rule, not `set_ttl`'s: `SchemaError` for the server's own CREATE-path refusal (e.g. 36 BAD_ARGUMENTS for a non-deterministic key, 549), `UnsupportedError` for a decline (-2 is a key the server accepts but this build will not evaluate).
+- **`RowResult.partition_id`** and **`BatchResult.partition_count`**, both `None` unless the schema declared a key. A batch over `max_partitions_per_insert_block` is an ordinary `Outcome.REJECTED` with `err_code` 252.
+
+### Changed
+
+- **Speaks ABI revision 6, and refuses revision-5 artifacts** — and a revision-5 binding refuses revision-6 ones. Revision 6 only ADDS `chs_error_codes` and `chs_schema_partition_by`; no existing declaration changed. It is still a new number, so a fetch after upgrading downloads revision-6 artifacts into their own `abi6` cache directory, and a directory holding only revision-5 artifacts is refused at load, naming both revisions. Revision-6 artifacts are published by the artifact producer; until they are, this binding has nothing to load.
+- **A TTL on a schema with a `CHECK` constraint is now evaluated.** `Schema.set_ttl` on such a schema used to answer `UnsupportedError`; against revision-6 artifacts it answers as on any other schema, accepting the TTL or giving the server's own refusal. That matches a server, whose TTL validation does not read constraints. The change is in the artifacts, so it arrives with them.
+
 ## [0.3.2] — 2026-09-28
 
 Speaks ABI revision 5, unchanged from 0.3.1: every artifact 0.3.1 loads, this release loads.

{chtypes-0.3.2 → chtypes-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: chtypes
-Version: 0.3.2
+Version: 0.4.0
 Summary: Python binding for the chtypes artifacts: ClickHouse's own type system, per version, behind the frozen chs_* C ABI
 Project-URL: Homepage, https://github.com/wave-rf/chtypes
 Project-URL: Repository, https://github.com/wave-rf/chtypes
@@ -84,7 +84,7 @@ A bad **row** is a verdict, not an exception: `outcome` becomes `Outcome.REJECTE
 
 **`ctypes` releases the GIL for the whole duration of a foreign call**, so the GIL is not the exclusion. The package uses a writer-preferring readers-writer lock per loaded image plus one plain lock per `Schema`; `set_default_settings` and `close` take it exclusively, as the ABI requires. Measured under contention: 27,770 batch reads across 8 threads against 566 concurrent settings swaps, every answer byte-identical to the uncontended one.
 
-**The INSERT column list (ABI revision 5) is a keyword-only `columns` on the same calls** — `schema.row(fmt, raw, columns=["id", "e"])`, and the same argument on `Schema.rows` and `Schema.parse_block`. `None` or an empty sequence is the no-list behavior of every earlier revision; a list makes the data supply exactly those columns, with a listed `EPHEMERAL` value read and in scope for the DEFAULTs that reference it but never stored. This release requires a revision-5 artifact — a revision-4 one is refused at load, naming both revisions.
+**The INSERT column list (ABI revision 5) is a keyword-only `columns` on the same calls** — `schema.row(fmt, raw, columns=["id", "e"])`, and the same argument on `Schema.rows` and `Schema.parse_block`. `None` or an empty sequence is the no-list behavior of every earlier revision; a list makes the data supply exactly those columns, with a listed `EPHEMERAL` value read and in scope for the DEFAULTs that reference it but never stored. The column list needs an artifact of revision 5 or later, and this binding loads only artifacts at its own `chtypes.ABI_REVISION` — any other is refused at load, naming both revisions.
 
 ## Tests
 

{chtypes-0.3.2 → chtypes-0.4.0}/README.md

@@ -66,7 +66,7 @@ A bad **row** is a verdict, not an exception: `outcome` becomes `Outcome.REJECTE
 
 **`ctypes` releases the GIL for the whole duration of a foreign call**, so the GIL is not the exclusion. The package uses a writer-preferring readers-writer lock per loaded image plus one plain lock per `Schema`; `set_default_settings` and `close` take it exclusively, as the ABI requires. Measured under contention: 27,770 batch reads across 8 threads against 566 concurrent settings swaps, every answer byte-identical to the uncontended one.
 
-**The INSERT column list (ABI revision 5) is a keyword-only `columns` on the same calls** — `schema.row(fmt, raw, columns=["id", "e"])`, and the same argument on `Schema.rows` and `Schema.parse_block`. `None` or an empty sequence is the no-list behavior of every earlier revision; a list makes the data supply exactly those columns, with a listed `EPHEMERAL` value read and in scope for the DEFAULTs that reference it but never stored. This release requires a revision-5 artifact — a revision-4 one is refused at load, naming both revisions.
+**The INSERT column list (ABI revision 5) is a keyword-only `columns` on the same calls** — `schema.row(fmt, raw, columns=["id", "e"])`, and the same argument on `Schema.rows` and `Schema.parse_block`. `None` or an empty sequence is the no-list behavior of every earlier revision; a list makes the data supply exactly those columns, with a listed `EPHEMERAL` value read and in scope for the DEFAULTs that reference it but never stored. The column list needs an artifact of revision 5 or later, and this binding loads only artifacts at its own `chtypes.ABI_REVISION` — any other is refused at load, naming both revisions.
 
 ## Tests
 

{chtypes-0.3.2 → chtypes-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "chtypes"
-version = "0.3.2"
+version = "0.4.0"
 description = "Python binding for the chtypes artifacts: ClickHouse's own type system, per version, behind the frozen chs_* C ABI"
 readme = "README.md"
 license = "Apache-2.0"

{chtypes-0.3.2 → chtypes-0.4.0}/src/chtypes/__init__.py

@@ -43,6 +43,7 @@ from __future__ import annotations
 from importlib.metadata import PackageNotFoundError as _PackageNotFound
 from importlib.metadata import version as _package_version
 
+from ._error_codes import ErrorCodeEntry, ErrorCodeTable
 from ._native import ABI_REVISION
 from ._rawjson import RawNumber, quote_bare_denormals
 from .discover import (
@@ -165,6 +166,8 @@ __all__ = [
     "Computed",
     "DefaultKind",
     "DiscoveredColumn",
+    "ErrorCodeEntry",
+    "ErrorCodeTable",
     "Filter",
     "FilterOutcome",
     "FilterResult",

{chtypes-0.3.2 → chtypes-0.4.0}/src/chtypes/_document.py

@@ -196,6 +196,10 @@ def _row_result(doc: RawObject) -> RowResult:
     verdict_code = _count(doc, "verdict_code")
     verdict_err = _text(doc, "verdict_err")
 
+    # `partition_id` (revision 6) is present exactly when the schema declared
+    # a partition key and this row would be stored; absent is None.
+    partition_id = doc.get("partition_id")
+
     return RowResult(
         outcome=outcome,
         err_code=_count(doc, "code"),
@@ -209,6 +213,7 @@ def _row_result(doc: RawObject) -> RowResult:
         verdict=verdict,
         verdict_code=verdict_code,
         verdict_err=verdict_err,
+        partition_id=partition_id if isinstance(partition_id, str) else None,
     )
 
 
@@ -244,6 +249,7 @@ def parse_batch_document(raw: bytes, payload: bytes | None = None) -> BatchResul
                 verdict=row.verdict,
                 verdict_code=row.verdict_code,
                 verdict_err=row.verdict_err,
+                partition_id=row.partition_id,
             )
         )
         transformed.extend(indexed)
@@ -297,6 +303,11 @@ def parse_batch_document(raw: bytes, payload: bytes | None = None) -> BatchResul
         export_declined=_text(doc, "export_declined"),
         rows_passed=_count(doc, "rows_passed"),
         rows_cut=_count(doc, "rows_cut"),
+        # Revision 6: present exactly when the schema declared a partition
+        # key; absent is None, never a guessed 0.
+        partition_count=_count(doc, "partition_count")
+        if isinstance(doc.get("partition_count"), RawNumber)
+        else None,
     )
 
 

chtypes-0.4.0/src/chtypes/_error_codes.py

@@ -0,0 +1,153 @@
+"""The error-code table (revision 6): one loaded build's own code -> name map.
+
+There is no table in this package, and there must never be one. The table is a
+property of the BUILD: codes join and leave between ClickHouse lines, and one
+number can name two different errors on two lines (903 is LICENSE_EXPIRED on
+25.3 and 25.8, absent on 25.10, and DISTRIBUTED_CACHE_REGISTRY_SHUTDOWN on 26.2
+through 26.9). Every answer
+therefore comes from `Library.error_codes()`, i.e. from `chs_error_codes` of
+the library being asked, and `scripts/check-no-error-code-table.py` fails the
+build if a literal code -> name table appears in any binding.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+
+from .errors import ChtypesError
+
+__all__ = ["ErrorCodeEntry", "ErrorCodeTable"]
+
+
+@dataclass(frozen=True, slots=True)
+class ErrorCodeEntry:
+    """One row of a build's error-code table: a ClickHouse error code and the
+    name THAT BUILD gives it."""
+
+    code: int
+    name: str
+
+
+class ErrorCodeTable:
+    """One loaded library's own error-code table, from `chs_error_codes` —
+    obtained from `Library.error_codes()` and valid for that library's
+    ClickHouse line only. Immutable, so safe to share between threads.
+
+    Lookups answer only what the build's own table holds: an unknown code, a
+    negative code (the ABI's -1 and -2 sentinels included — they are not
+    ClickHouse codes) or an unknown name is `None`, never a synthesized
+    spelling. Names match exactly and case-sensitively, as the server prints
+    them. Iterating yields the entries in ascending code order, as `all()`
+    returns them.
+    """
+
+    __slots__ = ("_by_code", "_by_name", "_entries")
+
+    def __init__(self, entries: tuple[ErrorCodeEntry, ...]) -> None:
+        by_code: dict[int, str] = {}
+        by_name: dict[str, int] = {}
+        kept: list[ErrorCodeEntry] = []
+        for e in entries:
+            # Not a name, not a ClickHouse code, or a repeat: the first entry
+            # for a code or a name wins, and nothing else is invented.
+            if not e.name or e.code < 0 or e.code in by_code or e.name in by_name:
+                continue
+            by_code[e.code] = e.name
+            by_name[e.name] = e.code
+            kept.append(e)
+        self._entries = tuple(sorted(kept, key=lambda e: e.code))
+        self._by_code = by_code
+        self._by_name = by_name
+
+    def name(self, code: int) -> str | None:
+        """The name this build gives `code`, or None."""
+        if code < 0:
+            return None
+        return self._by_code.get(code)
+
+    def code(self, name: str) -> int | None:
+        """The code this build gives `name` — an exact, case-sensitive match —
+        or None."""
+        return self._by_name.get(name)
+
+    def all(self) -> tuple[ErrorCodeEntry, ...]:
+        """Every entry, in ascending code order."""
+        return self._entries
+
+    def __iter__(self) -> Iterator[ErrorCodeEntry]:
+        return iter(self._entries)
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def __repr__(self) -> str:
+        return f"<chtypes.ErrorCodeTable {len(self._entries)} codes>"
+
+
+def parse_error_codes_document(raw: bytes) -> ErrorCodeTable:
+    """Build a table from a `chs_error_codes` document,
+    `{"error_codes":[{"code":N,"name":"…"}, …]}`.
+
+    Unknown keys are ignored and an absent (or null) key is its default, like
+    every document this ABI hands back. A value of the wrong type is a bad
+    document, never a guess.
+    """
+    try:
+        doc = json.loads(raw)
+    except ValueError as exc:
+        raise ChtypesError(f"chtypes: bad chs_error_codes document: {exc}") from exc
+    if not isinstance(doc, dict):
+        raise ChtypesError("chtypes: bad chs_error_codes document: not a JSON object")
+    rows = doc.get("error_codes")
+    if rows is None:
+        rows = []
+    if not isinstance(rows, list):
+        raise ChtypesError("chtypes: bad chs_error_codes document: error_codes is not an array")
+    entries: list[ErrorCodeEntry] = []
+    for row in rows:
+        if not isinstance(row, dict):
+            raise ChtypesError("chtypes: bad chs_error_codes document: an entry is not an object")
+        code = row.get("code")
+        name = row.get("name")
+        if code is None:
+            code = 0
+        if name is None:
+            name = ""
+        if isinstance(code, bool) or not isinstance(code, int) or not isinstance(name, str):
+            raise ChtypesError(f"chtypes: bad chs_error_codes document: entry {row!r}")
+        entries.append(ErrorCodeEntry(code=code, name=name))
+    return ErrorCodeTable(tuple(entries))
+
+
+class _ErrorCodeCache:
+    """One library's table once it has been built, and only then.
+
+    A NULL answer from `chs_error_codes` is a guarded exception inside the
+    library — transient by definition — so it raises `ChtypesError` and is NOT
+    remembered: the next call asks again. A missing symbol raises the decline
+    type and is not remembered either. Only a table that was actually built is
+    kept.
+    """
+
+    __slots__ = ("_mu", "_table")
+
+    def __init__(self) -> None:
+        self._mu = threading.Lock()
+        self._table: ErrorCodeTable | None = None
+
+    def get(self, fetch: Callable[[], bytes | None]) -> ErrorCodeTable:
+        with self._mu:
+            if self._table is not None:
+                return self._table
+            raw = fetch()
+            if raw is None:
+                raise ChtypesError(
+                    "chtypes: chs_error_codes returned no document (a guarded exception "
+                    "inside the library); nothing was cached, so the next call asks again"
+                )
+            table = parse_error_codes_document(raw)
+            self._table = table
+            return table

{chtypes-0.3.2 → chtypes-0.4.0}/src/chtypes/_native.py

@@ -78,6 +78,11 @@ _SIGNATURES: Final[dict[str, tuple[object, list[object]]]] = {
     ),
     "chs_registered_families": (ctypes.c_void_p, []),
     "chs_function_flags": (ctypes.c_void_p, []),
+    # Revision 6: the build's own error-code table, an owned JSON document.
+    # Optional: an artifact that predates it degrades to UnsupportedError at
+    # call time. NULL from a PRESENT symbol is a guarded exception, which is a
+    # different answer — see `error_codes`.
+    "chs_error_codes": (ctypes.c_void_p, []),
     # settings_json + mode compile a column list under a DECLARED settings
     # profile; NULL/"{}" settings_json and mode 0 answer identically to the
     # pre-consolidation, settings-less compile — structurally, not just by
@@ -94,6 +99,9 @@ _SIGNATURES: Final[dict[str, tuple[object, list[object]]]] = {
         [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_char_p, ctypes.c_char_p, _c_owned_p],
     ),
     "chs_schema_ttl": (ctypes.c_int, [ctypes.c_void_p, ctypes.c_char_p, _c_owned_p]),
+    # Revision 6: the partition key — chs_schema_ttl's exact C shape. The SIGN
+    # rule its return follows is chs_schema_engine's (see Schema.set_partition_by).
+    "chs_schema_partition_by": (ctypes.c_int, [ctypes.c_void_p, ctypes.c_char_p, _c_owned_p]),
     "chs_schema_column_count": (ctypes.c_int, [ctypes.c_void_p]),
     "chs_schema_column_name": (ctypes.c_char_p, [ctypes.c_void_p, ctypes.c_int]),
     "chs_schema_column_type": (ctypes.c_char_p, [ctypes.c_void_p, ctypes.c_int]),
@@ -189,7 +197,10 @@ _SIGNATURES: Final[dict[str, tuple[object, list[object]]]] = {
 # (chs_block_parse / chs_block_free / chs_filter_eval).
 # 5 = the explicit INSERT column list, 2026-09-15: chs_row, chs_rows and
 # chs_block_parse each gained a trailing columns_json.
-ABI_REVISION: Final = 5
+# 6 = the error-code table and the partition key: chs_error_codes and
+# chs_schema_partition_by joined the surface. Purely additive, and still a
+# new number: a revision-6 binding refuses a revision-5 artifact.
+ABI_REVISION: Final = 6
 
 _MANDATORY: Final = (
     "chs_clickhouse_version",
@@ -217,7 +228,8 @@ class _RWLock:
 
     **Readers** are every call that reaches `chs_row`, `chs_rows`,
     `chs_schema_compile`, `chs_schema_engine`, `chs_schema_ttl`,
-    `chs_validate_type` and the column accessors. The C ABI contract
+    `chs_schema_partition_by`, `chs_validate_type`, `chs_error_codes` and the
+    column accessors. The C ABI contract
     §Thread-safety declares those safe together **on distinct handles**, so
     per-handle serialization is `Schema`'s own lock and not this one.
 
@@ -507,6 +519,16 @@ class NativeLibrary:
             raw = self._take(fn())
         return (raw or b"").decode("utf-8", "surrogateescape")
 
+    def error_codes(self) -> bytes | None:
+        """The build's own error-code table as the raw JSON document, or None
+        when the library could not build it (a guarded exception — transient,
+        so the caller must not remember it). A missing symbol raises
+        `UnsupportedError`, which is a different answer: the artifact predates
+        revision 6."""
+        fn = self._need("chs_error_codes", "this artifact predates chs_error_codes (rebuild it)")
+        with self._lock.read():
+            return self._take(fn())
+
     def function_flags(self) -> str:
         """The function-volatility TSV audit, verbatim. Requires chs_init."""
         fn = self._need(
@@ -576,6 +598,17 @@ class NativeLibrary:
             rc = int(fn(ctypes.c_void_p(handle), ttl_sql.encode(), ctypes.byref(err)))
             return rc, self._take_err(err)
 
+    def schema_partition_by(self, handle: int, partition_by: str) -> tuple[int, str]:
+        """(rc, err) from chs_schema_partition_by. The caller maps rc by the
+        SIGN rule chs_schema_engine uses, not chs_schema_ttl's."""
+        fn = self._need(
+            "chs_schema_partition_by", "this artifact predates chs_schema_partition_by (rebuild it)"
+        )
+        err = ctypes.c_void_p()
+        with self._lock.read():
+            rc = int(fn(ctypes.c_void_p(handle), partition_by.encode(), ctypes.byref(err)))
+            return rc, self._take_err(err)
+
     def schema_columns(self, handle: int) -> list[tuple[str, str, str, str, bool]]:
         """(name, type, default_kind, default_expr, default_is_literal) per column."""
         if not self.has_columns:

{chtypes-0.3.2 → chtypes-0.4.0}/src/chtypes/registry.py

@@ -19,6 +19,7 @@ from types import TracebackType
 from typing import Final
 
 from ._document import parse_batch_document, parse_filter_document, parse_row_document
+from ._error_codes import ErrorCodeTable, _ErrorCodeCache
 from ._manifest import (
     Manifest,
     cache_registry_dir,
@@ -349,6 +350,38 @@ class Schema:
         if rc != 0:
             raise UnsupportedError(err or "TTL form not modeled by this build")
 
+    def set_partition_by(self, expr: str) -> None:
+        """Declare the table's partition key — the `PARTITION BY` clause after
+        the engine, e.g. "toYYYYMM(ts)" or "(toDate(ts), tenant)"
+        (`chs_schema_partition_by`, revision 6).
+
+        The key is built by the server's own CREATE-path call over this
+        schema's columns, under the handle's compile profile. A second call
+        REPLACES the first; "" removes the declaration, and the schema then
+        answers exactly as one that never declared a key.
+
+        With a key declared, `row` and `rows` answer `RowResult.partition_id`
+        for every row that would be stored and `BatchResult.partition_count`
+        for the batch, and a body that would split into more partitions than
+        the call's `max_partitions_per_insert_block` allows is an ordinary
+        `Outcome.REJECTED` with `err_code` 252 (TOO_MANY_PARTS), the server's
+        own — a verdict, never an exception.
+
+        The return follows `set_engine`'s SIGN rule, not `set_ttl`'s: raises
+        `SchemaError` when the server's own CREATE path refuses the key (e.g.
+        36 BAD_ARGUMENTS for a non-deterministic key, 549
+        DATA_TYPE_CANNOT_BE_USED_IN_KEY, with the server's message), and
+        `UnsupportedError` when this build declines (-1, a guarded exception)
+        or the artifact predates the symbol. -2 is a key the server accepts but
+        this build will not evaluate; a non-deterministic key is the server's
+        own rejection, 36 BAD_ARGUMENTS.
+        """
+        with self._mu:
+            rc, err = self._library._native.schema_partition_by(self._live(), expr)
+        if rc == 0:
+            return
+        raise _error_for(rc, err or "partition key refused")
+
     # -- rows ---------------------------------------------------------------
 
     def row(
@@ -823,6 +856,7 @@ class Library:
 
     __slots__ = (
         "_closed",
+        "_error_codes",
         "_image_key",
         "_native",
         "abi_revision",
@@ -836,6 +870,9 @@ class Library:
         self.path = path
         self.manifest = manifest
         self._closed = False
+        # This library's own error-code table, once built (see error_codes).
+        # Per Library and never shared: the table is a property of the build.
+        self._error_codes = _ErrorCodeCache()
         self._native = NativeLibrary(path)
         # The library names itself; nothing is inferred from the directory or
         # the file name.
@@ -1013,6 +1050,25 @@ class Library:
         """
         return [line for line in self._native.registered_families().split("\n") if line]
 
+    def error_codes(self) -> ErrorCodeTable:
+        """THIS library's own error-code table (`chs_error_codes`, revision 6):
+        every code the vendored ClickHouse names, with the name it gives it —
+        the table the server's `system.errors` enumerates and the name it
+        prints after "Code: N." in an exception message.
+
+        The table belongs to the build, not to this package: codes join and
+        leave between lines, and one number can name different errors on two
+        lines (903 differs between 25.8 and 26.2). Ask the library whose line
+        you are answering for; there is no package-level table.
+
+        Built on the first call and kept for this library's life — the answer
+        never changes for a loaded library. Only a table that was actually
+        built is kept: a NULL answer (a guarded exception inside the library)
+        raises `ChtypesError` and the next call asks again. Raises
+        `UnsupportedError` when the artifact predates `chs_error_codes`.
+        """
+        return self._error_codes.get(self._native.error_codes)
+
     def function_flags(self) -> str:
         """TSV audit of every registered function's volatility, VERBATIM: one
         function per line, six tab-separated fields (`name`, `deterministic`,

{chtypes-0.3.2 → chtypes-0.4.0}/src/chtypes/results.py

@@ -492,6 +492,12 @@ class RowResult:
     # parse error, reported as DECLINE). 0/"" otherwise.
     verdict_code: int = 0
     verdict_err: str = ""
+    # Revision 6: the partition this row lands in, as the loaded build's own
+    # MergeTreePartition::getID spells it — present only when the schema
+    # declared a partition key (`Schema.set_partition_by`) and the row would
+    # be stored; None otherwise. Grouping an accepted batch's `spans` by it
+    # gives per-partition bodies, each directly INSERT-able.
+    partition_id: str | None = None
 
     @property
     def accepted(self) -> bool:
@@ -596,6 +602,12 @@ class BatchResult:
     # these being nonzero.
     rows_passed: int = 0
     rows_cut: int = 0
+    # Revision 6: the distinct partitions this batch's stored rows span —
+    # present only when the schema declared a partition key
+    # (`Schema.set_partition_by`); None otherwise. A batch over the call's
+    # max_partitions_per_insert_block is an ordinary REJECTED with err_code
+    # 252 (TOO_MANY_PARTS), the server's own.
+    partition_count: int | None = None
 
     @property
     def lossy_transforms(self) -> tuple[Transform, ...]:

chtypes-0.4.0/tests/test_error_codes.py

@@ -0,0 +1,250 @@
+"""Revision 6's error-code table.
+
+The first half needs no artifact: it parses documents in the shape
+`chs_error_codes` returns through the SAME parser `Library.error_codes()` uses,
+and drives the success-only cache with a stand-in for the native call. What it
+pins is the binding's own contract — unknown is absent, `all()` is ascending,
+names match exactly, a NULL answer is never remembered — and none of it is a
+ClickHouse fact.
+
+The second half asks a loaded revision-6 library and skips LOUDLY, by name,
+without one.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import pytest
+
+import chtypes
+from chtypes._error_codes import _ErrorCodeCache, parse_error_codes_document
+
+# Out of order on purpose, with unknown keys at both levels, an entry with no
+# name and a negative code — none of which may reach a lookup.
+FAKE = b"""{
+  "error_codes": [
+    {"code": 252, "name": "TOO_MANY_PARTS", "since": "whatever"},
+    {"code": 0, "name": "OK"},
+    {"code": 1, "name": "UNSUPPORTED_METHOD"},
+    {"code": 7, "name": ""},
+    {"code": -2, "name": "NOT_A_CLICKHOUSE_CODE"},
+    {"code": 47, "name": "UNKNOWN_IDENTIFIER"}
+  ],
+  "generator": "ignored"
+}"""
+
+KNOWN = {0: "OK", 1: "UNSUPPORTED_METHOD", 47: "UNKNOWN_IDENTIFIER", 252: "TOO_MANY_PARTS"}
+
+
+def test_lookups_answer_the_document_and_nothing_else() -> None:
+    table = parse_error_codes_document(FAKE)
+    for code, name in KNOWN.items():
+        assert table.name(code) == name
+        assert table.code(name) == code
+    # Absent, never synthesized: an unknown code, the unnamed entry, a
+    # negative code even though the document carried one, the ABI sentinels.
+    for code in (2, 7, 999_999, -1, -2, -3):
+        assert table.name(code) is None, code
+    # Exact and case-sensitive; no trimming, no folding.
+    for name in (
+        "too_many_parts",
+        "Too_Many_Parts",
+        " TOO_MANY_PARTS",
+        "TOO_MANY_PARTS ",
+        "",
+        "NOT_A_CLICKHOUSE_CODE",
+        "NO_SUCH_ERROR",
+    ):
+        assert table.code(name) is None, name
+
+
+def test_all_and_iteration_are_ascending() -> None:
+    table = parse_error_codes_document(FAKE)
+    want = tuple(chtypes.ErrorCodeEntry(code=c, name=n) for c, n in sorted(KNOWN.items()))
+    assert table.all() == want
+    assert tuple(table) == want
+    assert len(table) == len(want)
+
+
+def test_the_first_entry_wins_on_a_repeat() -> None:
+    table = parse_error_codes_document(
+        b'{"error_codes":[{"code":5,"name":"A_NAME"},{"code":5,"name":"B_NAME"},'
+        b'{"code":6,"name":"A_NAME"}]}'
+    )
+    assert table.name(5) == "A_NAME"
+    assert table.name(6) is None
+    assert len(table.all()) == 1
+
+
+@pytest.mark.parametrize(
+    "doc",
+    [b"{}", b'{"error_codes":null}', b'{"error_codes":[]}', b'{"something_else":[1,2,3]}'],
+)
+def test_absent_keys_are_an_empty_table(doc: bytes) -> None:
+    table = parse_error_codes_document(doc)
+    assert table.all() == ()
+    assert table.name(0) is None
+
+
+@pytest.mark.parametrize(
+    "doc",
+    # The same list every binding's bad-document test runs: a truncated
+    # document, a top-level value that is not an object, error_codes that is not
+    # an array, an entry that is not an object, and a field of the wrong type.
+    [
+        b'{"error_codes":[',
+        b"[]",
+        b"null",
+        b"42",
+        b'"x"',
+        b'{"error_codes":{}}',
+        b'{"error_codes":[null]}',
+        b'{"error_codes":[[252,"X"]]}',
+        b'{"error_codes":[{"code":"252","name":"X"}]}',
+        b'{"error_codes":[{"code":252.5,"name":"X"}]}',
+        b'{"error_codes":[{"code":1,"name":5}]}',
+    ],
+)
+def test_a_bad_document_is_the_general_error(doc: bytes) -> None:
+    with pytest.raises(chtypes.ChtypesError) as info:
+        parse_error_codes_document(doc)
+    assert not isinstance(info.value, (chtypes.SchemaError, chtypes.UnsupportedError))
+
+
+def test_the_cache_keeps_a_built_table_and_nothing_else() -> None:
+    cache = _ErrorCodeCache()
+    calls: list[str] = []
+
+    def null() -> bytes | None:
+        calls.append("null")
+        return None
+
+    def missing() -> bytes | None:
+        calls.append("missing")
+        raise chtypes.UnsupportedError("this artifact predates chs_error_codes (rebuild it)")
+
+    def built() -> bytes | None:
+        calls.append("built")
+        return FAKE
+
+    # A NULL answer: the general error, not a decline, and not remembered.
+    with pytest.raises(chtypes.ChtypesError) as info:
+        cache.get(null)
+    assert not isinstance(info.value, chtypes.UnsupportedError)
+    # A missing symbol: the decline type, not remembered either.
+    with pytest.raises(chtypes.UnsupportedError):
+        cache.get(missing)
+    first = cache.get(built)
+    assert first.name(252) == "TOO_MANY_PARTS"
+
+    def never() -> bytes | None:
+        raise AssertionError("the cache asked the library again after a table was built")
+
+    assert cache.get(never) is first
+    assert calls == ["null", "missing", "built"]
+
+
+def test_no_package_level_table() -> None:
+    """The table hangs off a Library; the package carries none."""
+    assert not hasattr(chtypes, "ERROR_CODES")
+    assert not hasattr(chtypes, "error_codes")
+
+
+# ------------------------------------------------------- through the ABI fixture
+
+
+def test_error_codes_through_the_abi_fixture(isolated_search_path: Path) -> None:
+    """`chs_error_codes` through the REAL ctypes path, on the at-revision stub
+    the ABI fixture builds from THIS header — the one library that exists
+    before any revision-6 artifact does, and the one every pull request's
+    abi-fixtures job loads. The stub answers by return type, not with a table,
+    so this pins the wiring rather than an answer: the symbol resolves (never
+    the decline type, never a refusal), and whatever it answers takes the rule
+    — a NULL is the general error and is not kept, a document is kept.
+
+    Nothing here closes the library: reopening after a close is measured to
+    segfault (docs/reference/bindings.md §Teardown)."""
+    env = os.environ.get("CHTYPES_ABI_FIXTURES")
+    if not env:
+        pytest.skip(
+            "no ABI revision fixture: $CHTYPES_ABI_FIXTURES is unset (build one with "
+            "abi-revision/gen.py build --out DIR --header include/chtypes.h)"
+        )
+    root = Path(env)
+    doc = json.loads((root / "fixture.json").read_text())
+    library = chtypes.Registry(root / "at-revision").for_version(doc["clickhouse_minor"])
+    try:
+        first = library.error_codes()
+    except (chtypes.UnsupportedError, chtypes.SchemaError) as exc:
+        pytest.fail(
+            f"error_codes() on a stub built from this header raised {exc!r}; the symbol is "
+            f"declared there, so neither a decline nor a refusal is a possible answer"
+        )
+    except chtypes.ChtypesError as exc:
+        assert "returned no document" in str(exc), exc
+        # Not kept: the next call asks the library again, and gets NULL again.
+        with pytest.raises(chtypes.ChtypesError, match="returned no document"):
+            library.error_codes()
+    else:
+        assert library.error_codes() is first, "a built table was not kept"
+
+
+# ---------------------------------------------------------------- with artifacts
+
+
+def _rev6_libraries(registry: chtypes.Registry) -> list[chtypes.Library]:
+    libs: list[chtypes.Library] = []
+    for version in registry.versions():
+        try:
+            lib = registry.for_version(version)
+        except chtypes.ChtypesError:
+            continue
+        if lib.abi_revision >= 6:
+            libs.append(lib)
+    if not libs:
+        pytest.skip(
+            f"{registry.directory} holds no ABI revision-6 artifact: every case here needs one — "
+            f"fetch one with `scripts/fetch.sh` (docs/guides/fetch.md)"
+        )
+    return libs
+
+
+def test_error_codes_from_the_loaded_library(registry: chtypes.Registry) -> None:
+    for lib in _rev6_libraries(registry):
+        table = lib.error_codes()
+        entries = table.all()
+        assert entries, lib.minor
+        codes = [e.code for e in entries]
+        assert codes == sorted(set(codes)), f"{lib.minor}: all() is not strictly ascending"
+        for e in entries:
+            assert table.name(e.code) == e.name
+            assert table.code(e.name) == e.code
+        assert table.name(252) == "TOO_MANY_PARTS", lib.minor
+        assert table.name(-1) is None and table.name(-2) is None
+        assert lib.error_codes() is table, f"{lib.minor}: the table was not kept"
+
+
+# The header's own example of one number naming different errors on different
+# lines, per the producer's measurement of every served line. None is ABSENT (on
+# 25.10), never a synthesized name. A line not named here (26.10 and later) has
+# no expectation and is not checked.
+ERROR_CODE_903: dict[str, str | None] = {
+    "25.3": "LICENSE_EXPIRED",
+    "25.8": "LICENSE_EXPIRED",
+    "25.10": None,
+    **{f"26.{m}": "DISTRIBUTED_CACHE_REGISTRY_SHUTDOWN" for m in range(2, 10)},
+}
+
+
+def test_code_903_differs_across_lines(registry: chtypes.Registry) -> None:
+    checked = 0
+    for lib in _rev6_libraries(registry):
+        if lib.minor not in ERROR_CODE_903:
+            continue
+        assert lib.error_codes().name(903) == ERROR_CODE_903[lib.minor], lib.minor
+        checked += 1
+    if not checked:
+        pytest.skip("no loaded revision-6 line has a documented expectation for code 903")

chtypes-0.4.0/tests/test_partition_key.py

@@ -0,0 +1,169 @@
+"""Revision 6's partition key: the two result fields, the setter's sign rule,
+and — with a revision-6 artifact — the key end to end.
+
+The unit half parses documents through the SAME parsers every `row`/`rows`
+call uses, and drives `Schema.set_partition_by` through a stand-in native
+layer, so the rc -> exception mapping that ships is the one tested. The
+artifact half skips LOUDLY, by name, without a revision-6 registry.
+"""
+
+from __future__ import annotations
+
+import threading
+import weakref
+
+import pytest
+
+import chtypes
+from chtypes._document import parse_batch_document, parse_row_document
+
+
+def test_partition_fields_parse() -> None:
+    batch = parse_batch_document(
+        b'{"outcome":"accepted","rows_read":3,"partition_count":2,"rows":['
+        b'{"outcome":"accepted","cols":[],"partition_id":"202601"},'
+        b'{"outcome":"accepted","cols":[],"partition_id":"202602"},'
+        b'{"outcome":"rejected","code":27,"err":"x","cols":[]}]}'
+    )
+    assert batch.partition_count == 2
+    assert [r.partition_id for r in batch.rows] == ["202601", "202602", None]
+
+
+def test_partition_fields_absent_are_none() -> None:
+    batch = parse_batch_document(
+        b'{"outcome":"accepted","rows":[{"outcome":"accepted","cols":[]}]}'
+    )
+    assert batch.partition_count is None
+    assert batch.rows[0].partition_id is None
+    row = parse_row_document(b'{"outcome":"accepted","cols":[],"partition_id":"all"}')
+    assert row.partition_id == "all"
+    # A present zero is a real answer (a key, and no stored row), not absence.
+    assert parse_batch_document(b'{"outcome":"accepted","partition_count":0}').partition_count == 0
+
+
+def test_too_many_parts_is_an_ordinary_rejection() -> None:
+    batch = parse_batch_document(
+        b'{"outcome":"rejected","code":252,"err":"Too many partitions for single INSERT block",'
+        b'"rows_read":2,"rows":[{"outcome":"accepted","cols":[],"partition_id":"1"},'
+        b'{"outcome":"accepted","cols":[],"partition_id":"2"}]}'
+    )
+    assert batch.outcome is chtypes.Outcome.REJECTED
+    assert batch.err_code == 252
+    assert len(batch.rows) == 2
+
+
+class _StubNative:
+    """Just enough of NativeLibrary for Schema.set_partition_by to reach."""
+
+    def __init__(self, rc: int, err: str) -> None:
+        self.rc, self.err = rc, err
+        self.calls: list[str] = []
+
+    def schema_partition_by(self, handle: int, expr: str) -> tuple[int, str]:
+        self.calls.append(expr)
+        return self.rc, self.err
+
+    def schema_free(self, handle: int) -> None:
+        pass
+
+
+class _StubLibrary:
+    def __init__(self, native: _StubNative) -> None:
+        self._native = native
+
+
+def _schema_over(native: _StubNative) -> chtypes.Schema:
+    """A Schema whose native layer is the stub: the real method, a fake C side."""
+    schema = object.__new__(chtypes.Schema)
+    schema._library = _StubLibrary(native)
+    schema._handle = 1
+    schema._mu = threading.Lock()
+    schema._filters = weakref.WeakSet()
+    schema._blocks = weakref.WeakSet()
+    return schema
+
+
+def test_set_partition_by_follows_the_engine_sign_rule() -> None:
+    ok = _StubNative(0, "")
+    _schema_over(ok).set_partition_by("toYYYYMM(ts)")
+    assert ok.calls == ["toYYYYMM(ts)"]
+
+    # Positive codes are the server's own refusal: 36 BAD_ARGUMENTS is what a
+    # non-deterministic key gets on every served line, 549 a key over a type
+    # the line will not key on.
+    for rc, expr in ((36, "rand()"), (549, "m")):
+        with pytest.raises(chtypes.SchemaError) as refused:
+            _schema_over(_StubNative(rc, "the server's own message")).set_partition_by(expr)
+        assert refused.value.code == rc
+        assert "the server's own message" in str(refused.value)
+
+    # Negative codes are declines: -2 a key the server accepts but this build
+    # will not evaluate, -1 a guarded exception.
+    for rc in (-1, -2):
+        with pytest.raises(chtypes.UnsupportedError) as declined:
+            _schema_over(_StubNative(rc, "why")).set_partition_by("k")
+        assert not isinstance(declined.value, chtypes.SchemaError)
+
+
+def test_set_partition_by_empty_string_is_passed_through() -> None:
+    native = _StubNative(0, "")
+    _schema_over(native).set_partition_by("")
+    assert native.calls == [""]
+
+
+# ---------------------------------------------------------------- with artifacts
+
+
+def _rev6_libraries(registry: chtypes.Registry) -> list[chtypes.Library]:
+    libs: list[chtypes.Library] = []
+    for version in registry.versions():
+        try:
+            lib = registry.for_version(version)
+        except chtypes.ChtypesError:
+            continue
+        if lib.abi_revision >= 6:
+            libs.append(lib)
+    if not libs:
+        pytest.skip(
+            f"{registry.directory} holds no ABI revision-6 artifact: every case here needs one — "
+            f"fetch one with `scripts/fetch.sh` (docs/guides/fetch.md)"
+        )
+    return libs
+
+
+BODY = (
+    b'{"ts":"2026-01-15 10:00:00","tenant":"a"}\n'
+    b'{"ts":"2026-01-20 10:00:00","tenant":"b"}\n'
+    b'{"ts":"2026-02-01 10:00:00","tenant":"a"}\n'
+)
+
+
+def test_partition_key_end_to_end(registry: chtypes.Registry) -> None:
+    for lib in _rev6_libraries(registry):
+        with lib.compile_ddl("ts DateTime, tenant String") as schema:
+            plain = schema.rows(chtypes.Format.JSON_EACH_ROW, BODY)
+            assert plain.partition_count is None and plain.rows[0].partition_id is None
+
+            schema.set_partition_by("toYYYYMM(ts)")
+            keyed = schema.rows(chtypes.Format.JSON_EACH_ROW, BODY)
+            assert keyed.outcome is chtypes.Outcome.ACCEPTED, lib.minor
+            assert keyed.partition_count == 2, lib.minor
+            p0, p1, p2 = (r.partition_id for r in keyed.rows)
+            assert p0 and p0 == p1 and p0 != p2, (lib.minor, p0, p1, p2)
+
+            over = schema.rows(
+                chtypes.Format.JSON_EACH_ROW, BODY, {"max_partitions_per_insert_block": "1"}
+            )
+            assert over.outcome is chtypes.Outcome.REJECTED, lib.minor
+            assert over.err_code == 252, lib.minor
+            assert len(over.rows) == 3, lib.minor
+
+            schema.set_partition_by("")
+            cleared = schema.rows(chtypes.Format.JSON_EACH_ROW, BODY)
+            assert cleared.partition_count is None and cleared.rows[0].partition_id is None
+
+            # A non-deterministic key is the server's own rejection — 36
+            # BAD_ARGUMENTS on every served line — not a decline.
+            with pytest.raises(chtypes.SchemaError) as refused:
+                schema.set_partition_by("rand()")
+            assert refused.value.code == 36, lib.minor

{chtypes-0.3.2 → chtypes-0.4.0}/uv.lock

@@ -4,7 +4,7 @@ requires-python = ">=3.11"
 
 [[package]]
 name = "chtypes"
-version = "0.3.2"
+version = "0.4.0"
 source = { editable = "." }
 
 [package.dev-dependencies]