chtypes 2.0.0.dev10__tar.gz → 2.0.0.dev12__tar.gz

{chtypes-2.0.0.dev10 → chtypes-2.0.0.dev12}/CHANGELOG.md

@@ -8,6 +8,15 @@ The four bindings in this repository are released together and give one answer,
 
 ### Added
 
+- Tests: the shared revocation-statement table (`tests/fixtures/revocation-statement/cases.json`) runs against `verify_revocation` and `check_installed`: `superseded_by` must be a string (`""` = no fix), and the first verifying revocation in a listing wins. No behavior changed.
+- `column_defaults` is covered by unit tests (ABI v2): the exact `insert_options` JSON for a UTF-8 value, a non-UTF-8 value (`value_b64`), an empty value (sent as `""`) and two entries in order, and the decode of a `default_override` cell (`Source.DEFAULT_OVERRIDE`, stored). The batches guide gains a usage section. No behavior changed.
+- Docs: `docs/guides/batches.md` shows how a `column_defaults` value is read, in the body format's own field encoding (CSV quoting, TSV escapes, a JSON string or number), with a value that doesn't read refused at the call before any body byte.
+- `CODE_DECLINED` (ABI v2, -2): the code a declined row, outcome or verdict carries, generated from the description and exported from `chtypes`, as `bindings-v1.md` section 3 promises.
+- `CallError.reason` (ABI v2): the error's catalog id, read through `chs_error_reason` and passed through verbatim (ASCII, empty if none), on all four call classes.
+- Spec batch 2, the options documents (ABI v2; moves the dev fingerprint): keyword-only `insertable_columns`, `column_defaults` (a sequence of `ColumnDefault`), `verdict_basis` (`VerdictBasis`: `INPUT`, `EXPORT`) and `defer_defaults` (`DeferDefaults`: `NONE`, `SERVER`) build `insert_options` for `Schema.row`, `Schema.rows`, `Schema.parse_block` and `Filter.rows`; `param_encoding` (`ParamEncoding`: `ESCAPED`, `RAW`) builds `filter_options` for `Schema.compile_filter`; `posture` (`Posture`: `CREATE`, `LOAD`) builds `schema_options` for `Library.compile_table`. `insert_options_extra`, `filter_options_extra` and `schema_options_extra` pass a member the binding has no name for through as JSON text, so the library, which refuses an unknown key (rule r1), is the only judge. A document with no member set is not sent. `Filter.rows` takes `columns` (`chs_filter_eval_body` takes the column list).
+- Spec batch 2, a value that is not UTF-8 (ABI v2): a settings value, a query-parameter value, a `setup` default and a server profile's settings value is sent as `{"b64": ...}` (the content `json_object_byte_values`), where the binding used to refuse it, and `SchemaServer.settings` decodes the same form back (as `surrogateescape` text, the spelling the input side takes).
+- Spec batch 2, the decline and refusal members (ABI v2): `RowResult`, `BatchResult` and `FilterResult` carry `reason` (the catalog id, present where the code is -2, `CHS_CODE_DECLINED`), `refused_at` (a `RefusalSite`: `CALL`, `BODY_READ`, `ROW`, `BODY_STEP`) and `refused_row`; `RowResult.verdict_reason`; `FilterRowError.reason`; `BatchResult.export_columns` and `BatchResult.export_declined_reason`.
+- Spec batch 2, the schema description (ABI v2): `SchemaDescription.posture`, and `Column.default_support` (a `DefaultSupport`), `Column.default_support_reason` and `Column.reads`, reserved members a build reports when it implements them. `Source.DEFAULT_DEFERRED`, `Source.DEFAULT_OVERRIDE` (stored) and `DeclinedTier.SERVER_REFUSES` join the vocabularies.
 - A fetch-only call (#492): `Registry.fetch(request) -> Resolved` resolves, fetches, verifies and installs the build a request names into the cache, as `chtypes fetch` does, and opens nothing: no library is loaded and the process setup is untouched, so it needs no `setup`. It honors the registry's fetch options (offline, the cache, and under the production channel the bases, the trust and the lock), and a concurrent `fetch` and open of one request share one fetch. The `Resolved` names the installed version, build, digests and library path; errors are the fetch codes' classes.
 - `chtypes resolve <spelling> [--json]` (#493): what a line or version resolves to on every platform the registry offers, one `resolved <version> <platform> <build> <manifest>` line each, or with `--json` one JSON array of `{platform, version, build, manifest}` objects, each signed statement verified exactly as a fetch verifies it and no layer downloaded; `--offline` answers from the cache. The four CLIs print the same bytes, so one parser reads them (a CI cache key, for example).
 - `chtypes prune [--line <line>] [--keep <n>] [--dry-run]` (#494): removes the installed builds of each line and platform that at least n newer installed builds supersede (n defaults to 1), each with its record, its blobs and its `index.json` entry; `--dry-run` prints exactly what would go. It never removes a build a running process holds: a registry now holds every build it opens or fetches, with a shared `flock` on the entry's `verified.json` until the process exits, and prune removes an entry only after taking the exclusive lock without waiting, reporting it `in-use` otherwise. It never touches a system directory, nor, on the dev channel, another fingerprint's builds. The rules are `docs/guides/fetch-v1.md` sections 1 and 3, and the `resolve-build-*` and `prune-*` conformance cases hold all four bindings to them.
@@ -27,6 +36,11 @@ The four bindings in this repository are released together and give one answer,
 
 ### Changed
 
+- **Breaking (vs the 2.0.0-dev releases):** the batch preview's default `doc_flags` is now 0 (the lean result): `Schema.rows` without `doc_flags=` returns no per-value documents. Pass `doc_flags=DocFlags.ALL` explicitly to get every column's per-value documents.
+- **Breaking (ABI v2 dev): `BatchResult.spans` is a tuple of `Span | None`**, one entry per `rows` entry and index-aligned with it: `row_spans` carries `null` for a row the export did not carry (a skipped row, or a row a filter cut), which reads as `None`. It was the exported rows' spans only. Code that reads `span.off` from every entry raises `AttributeError` on a `None` entry: check each entry before reading it.
+- **Breaking (ABI v2 dev): `AtMergeEntry.row` is `AtMergeEntry.part_row`**, the document's `part_row`.
+- A document's `code` can be -2 (`CHS_CODE_DECLINED`) for a row, batch, filter result or verdict this build declined, and every decline names its `reason`.
+- The refusal of a settings, query-parameter, default or server-settings value that is not valid UTF-8 is gone (it is the `{"b64": ...}` form now); a key that is not valid UTF-8, a macro and a server timezone are still refused, as a `UsageError` naming the input.
 - `chtypes list` and the tag listing name the published lines only (two-part, numeric order), as Go's always did; `chtypes resolve <line>` prints the exact version a line resolves to (#613).
 - **Breaking: the public surface the parity gate carried as exceptions is resolved, before the v2 lock (#499, #500).** A convenience exists in every binding or in none (`docs/reference/bindings-v1.md` §1, principle 2). Migration, old → new:
   - `chtypes.errors.internal` and `chtypes.errors.misuse` → private (#499): they were the binding's own construction helpers, never documented. Catch `InternalError` and `UsageError`, as before.
@@ -68,13 +82,17 @@ The four bindings in this repository are released together and give one answer,
 - **Enforcement gate lifted** for `26.8` on `darwin-arm64`.
 - **Enforcement gate lifted** for `26.9` on `darwin-arm64`.
 - `docs/limitations.md` is re-checked against artifact build `20261012.142240` (v2-dev.13), the library half measured on that build: functions that need a server, in a column expression, and a body the server may read serially or in parallel under a non-zero error budget are listed under "Declined by design"; the known divergence for a column expression that calls a function needing a server is retired, since that build declines those schemas (on 26.8 and 26.9 the `AI*` and `ai*` functions compile, as the page says); and the `lossy` raw-NUL TSV gap is marked fixed on that build and still present in the 1.0 libraries. `docs/guides/filters.md` gains a section on subcolumn filters and a JSON value typed by its batch.
+- The ABI v2 spec now states the INSERT-time settings layering the library already uses, since artifact build `20261021.025722` (#632): at the INSERT, the schema's own settings (the compile profile) reach only the parse, minus a type gate, and every expression the INSERT evaluates and its limits (`max_partitions_per_insert_block` among them) run under the call's own settings, the server profile and the setup defaults only. A setting your INSERT session carries for those goes in the call's settings or the server profile (`docs/guides/settings.md`). No API change.
 
 ### Removed
 
+- **Breaking (ABI v2 dev): `RowResult.unsupported_settings`**: the row document no longer carries `unsupported_settings`; the batch's and the filter result's lists stay.
 - `SchemaServer.filter_declined_settings` (a breaking change inside v2 dev, #588): the server member no longer carries the list. Read `SchemaDescription.filter_declined_settings`, whose `server`-layer entries are the profile's.
 
 ### Fixed
 
+- An offline lookup no longer reads every cached blob once per pre-seeded entry (#690). For each `index.json` entry with no record, the lookup read every blob of the layout, layers included, to find its signature, so entries it could not install (a signature not present, or one no trusted key verifies) cost entries × cache bytes on every lookup: about 4.9 s for 27 such entries over 1.27 GB (`measured`, darwin-arm64). The signature referrers are now read once per lookup, and never a layer, because a blob larger than `limits.manifest_bytes` cannot be a manifest. Installed entries were already skipped. The build that is installed is verified exactly as before: its manifest against its descriptor, its whole layer against its digest, and its signature, platform, request and fingerprint. A unit test counts the blob reads of one lookup that installs nothing and holds them to at most two per blob and five per entry, with no layer read, at 2 and at 20 entries alike.
+- Docs: `docs/guides/settings.md` names the ABI v2 admission time budget `chtypes_default_eval_cpu_nanos`, the evaluating thread's CPU time. Its examples used the 1.x name `chtypes_default_eval_wall_nanos`, which v2 refuses with `CHS_INVALID_ARGUMENT`.
 - A response body cut off part way (shorter than its Content-Length, a reset, a TLS close) is retried like a 5xx and, once the retry table is spent, is `CHTYPES_SOURCE_UNREACHABLE`; only an oversize body is `CHTYPES_ARTIFACT_CORRUPT`, and it is never retried (#641). Python took a body that ended before its Content-Length as the whole body and failed its digest check as corrupt without a retry; now a short body, or `http.client.IncompleteRead`, is retried and ends as unreachable. The rule is `docs/guides/fetch-v1.md` section 7, and the new `body-cut-off-then-ok` and `body-cut-off-exhausted` conformance cases hold every binding to it.
 - A chunked response body cut off before its terminating zero-length chunk is held to the same rule (#644): the new `body-cut-off-chunked-then-ok` and `body-cut-off-chunked-exhausted` conformance cases cut one on the layer blob GET, and this binding already retried it and ended as `CHTYPES_SOURCE_UNREACHABLE` once the retry table was spent. No behavior change; the case now holds it.
 - A settings or query-parameter key or value that is not valid UTF-8 is refused as a usage error; it was silently replaced with U+FFFD, so the library saw a different value. A string holding a lone surrogate (what `surrogateescape` makes of undecodable bytes) was sent as a `\udXXX` escape; the same inputs are refused now, for the per-call zone, the setup defaults and the server profile too. Valid UTF-8 serializes as before.

{chtypes-2.0.0.dev10 → chtypes-2.0.0.dev12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: chtypes
-Version: 2.0.0.dev10
+Version: 2.0.0.dev12
 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
@@ -43,7 +43,7 @@ uv add "chtypes>=2.0.0.dev0"            # or: pip install "chtypes>=2.0.0.dev0"
 
 ```python
 import chtypes
-from chtypes import Format, Registry
+from chtypes import DocFlags, Format, Registry
 
 chtypes.setup(timezone="UTC")  # once, before the first open (optional)
 registry = Registry(autofetch=True)
@@ -51,7 +51,7 @@ library = registry.for_version("26.8")  # a release line or an exact version
 
 ddl = b"CREATE TABLE t (x UInt8, ts DateTime DEFAULT now()) ENGINE = Memory"
 with library.compile_table(ddl) as schema:
-    batch = schema.rows(Format.JSON_EACH_ROW, b'{"x":256}\n')
+    batch = schema.rows(Format.JSON_EACH_ROW, b'{"x":256}\n', doc_flags=DocFlags.ALL)
 
 row = batch.rows[0]
 print(batch.outcome)  # accepted
@@ -96,7 +96,7 @@ A bad **row** is a verdict, not an exception: `outcome` becomes `Outcome.REJECTE
 
 **`ctypes` releases the GIL for the whole of a foreign call**, so calls on compiled handles run in parallel across threads. The package takes no lock around a call; it keeps a close guard per handle and one setup guard.
 
-**The INSERT column list is a keyword-only `columns`** on `schema.row`, `schema.rows` and `schema.parse_block`: `schema.row(Format.JSON_EACH_ROW, body, columns=["id", "e"])`. `None` or an empty sequence is the no-list shape; 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 INSERT column list is a keyword-only `columns`** on `schema.row`, `schema.rows`, `schema.parse_block` and `filter.rows`: `schema.row(Format.JSON_EACH_ROW, body, columns=["id", "e"])`. `None` or an empty sequence is the no-list shape; 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.
 
 **Known gaps in 1.0** are listed, with workarounds, in [`docs/limitations.md`](https://github.com/wave-rf/chtypes/blob/main/docs/limitations.md#known-gaps-in-10).
 

{chtypes-2.0.0.dev10 → chtypes-2.0.0.dev12}/README.md

@@ -24,7 +24,7 @@ uv add "chtypes>=2.0.0.dev0"            # or: pip install "chtypes>=2.0.0.dev0"
 
 ```python
 import chtypes
-from chtypes import Format, Registry
+from chtypes import DocFlags, Format, Registry
 
 chtypes.setup(timezone="UTC")  # once, before the first open (optional)
 registry = Registry(autofetch=True)
@@ -32,7 +32,7 @@ library = registry.for_version("26.8")  # a release line or an exact version
 
 ddl = b"CREATE TABLE t (x UInt8, ts DateTime DEFAULT now()) ENGINE = Memory"
 with library.compile_table(ddl) as schema:
-    batch = schema.rows(Format.JSON_EACH_ROW, b'{"x":256}\n')
+    batch = schema.rows(Format.JSON_EACH_ROW, b'{"x":256}\n', doc_flags=DocFlags.ALL)
 
 row = batch.rows[0]
 print(batch.outcome)  # accepted
@@ -77,7 +77,7 @@ A bad **row** is a verdict, not an exception: `outcome` becomes `Outcome.REJECTE
 
 **`ctypes` releases the GIL for the whole of a foreign call**, so calls on compiled handles run in parallel across threads. The package takes no lock around a call; it keeps a close guard per handle and one setup guard.
 
-**The INSERT column list is a keyword-only `columns`** on `schema.row`, `schema.rows` and `schema.parse_block`: `schema.row(Format.JSON_EACH_ROW, body, columns=["id", "e"])`. `None` or an empty sequence is the no-list shape; 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 INSERT column list is a keyword-only `columns`** on `schema.row`, `schema.rows`, `schema.parse_block` and `filter.rows`: `schema.row(Format.JSON_EACH_ROW, body, columns=["id", "e"])`. `None` or an empty sequence is the no-list shape; 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.
 
 **Known gaps in 1.0** are listed, with workarounds, in [`docs/limitations.md`](https://github.com/wave-rf/chtypes/blob/main/docs/limitations.md#known-gaps-in-10).
 

{chtypes-2.0.0.dev10 → chtypes-2.0.0.dev12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "chtypes"
-version = "2.0.0.dev10"
+version = "2.0.0.dev12"
 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-2.0.0.dev10 → chtypes-2.0.0.dev12}/src/chtypes/__init__.py

@@ -13,14 +13,15 @@ C ABI. Nothing here reimplements a coercion rule, which is why the answers are
 exact by construction rather than approximately right.
 
     import chtypes
-    from chtypes import Format, Registry
+    from chtypes import DocFlags, Format, Registry
 
     chtypes.setup(timezone="UTC")                # once, before the first open
     registry = Registry(autofetch=True)
     library = registry.for_version("26.8")       # a release line or an exact version
     ddl = b"CREATE TABLE t (ts DateTime, seq UInt8) ENGINE = Memory"
     with library.compile_table(ddl) as schema:
-        batch = schema.rows(Format.JSON_EACH_ROW, b'{"ts":"2026-01-15 10:30:00","seq":256}\\n')
+        body = b'{"ts":"2026-01-15 10:30:00","seq":256}\\n'
+        batch = schema.rows(Format.JSON_EACH_ROW, body, doc_flags=DocFlags.ALL)
 
     batch.outcome        # Outcome.ACCEPTED: the insert would succeed
     batch.transformed    # the changes ClickHouse makes and reports as success
@@ -47,22 +48,34 @@ from importlib.metadata import PackageNotFoundError as _PackageNotFound
 from importlib.metadata import version as _package_version
 
 from ._abi2._vocab import (
+    CODE_DECLINED,
     EXPORT_NONE,
     DeclinedLayer,
     DeclinedTier,
     DefaultKind,
+    DefaultSupport,
     DiscoverQueryParam,
     DocFlags,
     FilterOutcome,
     Format,
     MergeReason,
     Outcome,
+    Posture,
     Reason,
+    RefusalSite,
     Source,
     Status,
     Verdict,
 )
-from ._input import BytesIn, ServerProfile, Settings
+from ._input import (
+    BytesIn,
+    ColumnDefault,
+    DeferDefaults,
+    ParamEncoding,
+    ServerProfile,
+    Settings,
+    VerdictBasis,
+)
 from ._setup import setup
 from .errors import (
     CODE_ARTIFACT_CORRUPT,
@@ -143,6 +156,7 @@ __all__ = [
     "CODE_SOURCE_RETIRED",
     "CODE_SOURCE_UNAUTHORIZED",
     "CODE_SOURCE_UNREACHABLE",
+    "CODE_DECLINED",
     "EXPORT_NONE",
     "Advisory",
     "ArtifactCorruptError",
@@ -163,11 +177,14 @@ __all__ = [
     "Capabilities",
     "ChtypesError",
     "Column",
+    "ColumnDefault",
     "Computed",
     "DeclinedLayer",
     "DeclinedSetting",
     "DeclinedTier",
+    "DeferDefaults",
     "DefaultKind",
+    "DefaultSupport",
     "DiscoverQueryParam",
     "DiscoveredColumn",
     "Discovery",
@@ -187,8 +204,11 @@ __all__ = [
     "Library",
     "MergeReason",
     "Outcome",
+    "ParamEncoding",
+    "Posture",
     "Reason",
     "Registry",
+    "RefusalSite",
     "Resolved",
     "Revocation",
     "RowResult",
@@ -213,6 +233,7 @@ __all__ = [
     "UsageError",
     "Value",
     "Verdict",
+    "VerdictBasis",
     "cache_root",
     "open_unverified",
     "search_dirs",

{chtypes-2.0.0.dev10 → chtypes-2.0.0.dev12}/src/chtypes/_abi2/_decls.py

@@ -1,4 +1,4 @@
-# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:d60a681ea0e249ab9e2c83b50640ad9cef040261ddf61805106c93e2c68774e4) — DO NOT EDIT  # noqa: E501
+# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:d53239933966e15a3c363e631a94fbba1231d84c4300337115d3ae5377bb41c2) — DO NOT EDIT  # noqa: E501
 """The Python binding's generated ABI v2 layer: ctypes signatures, the handle
 classes, the two-phase resolve functions and invoke_by_name(), the test-only
 dispatcher the conformance suite drives from tests/fixtures/abi-v2/cases.json.
@@ -19,7 +19,7 @@ from dataclasses import dataclass, field
 from . import _errmap
 
 CHS_ABI_VERSION = 2
-CHS_ABI_FINGERPRINT = "sha256:d60a681ea0e249ab9e2c83b50640ad9cef040261ddf61805106c93e2c68774e4"
+CHS_ABI_FINGERPRINT = "sha256:d53239933966e15a3c363e631a94fbba1231d84c4300337115d3ae5377bb41c2"
 
 # The description's stability: "unstable" while this generation is being
 # designed, so CHS_ABI_FINGERPRINT moves with every change, and "locked" after
@@ -87,6 +87,7 @@ ALL_SYMBOLS: tuple[str, ...] = (
     "chs_error_column",
     "chs_error_free",
     "chs_error_message",
+    "chs_error_reason",
     "chs_error_status",
     "chs_filter_create",
     "chs_filter_eval_block",
@@ -248,6 +249,7 @@ _add("chs_error_ch_code", "scalar", "int32", _P("error", "handle", "chs_error"))
 _add("chs_error_ch_name", "handle", "chs_buf", _P("error", "handle", "chs_error"))
 _add("chs_error_message", "handle", "chs_buf", _P("error", "handle", "chs_error"))
 _add("chs_error_column", "handle", "chs_buf", _P("error", "handle", "chs_error"))
+_add("chs_error_reason", "handle", "chs_buf", _P("error", "handle", "chs_error"))
 _add("chs_error_free", "void", None, _P("error", "handle", "chs_error", nullable=True))
 _add(
     "chs_live_handles",
@@ -371,6 +373,7 @@ _add(
     _P("body", "bytes_in", None),
     _P("settings", "bytes_in", None),
     _P("columns", "bytes_in", None),
+    _P("options", "bytes_in", None),
     _P("out", "out_handle", "chs_buf"),
     _P("err", "out_error", "chs_error", nullable=True),
 )
@@ -386,6 +389,7 @@ _add(
     _P("filter", "handle", "chs_filter", nullable=True),
     _P("export_format", "scalar", "int32"),
     _P("doc_flags", "scalar", "uint32"),
+    _P("options", "bytes_in", None),
     _P("out", "out_handle", "chs_buf"),
     _P("out_export", "out_handle", "chs_buf", nullable=True),
     _P("err", "out_error", "chs_error", nullable=True),
@@ -398,6 +402,7 @@ _add(
     _P("expr", "bytes_in", None),
     _P("query_params", "bytes_in", None),
     _P("settings", "bytes_in", None),
+    _P("options", "bytes_in", None),
     _P("out", "out_handle", "chs_filter"),
     _P("err", "out_error", "chs_error", nullable=True),
 )
@@ -410,6 +415,8 @@ _add(
     _P("format", "enum", "chs_format"),
     _P("body", "bytes_in", None),
     _P("settings", "bytes_in", None),
+    _P("columns", "bytes_in", None),
+    _P("options", "bytes_in", None),
     _P("out", "out_handle", "chs_buf"),
     _P("err", "out_error", "chs_error", nullable=True),
 )
@@ -422,6 +429,7 @@ _add(
     _P("body", "bytes_in", None),
     _P("settings", "bytes_in", None),
     _P("columns", "bytes_in", None),
+    _P("options", "bytes_in", None),
     _P("out", "out_handle", "chs_block"),
     _P("err", "out_error", "chs_error", nullable=True),
 )
@@ -563,6 +571,7 @@ class Api:
             info.ch_name.decode("ascii", "replace") if info else "",
             message,
             info.column if info else b"",
+            reason=info.reason.decode("ascii", "replace") if info else "",
         )
 
     def live_handles(self) -> bytes:
@@ -801,6 +810,7 @@ class Api:
         body: bytes | None,
         settings: bytes | None,
         columns: bytes | None,
+        options: bytes | None,
     ) -> bytes:
         """The generated call wrapper for chs_preview_row (thread class shared).
 
@@ -813,6 +823,7 @@ class Api:
             *_bytes_in(body),
             *_bytes_in(settings),
             *_bytes_in(columns),
+            *_bytes_in(options),
             ctypes.byref(out),
             ctypes.byref(err),
         )
@@ -829,6 +840,7 @@ class Api:
         filter: FilterHandle | None,
         export_format: int,
         doc_flags: int,
+        options: bytes | None,
     ) -> tuple[bytes, bytes | None]:
         """The generated call wrapper for chs_preview_batch (thread class shared).
 
@@ -845,6 +857,7 @@ class Api:
             None if filter is None else filter.value,
             int(export_format),
             int(doc_flags),
+            *_bytes_in(options),
             ctypes.byref(out),
             ctypes.byref(out_export),
             ctypes.byref(err),
@@ -861,6 +874,7 @@ class Api:
         expr: bytes | None,
         query_params: bytes | None,
         settings: bytes | None,
+        options: bytes | None,
     ) -> FilterHandle:
         """The generated call wrapper for chs_filter_create (thread class shared).
 
@@ -872,6 +886,7 @@ class Api:
             *_bytes_in(expr),
             *_bytes_in(query_params),
             *_bytes_in(settings),
+            *_bytes_in(options),
             ctypes.byref(out),
             ctypes.byref(err),
         )
@@ -884,6 +899,8 @@ class Api:
         format: int,
         body: bytes | None,
         settings: bytes | None,
+        columns: bytes | None,
+        options: bytes | None,
     ) -> bytes:
         """The generated call wrapper for chs_filter_eval_body (thread class shared).
 
@@ -895,6 +912,8 @@ class Api:
             int(format),
             *_bytes_in(body),
             *_bytes_in(settings),
+            *_bytes_in(columns),
+            *_bytes_in(options),
             ctypes.byref(out),
             ctypes.byref(err),
         )
@@ -908,6 +927,7 @@ class Api:
         body: bytes | None,
         settings: bytes | None,
         columns: bytes | None,
+        options: bytes | None,
     ) -> BlockHandle:
         """The generated call wrapper for chs_block_create (thread class shared).
 
@@ -920,6 +940,7 @@ class Api:
             *_bytes_in(body),
             *_bytes_in(settings),
             *_bytes_in(columns),
+            *_bytes_in(options),
             ctypes.byref(out),
             ctypes.byref(err),
         )
@@ -1007,6 +1028,7 @@ class ErrorInfo:
     ch_name: bytes
     message: bytes
     column: bytes
+    reason: bytes = b""
 
 
 @dataclass
@@ -1068,6 +1090,7 @@ def _decode_error(api: Api, err_ptr: int) -> ErrorInfo:
     ch_name = _read_buf(api, api._raw["chs_error_ch_name"](err_ptr))
     message = _read_buf(api, api._raw["chs_error_message"](err_ptr))
     column = _read_buf(api, api._raw["chs_error_column"](err_ptr))
+    reason = _read_buf(api, api._raw["chs_error_reason"](err_ptr))
     api._raw["chs_error_free"](err_ptr)
     return ErrorInfo(
         status=STATUS_BY_VALUE.get(status_val, f"UNKNOWN:{status_val}"),
@@ -1075,6 +1098,7 @@ def _decode_error(api: Api, err_ptr: int) -> ErrorInfo:
         ch_name=ch_name,
         message=message,
         column=column,
+        reason=reason,
     )
 
 

{chtypes-2.0.0.dev10 → chtypes-2.0.0.dev12}/src/chtypes/_abi2/_errmap.py

@@ -1,4 +1,4 @@
-# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:d60a681ea0e249ab9e2c83b50640ad9cef040261ddf61805106c93e2c68774e4) — DO NOT EDIT  # noqa: E501
+# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:d53239933966e15a3c363e631a94fbba1231d84c4300337115d3ae5377bb41c2) — DO NOT EDIT  # noqa: E501
 """spec/abi-v2/sdk.json's error-mapping tables, as references to the
 public classes (python/src/chtypes/errors.py, re-exported by
 python/src/chtypes/_abi2/_errors.py). Only the MAPPING is generated: the

{chtypes-2.0.0.dev10 → chtypes-2.0.0.dev12}/src/chtypes/_abi2/_vocab.py

@@ -1,4 +1,4 @@
-# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:d60a681ea0e249ab9e2c83b50640ad9cef040261ddf61805106c93e2c68774e4) — DO NOT EDIT  # noqa: E501
+# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:d53239933966e15a3c363e631a94fbba1231d84c4300337115d3ae5377bb41c2) — DO NOT EDIT  # noqa: E501
 """The Python binding's generated vocabularies, from spec/abi-v2/abi.json: the C
 enums (`Format`, `Status`), the document vocabularies (`Outcome`, `FilterOutcome`,
 `Verdict`, `DefaultKind`, `MergeReason`, `DeclinedTier`, `DeclinedLayer`, `Reason`,
@@ -256,6 +256,7 @@ class DeclinedTier(StrEnum):
     PREDICATE = "predicate"
     PREDICATE_UNFLIPPED = "predicate-unflipped"
     RESULT_CONTENT = "result-content"
+    SERVER_REFUSES = "server-refuses"
 
     @classmethod
     def _missing_(cls, value: object) -> DeclinedTier | None:
@@ -299,6 +300,83 @@ class DeclinedLayer(StrEnum):
         return cls(text)
 
 
+class Posture(StrEnum):
+    """How a schema's statement was compiled: `create`, as a server's CREATE TABLE,
+    or `load`, as a server loads the stored definition of a table it holds."""
+
+    CREATE = "create"
+    LOAD = "load"
+
+    @classmethod
+    def _missing_(cls, value: object) -> Posture | None:
+        return _unknown_str(cls, value)
+
+    @property
+    def known(self) -> bool:
+        """Whether the description lists this value: False for exactly the unknown(n)
+        member an unlisted value reads as (rule r3)."""
+        return type(self)._value2member_map_.get(self._value_) is self
+
+    @classmethod
+    def of(cls, text: str) -> Posture:
+        """Map a document's spelling. One the description does not list is kept as
+        this vocabulary's unknown(n) member, carrying it (rule r3)."""
+        return cls(text)
+
+
+class RefusalSite(StrEnum):
+    """Where a batch or filter document's refusal sits: `call` (the call, its settings or its
+    column list), `body_read` (the body outside any row: a header, the framing), `row` (one
+    row, `refused_row`) or `body_step` (a whole-body step)."""
+
+    CALL = "call"
+    BODY_READ = "body_read"
+    ROW = "row"
+    BODY_STEP = "body_step"
+
+    @classmethod
+    def _missing_(cls, value: object) -> RefusalSite | None:
+        return _unknown_str(cls, value)
+
+    @property
+    def known(self) -> bool:
+        """Whether the description lists this value: False for exactly the unknown(n)
+        member an unlisted value reads as (rule r3)."""
+        return type(self)._value2member_map_.get(self._value_) is self
+
+    @classmethod
+    def of(cls, text: str) -> RefusalSite:
+        """Map a document's spelling. One the description does not list is kept as
+        this vocabulary's unknown(n) member, carrying it (rule r3)."""
+        return cls(text)
+
+
+class DefaultSupport(StrEnum):
+    """What this build does with a column's DEFAULT, as `schema_description` reports it per
+    column: `computed`, `generated`, `deferred` or `declined` (with a reason)."""
+
+    COMPUTED = "computed"
+    GENERATED = "generated"
+    DEFERRED = "deferred"
+    DECLINED = "declined"
+
+    @classmethod
+    def _missing_(cls, value: object) -> DefaultSupport | None:
+        return _unknown_str(cls, value)
+
+    @property
+    def known(self) -> bool:
+        """Whether the description lists this value: False for exactly the unknown(n)
+        member an unlisted value reads as (rule r3)."""
+        return type(self)._value2member_map_.get(self._value_) is self
+
+    @classmethod
+    def of(cls, text: str) -> DefaultSupport:
+        """Map a document's spelling. One the description does not list is kept as
+        this vocabulary's unknown(n) member, carrying it (rule r3)."""
+        return cls(text)
+
+
 class DiscoverQueryParam(StrEnum):
     """A query parameter of the SQL `discover_query` returns, which the caller binds
     when it runs the query."""
@@ -409,6 +487,8 @@ class Source:
     DEFAULT_EXPR_UNSUPPORTED: Final = "default_expr_unsupported"
     DEFAULT_VOLATILE_UNRESOLVED: Final = "default_volatile_unresolved"
     DEFAULT_PENDING: Final = "default_pending"
+    DEFAULT_DEFERRED: Final = "default_deferred"
+    DEFAULT_OVERRIDE: Final = "default_override"
 
     @staticmethod
     def known(source: str) -> bool:
@@ -417,9 +497,8 @@ class Source:
 
     @staticmethod
     def is_stored(source: str) -> bool:
-        """The description's `is_stored` fact for `source`. The description does not yet
-        say what an unknown(n) source reports (rule r3, "Facts without a fallback");
-        until it does, an unlisted source is not stored."""
+        """The description's `is_stored` fact for `source`; an unknown(n) source
+        reports its fallback's (`skipped`), as rule r3 says."""
         return _SOURCE_IS_STORED.get(source, False)
 
 
@@ -435,6 +514,8 @@ _SOURCE_IS_STORED: Final[dict[str, bool]] = {
     "default_expr_unsupported": False,
     "default_volatile_unresolved": False,
     "default_pending": False,
+    "default_deferred": False,
+    "default_override": True,
 }
 
 
@@ -450,6 +531,10 @@ class DocFlags(IntFlag):
 # `chs_preview_batch`'s `export_format` for no export (`CHS_EXPORT_NONE`).
 EXPORT_NONE: Final = -1
 
+# The code a declined row, outcome or verdict carries (`CHS_CODE_DECLINED`), outside
+# ClickHouse's code table.
+CODE_DECLINED: Final = -2
+
 # Every enum the description defines, by its own name, and the Python type that
 # spells it: rule r3's tests reach every one from here, so a new enum is covered
 # without a hand-kept list.
@@ -463,10 +548,13 @@ DESCRIBED_VOCABULARIES: Final[dict[str, type]] = {
     "batch_outcome": Outcome,
     "filter_outcome": FilterOutcome,
     "filter_verdict": Verdict,
+    "refusal_site": RefusalSite,
     "discover_query_param": DiscoverQueryParam,
     "default_kind": DefaultKind,
+    "default_support": DefaultSupport,
     "declined_tier": DeclinedTier,
     "declined_layer": DeclinedLayer,
+    "posture": Posture,
 }