chtypes 1.1.0__tar.gz → 2.0.0.dev0__tar.gz

{chtypes-1.1.0 → chtypes-2.0.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: chtypes
-Version: 1.1.0
+Version: 2.0.0.dev0
 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
@@ -19,6 +19,8 @@ Description-Content-Type: text/markdown
 
 # chtypes — Python SDK
 
+> **2.0.0-dev: UNSTABLE, staging only, not for production.** This is the ABI v2 development binding (public issue #511). It speaks ABI v2's unstable description, pins its dev fingerprint and refuses a library with any other ("update your dev SDK"). It fetches only from the staging dev channel (`https://registry-staging.wavehouse.dev/chtypes/v2-dev`) and trusts only the staging key; `CHTYPES_ARTIFACTS_URL`, `CHTYPES_TRUSTED_KEYS` and `CHTYPES_ALLOW_UNSIGNED`, and the `bases`, `trusted_keys` and `allow_unsigned` fetch options, are ignored, each with one warning; `--lock`, `--frozen` and `--update`, and the `frozen`, `lock_path`, `lock_write` and `update` options, are refused, because a dev build is replaceable and a superseded one expires after 14 days. Its cache is `${XDG_CACHE_HOME:-~/.cache}/chtypes/v2-dev`, or `<CHTYPES_CACHE>/v2-dev` under an explicit cache, which no 1.x SDK reads. Every vocabulary keeps a value it does not list as its `unknown(n)` member (`Outcome("x")`, whose `known` is `False`) instead of failing the document. The rules are r1 to r6 of [`docs/reference/abi-v2.md`](../docs/reference/abi-v2.md). For production, use the 1.x package: `pip install "chtypes<2"`.
+
 **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 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.
@@ -28,9 +30,11 @@ Pure ctypes: no compiler, no build step. The only dependency is a zstd decompres
 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
+uv add "chtypes>=2.0.0.dev0"            # or: pip install "chtypes>=2.0.0.dev0"
 ```
 
+`uv add chtypes` and `pip install chtypes` never select a pre-release on their own: the specifier names a dev version, which is what allows one.
+
 ## Quickstart
 
 ```python

{chtypes-1.1.0 → chtypes-2.0.0.dev0}/README.md

@@ -1,5 +1,7 @@
 # chtypes — Python SDK
 
+> **2.0.0-dev: UNSTABLE, staging only, not for production.** This is the ABI v2 development binding (public issue #511). It speaks ABI v2's unstable description, pins its dev fingerprint and refuses a library with any other ("update your dev SDK"). It fetches only from the staging dev channel (`https://registry-staging.wavehouse.dev/chtypes/v2-dev`) and trusts only the staging key; `CHTYPES_ARTIFACTS_URL`, `CHTYPES_TRUSTED_KEYS` and `CHTYPES_ALLOW_UNSIGNED`, and the `bases`, `trusted_keys` and `allow_unsigned` fetch options, are ignored, each with one warning; `--lock`, `--frozen` and `--update`, and the `frozen`, `lock_path`, `lock_write` and `update` options, are refused, because a dev build is replaceable and a superseded one expires after 14 days. Its cache is `${XDG_CACHE_HOME:-~/.cache}/chtypes/v2-dev`, or `<CHTYPES_CACHE>/v2-dev` under an explicit cache, which no 1.x SDK reads. Every vocabulary keeps a value it does not list as its `unknown(n)` member (`Outcome("x")`, whose `known` is `False`) instead of failing the document. The rules are r1 to r6 of [`docs/reference/abi-v2.md`](../docs/reference/abi-v2.md). For production, use the 1.x package: `pip install "chtypes<2"`.
+
 **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 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.
@@ -9,9 +11,11 @@ Pure ctypes: no compiler, no build step. The only dependency is a zstd decompres
 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
+uv add "chtypes>=2.0.0.dev0"            # or: pip install "chtypes>=2.0.0.dev0"
 ```
 
+`uv add chtypes` and `pip install chtypes` never select a pre-release on their own: the specifier names a dev version, which is what allows one.
+
 ## Quickstart
 
 ```python

{chtypes-1.1.0 → chtypes-2.0.0.dev0}/pyproject.toml

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

@@ -1,5 +1,11 @@
 """chtypes: ClickHouse's own type system, per version, from Python.
 
+2.0.0-dev: UNSTABLE, staging only, not for production. This pre-release speaks
+the ABI v2 dev description (spec/abi-v2/docs.md): it fetches only from the
+staging dev channel and trusts only its key, refuses locks and frozen fetches,
+caches under its own `v2-dev` root, and refuses a library built from any other
+dev fingerprint (rules r5 and r6).
+
 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
@@ -40,9 +46,10 @@ from __future__ import annotations
 from importlib.metadata import PackageNotFoundError as _PackageNotFound
 from importlib.metadata import version as _package_version
 
-from ._abi1._vocab import (
+from ._abi2._vocab import (
     EXPORT_NONE,
     DefaultKind,
+    DiscoverQueryParam,
     DocFlags,
     FilterOutcome,
     Format,
@@ -140,6 +147,7 @@ __all__ = [
     "Column",
     "Computed",
     "DefaultKind",
+    "DiscoverQueryParam",
     "DiscoveredColumn",
     "Discovery",
     "EngineCell",

{chtypes-1.1.0 → chtypes-2.0.0.dev0}/src/chtypes/__main__.py

@@ -12,6 +12,15 @@ A spelling is `26.8`, `26.8.15` or `26.8.15.10`. Exit statuses come from the
 as `ERROR_EXIT_CODES`); a usage error exits 2 and success exits 0. Progress and
 diagnostics go to stderr; `fetch` prints one installed library path per line on
 stdout.
+
+2.0.0-dev: UNSTABLE, staging only, not for production. This CLI speaks the ABI
+v2 dev channel (spec/abi-v2/docs.md, rules r5 and r6): it fetches only from
+https://registry-staging.wavehouse.dev/chtypes/v2-dev and trusts only the
+staging key; CHTYPES_ARTIFACTS_URL, CHTYPES_TRUSTED_KEYS and
+CHTYPES_ALLOW_UNSIGNED are ignored, each with one warning; --lock, --frozen and
+--update are refused before any network call; its default cache is
+${XDG_CACHE_HOME:-~/.cache}/chtypes/v2-dev, and an explicit one (--cache,
+CHTYPES_CACHE) is used through its v2-dev subroot.
 """
 
 from __future__ import annotations
@@ -24,6 +33,7 @@ from collections.abc import Sequence
 
 from . import __version__ as chtypes_version
 from . import _ocifetch as fetch_layer
+from ._ocifetch import _channel
 from ._ocifetch import _constants as C
 from ._ocifetch._ensure import _translate_transport_error, detect_host_platform, missing_notes
 from ._ocifetch._errors import ArtifactCorruptError, ArtifactMissingError, FetchError
@@ -67,6 +77,12 @@ def build_parser() -> argparse.ArgumentParser:
     parser = _Parser(
         prog="chtypes",
         description="Fetch, verify and locate chtypes artifacts (docs/guides/fetch-v1.md).",
+        epilog=(
+            "2.0.0-dev: UNSTABLE, staging only, not for production. Fetches only from the staging "
+            "dev channel and trusts only its key; --lock, --frozen and --update are refused; "
+            "CHTYPES_ARTIFACTS_URL, CHTYPES_TRUSTED_KEYS and CHTYPES_ALLOW_UNSIGNED are ignored "
+            "(spec/abi-v2/docs.md, rule r6)."
+        ),
     )
     parser.add_argument("--version", action="version", version=f"chtypes {_display_version()}")
     sub = parser.add_subparsers(dest="command", metavar="<command>")
@@ -196,6 +212,10 @@ def _published_tags(options) -> list[str]:
 
 
 def _cmd_fetch(args: argparse.Namespace) -> int:
+    # A dev SDK pins nothing: the refusal comes before anything else, the
+    # network above all (rule r6).
+    if (args.lock or args.frozen or args.update) and not _channel.active().pinnable:
+        raise ValueError(f"chtypes: {_channel.PINNING_REFUSED}")
     if args.all and args.spellings:
         raise ValueError("chtypes: give spellings or --all, not both")
     if not args.all and not args.spellings and not args.update:

{chtypes-1.1.0/src/chtypes/_abi1 → chtypes-2.0.0.dev0/src/chtypes/_abi2}/__init__.py

@@ -1,4 +1,4 @@
-"""The ABI v1 loader and generated declaration layer (plan
+"""The ABI v2 loader and generated declaration layer (plan
 PLAN-sdk-v1-ffi-2026-10-01.md), private to this binding. Not part of `chtypes`'s
 public surface: the public API (`chtypes.library`, `chtypes.registry`) is built
 over it, and re-exports the vocabularies and errors it defines.
@@ -7,11 +7,13 @@ over it, and re-exports the vocabularies and errors it defines.
   handle classes, the typed call wrappers on `Api`, and the test-only
   `invoke_by_name()` dispatcher.
 - `_vocab`: GENERATED -- `Format`, `Status`, `Outcome`, `Verdict`, `Reason`,
-  `Source`, `DefaultKind`, `DocFlags` and the facts the description attaches.
+  `Source`, `DefaultKind`, `DiscoverQueryParam`, `DocFlags` and the facts the
+  description attaches, each vocabulary with its unknown(n) member (rule r3).
 - `_errors`: the public `chtypes.errors` classes, re-exported under the names
   `_errmap` uses.
 - `_errmap`: GENERATED -- the sdk.json status/reason -> `_errors` class maps.
-- `_loader`: hand-written -- `open()`/`open_unverified()`, the loader steps.
+- `_loader`: hand-written -- `open()`/`open_unverified()`, the loader steps,
+  and rule r6's exact refusal of another fingerprint.
 """
 
 from __future__ import annotations

{chtypes-1.1.0/src/chtypes/_abi1 → chtypes-2.0.0.dev0/src/chtypes/_abi2}/_decls.py

@@ -1,9 +1,9 @@
-# GENERATED by scripts/abi-v1/gen.py from spec/abi-v1/abi.json (CHS_ABI_FINGERPRINT sha256:856e5cb7543db291b4db716662bf6e487b2258973b959bbf5d58b4bd46d73285) — DO NOT EDIT  # noqa: E501
-"""The Python binding's generated ABI v1 layer: ctypes signatures, the handle
+# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:8ec0c6941f000aa07bfb9fbfef20205d3ee0a588833856bd12270ba42912bfb3) — 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-v1/cases.json.
+dispatcher the conformance suite drives from tests/fixtures/abi-v2/cases.json.
 See scripts/abi-v1/emit/python.py's module docstring for the design this file
-implements and why. This is the ONLY python/src/chtypes/_abi1 file that reads
+implements and why. This is the ONLY python/src/chtypes/_abi2 file that reads
 a chs_* attribute (scripts/abi-v1/check-no-hand-decls.py exempts it by its
 banner, above); every other file in this package calls the non-chs_-prefixed
 names this module exposes instead.
@@ -18,8 +18,14 @@ from dataclasses import dataclass, field
 
 from . import _errmap
 
-CHS_ABI_VERSION = 1
-CHS_ABI_FINGERPRINT = "sha256:856e5cb7543db291b4db716662bf6e487b2258973b959bbf5d58b4bd46d73285"
+CHS_ABI_VERSION = 2
+CHS_ABI_FINGERPRINT = "sha256:8ec0c6941f000aa07bfb9fbfef20205d3ee0a588833856bd12270ba42912bfb3"
+
+# The description's stability: "unstable" while this generation is being
+# designed, so CHS_ABI_FINGERPRINT moves with every change, and "locked" after
+# (spec/abi-v2/docs.md, rule r6). A dev SDK refuses any other fingerprint with
+# the dev message (_loader.py).
+CHS_ABI_STABILITY = "unstable"
 
 # sdk.json's loader.cross_check: (build_info field, predicate field, how to
 # compare), read by _loader.py's step 5 without it ever touching sdk.json
@@ -516,7 +522,7 @@ class Api:
         cls = _errmap.call_error_class(name)
         message = info.message if info else b""
         if name not in STATUS_BY_NAME:
-            message = f"status {status} is outside the closed chs_status set".encode() + (
+            message = f"call status unknown({status}) is outside the closed set".encode() + (
                 b": " + message if message else b""
             )
         raise cls(
@@ -927,7 +933,7 @@ def resolve_all(lib: ctypes.CDLL) -> Api:
     time step 6 runs, step 3 has already proven it exists). The first symbol
     ctypes cannot dlsym raises MissingSymbol(name); _loader.py's step 6 turns
     that into "missing_symbol:<name>", matching every missing-<sym> stub
-    variant (tests/fixtures/abi-v1/cases.json), chs_build_info and
+    variant (tests/fixtures/abi-v2/cases.json), chs_build_info and
     chs_clickhouse_version included -- loader step 4 needs chs_build_info
     already resolved, which is exactly why this sweep must run before it."""
     raw: dict = {}
@@ -1028,7 +1034,7 @@ def invoke_by_name(api: Api, name: str, args: Iterable[object] = ()) -> InvokeRe
     (or None, where nullable) for handle. Output parameters are never
     supplied by the caller: this dispatcher allocates them, and decodes them
     into the returned InvokeResult. Test-only: every chs_ spelling below is
-    why this file, alone in python/src/chtypes/_abi1, carries the generated
+    why this file, alone in python/src/chtypes/_abi2, carries the generated
     banner check-no-hand-decls.py exempts."""
     spec = FUNCTIONS[name]
     fn = api._raw[name]

{chtypes-1.1.0/src/chtypes/_abi1 → chtypes-2.0.0.dev0/src/chtypes/_abi2}/_errmap.py

@@ -1,7 +1,7 @@
-# GENERATED by scripts/abi-v1/gen.py from spec/abi-v1/abi.json (CHS_ABI_FINGERPRINT sha256:856e5cb7543db291b4db716662bf6e487b2258973b959bbf5d58b4bd46d73285) — DO NOT EDIT  # noqa: E501
-"""spec/abi-v1/sdk.json's error-mapping tables, as references to the
+# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:8ec0c6941f000aa07bfb9fbfef20205d3ee0a588833856bd12270ba42912bfb3) — 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/_abi1/_errors.py). Only the MAPPING is generated: the
+python/src/chtypes/_abi2/_errors.py). Only the MAPPING is generated: the
 classes themselves are stable across a regeneration (plan section 3.4), so a
 status renumbering or a new loader refusal reason changes this file, never
 the classes.

{chtypes-1.1.0/src/chtypes/_abi1 → chtypes-2.0.0.dev0/src/chtypes/_abi2}/_loader.py

@@ -1,4 +1,4 @@
-"""The ABI v1 loader, Python half (plan PLAN-sdk-v1-ffi section 3.2/3.3).
+"""The ABI v2 loader, Python half (plan PLAN-sdk-v1-ffi section 3.2/3.3).
 
 Decoupled from the fetch PRs on purpose (plan section 3.1): `open()` takes a
 small, loader-owned `predicate` mapping rather than the fetch module's
@@ -8,13 +8,13 @@ wired up; `predicate` is passed through exactly as that seam promises.
 
 Every `chs_*` spelling in this module is forbidden by
 scripts/abi-v1/check-no-hand-decls.py (it is not a generated file), so this
-calls ONLY python/src/chtypes/_abi1/_decls.py's non-`chs_`-prefixed surface:
+calls ONLY python/src/chtypes/_abi2/_decls.py's non-`chs_`-prefixed surface:
 `resolve_abi_version()`, `resolve_all()`, and the `Api` object they return.
 
 Steps 1-6 run in the order plan section 3.2 gives (with step 6's full
 resolve-all sweep run right after step 3, BEFORE step 4's
 `chs_build_info()` call -- step 4 needs that symbol already resolved, and
-`tests/fixtures/abi-v1/cases.json`'s `missing-chs_build_info` and
+`tests/fixtures/abi-v2/cases.json`'s `missing-chs_build_info` and
 `missing-chs_clickhouse_version` stub variants both expect the step 6
 `missing_symbol:<name>` reason, not a step 4 one, which is only possible if
 the full symbol sweep happens before chs_build_info is ever called). Step 7
@@ -54,6 +54,25 @@ def _refuse(reason: str, path: str, want: object = None, got: object = None) ->
     raise cls(reason=reason, path=path, want=want, got=got)
 
 
+def dev_fingerprint_message(sdk: str, library: str) -> str:
+    """Rule r6's exact refusal of a library whose fingerprint is not this dev
+    SDK's (spec/abi-v2/docs.md): `sdk` is the SDK's own fingerprint and
+    `library` the library's, both full "sha256:" spellings."""
+    return f"this SDK speaks dev fingerprint {sdk}; the library has {library} — update your dev SDK"
+
+
+def _refuse_fingerprint(path: str, got: object) -> None:
+    """Loader step 4's fingerprint refusal: CHTYPES_ARTIFACT_INCOMPATIBLE.
+    While this generation's description is unstable (a 2.0.0-dev SDK), its
+    message is exactly rule r6's; after the lock it is the ordinary refusal."""
+    want = _decls.CHS_ABI_FINGERPRINT
+    cls = _errmap.loader_error_class("fingerprint")
+    if _decls.CHS_ABI_STABILITY == "unstable":
+        message = dev_fingerprint_message(want, str(got))
+        raise cls(message, reason="fingerprint", path=path, want=want, got=got)
+    raise cls(reason="fingerprint", path=path, want=want, got=got)
+
+
 def _glibc_version() -> tuple[int, int] | None:
     """Resolve `gnu_get_libc_version` dynamically from the running process:
     `ctypes.CDLL(None)` is the process image's own global symbols (glibc's,
@@ -193,9 +212,7 @@ def _open(
     info = _parse_build_info(raw, path)
 
     if info["abi_fingerprint"] != _decls.CHS_ABI_FINGERPRINT:
-        _refuse(
-            "fingerprint", path, want=_decls.CHS_ABI_FINGERPRINT, got=info.get("abi_fingerprint")
-        )
+        _refuse_fingerprint(path, info.get("abi_fingerprint"))
 
     if not skip_step5:
         _cross_check(info, predicate, path)
@@ -231,7 +248,7 @@ def open(
     timezone: bytes = b"",
     defaults: bytes = b"",
 ) -> LoadResult:
-    """Load and verify a v1 artifact at `path` against its (already verified
+    """Load and verify an ABI v2 artifact at `path` against its (already verified
     elsewhere) signed `predicate`, then set the image zone (`timezone`, empty
     = UTC) and the default settings (`defaults`, a JSON object of string
     values, empty for none): step 7. Raises an artifact error naming the exact