chtypes 2.0.0.dev0__py3-none-any.whl → 2.0.0.dev2__py3-none-any.whl

chtypes/__init__.py

@@ -59,7 +59,7 @@ from ._abi2._vocab import (
     Status,
     Verdict,
 )
-from ._input import BytesIn, Settings
+from ._input import BytesIn, ServerProfile, Settings
 from ._setup import setup
 from .errors import (
     CODE_ARTIFACT_CORRUPT,
@@ -92,8 +92,8 @@ from .errors import (
     UnsupportedError,
     UsageError,
 )
-from .library import Block, Filter, Library, Schema, open_unverified
-from .registry import FetchOptions, Registry, Resolved, TrustedKey
+from .library import Block, Filter, Library, Schema, Server, open_unverified
+from .registry import FetchOptions, Registry, Resolved, TrustedKey, cache_root, search_dirs
 from .results import (
     BatchResult,
     BuildInfo,
@@ -111,6 +111,8 @@ from .results import (
     Header,
     RowResult,
     SchemaDescription,
+    SchemaReplicated,
+    SchemaServer,
     Span,
     Transform,
     Value,
@@ -172,6 +174,10 @@ __all__ = [
     "Schema",
     "SchemaDescription",
     "SchemaError",
+    "SchemaReplicated",
+    "SchemaServer",
+    "Server",
+    "ServerProfile",
     "Settings",
     "Source",
     "SourceForbiddenError",
@@ -186,7 +192,9 @@ __all__ = [
     "UsageError",
     "Value",
     "Verdict",
+    "cache_root",
     "open_unverified",
+    "search_dirs",
     "setup",
 ]
 

chtypes/__main__.py

@@ -5,7 +5,7 @@
                                          [--frozen] [--offline] [--update] [--strict]
     chtypes verify [--cache <dir>] [--strict]   re-verify every installed build
     chtypes list   [--cache <dir>] [--offline] [--strict]
-    chtypes where  [--cache <dir>] [--strict]   the cache root
+    chtypes where  [--cache <dir>] [--strict] [--all]   the cache root; --all: every search dir
 
 A spelling is `26.8`, `26.8.15` or `26.8.15.10`. Exit statuses come from the
 `errors` table of spec/fetch-v1/constants.json (generated into the fetch layer
@@ -137,7 +137,10 @@ def build_parser() -> argparse.ArgumentParser:
     fetch.add_argument(
         "--offline",
         action="store_true",
-        help="never touch a source: installed and verified, or CHTYPES_ARTIFACT_MISSING",
+        help=(
+            "never touch a source: installed and verified, or CHTYPES_ARTIFACT_MISSING "
+            "(or set CHTYPES_OFFLINE=1)"
+        ),
     )
 
     verify = sub.add_parser(
@@ -154,11 +157,22 @@ def build_parser() -> argparse.ArgumentParser:
     )
     cache_option(listing)
     listing.add_argument(
-        "--offline", action="store_true", help="list only what is installed; no network"
+        "--offline",
+        action="store_true",
+        help="list only what is installed; no network (or set CHTYPES_OFFLINE=1)",
     )
 
-    where = sub.add_parser("where", help="the cache root", description="Print the cache root.")
+    where = sub.add_parser(
+        "where",
+        help="the cache root",
+        description="Print the cache root; with --all, every directory searched.",
+    )
     cache_option(where)
+    where.add_argument(
+        "--all",
+        action="store_true",
+        help="every directory searched, in order, the cache root first (one per line)",
+    )
     return parser
 
 
@@ -294,7 +308,7 @@ def _cmd_list(args: argparse.Namespace) -> int:
         sys.stdout.write(f"installed {r.version} {r.platform} {r.dir}\n")
     sys.stdout.flush()
     _say_notes(options)
-    if not args.offline:
+    if not options.resolved_offline():
         for tag in _published_tags(options):
             sys.stdout.write(f"published {tag} support unknown\n")
     sys.stdout.flush()
@@ -306,6 +320,10 @@ def _cmd_where(args: argparse.Namespace) -> int:
     if options.resolved_strict():
         # Strict mode checks the root before naming it.
         probe_roots(search_roots(options.cache_dir, options.system_dirs), strict=True)
+    if args.all:
+        for directory in search_roots(options.cache_dir, options.system_dirs):
+            sys.stdout.write(f"{directory}\n")
+        return EXIT_OK
     sys.stdout.write(f"{resolve_cache_root(args.cache)}\n")
     return EXIT_OK
 

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:8ec0c6941f000aa07bfb9fbfef20205d3ee0a588833856bd12270ba42912bfb3) — DO NOT EDIT  # noqa: E501
+# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:d87e91be2bbe75b985c38224268c2f7dc5d8236dab0a4b4d61357c6dfdc1a232) — 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:8ec0c6941f000aa07bfb9fbfef20205d3ee0a588833856bd12270ba42912bfb3"
+CHS_ABI_FINGERPRINT = "sha256:d87e91be2bbe75b985c38224268c2f7dc5d8236dab0a4b4d61357c6dfdc1a232"
 
 # The description's stability: "unstable" while this generation is being
 # designed, so CHS_ABI_FINGERPRINT moves with every change, and "locked" after
@@ -61,6 +61,7 @@ _STATUS_OK = 0
 HANDLE_FREE: dict[str, str] = {
     "chs_buf": "chs_buf_free",
     "chs_error": "chs_error_free",
+    "chs_server": "chs_server_free",
     "chs_schema": "chs_schema_free",
     "chs_filter": "chs_filter_free",
     "chs_block": "chs_block_free",
@@ -102,6 +103,8 @@ ALL_SYMBOLS: tuple[str, ...] = (
     "chs_schema_create",
     "chs_schema_describe",
     "chs_schema_free",
+    "chs_server_create",
+    "chs_server_free",
     "chs_set_defaults",
     "chs_shutdown",
     "chs_type_validate",
@@ -174,6 +177,10 @@ class ErrorHandle(Handle):
     """A `chs_error` the library owns the free function for."""
 
 
+class ServerHandle(Handle):
+    """A `chs_server` the library owns the free function for."""
+
+
 class SchemaHandle(Handle):
     """A `chs_schema` the library owns the free function for."""
 
@@ -189,6 +196,7 @@ class BlockHandle(Handle):
 _HANDLE_CLASS: dict[str, type[Handle]] = {
     "chs_buf": BufHandle,
     "chs_error": ErrorHandle,
+    "chs_server": ServerHandle,
     "chs_schema": SchemaHandle,
     "chs_filter": FilterHandle,
     "chs_block": BlockHandle,
@@ -324,12 +332,24 @@ _add(
     _P("out", "out_handle", "chs_buf"),
     _P("err", "out_error", "chs_error", nullable=True),
 )
+_add(
+    "chs_server_create",
+    "status",
+    "chs_status",
+    _P("profile", "bytes_in", None),
+    _P("options", "bytes_in", None),
+    _P("out", "out_handle", "chs_server"),
+    _P("err", "out_error", "chs_error", nullable=True),
+)
+_add("chs_server_free", "void", None, _P("server", "handle", "chs_server", nullable=True))
 _add(
     "chs_schema_create",
     "status",
     "chs_status",
+    _P("server", "handle", "chs_server", nullable=True),
     _P("create_table", "bytes_in", None),
     _P("settings", "bytes_in", None),
+    _P("options", "bytes_in", None),
     _P("out", "out_handle", "chs_schema"),
     _P("err", "out_error", "chs_error", nullable=True),
 )
@@ -486,6 +506,18 @@ def resolve_abi_version(lib: ctypes.CDLL) -> Callable[..., object]:
     return fn
 
 
+def resolve_build_info(lib: ctypes.CDLL) -> Callable[..., object]:
+    """Loader step 4's dlsym: `chs_build_info` ALONE, so the fingerprint can be
+    compared before step 6's full sweep (rule r6 beats a missing symbol,
+    public issue #537). Absent is MissingSymbol, the step 4 refusal."""
+    try:
+        fn = lib.chs_build_info
+    except AttributeError:
+        raise MissingSymbol("chs_build_info") from None
+    _set_signature(fn, FUNCTIONS["chs_build_info"])
+    return fn
+
+
 class Api:
     """Every described symbol, resolved and signature-typed, step 6
     (plan section 3.2). Constructed ONLY by resolve_all(): the constructor
@@ -703,19 +735,42 @@ class Api:
         self._check(status, err)
         return _read_buf(self, out.value)
 
+    def server_create(
+        self,
+        profile: bytes | None,
+        options: bytes | None,
+    ) -> ServerHandle:
+        """The generated call wrapper for chs_server_create (thread class any).
+
+        Raises the class the status maps to on a non-OK status."""
+        out = ctypes.c_void_p()
+        err = ctypes.c_void_p()
+        status = self._raw["chs_server_create"](
+            *_bytes_in(profile),
+            *_bytes_in(options),
+            ctypes.byref(out),
+            ctypes.byref(err),
+        )
+        self._check(status, err)
+        return ServerHandle(out.value, self._raw["chs_server_free"])
+
     def schema_create(
         self,
+        server: ServerHandle | None,
         create_table: bytes | None,
         settings: bytes | None,
+        options: bytes | None,
     ) -> SchemaHandle:
-        """The generated call wrapper for chs_schema_create (thread class any).
+        """The generated call wrapper for chs_schema_create (thread class shared).
 
         Raises the class the status maps to on a non-OK status."""
         out = ctypes.c_void_p()
         err = ctypes.c_void_p()
         status = self._raw["chs_schema_create"](
+            None if server is None else server.value,
             *_bytes_in(create_table),
             *_bytes_in(settings),
+            *_bytes_in(options),
             ctypes.byref(out),
             ctypes.byref(err),
         )
@@ -925,17 +980,15 @@ _API_KEY = object()
 
 
 def resolve_all(lib: ctypes.CDLL) -> Api:
-    """Every described symbol, in sorted, deterministic order -- chs_abi_version
-    INCLUDED, even though _loader.py's step 3 (resolve_abi_version) already
-    resolved it before this runs: the test-only invoke_by_name() dispatcher
-    below needs every symbol reachable through ONE Api, handshake class
-    included, and re-resolving an already-present symbol is harmless (by the
-    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-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."""
+    """Every described symbol, in sorted, deterministic order -- the handshake
+    symbols INCLUDED, even though _loader.py's steps 3 and 4 (resolve_abi_version,
+    resolve_build_info) already resolved theirs before this runs: the test-only
+    invoke_by_name() dispatcher below needs every symbol reachable through ONE
+    Api, and re-resolving an already-present symbol is harmless. 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. Step 6 runs AFTER step 4's fingerprint comparison, so a library
+    with another fingerprint is refused with rule r6's message first."""
     raw: dict = {}
     for name in ALL_SYMBOLS:
         try:

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:8ec0c6941f000aa07bfb9fbfef20205d3ee0a588833856bd12270ba42912bfb3) — DO NOT EDIT  # noqa: E501
+# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:d87e91be2bbe75b985c38224268c2f7dc5d8236dab0a4b4d61357c6dfdc1a232) — 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/_abi2/_loader.py

@@ -9,15 +9,20 @@ 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/_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-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
+`resolve_abi_version()`, `resolve_build_info()`, `resolve_all()`, and the `Api` object they return.
+
+Steps 1-7 run in the documented order, the order Go, TypeScript and Rust
+run: glibc (1), dlopen (2), `chs_abi_version` alone (3), `chs_build_info`
+alone, parsed strictly and its fingerprint compared (4: rule r6's exact
+message wins here), the signed-statement cross-check (5), and only then the
+resolve-every-declared-symbol sweep (6). A library with another fingerprint
+that also lacks a symbol this SDK declares (every fingerprint move that adds
+an export meets one) is therefore refused with r6's message, never as
+`missing_symbol:<name>` (public issue #537; the stub variant
+`fingerprint-other-missing-symbol`). A symbol missing from step 4's own
+`chs_build_info` is still `missing_symbol:chs_build_info`, and
+`tests/fixtures/abi-v2/cases.json`'s other `missing-<sym>` variants still
+expect `missing_symbol:<name>` from step 6. Step 7
 calls the image's once-per-image zone setup (empty zone = UTC unless the
 caller supplies one) and then its default settings.
 """
@@ -198,15 +203,15 @@ def _open(
     if version != _decls.CHS_ABI_VERSION:
         _refuse("abi_version", path, want=_decls.CHS_ABI_VERSION, got=version)
 
+    # Step 4: chs_build_info ALONE, parsed strictly, then the fingerprint
+    # compared. Rule r6 is decided here, before the step 6 sweep can name a
+    # missing symbol instead (#537).
     try:
-        api = _decls.resolve_all(lib)
+        build_info_fn = _decls.resolve_build_info(lib)
     except _decls.MissingSymbol as e:
         _refuse(f"missing_symbol:{e.name}", path, want=e.name, got=None)
-        # _refuse always raises; the following line only satisfies a type
-        # checker that cannot see that. (Never reached.)
-        raise
-
-    raw = api.build_info()
+        raise  # never reached: _refuse always raises
+    raw = build_info_fn()
     if raw is None:
         _refuse("build_info_malformed", path, got="chs_build_info() returned NULL")
     info = _parse_build_info(raw, path)
@@ -214,9 +219,17 @@ def _open(
     if info["abi_fingerprint"] != _decls.CHS_ABI_FINGERPRINT:
         _refuse_fingerprint(path, info.get("abi_fingerprint"))
 
+    # Step 5: the signed predicate against build_info.
     if not skip_step5:
         _cross_check(info, predicate, path)
 
+    # Step 6: resolve every declared symbol.
+    try:
+        api = _decls.resolve_all(lib)
+    except _decls.MissingSymbol as e:
+        _refuse(f"missing_symbol:{e.name}", path, want=e.name, got=None)
+        raise  # never reached: _refuse always raises
+
     # Step 7: the once-per-image setup (docs/reference/bindings-v1.md section
     # 6): the image zone (empty = UTC), then the default settings when there
     # are any. After every handshake check and before any other call. A

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:8ec0c6941f000aa07bfb9fbfef20205d3ee0a588833856bd12270ba42912bfb3) — DO NOT EDIT  # noqa: E501
+# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:d87e91be2bbe75b985c38224268c2f7dc5d8236dab0a4b4d61357c6dfdc1a232) — 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`, `Reason`, `Source`, `DiscoverQueryParam`) with the facts the

chtypes/_decode.py

@@ -47,6 +47,8 @@ from .results import (
     Header,
     RowResult,
     SchemaDescription,
+    SchemaReplicated,
+    SchemaServer,
     Span,
     Transform,
     Value,
@@ -449,10 +451,55 @@ def _column(obj: dict[str, Any], where: str) -> Column:
     )
 
 
+def _string_map(obj: Mapping[str, Any], key: str, where: str) -> dict[str, str] | None:
+    """An object of plain JSON strings (a server's settings or macros, the
+    caller's own values given back): None when absent, a dict, even an empty
+    one, when present, so absent and `{}` stay apart."""
+    value = obj.get(key)
+    if value is None:
+        return None
+    inner = _obj(value, where, key)
+    out: dict[str, str] = {}
+    for name, item in inner.items():
+        if not isinstance(item, str):
+            raise _wrong(f"{where}.{key}", name, "a string", item)
+        out[name] = item
+    return out
+
+
+def _server(obj: dict[str, Any], where: str) -> SchemaServer:
+    return SchemaServer(
+        timezone=_text(obj, "timezone", where),
+        settings=_string_map(obj, "settings", where) or {},
+        macros=_string_map(obj, "macros", where),
+    )
+
+
+def _replicated(obj: dict[str, Any], where: str) -> SchemaReplicated:
+    return SchemaReplicated(
+        zookeeper_path=_bytes(obj, "zookeeper_path", where),
+        replica_name=_bytes(obj, "replica_name", where),
+    )
+
+
 def decode_schema_description(raw: bytes) -> SchemaDescription:
     where = "schema_description"
     obj = _obj(strict_loads(raw, where), where)
-    return SchemaDescription(columns=_objects(obj, "columns", where, _column))
+    # Both are absent on a schema compiled without a server, so that document
+    # decodes exactly as it did before servers existed.
+    server = obj.get("server")
+    replicated = obj.get("replicated")
+    return SchemaDescription(
+        columns=_objects(obj, "columns", where, _column),
+        server=None
+        if server is None
+        else _server(_obj(server, where, "server"), f"{where}.server"),
+        replicated=(
+            None
+            if replicated is None
+            else _replicated(_obj(replicated, where, "replicated"), f"{where}.replicated")
+        ),
+    )
 
 
 def _discovered(obj: dict[str, Any], where: str) -> DiscoveredColumn:

chtypes/_input.py

@@ -12,10 +12,11 @@ from __future__ import annotations
 import base64
 import json
 from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
 
 from .errors import misuse
 
-__all__ = ["BytesIn", "Settings"]
+__all__ = ["BytesIn", "ServerProfile", "Settings"]
 
 BytesIn = bytes | str
 Settings = Mapping[str, str]
@@ -107,3 +108,43 @@ def columns_json(columns: Sequence[BytesIn] | None) -> bytes | None:
         except UnicodeDecodeError:
             names.append({"name_b64": base64.b64encode(raw).decode("ascii")})
     return _dump(names)
+
+
+@dataclass(frozen=True, slots=True)
+class ServerProfile:
+    """One ClickHouse server, as the library's `input:server_profile` describes
+    it. Every field is optional and passed through as given: the library
+    validates the zone with DateLUT, each setting with the server's own SET
+    check, and the macros with ClickHouse's own reader. The binding validates
+    nothing in it.
+
+    `timezone` is the server's zone, the one its `timezone()` returns; None or
+    "" leaves it undescribed (omitted) and the image zone applies. `settings` is
+    what the server's profile applies to every query, layered under a schema's
+    and a call's own; None omits it, and `{}` is sent as `{}`. `macros` is the
+    server's `<macros>`: None omits it, and the server's macros are UNKNOWN (a
+    schema whose engine reads one is declined); a mapping, even an empty one, is
+    sent (`{}` when empty) and is the server's COMPLETE set."""
+
+    timezone: str | None = None
+    settings: Settings | None = None
+    macros: Settings | None = None
+
+
+def server_profile_json(profile: ServerProfile) -> bytes:
+    """The profile document: an empty or absent zone and an absent map are
+    omitted; a present map is sent as given, `{}` when empty. Absent `macros` is
+    not empty `macros`."""
+    if not isinstance(profile, ServerProfile):
+        raise TypeError(f"profile must be a ServerProfile, not {type(profile).__name__}")
+    doc: dict[str, object] = {}
+    if profile.timezone is not None:
+        if not isinstance(profile.timezone, str):
+            raise TypeError(f"timezone must be str, not {type(profile.timezone).__name__}")
+        if profile.timezone != "":
+            doc["timezone"] = profile.timezone
+    if profile.settings is not None:
+        doc["settings"] = _string_map(profile.settings, "settings")
+    if profile.macros is not None:
+        doc["macros"] = _string_map(profile.macros, "macros")
+    return _dump(doc)

chtypes/_ocifetch/_channel.py

@@ -69,6 +69,10 @@ DEV_KEY_ID: Final = "824345f9bcf8e5bf"
 DEV_KEY_HEX: Final = "5cd30c53c65a1ebc2d85836a41deb06661bb0ae7b658adb9eb116ec2db8e9b1c"
 # The dev channel's cache directory name: the default root's last element and
 # an explicit cache's subroot (rule r5).
+# The environment twin of the offline option (public issue #528): CHTYPES_OFFLINE=1
+# reads the cache only and makes no request. It names no source, so rule r6 holds.
+# Not a generated constant: the generated set is the v1 fetch contract's.
+ENV_OFFLINE_NAME: Final = "CHTYPES_OFFLINE"
 DEV_CACHE_DIR: Final = "v2-dev"
 # The verified.json schema the dev channel writes, and the only one it reads (rule r5).
 DEV_RECORD_SCHEMA: Final = 2

chtypes/_ocifetch/_ensure.py

@@ -137,6 +137,8 @@ class Options:
     token: str | None = None
     trusted_keys: tuple[TrustedKey, ...] | None = None
     allow_unsigned: bool = False
+    # Offline mode is on when this is set OR CHTYPES_OFFLINE=1; neither turns
+    # the other off (public issue #528).
     offline: bool = False
     frozen: bool = False
     lock_path: str | os.PathLike[str] | None = None
@@ -185,6 +187,9 @@ class Options:
     def resolved_platform(self) -> str:
         return self.platform or detect_host_platform()
 
+    def resolved_offline(self) -> bool:
+        return self.offline or os.environ.get(_channel.ENV_OFFLINE_NAME) == "1"
+
     def resolved_strict(self) -> bool:
         if self.strict_cache is not None:
             return self.strict_cache
@@ -1012,7 +1017,7 @@ def _ensure(
     request: Request, platform_key: str, options: Options, lock: Lock | None, roots: Sequence[Path]
 ) -> Resolved:
     try:
-        if options.offline:
+        if options.resolved_offline():
             resolved = resolve_installed(request, platform_key, options)
             if resolved is None:
                 raise ArtifactMissingError(

chtypes/_ocifetch/_layout.py

@@ -49,20 +49,30 @@ def _expand_template(template: str) -> str:
     return string.Template(out).safe_substitute(mapping)
 
 
+def _absolute(p: str | os.PathLike[str]) -> Path:
+    """A relative cache directory is the process cwd's at this call, resolved here
+    once so every path derived from it is absolute (fetch-v1.md section 9, public
+    issue #541). Lexical, like Go's `filepath.Abs`: no symlink is followed."""
+    return Path(os.path.abspath(p))
+
+
 def resolve_cache_root(cache_dir: str | os.PathLike[str] | None = None) -> Path:
     """`CHTYPES_CACHE` (or an explicit override) names the cache directory
     ITSELF, not a parent `chtypes/` to append to (constants: `cache.root_template`).
 
     The active fetch contract decides the rest (_channel.py): under the dev
-    channel an explicit cache is used through its subroot `<cache>/v2-dev`,
-    never as a whole layout, which a 1.x binding uses (rule r5, a MUST), and
-    the default root is `${XDG_CACHE_HOME:-~/.cache}/chtypes/v2-dev`."""
+    channel an explicit cache, from the environment or the option, is used
+    through its subroot `<cache>/v2-dev`, never as a whole layout, which a 1.x
+    binding uses (rule r5, a MUST), and the default root is
+    `${XDG_CACHE_HOME:-~/.cache}/chtypes/v2-dev`. The result is absolute (#541)."""
     channel = _channel.active()
-    explicit = cache_dir if cache_dir is not None else (os.environ.get(C.ENV_CACHE_NAME) or None)
-    if explicit is not None:
-        root = Path(explicit)
+    explicit = os.fspath(cache_dir) if cache_dir is not None else ""
+    if not explicit:
+        explicit = os.environ.get(C.ENV_CACHE_NAME) or ""
+    if explicit:
+        root = _absolute(explicit)
         return root / channel.subroot if channel.subroot else root
-    return Path(_expand_template(C.CACHE_ROOT_TEMPLATE)).parent / channel.root_leaf
+    return _absolute(Path(_expand_template(C.CACHE_ROOT_TEMPLATE)).parent / channel.root_leaf)
 
 
 def cache_root(cache_dir: str | os.PathLike[str] | None = None) -> Path:

chtypes/library.py

@@ -23,9 +23,11 @@ from ._abi2._vocab import EXPORT_NONE, DocFlags, Format
 from ._guard import CloseGuard
 from ._input import (
     BytesIn,
+    ServerProfile,
     Settings,
     body_bytes,
     columns_json,
+    server_profile_json,
     settings_json,
     string_map_json,
     to_bytes,
@@ -40,7 +42,7 @@ from .results import (
     SchemaDescription,
 )
 
-__all__ = ["Block", "Filter", "Library", "Schema", "open_unverified"]
+__all__ = ["Block", "Filter", "Library", "Schema", "Server", "open_unverified"]
 
 # One image per file, process-wide: keyed on the realpath's device and inode, so
 # two registries, two spellings or a hardlink of one artifact share one image
@@ -159,6 +161,19 @@ class _Handle:
         self.close()
 
 
+class Server(_Handle):
+    """One ClickHouse server (`chs_server`), made by `Library.new_server` and
+    passed to `Library.compile_table(server=)`. Immutable once made, so safe to
+    share across threads: any number of threads may compile tables on one server
+    at once. `close` releases the caller's reference, after the compiles already
+    using the server have returned; a schema compiled on the server holds its own
+    counted reference inside the library, so a server and its schemas close in
+    any order."""
+
+    __slots__ = ()
+    _what = "Server"
+
+
 class Block(_Handle):
     """A body parsed once, for evaluating many filters over it. It holds a counted
     reference to its schema inside the library."""
@@ -388,16 +403,45 @@ class Library:
         """Live handle counts per kind in this image (a diagnostic)."""
         return _decode.decode_live_handles(self._api.live_handles())
 
+    def new_server(self, profile: ServerProfile) -> Server:
+        """Describe one ClickHouse server from a profile (`chs_server_create`). The
+        library validates the whole profile here, once: a zone DateLUT cannot
+        load, or a setting the server's SET check refuses, is the library's own
+        refusal (`SchemaError`); a malformed macro set is a `UsageError`; a build
+        that will not describe the profile declines it (`UnsupportedError`). The
+        binding checks none of it first. No server option is defined yet, so the
+        options document is empty."""
+        document = server_profile_json(profile)
+        return Server(self, self._api.server_create(document, None))
+
     def compile_table(
         self,
         create_table: BytesIn,
         *,
         settings: Settings | None = None,
         session_timezone: str | None = None,
+        server: Server | None = None,
     ) -> Schema:
         """Compile exactly one `CREATE TABLE` statement. `settings` is the profile;
-        a compiled type always takes the image zone, never the profile's."""
+        a compiled type always takes the image zone, never the profile's.
+
+        `server` (from `new_server`) compiles the table on that server: the
+        schema's home zone is the server's timezone, the server's settings layer
+        under the schema's own, and a Replicated engine's ZooKeeper path and
+        replica name expand the server's macros. A closed server is a
+        `UsageError`, raised before any call; a server from another library is
+        that library's own refusal, also a `UsageError`. `None` is no server: the
+        schema is on the image's own server."""
         statement = to_bytes(create_table, "create_table")
         settings_bytes = settings_json(settings, session_timezone)
-        handle = self._api.schema_create(statement, settings_bytes)
+        if server is not None and not isinstance(server, Server):
+            raise TypeError(f"server must be a Server, not {type(server).__name__}")
+        # No schema option is defined yet: none, which the library reads as `{}`.
+        # A closed server is refused here, before the call, because its freed
+        # handle would cross as NULL and the library would compile on the
+        # image's server instead of refusing.
+        with _hold(*(() if server is None else (server._guard,))):
+            handle = self._api.schema_create(
+                None if server is None else server._handle, statement, settings_bytes, None
+            )
         return Schema(self, handle)

chtypes/registry.py

@@ -32,10 +32,11 @@ from ._ocifetch import _constants as _fetch_constants
 from ._ocifetch._dsse import TrustedKey
 from ._ocifetch._ensure import detect_host_platform, missing_notes, with_notes
 from ._ocifetch._errors import FetchError
+from ._ocifetch._layout import resolve_cache_root, search_roots
 from ._ocifetch._oci import version_within_request
 from .library import Library, open_image
 
-__all__ = ["FetchOptions", "Registry", "Resolved", "TrustedKey"]
+__all__ = ["FetchOptions", "Registry", "Resolved", "TrustedKey", "cache_root", "search_dirs"]
 
 _TRUTHY = ("1", "true", "yes", "on")
 
@@ -80,6 +81,8 @@ class FetchOptions:
     token: str | None = None
     trusted_keys: Sequence[TrustedKey] | None = None
     allow_unsigned: bool | None = None
+    # Offline reads the cache only and makes no request. It is on when this is
+    # set OR CHTYPES_OFFLINE=1; neither turns the other off (public issue #528).
     offline: bool = False
     frozen: bool = False
     lock_path: str | os.PathLike[str] | None = None
@@ -120,6 +123,27 @@ class FetchOptions:
         )
 
 
+def cache_root(options: FetchOptions | None = None) -> Path:
+    """The cache root a fetch, list or `chtypes where` with `options` would use:
+    `options.cache_dir`, else `CHTYPES_CACHE` (each used through its `v2-dev`
+    subroot, spec/abi-v2/docs.md rule r5), else
+    `${XDG_CACHE_HOME:-~/.cache}/chtypes/v2-dev`.
+
+    It is the fetch layer's own resolution, `search_dirs(options)[0]`. It
+    creates nothing and reads no cache."""
+    return resolve_cache_root((options or FetchOptions()).cache_dir)
+
+
+def search_dirs(options: FetchOptions | None = None) -> tuple[Path, ...]:
+    """Every directory a lookup reads for installed builds, in the order it reads
+    them: the cache root first, then each read-only system directory
+    (`options.system_dirs`; `None` is the built-in list, an empty sequence none).
+    The order is the fetch layer's own, and on a tie the earlier directory wins.
+    It creates nothing and touches no file."""
+    o = options or FetchOptions()
+    return search_roots(o.cache_dir, o.system_dirs)
+
+
 def _wrap(exc: FetchError) -> errors.ArtifactError:
     """The fetch layer's error as the public class of its code, one family with
     the loader's. The original stays as `__cause__`."""

chtypes/results.py

@@ -11,6 +11,7 @@ vendored reader does not know a fact, the document says `null` and the field is
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from dataclasses import dataclass
 
 from ._abi2._vocab import DefaultKind, FilterOutcome, Outcome, Verdict
@@ -32,6 +33,8 @@ __all__ = [
     "Header",
     "RowResult",
     "SchemaDescription",
+    "SchemaReplicated",
+    "SchemaServer",
     "Span",
     "Transform",
     "Value",
@@ -210,9 +213,38 @@ class Column:
     default_expr: bytes
 
 
+@dataclass(frozen=True, slots=True)
+class SchemaServer:
+    """The server a schema was compiled on, as the library holds it. Its strings
+    are the caller's own profile values given back, so they are plain text, not
+    data-derived. `timezone` is the zone the schema's types bind: the profile's,
+    or else the image zone. `settings` is the profile's settings (`{}` when it
+    gave none). `macros` is None exactly when the profile carried no macros
+    (unknown), and a mapping, even an empty one, when it did (the complete set)."""
+
+    timezone: str
+    settings: Mapping[str, str]
+    macros: Mapping[str, str] | None
+
+
+@dataclass(frozen=True, slots=True)
+class SchemaReplicated:
+    """What ClickHouse's own TableZnodeInfo resolved for a Replicated engine on a
+    server, fully expanded. Both expand DDL bytes, so both are `bytes`."""
+
+    zookeeper_path: bytes
+    replica_name: bytes
+
+
 @dataclass(frozen=True, slots=True)
 class SchemaDescription:
+    """A schema's columns, in declared order, and the server it was compiled on.
+    `server` is None exactly when it was compiled without one; `replicated` is
+    None when the document carries none."""
+
     columns: tuple[Column, ...]
+    server: SchemaServer | None = None
+    replicated: SchemaReplicated | None = None
 
 
 @dataclass(frozen=True, slots=True)

{chtypes-2.0.0.dev0.dist-info → chtypes-2.0.0.dev2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: chtypes
-Version: 2.0.0.dev0
+Version: 2.0.0.dev2
 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
@@ -20,6 +20,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"`.
+>
+> An explicit cache directory gets the `v2-dev` subroot whether it comes from `CHTYPES_CACHE` or from `FetchOptions(cache_dir=...)`: the layout is under `<cache_dir>/v2-dev`, never in the directory itself, so code that inspects or pre-populates a cache looks there; `chtypes.cache_root` and `chtypes.search_dirs` return the resolved paths. `CHTYPES_OFFLINE=1` is the environment twin of `FetchOptions(offline=True)` and `--offline`: the cache only, no request.
 
 **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.
 
@@ -41,18 +43,18 @@ uv add "chtypes>=2.0.0.dev0"            # or: pip install "chtypes>=2.0.0.dev0"
 import chtypes
 from chtypes import Format, Registry
 
-chtypes.setup(timezone="UTC")             # once, before the first open (optional)
+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
+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')
 
 row = batch.rows[0]
-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
+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 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.

{chtypes-2.0.0.dev0.dist-info → chtypes-2.0.0.dev2.dist-info}/RECORD

@@ -1,37 +1,37 @@
-chtypes/__init__.py,sha256=UkNZYe0u3tqvvKDIsp4D0fPHTMLeuKtp60hs_TOkn_k,5715
-chtypes/__main__.py,sha256=m75yDXRqTSyqNZJ-p3TTl_5knMkaKyurjxyd8gZ1OLw,13474
-chtypes/_decode.py,sha256=TQX9LyzqvVus5gHRUoFI9x9ELYOaf33hcan2jZtC6ko,19507
+chtypes/__init__.py,sha256=aIVdrUX79p18amwUcV27FItM4SA1n-LlipJHLopgHgU,5919
+chtypes/__main__.py,sha256=XYGNTpTLXI1AUp7srvuNVv2SZAcfwLaXpoXRVInyhF4,14030
+chtypes/_decode.py,sha256=i_nHXx6QKCbXej0GJMnfq_utRE-Oq7SiqPNETOmhFZ4,21149
 chtypes/_ed25519.py,sha256=uwaAKWvgoc936e1ZfgLrtR47W87WWCL541kFaqBXrB0,4141
 chtypes/_guard.py,sha256=zTtwprCS0XvGWY7GDozo-IP6GwjMAWl-o-AjShdCSVI,1985
-chtypes/_input.py,sha256=GonZVBB7gOPXEoDBDjEExiZXMIW7gbTIFAopvcxqnTs,4039
+chtypes/_input.py,sha256=i4OUmgmHxx618g0DVFYy8LmHhggfBT03NyMxH3ptZBI,6020
 chtypes/_setup.py,sha256=n84T0hFmXu_fdnXQIFhk3dMVL0_-yhfdRZsqCXTLzzg,6114
 chtypes/errors.py,sha256=9qv94rxbe7hm7lSVFG33Qri82FwDtCY-EnJiwnMfkp8,9501
-chtypes/library.py,sha256=gG4MN2zwfiLOFn0k-nZsZ2vAaBQBNe97DBbUbTtus7k,15426
+chtypes/library.py,sha256=G6DJFiRuv8--JARxfiSNEqeFLkafaMs_n9nG-IwoC74,17878
 chtypes/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-chtypes/registry.py,sha256=Wra-DzLYrWPHsyPlsTPOmPvuc1as5jPEfA7gxVYHPs4,12444
-chtypes/results.py,sha256=JXHgnd06jXGbNGfHToBO0tRxUPy1Q3urOsH4EXax3-0,8062
+chtypes/registry.py,sha256=HTrzS_3HjOkH4rU90AVMNfFLsLoaut0jgNlt_BJ28QY,13727
+chtypes/results.py,sha256=AI0QALKW-NcgM5qOUxUMesFXd4BcsujzuiaG8ejBelg,9330
 chtypes/_abi2/__init__.py,sha256=d3i7_iUDMFT1jg49vRQz1SMH6oseYZHUR0oPt6aSTiY,1042
-chtypes/_abi2/_decls.py,sha256=qlbkMEzXwjp7mZta5-NXVHU2DTEDqTd1Qzwc4rP0RKA,36677
-chtypes/_abi2/_errmap.py,sha256=sgx97MNwOP3zgnonkcH8OKFOHiClaecL2AMOc3BKBqc,2886
+chtypes/_abi2/_decls.py,sha256=c2xuqG0rFgSthOO1FHEGzPhr4ldKQzoOdRxyXaEslq8,38454
+chtypes/_abi2/_errmap.py,sha256=L6WmPSXqqEoNchX1jrfWsbogthm5crwF-8tQBly330E,2886
 chtypes/_abi2/_errors.py,sha256=wRE9M0oYtJz_9izQqpEBh5571M_1QzGWBoJ3pJTykWw,761
-chtypes/_abi2/_loader.py,sha256=RuhC9COv3lWA67SHYd7UAPdg7FsjIVkXgWNg2_Lr0HM,11717
-chtypes/_abi2/_vocab.py,sha256=X_3ebytcvCklP2iJfHMaLTrvwQVz3FmJP1dxp6CWTCM,14663
+chtypes/_abi2/_loader.py,sha256=VMWrbWMp9Uq3K-7a219lfqAmSmBlD2hcB6WDJgG8XG0,12514
+chtypes/_abi2/_vocab.py,sha256=6UyJwWDnp_R59YMDF7ZWuLchVU7Sq8asmQChH21QEDw,14663
 chtypes/_ocifetch/__init__.py,sha256=enfPOKkqP4kqAKqckBGWXN1OQsiYo9ngDP-wzG0zn2I,1484
-chtypes/_ocifetch/_channel.py,sha256=aumM_S8X7_H2GXhaDZwoSTcg-m9_k4QSu5XTqSWZ6EQ,11836
+chtypes/_ocifetch/_channel.py,sha256=p6FbWbrCBTyXmYjdP4UOkkjj02aEkn8Em9EE6xuUZ1Y,12121
 chtypes/_ocifetch/_constants.py,sha256=UdOGIShDXaDP13NGbuftKZRE4u7VK8JfZmoeChw4GMU,5467
 chtypes/_ocifetch/_dsse.py,sha256=0RaFJaG1jhXr1uPfuHxm7yAn6viNzYhfCRUf-sW5SvQ,9333
-chtypes/_ocifetch/_ensure.py,sha256=lVD_Ysg-IRNjJ_EuIHRz3fnfxy_j5Ib7M_ouLifZCfw,60521
+chtypes/_ocifetch/_ensure.py,sha256=NG_Fhg-UkafZZC5oHnG4f61W9-sWp9jE8gXOWEWJWrs,60772
 chtypes/_ocifetch/_errors.py,sha256=u0eIdrr3g00ugy8ZZoAXYIgUuZgEs6eMue2QkcWXC6w,6595
 chtypes/_ocifetch/_faults.py,sha256=HpoB9tJW7aLRiJdCFnspzkwhpFATZ6f6hGi49Mbfnhs,7609
 chtypes/_ocifetch/_goldens.py,sha256=8MicgeJSRd4WZkaEsdujRnOa7twQvbT-wfSMPZaD-ms,4191
 chtypes/_ocifetch/_http.py,sha256=vz3i0p5I8ch8SONpoEab0Vb5uX9MvPOHjfcaGU03bgo,22807
-chtypes/_ocifetch/_layout.py,sha256=SwaBgxwvYh5zGyHTZrP4-icAzhqenQSSUMIMKDlEn2A,20842
+chtypes/_ocifetch/_layout.py,sha256=ezEoVrsSMhvDhQ4U04hsGdu1-_ISZQ4V6zg4gGIChTQ,21300
 chtypes/_ocifetch/_lock.py,sha256=14_uex9qXdOht-5FSrSvFvd99-gB7DmI3bDuxXs4YU8,5530
 chtypes/_ocifetch/_oci.py,sha256=lmrlykbyQev55uFDn8UBwXyMLthd3-pQq3xIyfXCUXY,12704
 chtypes/_ocifetch/_referrers.py,sha256=J2b4gN6vryz_IzYHxrd2Tp-tQO9Cz766rZtKgCVcKqA,6008
 chtypes/_ocifetch/_unpack.py,sha256=Cn4-up63KL63L8pnkS5zwJ6VbbHPSigpCnmOdcHJ4RI,5609
-chtypes-2.0.0.dev0.dist-info/METADATA,sha256=RlGXGLQU7lKwz8_nNkEyQQOx8gbef-84qlB_kNdwVgM,10213
-chtypes-2.0.0.dev0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-chtypes-2.0.0.dev0.dist-info/entry_points.txt,sha256=TdNcluWBR0VOt5mVFROsp-NiVPAdR3EHo0UsHlMC0r0,50
-chtypes-2.0.0.dev0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-chtypes-2.0.0.dev0.dist-info/RECORD,,
+chtypes-2.0.0.dev2.dist-info/METADATA,sha256=ORRyWPTzbIQl_tI3z1ZSAWNYwcOesmInGA0xvW6Eb5o,10632
+chtypes-2.0.0.dev2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+chtypes-2.0.0.dev2.dist-info/entry_points.txt,sha256=TdNcluWBR0VOt5mVFROsp-NiVPAdR3EHo0UsHlMC0r0,50
+chtypes-2.0.0.dev2.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+chtypes-2.0.0.dev2.dist-info/RECORD,,