chtypes 0.5.2__tar.gz → 1.0.2__tar.gz

{chtypes-0.5.2 → chtypes-1.0.2}/CHANGELOG.md

@@ -6,6 +6,46 @@ The four bindings in this repository are released together and give one answer,
 
 ## [Unreleased]
 
+## [1.0.2] — 2026-10-06
+
+There is no 1.0.1 of this binding: 1.0.1 was a Go-only fix to that module's metadata. From 1.0.2 the four bindings release together again.
+
+### Fixed
+
+- `setup` now latches only once an image completes load step 7 (#458). A zone the library refuses, such as `setup(timezone="Not/AZone")`, used to fix the process setup at the first open: every later open failed with ClickHouse's code 36, and a corrected `setup` was a `UsageError` until the process restarted. Now, if step 7 (`chs_initialize`, then `chs_set_defaults` when there are defaults) fails before any image has completed it, the setup record is cleared. That open still raises the library's own error, a corrected `setup` is accepted, and the next open runs step 7 again with it, on the same image too: a failed step 7 is never remembered (`open_unverified` and `Registry.for_version` alike). Once an image has completed step 7, a different setup is still a `UsageError`. No name or signature changes. All four bindings run the same case, `tests/fixtures/abi-v1/setup-cases.json`, and the rule is `docs/reference/bindings-v1.md` section 6.
+
+## [1.0.0] — 2026-10-04
+
+The Python binding's first v1 release, and a deliberate break from 0.x. The default branch switches to v1 shortly after release. The sections below are the entries written as each part landed; this is what they add up to.
+
+- **A new ABI.** The binding speaks the generated ABI v1 layer, identified by an ABI fingerprint in `include/chtypes.h` rather than a revision number, so every FFI declaration is generated from `spec/abi-v1/abi.json`, not written by hand. The ABI stays provisional until the maintainer confirms it.
+- **Fetch over OCI, with signed statements.** Libraries are fetched from an OCI registry and verified against a signed statement before they are loaded; the default trust is the release key only (`docs/guides/fetch-v1.md`).
+- **The public API is `docs/reference/bindings-v1.md`**, the same four-binding contract with each language's own spelling.
+- **The CLI** is `python -m chtypes` and the `chtypes` console script: `fetch`, `verify`, `list` and `where`.
+- **The v0 surface is removed**; the list, and the reason for each removal, is `docs/reference/bindings-v1.md` section 7.
+- **Known gaps** are listed in [`docs/limitations.md`](../docs/limitations.md#known-gaps-in-10), and support for a line this release does not mention is "support unknown", never "unsupported".
+
+### Changed (v1, breaking)
+
+- **The public API is the one in `docs/reference/bindings-v1.md`, over the generated ABI v1 layer and the OCI fetch layer.** `setup(timezone=, defaults=)` is the one process setup; `Registry(*, fetch=, autofetch=, preload=)` is keyword-only and opens nothing at construction; `Registry.for_version`, `installed()` and `libraries()` replace the directory-scanning registry; `Library.compile_table` (exactly one `CREATE TABLE`) replaces `compile_ddl`; `open_unverified(path, allow=)` replaces `Load`.
+- **Names, SQL, messages and renderings are `bytes`.** Result types are one-to-one decodes of the library's documents (`RowResult.columns` is every entry, `values` the stored subset by the description's own `is_stored` fact), and every vocabulary (`Format`, `Outcome`, `Verdict`, `Reason`, `Source`, `DefaultKind`, `DocFlags`) is generated from the ABI description.
+- **One error family.** `CallError` (under `ChtypesError`) carries `status`, `ch_code`, `ch_name`, `message` and `column`; `SchemaError`, `UnsupportedError`, `UsageError` and `InternalError` are peers. Fetch and loader errors are `ArtifactError` subclasses, one class per code.
+- **Each `Schema`, `Filter` and `Block` has a close guard**: `close` waits for calls already inside the object, and a call after close is a `UsageError` raised before any C call. No lock is taken around a call.
+
+- **`python -m chtypes` and the `chtypes` console script are back, over the v1 fetch layer**: `fetch <spelling>... | --all [--lock FILE] [--frozen] [--offline]`, `verify`, `list [--offline]` and `where`. Exit statuses are the `errors` table of `spec/fetch-v1/constants.json`, usage errors exit 2.
+- **`FetchOptions.system_dirs`** names the read-only directories searched after the cache (`None` keeps the default list, an empty sequence searches none), and `FetchOptions.to_options` is private. `CHTYPES_TRUSTED_KEYS` (comma-separated hex public keys) replaces the default trust list when set, as `docs/guides/fetch-v1.md` §4 says.
+
+### Removed (v1)
+
+- `compile_ddl`, the engine, TTL and partition-key setters, `encode_settings`, the transform classifier, discovery reconstruction, the hand JSON readers, `quote_bare_denormals`, the hand error-code table parser, the manifest and revision machinery, the v0 fetch module and its `python -m chtypes` command line, `ABI_REVISION`, `COMPILE_DECLARED`, `Registry.shutdown`, `Library.close` and the `Registry` context manager.
+
+### Fixed
+
+- **The crash-guard refuse-list is now sourced identically to the other three bindings, and an artifact with neither source refuses rather than loading unguarded.** This binding already fell back to the manifest's `unsafe_families` field when `unsafe_families.txt` was absent, but a manifest predating the field (or one that simply omitted it) was indistinguishable from a present, empty field, so `chs_init` silently ran with no refuse-list. `Manifest.unsafe_families` is now `None` when the field is absent rather than defaulting to `""`, and a directory with neither the file nor the field is refused, naming both, instead of loading unguarded (`docs/reference/artifact.md` step 9).
+- **`ensure`/`fetch` now retry a transient HTTP 5xx, 408 or 429 from the artifacts host, and a connection-level failure (refused, reset, timed out, DNS), within the existing retry budget and schedule** (`docs/guides/fetch.md` §3a: 5 attempts, delays doubling from 4s) — previously `_Source._open`/`download` ran their own separate, shorter retry (3 attempts, incrementing by whole seconds) before giving up, independent of the publish-window budget, and a 408 was never retried at all. A `Retry-After` on a 503 or 429 is honored, in both the delta-seconds and HTTP-date forms, capped so it never makes the total wait exceed the existing budget — one that does not fit fails at once, naming the requested delay. A 404 or 410, and a tarball hash or size mismatch, are still decided on the first attempt, never retried. `SourceUnreachableError` gains `.retryable`/`.retry_after` attributes (closes #365).
+- **`fetch`/`ensure` now send `CHTYPES_DOWNLOAD_TOKEN` as a bearer token** to an HTTP source, matching the other three bindings and `scripts/fetch.sh` — found missing during the #365 audit.
+- **A `Filter` or `Block` held in a reference cycle with its `Schema` could be freed AFTER the schema**, a use-after-free the C contract forbids (handle lifetime, §Filters/§Blocks). `Schema` tracked open children through a `weakref.WeakSet`, and CPython clears a `WeakSet`'s membership before running `Schema.__del__` when the schema and a child die together in one `gc.collect()`, so the safety net saw the set already empty and freed the schema handle first. `Schema`/`Filter`/`Block` now coordinate through a small native-half object per handle — the shape TypeScript has used since #334 — and the safety net is a `weakref.finalize` callback bound only to that native half, never `__del__`, so it holds no reference back to the Schema/Filter/Block and runs correctly regardless of a reference cycle or which object's finalizer the collector happens to run first (#381).
+
 ## [0.5.2] — 2026-10-01
 
 ### Added

{chtypes-0.5.2 → chtypes-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: chtypes
-Version: 0.5.2
+Version: 1.0.2
 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
@@ -14,54 +14,56 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Database
 Requires-Python: >=3.11
+Requires-Dist: backports-zstd>=1.7; python_version < '3.14'
 Description-Content-Type: text/markdown
 
 # chtypes — Python SDK
 
 **If this row were inserted into this table on this ClickHouse version, what would happen?** chtypes answers with ClickHouse's own code: the real C++ type machinery, vendored per release into a native library behind the frozen `chs_*` C ABI and reached here through stdlib `ctypes`. Nothing semantic is reimplemented, so _"what does ClickHouse do with `256` into a `UInt8`?"_ is answered by ClickHouse rather than by a model of it. One peer binding among `{go, python, ts, rust}` — no language is privileged, and all four give one answer.
 
-Pure Python: **zero dependencies, no build step, no compiler.**
+Pure ctypes: no compiler, no build step. The only dependency is a zstd decompressor for the artifact layer, which is the standard library's own from Python 3.14 and the `backports.zstd` package before that.
 
 ## Install
 
-Two things: this package, and at least one **artifact** — the per-version native library it `dlopen`s at runtime.
+Two things: this package, and at least one **artifact** — the per-version native library it `dlopen`s at runtime. The registry fetches the artifact on first use when autofetch is on (`Registry(autofetch=True)` or `CHTYPES_AUTOFETCH=1`), after verifying its signature and every byte against the signed statement; with autofetch off it answers only from what is already installed.
 
 ```sh
 uv add chtypes            # or: pip install chtypes
-python -m chtypes fetch 26.8
 ```
 
-The fetch lands in `~/.cache/chtypes/artifacts/abi<R>/<os>-<arch>/26.8/` — the per-user cache every chtypes binding reads by default, `<R>` the ABI revision this SDK speaks (fetch installs only artifacts built at it) — after checking an ed25519 signature over the release and the sha256 of every byte. `$CHTYPES_REGISTRY` overrides it. The ed25519 verifier is pure stdlib too.
-
 ## Quickstart
 
 ```python
+import chtypes
 from chtypes import Format, Registry
 
-registry = Registry()                   # walks the search path
-library = registry.for_version("26.8")  # a line or an exact patch; never a nearest match
+chtypes.setup(timezone="UTC")             # once, before the first open (optional)
+registry = Registry(autofetch=True)
+library = registry.for_version("26.8")    # a release line or an exact version
 
-with library.compile_ddl("x UInt8, ts DateTime DEFAULT now()") as schema:
+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')
 
 row = batch.rows[0]
-print(batch.outcome)              # accepted
-print(row.value("x").text)        # 0             — what would actually be stored
-print(row.transformed[0].reason)  # overflow_wrap — which is the product
-print(row.substituted)            # ts: send it explicitly, or preview != stored
+print(batch.outcome)                  # accepted
+print(row.values[0].text)             # b'0'          what would actually be stored
+print(row.transformed[0].reason)      # overflow_wrap which is the product
 ```
 
-The row is **accepted** and `256` is silently stored as `0`. That report — `transformed` — is the one derived answer in the system and the reason it exists.
+The row is **accepted** and `256` is silently stored as `0`. That report — `transformed` — is why chtypes exists. Names, SQL, messages and renderings come back as `bytes`, never decoded for you: a column name that is not valid UTF-8 round-trips exactly.
 
-`ts` was substituted rather than stored: send every substituted column as an explicit value in the real INSERT, or the server re-evaluates `now()` at its own instant and your preview is not what landed. Pin the instant in tests with `settings={"chtypes_now_epoch_nanos": "1700000000000000000"}`.
+A column whose DEFAULT calls a random or UUID generator is drawn by the library (`Source.DEFAULT_GENERATED`). Ask `rows` for an `export` and insert its `payload`, never the original body, or the server draws a different value than the one previewed.
 
-## Three outcomes, and conflating any two is a bug
+## Errors
 
-A bad **row** is a verdict, not an exception: `outcome` becomes `Outcome.REJECTED` with ClickHouse's own code. Exceptions are for schema-level answers and for the machinery.
+A bad **row** is a verdict, not an exception: `outcome` becomes `Outcome.REJECTED` with ClickHouse's own code. Exceptions are for the call and for the machinery. Every call error carries `status`, `ch_code`, `ch_name`, `message` (bytes) and `column` (bytes).
 
-- `SchemaError` — the server itself would refuse this, and `.code` is a real ClickHouse code.
+- `SchemaError` — the server itself would refuse this, and `.ch_code` is a real ClickHouse code.
 - `UnsupportedError` — this build declines to answer, and a real server might well have accepted. **Fall back to the server**; never tell a user they are wrong on the strength of a decline.
-- **`UnsupportedError` is a peer of `SchemaError`, not a subclass.** `except SchemaError` never catches a decline. Handle the two arms explicitly, or catch `ChtypesError` for both.
+- `UsageError` — a misuse: a closed object, a conflicting `setup`, a zone given twice. `InternalError` — a library bug.
+- **`UnsupportedError` is a peer of `SchemaError`, not a subclass**, so `except SchemaError` never catches a decline. Catch `CallError` for all four, deliberately.
+- `ArtifactError` and its subclasses cover fetching and loading: `ArtifactCorruptError`, `ArtifactIncompatibleError`, `ArtifactMissingError` and the rest, one class per code.
 
 ## Documentation
 
@@ -76,15 +78,19 @@ A bad **row** is a verdict, not an exception: `outcome` becomes `Outcome.REJECTE
 | [Filters](https://github.com/wave-rf/chtypes/blob/main/docs/guides/filters.md) · [Multi-version](https://github.com/wave-rf/chtypes/blob/main/docs/guides/multi-version.md) | boolean expressions over rows; several ClickHouse versions in one process    |
 | [Support matrix](https://github.com/wave-rf/chtypes/blob/main/docs/support.md) · [Limitations](https://github.com/wave-rf/chtypes/blob/main/docs/limitations.md)            | what works where; what chtypes declines to answer                            |
 
-## Four things specific to this binding
+## Fetching from the command line
+
+`chtypes fetch 26.8` (or `python -m chtypes fetch 26.8`) resolves, verifies and installs a build into the per-user cache; `chtypes verify`, `chtypes list` and `chtypes where` complete the four commands. `--lock FILE` records what was installed and `--frozen` fetches only what the lock pins. See the [Python API reference](https://github.com/wave-rf/chtypes/blob/main/docs/reference/python.md#the-command).
+
+## Things specific to this binding
 
-**A settings value must never be a `float`.** `encode_settings` stringifies an `int` exactly and raises `TypeError` on a `float`: a 19-digit `chtypes_now_epoch_nanos` does not survive an IEEE double, and as a JSON number the setting would be silently ignored.
+**A settings value is a string, and only a string.** `settings={"flatten_nested": "0"}`, never `0`: a non-string value is a `TypeError`, and nothing rewrites one for you.
 
-**`substituted` is on `RowResult`, not on `BatchResult`.** Reach it through `batch.rows[i].substituted`. `BatchResult` does carry a batch-level `transformed`, which folds in the storage layer's own verdicts.
+**`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.
 
-**`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 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 (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.
+**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).
 
 ## Tests
 

{chtypes-0.5.2 → chtypes-1.0.2}/README.md

@@ -2,48 +2,49 @@
 
 **If this row were inserted into this table on this ClickHouse version, what would happen?** chtypes answers with ClickHouse's own code: the real C++ type machinery, vendored per release into a native library behind the frozen `chs_*` C ABI and reached here through stdlib `ctypes`. Nothing semantic is reimplemented, so _"what does ClickHouse do with `256` into a `UInt8`?"_ is answered by ClickHouse rather than by a model of it. One peer binding among `{go, python, ts, rust}` — no language is privileged, and all four give one answer.
 
-Pure Python: **zero dependencies, no build step, no compiler.**
+Pure ctypes: no compiler, no build step. The only dependency is a zstd decompressor for the artifact layer, which is the standard library's own from Python 3.14 and the `backports.zstd` package before that.
 
 ## Install
 
-Two things: this package, and at least one **artifact** — the per-version native library it `dlopen`s at runtime.
+Two things: this package, and at least one **artifact** — the per-version native library it `dlopen`s at runtime. The registry fetches the artifact on first use when autofetch is on (`Registry(autofetch=True)` or `CHTYPES_AUTOFETCH=1`), after verifying its signature and every byte against the signed statement; with autofetch off it answers only from what is already installed.
 
 ```sh
 uv add chtypes            # or: pip install chtypes
-python -m chtypes fetch 26.8
 ```
 
-The fetch lands in `~/.cache/chtypes/artifacts/abi<R>/<os>-<arch>/26.8/` — the per-user cache every chtypes binding reads by default, `<R>` the ABI revision this SDK speaks (fetch installs only artifacts built at it) — after checking an ed25519 signature over the release and the sha256 of every byte. `$CHTYPES_REGISTRY` overrides it. The ed25519 verifier is pure stdlib too.
-
 ## Quickstart
 
 ```python
+import chtypes
 from chtypes import Format, Registry
 
-registry = Registry()                   # walks the search path
-library = registry.for_version("26.8")  # a line or an exact patch; never a nearest match
+chtypes.setup(timezone="UTC")             # once, before the first open (optional)
+registry = Registry(autofetch=True)
+library = registry.for_version("26.8")    # a release line or an exact version
 
-with library.compile_ddl("x UInt8, ts DateTime DEFAULT now()") as schema:
+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')
 
 row = batch.rows[0]
-print(batch.outcome)              # accepted
-print(row.value("x").text)        # 0             — what would actually be stored
-print(row.transformed[0].reason)  # overflow_wrap — which is the product
-print(row.substituted)            # ts: send it explicitly, or preview != stored
+print(batch.outcome)                  # accepted
+print(row.values[0].text)             # b'0'          what would actually be stored
+print(row.transformed[0].reason)      # overflow_wrap which is the product
 ```
 
-The row is **accepted** and `256` is silently stored as `0`. That report — `transformed` — is the one derived answer in the system and the reason it exists.
+The row is **accepted** and `256` is silently stored as `0`. That report — `transformed` — is why chtypes exists. Names, SQL, messages and renderings come back as `bytes`, never decoded for you: a column name that is not valid UTF-8 round-trips exactly.
 
-`ts` was substituted rather than stored: send every substituted column as an explicit value in the real INSERT, or the server re-evaluates `now()` at its own instant and your preview is not what landed. Pin the instant in tests with `settings={"chtypes_now_epoch_nanos": "1700000000000000000"}`.
+A column whose DEFAULT calls a random or UUID generator is drawn by the library (`Source.DEFAULT_GENERATED`). Ask `rows` for an `export` and insert its `payload`, never the original body, or the server draws a different value than the one previewed.
 
-## Three outcomes, and conflating any two is a bug
+## Errors
 
-A bad **row** is a verdict, not an exception: `outcome` becomes `Outcome.REJECTED` with ClickHouse's own code. Exceptions are for schema-level answers and for the machinery.
+A bad **row** is a verdict, not an exception: `outcome` becomes `Outcome.REJECTED` with ClickHouse's own code. Exceptions are for the call and for the machinery. Every call error carries `status`, `ch_code`, `ch_name`, `message` (bytes) and `column` (bytes).
 
-- `SchemaError` — the server itself would refuse this, and `.code` is a real ClickHouse code.
+- `SchemaError` — the server itself would refuse this, and `.ch_code` is a real ClickHouse code.
 - `UnsupportedError` — this build declines to answer, and a real server might well have accepted. **Fall back to the server**; never tell a user they are wrong on the strength of a decline.
-- **`UnsupportedError` is a peer of `SchemaError`, not a subclass.** `except SchemaError` never catches a decline. Handle the two arms explicitly, or catch `ChtypesError` for both.
+- `UsageError` — a misuse: a closed object, a conflicting `setup`, a zone given twice. `InternalError` — a library bug.
+- **`UnsupportedError` is a peer of `SchemaError`, not a subclass**, so `except SchemaError` never catches a decline. Catch `CallError` for all four, deliberately.
+- `ArtifactError` and its subclasses cover fetching and loading: `ArtifactCorruptError`, `ArtifactIncompatibleError`, `ArtifactMissingError` and the rest, one class per code.
 
 ## Documentation
 
@@ -58,15 +59,19 @@ A bad **row** is a verdict, not an exception: `outcome` becomes `Outcome.REJECTE
 | [Filters](https://github.com/wave-rf/chtypes/blob/main/docs/guides/filters.md) · [Multi-version](https://github.com/wave-rf/chtypes/blob/main/docs/guides/multi-version.md) | boolean expressions over rows; several ClickHouse versions in one process    |
 | [Support matrix](https://github.com/wave-rf/chtypes/blob/main/docs/support.md) · [Limitations](https://github.com/wave-rf/chtypes/blob/main/docs/limitations.md)            | what works where; what chtypes declines to answer                            |
 
-## Four things specific to this binding
+## Fetching from the command line
+
+`chtypes fetch 26.8` (or `python -m chtypes fetch 26.8`) resolves, verifies and installs a build into the per-user cache; `chtypes verify`, `chtypes list` and `chtypes where` complete the four commands. `--lock FILE` records what was installed and `--frozen` fetches only what the lock pins. See the [Python API reference](https://github.com/wave-rf/chtypes/blob/main/docs/reference/python.md#the-command).
+
+## Things specific to this binding
 
-**A settings value must never be a `float`.** `encode_settings` stringifies an `int` exactly and raises `TypeError` on a `float`: a 19-digit `chtypes_now_epoch_nanos` does not survive an IEEE double, and as a JSON number the setting would be silently ignored.
+**A settings value is a string, and only a string.** `settings={"flatten_nested": "0"}`, never `0`: a non-string value is a `TypeError`, and nothing rewrites one for you.
 
-**`substituted` is on `RowResult`, not on `BatchResult`.** Reach it through `batch.rows[i].substituted`. `BatchResult` does carry a batch-level `transformed`, which folds in the storage layer's own verdicts.
+**`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.
 
-**`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 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 (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.
+**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).
 
 ## Tests
 

{chtypes-0.5.2 → chtypes-1.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "chtypes"
-version = "0.5.2"
+version = "1.0.2"
 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"
@@ -13,15 +13,15 @@ classifiers = [
     "Programming Language :: Python :: 3",
     "Topic :: Database",
 ]
-# Zero runtime dependencies, on purpose. The binding is stdlib `ctypes` over the
-# artifact's C ABI, so installing it needs no compiler, no cffi build step and
-# no wheel per Python version — the native code already exists as a prebuilt
-# artifact and is dlopen'd at runtime. See README "Why ctypes".
-dependencies = []
-
-# `chtypes fetch 25.8` — the same surface as `python -m chtypes` (docs/guides/fetch.md §6).
-[project.scripts]
-chtypes = "chtypes.__main__:main"
+# Zero runtime dependencies was the rule through v0: the binding is stdlib
+# `ctypes` over the artifact's C ABI, so installing it needs no compiler, no
+# cffi build step and no wheel per Python version. v1's artifacts are zstd
+# (docs/guides/fetch-v1.md "Bytes"), and CPython's own `compression.zstd`
+# only exists from 3.14 (PEP 784); this binding's floor is 3.11, so 3.11-3.13
+# need a backport of the same stdlib-shaped API. 3.14+ needs nothing extra —
+# the marker below excludes it, so a 3.14 install still carries zero
+# dependencies. See README "Why ctypes".
+dependencies = ["backports.zstd>=1.7; python_version < '3.14'"]
 
 [project.urls]
 Homepage = "https://github.com/wave-rf/chtypes"
@@ -29,6 +29,9 @@ Repository = "https://github.com/wave-rf/chtypes"
 Documentation = "https://github.com/wave-rf/chtypes/blob/main/python/README.md"
 Changelog = "https://github.com/wave-rf/chtypes/releases"
 
+[project.scripts]
+chtypes = "chtypes.__main__:main"
+
 [dependency-groups]
 dev = [
     "pytest>=8.0",
@@ -39,6 +42,12 @@ dev = [
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.build]
+# Two v0 verification modules stay in the tree, unimported, so the security
+# carve-out in scripts/policy-merge-check.py keeps covering them until their
+# deletion is decided; they are not part of v1 and never ship.
+exclude = ["/src/chtypes/fetch.py", "/src/chtypes/_manifest.py"]
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/chtypes"]
 

chtypes-1.0.2/src/chtypes/__init__.py

@@ -0,0 +1,187 @@
+"""chtypes: ClickHouse's own type system, per version, from Python.
+
+One question, exactly: *if this row were inserted into this ClickHouse table on
+this ClickHouse version, what would happen?* The answer comes from ClickHouse's
+real C++ machinery, vendored per release into a shared library behind the frozen
+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
+
+    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')
+
+    batch.outcome        # Outcome.ACCEPTED: the insert would succeed
+    batch.transformed    # the changes ClickHouse makes and reports as success
+
+The specification is docs/reference/bindings-v1.md. Names, SQL, messages and
+renderings come back as `bytes`: a name that is not valid UTF-8 round-trips
+exactly, and nothing here decodes one for you.
+
+Three things a caller must not skip:
+
+* **`transformed` is the product.** ClickHouse returns success for every one of
+  those changes. Reading `outcome` alone says a row was accepted and nothing
+  about the value the table will hold.
+* **`Outcome.UNSUPPORTED` is not a rejection.** It means a real server might well
+  have accepted this and this build declines to answer.
+* **Insert the library's output, not your input**, when a row carries a
+  `Source.DEFAULT_GENERATED` column: ask `rows` for an `export` and insert its
+  `payload`.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError as _PackageNotFound
+from importlib.metadata import version as _package_version
+
+from ._abi1._vocab import (
+    EXPORT_NONE,
+    DefaultKind,
+    DocFlags,
+    FilterOutcome,
+    Format,
+    Outcome,
+    Reason,
+    Source,
+    Status,
+    Verdict,
+)
+from ._input import BytesIn, Settings
+from ._setup import setup
+from .errors import (
+    CODE_ARTIFACT_CORRUPT,
+    CODE_ARTIFACT_INCOMPATIBLE,
+    CODE_ARTIFACT_MISSING,
+    CODE_ARTIFACT_PINNED,
+    CODE_ARTIFACT_UNPUBLISHED,
+    CODE_ARTIFACT_UNTRUSTED,
+    CODE_SOURCE_FORBIDDEN,
+    CODE_SOURCE_INCOMPATIBLE,
+    CODE_SOURCE_UNAUTHORIZED,
+    CODE_SOURCE_UNREACHABLE,
+    ArtifactCorruptError,
+    ArtifactError,
+    ArtifactIncompatibleError,
+    ArtifactMissingError,
+    ArtifactPinnedError,
+    ArtifactUnpublishedError,
+    ArtifactUntrustedError,
+    CallError,
+    ChtypesError,
+    InternalError,
+    SchemaError,
+    SourceForbiddenError,
+    SourceIncompatibleError,
+    SourceUnauthorizedError,
+    SourceUnreachableError,
+    UnsupportedError,
+    UsageError,
+)
+from .library import Block, Filter, Library, Schema, open_unverified
+from .registry import FetchOptions, Registry, Resolved, TrustedKey
+from .results import (
+    BatchResult,
+    BuildInfo,
+    Capabilities,
+    Column,
+    Computed,
+    DiscoveredColumn,
+    Discovery,
+    EngineCell,
+    ErrorCodeEntry,
+    ErrorCodeTable,
+    FilterResult,
+    FilterRowError,
+    Framing,
+    Header,
+    RowResult,
+    SchemaDescription,
+    Span,
+    Transform,
+    Value,
+)
+
+__all__ = [
+    "CODE_ARTIFACT_CORRUPT",
+    "CODE_ARTIFACT_INCOMPATIBLE",
+    "CODE_ARTIFACT_MISSING",
+    "CODE_ARTIFACT_PINNED",
+    "CODE_ARTIFACT_UNPUBLISHED",
+    "CODE_ARTIFACT_UNTRUSTED",
+    "CODE_SOURCE_FORBIDDEN",
+    "CODE_SOURCE_INCOMPATIBLE",
+    "CODE_SOURCE_UNAUTHORIZED",
+    "CODE_SOURCE_UNREACHABLE",
+    "EXPORT_NONE",
+    "ArtifactCorruptError",
+    "ArtifactError",
+    "ArtifactIncompatibleError",
+    "ArtifactMissingError",
+    "ArtifactPinnedError",
+    "ArtifactUnpublishedError",
+    "ArtifactUntrustedError",
+    "BatchResult",
+    "Block",
+    "BuildInfo",
+    "BytesIn",
+    "CallError",
+    "Capabilities",
+    "ChtypesError",
+    "Column",
+    "Computed",
+    "DefaultKind",
+    "DiscoveredColumn",
+    "Discovery",
+    "EngineCell",
+    "DocFlags",
+    "ErrorCodeEntry",
+    "ErrorCodeTable",
+    "FetchOptions",
+    "Filter",
+    "FilterOutcome",
+    "FilterResult",
+    "FilterRowError",
+    "Format",
+    "Framing",
+    "Header",
+    "InternalError",
+    "Library",
+    "Outcome",
+    "Reason",
+    "Registry",
+    "Resolved",
+    "RowResult",
+    "Schema",
+    "SchemaDescription",
+    "SchemaError",
+    "Settings",
+    "Source",
+    "SourceForbiddenError",
+    "SourceIncompatibleError",
+    "SourceUnauthorizedError",
+    "SourceUnreachableError",
+    "Span",
+    "Status",
+    "Transform",
+    "TrustedKey",
+    "UnsupportedError",
+    "UsageError",
+    "Value",
+    "Verdict",
+    "open_unverified",
+    "setup",
+]
+
+# Derived, never written twice. pyproject.toml is the single source of truth and
+# the build reads it from there; asking importlib for it means this attribute
+# cannot drift from the package it names.
+try:
+    __version__ = _package_version("chtypes")
+except _PackageNotFound:  # a source tree that was never installed
+    __version__ = "0.0.0+unknown"