chtypes 2.0.0.dev3__py3-none-any.whl → 2.0.0.dev4__py3-none-any.whl

chtypes/__init__.py

@@ -48,6 +48,7 @@ from importlib.metadata import version as _package_version
 
 from ._abi2._vocab import (
     EXPORT_NONE,
+    DeclinedTier,
     DefaultKind,
     DiscoverQueryParam,
     DocFlags,
@@ -72,6 +73,7 @@ from .errors import (
     CODE_CACHE_UNUSABLE,
     CODE_SOURCE_FORBIDDEN,
     CODE_SOURCE_INCOMPATIBLE,
+    CODE_SOURCE_RETIRED,
     CODE_SOURCE_UNAUTHORIZED,
     CODE_SOURCE_UNREACHABLE,
     ArtifactCorruptError,
@@ -88,6 +90,7 @@ from .errors import (
     SchemaError,
     SourceForbiddenError,
     SourceIncompatibleError,
+    SourceRetiredError,
     SourceUnauthorizedError,
     SourceUnreachableError,
     UnsupportedError,
@@ -102,6 +105,7 @@ from .results import (
     Capabilities,
     Column,
     Computed,
+    DeclinedSetting,
     DiscoveredColumn,
     Discovery,
     EngineCell,
@@ -130,6 +134,7 @@ __all__ = [
     "CODE_CACHE_UNUSABLE",
     "CODE_SOURCE_FORBIDDEN",
     "CODE_SOURCE_INCOMPATIBLE",
+    "CODE_SOURCE_RETIRED",
     "CODE_SOURCE_UNAUTHORIZED",
     "CODE_SOURCE_UNREACHABLE",
     "EXPORT_NONE",
@@ -151,6 +156,8 @@ __all__ = [
     "ChtypesError",
     "Column",
     "Computed",
+    "DeclinedSetting",
+    "DeclinedTier",
     "DefaultKind",
     "DiscoverQueryParam",
     "DiscoveredColumn",
@@ -186,6 +193,7 @@ __all__ = [
     "Source",
     "SourceForbiddenError",
     "SourceIncompatibleError",
+    "SourceRetiredError",
     "SourceUnauthorizedError",
     "SourceUnreachableError",
     "Span",

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:4129dccc3f4e698dedb0e99cae413f5240085f633c5a1244e2c55bf7a7bb6c3a) — DO NOT EDIT  # noqa: E501
+# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:28c7445ce6b5c6d0ae33177fd60eb7b3b5654a966c842b8d812aea622824dc72) — 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:4129dccc3f4e698dedb0e99cae413f5240085f633c5a1244e2c55bf7a7bb6c3a"
+CHS_ABI_FINGERPRINT = "sha256:28c7445ce6b5c6d0ae33177fd60eb7b3b5654a966c842b8d812aea622824dc72"
 
 # The description's stability: "unstable" while this generation is being
 # designed, so CHS_ABI_FINGERPRINT moves with every change, and "locked" after

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:4129dccc3f4e698dedb0e99cae413f5240085f633c5a1244e2c55bf7a7bb6c3a) — DO NOT EDIT  # noqa: E501
+# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:28c7445ce6b5c6d0ae33177fd60eb7b3b5654a966c842b8d812aea622824dc72) — 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/_vocab.py

@@ -1,10 +1,10 @@
-# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:4129dccc3f4e698dedb0e99cae413f5240085f633c5a1244e2c55bf7a7bb6c3a) — DO NOT EDIT  # noqa: E501
+# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:28c7445ce6b5c6d0ae33177fd60eb7b3b5654a966c842b8d812aea622824dc72) — DO NOT EDIT  # noqa: E501
 """The Python binding's generated vocabularies, from spec/abi-v2/abi.json: the C
 enums (`Format`, `Status`), the document vocabularies (`Outcome`, `FilterOutcome`,
-`Verdict`, `DefaultKind`, `MergeReason`, `Reason`, `Source`, `DiscoverQueryParam`) with the
-facts the description attaches to each value (`Format.ch_name`, `Reason` lossy,
-`Source` is_stored, `Verdict.answered`), and the `DocFlags` groups. No other file in
-this package keeps a copy of any of it.
+`Verdict`, `DefaultKind`, `MergeReason`, `DeclinedTier`, `Reason`, `Source`,
+`DiscoverQueryParam`) with the facts the description attaches to each value
+(`Format.ch_name`, `Reason` lossy, `Source` is_stored, `Verdict.answered`), and the
+`DocFlags` groups. No other file in this package keeps a copy of any of it.
 
 Rule r3 (spec/abi-v2/docs.md): every vocabulary has an unknown(n) member, and a
 value the description does not list reads as it, carrying the raw value, for that
@@ -249,6 +249,31 @@ class MergeReason(StrEnum):
         return cls(text)
 
 
+class DeclinedTier(StrEnum):
+    """The WHERE-settings tier of a setting a server profile sets and this build's
+    filters do not honor in a WHERE, as a `DeclinedSetting` reports it."""
+
+    PREDICATE = "predicate"
+    PREDICATE_UNFLIPPED = "predicate-unflipped"
+    RESULT_CONTENT = "result-content"
+
+    @classmethod
+    def _missing_(cls, value: object) -> DeclinedTier | None:
+        return _unknown_str(cls, value)
+
+    @property
+    def known(self) -> bool:
+        """Whether the description lists this value: False for exactly the unknown(n)
+        member an unlisted value reads as (rule r3)."""
+        return type(self)._value2member_map_.get(self._value_) is self
+
+    @classmethod
+    def of(cls, text: str) -> DeclinedTier:
+        """Map a document's spelling. One the description does not list is kept as
+        this vocabulary's unknown(n) member, carrying it (rule r3)."""
+        return cls(text)
+
+
 class DiscoverQueryParam(StrEnum):
     """A query parameter of the SQL `discover_query` returns, which the caller binds
     when it runs the query."""
@@ -415,6 +440,7 @@ DESCRIBED_VOCABULARIES: Final[dict[str, type]] = {
     "filter_verdict": Verdict,
     "discover_query_param": DiscoverQueryParam,
     "default_kind": DefaultKind,
+    "declined_tier": DeclinedTier,
 }
 
 

chtypes/_decode.py

@@ -28,7 +28,16 @@ import json
 from collections.abc import Callable, Mapping
 from typing import Any
 
-from ._abi2._vocab import DefaultKind, FilterOutcome, MergeReason, Outcome, Reason, Source, Verdict
+from ._abi2._vocab import (
+    DeclinedTier,
+    DefaultKind,
+    FilterOutcome,
+    MergeReason,
+    Outcome,
+    Reason,
+    Source,
+    Verdict,
+)
 from .errors import ArtifactCorruptError, internal
 from .results import (
     AtMergeEntry,
@@ -37,6 +46,7 @@ from .results import (
     Capabilities,
     Column,
     Computed,
+    DeclinedSetting,
     DiscoveredColumn,
     Discovery,
     EngineCell,
@@ -493,11 +503,22 @@ def _string_map(obj: Mapping[str, Any], key: str, where: str) -> dict[str, str]
     return out
 
 
+def _declined_setting(obj: dict[str, Any], where: str) -> DeclinedSetting:
+    # An unlisted tier is its unknown(n): kept, never a failure (rule r3).
+    return DeclinedSetting(
+        name=_name(obj, "name", where),
+        tier=DeclinedTier.of(_text(obj, "tier", where)),
+    )
+
+
 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),
+        filter_declined_settings=_objects(
+            obj, "filter_declined_settings", where, _declined_setting
+        ),
     )
 
 

chtypes/_ocifetch/_channel.py

@@ -52,6 +52,7 @@ from typing import Final, Protocol
 from chtypes._abi2._decls import CHS_ABI_FINGERPRINT
 from chtypes._ocifetch import _constants as C
 from chtypes._ocifetch._dsse import TrustedKey
+from chtypes._ocifetch._errors import ArtifactUnpublishedError
 
 __all__ = [
     "ALIAS_SEPARATOR",
@@ -66,6 +67,7 @@ __all__ = [
     "PinningRefusedError",
     "abi",
     "active",
+    "ahead_of_registry",
     "alias_tag",
     "allow_overrides_for_tests",
     "channel_name",
@@ -274,6 +276,43 @@ def visible(predicate: object, channel: Channel | None = None) -> bool:
     return fingerprint == f"sha256:{channel.own_fingerprint}"
 
 
+def ahead_of_registry(
+    alias_absent: bool, predicate: object, channel: Channel | None = None
+) -> None:
+    """The dev channel's answer for an SDK whose fingerprint no published build
+    carries yet (docs/guides/fetch-v1.md §3; public issue #578): when every base
+    answered its own alias 404 (`alias_absent`) and the build the tag names is
+    signed for another fingerprint (`predicate`, the SIGNED predicate, the field
+    `visible` keys on), raise `ArtifactUnpublishedError`, the code a request no
+    build answers gets, naming both fingerprints. Nothing is installed and an
+    install of that build is never reported, because the lookup this SDK opens
+    through would refuse it. Returns in every other case: the alias answered,
+    the tag's build is this SDK's own, or the contract has no own fingerprint."""
+    channel = channel or active()
+    if not alias_absent or visible(predicate, channel):
+        return
+    raise ArtifactUnpublishedError(f"chtypes: {_ahead_message(channel.own_fingerprint, predicate)}")
+
+
+def _ahead_message(own: str, predicate: object) -> str:
+    """`ahead_of_registry`'s message: "no published build for this SDK's
+    fingerprint <own>; newest published on this channel is <fp> (build <id>)",
+    each fingerprint 64 lowercase hex without its `sha256:` prefix, the
+    parenthesis dropped when the predicate names no build, and "unnamed" for a
+    predicate that names no fingerprint."""
+    fields = predicate if isinstance(predicate, dict) else {}
+    theirs = fields.get("abi_fingerprint")
+    theirs = theirs.removeprefix("sha256:") if isinstance(theirs, str) else ""
+    message = (
+        f"no published build for this SDK's fingerprint {own}; "
+        f"newest published on this channel is {theirs or 'unnamed'}"
+    )
+    build = fields.get("build")
+    if isinstance(build, str) and build:
+        message += f" (build {build})"
+    return message
+
+
 def use_dev_channel_for_tests() -> Callable[[], None]:
     """Make this TEST run speak the dev channel exactly as a user's process does
     (undoing either function above, for a test of the dev channel itself).

chtypes/_ocifetch/_constants.py

@@ -1,6 +1,6 @@
 # Code generated by scripts/fetch-v1/gen-constants.py from
 # spec/fetch-v1/constants.json. DO NOT EDIT.
-# Source sha256: 163dbaa1e5173aa65de7d46f1eac27c02f862e96b5c8160a23fee8cfabd77a2a
+# Source sha256: 4554956faeb154fc324a6120b7b35976222c6bc8ecbce7fd0147502e3073611d
 """The v1 fetch constants, generated: see docs/guides/fetch-v1.md."""
 
 from __future__ import annotations
@@ -83,6 +83,7 @@ RETRY_AFTER_STATUSES: Final[tuple[int, ...]] = (429, 503)
 RETRY_AFTER_OVER_BUDGET: Final[str] = "refuse"
 DIGEST_404_POLICY: Final[str] = "next_base_then_retry_on_last"
 TAG_404_POLICY: Final[str] = "next_base_then_unpublished"
+RETIRED_STATUSES: Final[tuple[int, ...]] = (410,)
 
 CONNECT_TIMEOUT_S: Final[float] = 30.0
 IDLE_READ_TIMEOUT_S: Final[float] = 60.0
@@ -95,6 +96,8 @@ MAX_REFERRERS: Final[int] = 16
 MAX_REDIRECTS: Final[int] = 5
 MAX_UNPACKED_BYTES: Final[int] = 4294967296
 ZSTD_WINDOW_LOG_MAX: Final[int] = 27
+RETIRED_BODY_MAX_BYTES: Final[int] = 65536
+RETIRED_MESSAGE_MAX_CODE_POINTS: Final[int] = 256
 
 CACHE_ROOT_TEMPLATE: Final[str] = "${XDG_CACHE_HOME:-$HOME/.cache}/chtypes/v1"
 SYSTEM_CACHE_DIRS: Final[tuple[str, ...]] = ("/usr/local/share/chtypes/v1", "/opt/chtypes/v1")
@@ -122,4 +125,5 @@ ERROR_EXIT_CODES: Final[dict[str, int]] = {
     "CHTYPES_SOURCE_INCOMPATIBLE": 7,
     "CHTYPES_ARTIFACT_INCOMPATIBLE": 8,
     "CHTYPES_CACHE_UNUSABLE": 9,
+    "CHTYPES_SOURCE_RETIRED": 10,
 }

chtypes/_ocifetch/_ensure.py

@@ -38,6 +38,7 @@ from chtypes._ocifetch._errors import (
     ArtifactUntrustedError,
     FetchError,
     SourceForbiddenError,
+    SourceRetiredError,
     SourceUnauthorizedError,
     SourceUnreachableError,
 )
@@ -49,6 +50,7 @@ from chtypes._ocifetch._http import (
     ForbiddenHttpError,
     NotFoundHttpError,
     OversizeHttpError,
+    RetiredHttpError,
     RetryPolicy,
     TransportError,
     UnauthorizedHttpError,
@@ -440,7 +442,7 @@ def _find_verified_signature(
                 bases, ref.digest, policy=policy, retry=retry
             )
             blob_desc = manifest_single_layer(referrer_doc, expected_media_type=C.MEDIA_TYPE_BUNDLE)
-        except ArtifactCorruptError:
+        except (ArtifactCorruptError, RetiredHttpError):
             raise
         except (TransportError, FetchError):
             continue
@@ -458,7 +460,7 @@ def _find_verified_signature(
             with open(bundle_path, "rb") as f:
                 bundle_json = json.loads(f.read())
             verified = verify_bundle(bundle_json, trusted_keys)
-        except ArtifactCorruptError:
+        except (ArtifactCorruptError, RetiredHttpError):
             raise
         except (TransportError, FetchError, json.JSONDecodeError):
             continue
@@ -698,7 +700,7 @@ def _ensure_floating(
     cache_root_path = roots[0]
     scratch_root = _scratch_root(cache_root_path)
 
-    index_doc, index_bytes, index_digest = fetch_manifest_by_tag(
+    index_doc, index_bytes, index_digest, alias_absent = fetch_manifest_by_tag(
         bases,
         request.spelling,
         policy=policy,
@@ -711,6 +713,10 @@ def _ensure_floating(
     existing_dir = unpacked_dir_for(cache_root_path, manifest_hex)
     existing_record = read_verified_record(existing_dir)
     if existing_record is not None and existing_record.platform == platform_key:
+        # An install of another fingerprint's build, reached through the tag
+        # because the registry has none at this SDK's own, is never reported
+        # installed (public issue #578): refused before the cache is touched.
+        _channel.ahead_of_registry(alias_absent, existing_record.predicate)
         # A NEWER build within the request, installed beside it, is still the
         # answer ("monotonic-warning", docs/guides/fetch-v1.md §9).
         newer = _newer_installed(
@@ -801,6 +807,12 @@ def _ensure_floating(
         signed_by = verified.signed_by
 
     _check_predicate_matches_request(predicate, platform_key, request.spelling)
+    if found is not None:
+        # An SDK ahead of the registry (public issue #578): the alias for its
+        # own fingerprint answered 404 on every base, and the tag's build is
+        # signed for another. Refused from the signed statement, before the
+        # layer is requested, so nothing is downloaded or installed.
+        _channel.ahead_of_registry(alias_absent, predicate)
     newer = _newer_installed(roots, platform_key, predicate, request.spelling)
     if newer is not None:
         newer_dir, newer_record, warning = newer
@@ -983,6 +995,8 @@ def _translate_transport_error(e: TransportError) -> FetchError:
         return SourceForbiddenError(f"chtypes: {e}")
     if isinstance(e, OversizeHttpError):
         return ArtifactCorruptError(f"chtypes: {e}")
+    if isinstance(e, RetiredHttpError):
+        return SourceRetiredError(f"chtypes: {e}")
     if isinstance(e, UnreachableHttpError):
         return SourceUnreachableError(f"chtypes: {e}", retryable=getattr(e, "retryable", True))
     return SourceUnreachableError(f"chtypes: {e}")
@@ -1368,7 +1382,9 @@ def _fetch_signed_impl(repository: str, ref: str, predicate_type: str, options:
         doc, _raw = fetch_manifest_by_digest(bases, ref, policy=policy, retry=retry)
         manifest_digest = ref
     else:
-        doc, _raw, manifest_digest = fetch_manifest_by_tag(bases, ref, policy=policy, retry=retry)
+        doc, _raw, manifest_digest, _alias_absent = fetch_manifest_by_tag(
+            bases, ref, policy=policy, retry=retry
+        )
 
     layer_desc = manifest_single_layer(doc)
     found = _find_verified_signature(
@@ -1466,6 +1482,8 @@ def _fetch_goldens(
                     retry=retry,
                     max_bytes=C.MAX_UNPACKED_BYTES,
                 )
+            except RetiredHttpError:
+                raise
             except (TransportError, FetchError) as e:
                 first_failure = first_failure or e
                 continue
@@ -1580,6 +1598,8 @@ def _verify_goldens_signature(
         except ArtifactCorruptError as e:
             failure = failure or e
             continue
+        except RetiredHttpError:
+            raise
         except (TransportError, FetchError, json.JSONDecodeError):
             continue
         finally:

chtypes/_ocifetch/_errors.py

@@ -5,7 +5,7 @@ Scoped to `chtypes._ocifetch`: the stable, public exception types live in
 imports from or edits. A future switch lane decides how (or whether) these
 become public types; until then every name here is private.
 
-Every exception carries a `.code` string from one of the eleven codes
+Every exception carries a `.code` string from one of the twelve codes
 `spec/fetch-v1/constants.json`'s `errors` map assigns an exit status to
 (the generated `ERROR_EXIT_CODES` table), so a CLI added later needs no
 second mapping — it is the same lookup v0's `__main__.py` does today.
@@ -30,6 +30,7 @@ __all__ = [
     "CODE_CACHE_UNUSABLE",
     "CODE_SOURCE_FORBIDDEN",
     "CODE_SOURCE_INCOMPATIBLE",
+    "CODE_SOURCE_RETIRED",
     "CODE_SOURCE_UNAUTHORIZED",
     "CODE_SOURCE_UNREACHABLE",
     "ArtifactCorruptError",
@@ -41,6 +42,7 @@ __all__ = [
     "FetchError",
     "SourceForbiddenError",
     "SourceIncompatibleError",
+    "SourceRetiredError",
     "SourceUnauthorizedError",
     "SourceUnreachableError",
 ]
@@ -55,6 +57,7 @@ CODE_SOURCE_UNAUTHORIZED = "CHTYPES_SOURCE_UNAUTHORIZED"
 CODE_SOURCE_FORBIDDEN = "CHTYPES_SOURCE_FORBIDDEN"
 CODE_SOURCE_INCOMPATIBLE = "CHTYPES_SOURCE_INCOMPATIBLE"
 CODE_CACHE_UNUSABLE = "CHTYPES_CACHE_UNUSABLE"
+CODE_SOURCE_RETIRED = "CHTYPES_SOURCE_RETIRED"
 
 _CODES_USED_HERE = (
     CODE_ARTIFACT_MISSING,
@@ -67,6 +70,7 @@ _CODES_USED_HERE = (
     CODE_SOURCE_FORBIDDEN,
     CODE_SOURCE_INCOMPATIBLE,
     CODE_CACHE_UNUSABLE,
+    CODE_SOURCE_RETIRED,
 )
 
 # A drift guard, cheaper than a test: every code this module raises must be
@@ -187,3 +191,13 @@ class CacheUnusableError(FetchError):
         self.path = path
         self.reason = reason
         self.os_error = os_error
+
+
+class SourceRetiredError(FetchError):
+    """The source answered 410 Gone: a retired repository, which is permanent,
+    so the request was never retried and never sent to the next base
+    (docs/guides/fetch-v1.md §2, "A retired repository"; public issue #571).
+    The message names the URL that answered and carries the registry's own
+    message, made safe to print."""
+
+    code = CODE_SOURCE_RETIRED

chtypes/_ocifetch/_http.py

@@ -29,6 +29,7 @@ from email.utils import parsedate_to_datetime
 from urllib.parse import urljoin, urlsplit, urlunsplit
 
 from chtypes._ocifetch import _constants as C
+from chtypes._ocifetch._retired import retired_text
 
 __all__ = [
     "USER_AGENT",
@@ -38,6 +39,7 @@ __all__ = [
     "HttpResponse",
     "NotFoundHttpError",
     "OversizeHttpError",
+    "RetiredHttpError",
     "RetryPolicy",
     "TransportError",
     "UnauthorizedHttpError",
@@ -120,6 +122,13 @@ class OversizeHttpError(TransportError):
     """A response body exceeded the caller's declared size cap."""
 
 
+class RetiredHttpError(TransportError):
+    """A retired repository (`RETIRED_STATUSES`, a 410; docs/guides/fetch-v1.md
+    §2): permanent, so never retried and never a reason to try the next base.
+    Its text names the URL that answered and carries the registry's message,
+    made safe to print (`_retired.retired_message`)."""
+
+
 class Clock:
     """The real wall clock. Tests inject a fake with the same interface so
     retry cases run instantly and sleeps are asserted exactly."""
@@ -228,7 +237,16 @@ def _single_request(
             )
     except urllib.error.HTTPError as e:
         try:
-            body = _read_capped(e, max_bytes) if e.code not in _REDIRECT_CODES else b""
+            if e.code in C.RETIRED_STATUSES:
+                # Only the registry's message is wanted from a retired
+                # repository's answer: at most RETIRED_BODY_MAX_BYTES of it,
+                # and a body that fails part way is no body.
+                try:
+                    body = e.read(C.RETIRED_BODY_MAX_BYTES)
+                except (OSError, ValueError, AttributeError):
+                    body = b""
+            else:
+                body = _read_capped(e, max_bytes) if e.code not in _REDIRECT_CODES else b""
         finally:
             e.close()
         return HttpResponse(status=e.code, headers=dict(e.headers or {}), body=body, url=url)
@@ -380,6 +398,11 @@ def _http_get_once(
             headers.pop("Authorization", None)
             continue
 
+        if resp.status in C.RETIRED_STATUSES:
+            # A retired repository: permanent, never retried, and the
+            # exception ends fetch_from_bases's loop over bases.
+            raise RetiredHttpError(retired_text(current_url, resp.status, resp.body))
+
         if resp.status == 401:
             if not tried_anon_flow and not policy.token:
                 challenge = resp.headers.get("WWW-Authenticate") or resp.headers.get(
@@ -523,6 +546,10 @@ def fetch_from_bases(
     404, some unreachable — the outcome follows the LAST base tried, since
     bases are an explicit preference order and the last one is the final
     word a caller configured.
+
+    In every mode a retired repository (`RetiredHttpError`, a 410) ends the
+    loop on the base that answered it: it is permanent, never a reason to try
+    the next base, and in `alias` mode never a reason to fall back to the tag.
     """
     if not bases:
         raise UnreachableHttpError("no base URLs configured")

chtypes/_ocifetch/_oci.py

@@ -249,15 +249,19 @@ def fetch_manifest_by_tag(
     retry: RetryPolicy,
     max_bytes: int = C.MANIFEST_MAX_BYTES,
     alias: str | None = None,
-) -> tuple[dict, bytes, str]:
-    """GET manifests/<tag>; returns (doc, raw_bytes, resolved_digest).
+) -> tuple[dict, bytes, str, bool]:
+    """GET manifests/<tag>; returns (doc, raw_bytes, resolved_digest, alias_absent).
 
     With `alias` (the dev channel's `<tag>--fp-<fingerprint>`, from
     `_channel.alias_tag`), GET manifests/<alias> first, and the tag only when
     every base answered the alias 404 (docs/guides/fetch-v1.md §3); any other
     failure of the alias request is raised as it is. What is returned is then
-    trusted exactly as the tag's own answer would be."""
+    trusted exactly as the tag's own answer would be. `alias_absent` reports
+    that fallback: the alias was asked for and every base answered it 404, so
+    the registry has no build at this SDK's fingerprint, and the build the tag
+    names is checked against it (`_channel.ahead_of_registry`)."""
     accept = (C.MEDIA_TYPE_INDEX, C.MEDIA_TYPE_MANIFEST)
+    alias_absent = False
     if alias is not None:
         try:
             doc, resp = get_json(
@@ -270,9 +274,9 @@ def fetch_manifest_by_tag(
                 retry=retry,
             )
         except AliasNotFoundError:
-            pass
+            alias_absent = True
         else:
-            return doc, resp.body, f"sha256:{hashlib.sha256(resp.body).hexdigest()}"
+            return doc, resp.body, f"sha256:{hashlib.sha256(resp.body).hexdigest()}", False
     doc, resp = get_json(
         bases,
         f"/manifests/{tag}",
@@ -283,7 +287,7 @@ def fetch_manifest_by_tag(
         retry=retry,
     )
     digest = f"sha256:{hashlib.sha256(resp.body).hexdigest()}"
-    return doc, resp.body, digest
+    return doc, resp.body, digest, alias_absent
 
 
 def fetch_blob_to_path(

chtypes/_ocifetch/_retired.py

@@ -0,0 +1,77 @@
+"""A retired repository (docs/guides/fetch-v1.md §2, "A retired repository";
+public issue #571).
+
+The registry's operator answers every route of a retired repository with 410
+Gone (`RETIRED_STATUSES`) and a short error document. That is permanent: the
+transport never retries it and never asks the next base, so the caller sees
+`CHTYPES_SOURCE_RETIRED` with the URL that answered and the registry's own
+message, made safe to print by `retired_message`, the one function every
+binding has (tests/fixtures/retired-message/cases.json is the table all four
+answer alike).
+"""
+
+from __future__ import annotations
+
+import json
+
+from chtypes._ocifetch import _constants as C
+
+__all__ = ["retired_message", "retired_text"]
+
+_ELLIPSIS = "…"
+
+
+def _removed(code_point: int) -> bool:
+    return (
+        code_point <= 0x1F
+        or 0x7F <= code_point <= 0x9F
+        or code_point in (0x200E, 0x200F)
+        or 0x202A <= code_point <= 0x202E
+        or 0x2066 <= code_point <= 0x2069
+    )
+
+
+def _not_json(name: str) -> None:
+    # `json.loads` accepts NaN, Infinity and -Infinity, which are not JSON;
+    # the other three bindings' readers refuse them.
+    raise ValueError(f"{name} is not JSON")
+
+
+def retired_message(body: bytes) -> str | None:
+    """The registry's own message in a retired repository's response body,
+    made safe to print, or None when it sent none.
+
+    `body` is what was read of it (at most `RETIRED_BODY_MAX_BYTES`). When it is
+    UTF-8 JSON whose `errors[0].message` is a string, that string is the
+    message: every code point in U+0000-U+001F, U+007F-U+009F, U+200E, U+200F,
+    U+202A-U+202E and U+2066-U+2069 is removed, and the rest is cut to
+    `RETIRED_MESSAGE_MAX_CODE_POINTS` code points, with U+2026 appended when it
+    was cut. Nothing else is changed, and an empty result is no message."""
+    try:
+        text = body.decode("utf-8")
+        doc = json.loads(text, parse_constant=_not_json)
+    except (UnicodeDecodeError, ValueError, RecursionError):
+        return None
+    if not isinstance(doc, dict):
+        return None
+    errors = doc.get("errors")
+    if not isinstance(errors, list) or not errors or not isinstance(errors[0], dict):
+        return None
+    message = errors[0].get("message")
+    # A lone surrogate escape is not a Unicode string (and could not be printed).
+    if not isinstance(message, str) or any("\ud800" <= ch <= "\udfff" for ch in message):
+        return None
+    kept = [ch for ch in message if not _removed(ord(ch))]
+    if len(kept) > C.RETIRED_MESSAGE_MAX_CODE_POINTS:
+        kept = [*kept[: C.RETIRED_MESSAGE_MAX_CODE_POINTS], _ELLIPSIS]
+    return "".join(kept) or None
+
+
+def retired_text(url: str, status: int, body: bytes) -> str:
+    """The error text for a retired repository's answer: the URL and status
+    that answered, and the registry's message when it sent one."""
+    text = f"{url} answered {status} Gone: the repository is retired"
+    message = retired_message(body)
+    if message is not None:
+        text += f"; the registry says: {message}"
+    return text

chtypes/errors.py

@@ -31,6 +31,7 @@ __all__ = [
     "CODE_CACHE_UNUSABLE",
     "CODE_SOURCE_FORBIDDEN",
     "CODE_SOURCE_INCOMPATIBLE",
+    "CODE_SOURCE_RETIRED",
     "CODE_SOURCE_UNAUTHORIZED",
     "CODE_SOURCE_UNREACHABLE",
     "ArtifactCorruptError",
@@ -47,6 +48,7 @@ __all__ = [
     "SchemaError",
     "SourceForbiddenError",
     "SourceIncompatibleError",
+    "SourceRetiredError",
     "SourceUnauthorizedError",
     "SourceUnreachableError",
     "UnsupportedError",
@@ -66,6 +68,7 @@ CODE_SOURCE_UNAUTHORIZED = "CHTYPES_SOURCE_UNAUTHORIZED"
 CODE_SOURCE_FORBIDDEN = "CHTYPES_SOURCE_FORBIDDEN"
 CODE_SOURCE_INCOMPATIBLE = "CHTYPES_SOURCE_INCOMPATIBLE"
 CODE_CACHE_UNUSABLE = "CHTYPES_CACHE_UNUSABLE"
+CODE_SOURCE_RETIRED = "CHTYPES_SOURCE_RETIRED"
 
 # `chs_status` value of CHS_INVALID_ARGUMENT. The binding's own misuse errors
 # carry it so a handler sees one shape whichever side caught the misuse. It is
@@ -258,6 +261,15 @@ class SourceIncompatibleError(ArtifactError):
     code = CODE_SOURCE_INCOMPATIBLE
 
 
+class SourceRetiredError(ArtifactError):
+    """The source answered 410 Gone: a retired repository, which is permanent,
+    so the request was never retried and never sent to the next base. The
+    message names the URL that answered and carries the registry's own
+    message, made safe to print."""
+
+    code = CODE_SOURCE_RETIRED
+
+
 class CacheUnusableError(ArtifactError):
     """A cache directory or entry the fetch layer could not read or write, or
     one strict mode refuses: never "not installed", never the network's

chtypes/registry.py

@@ -51,6 +51,7 @@ _FETCH_CLASSES: dict[str, type[errors.ArtifactError]] = {
     errors.CODE_SOURCE_FORBIDDEN: errors.SourceForbiddenError,
     errors.CODE_SOURCE_INCOMPATIBLE: errors.SourceIncompatibleError,
     errors.CODE_CACHE_UNUSABLE: errors.CacheUnusableError,
+    errors.CODE_SOURCE_RETIRED: errors.SourceRetiredError,
 }
 
 

chtypes/results.py

@@ -14,7 +14,7 @@ from __future__ import annotations
 from collections.abc import Mapping
 from dataclasses import dataclass
 
-from ._abi2._vocab import DefaultKind, FilterOutcome, MergeReason, Outcome, Verdict
+from ._abi2._vocab import DeclinedTier, DefaultKind, FilterOutcome, MergeReason, Outcome, Verdict
 
 __all__ = [
     "AtMergeEntry",
@@ -23,6 +23,7 @@ __all__ = [
     "Capabilities",
     "Column",
     "Computed",
+    "DeclinedSetting",
     "DiscoveredColumn",
     "EngineCell",
     "Discovery",
@@ -223,8 +224,10 @@ class FilterRowError:
 
 @dataclass(frozen=True, slots=True)
 class FilterResult:
-    """The `filter_result` document. `e` and `d` are never answers, and a caller
-    enforcing visibility fails closed on both; `Verdict.answered` says which."""
+    """The `filter_result` document. A verdict counts only when `outcome` is `ok`;
+    otherwise treat every verdict as `d`, whatever the verdict string holds. Under
+    `ok`, `e` and `d` are never answers, and a caller enforcing visibility fails
+    closed on both; `Verdict.answered` says which."""
 
     outcome: FilterOutcome
     err_code: int
@@ -247,6 +250,18 @@ class Column:
     default_expr: bytes
 
 
+@dataclass(frozen=True, slots=True)
+class DeclinedSetting:
+    """One setting a server's profile sets that this build's filters do not honor
+    in a WHERE: an entry of the server's `filter_declined_settings` (ABI v2).
+    `name` is bytes (from `name` or `name_b64`). `tier` is the tier this build
+    line's WHERE-settings list gives it, a `DeclinedTier`; one the description
+    does not list is its unknown(n) member (rule r3)."""
+
+    name: bytes
+    tier: DeclinedTier
+
+
 @dataclass(frozen=True, slots=True)
 class SchemaServer:
     """The server a schema was compiled on, as the library holds it. Its strings
@@ -254,11 +269,17 @@ class SchemaServer:
     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)."""
+    (unknown), and a mapping, even an empty one, when it did (the complete set).
+    `filter_declined_settings` is the settings the profile sets that this
+    build's filters do not honor in a WHERE, in the profile's own order, empty
+    when it lists none: a schema on a server that lists any is one
+    `compile_filter` declines (`UnsupportedError`), and a consumer that streams
+    rows refuses such a tenant (spec/abi-v2/where-settings/README.md)."""
 
     timezone: str
     settings: Mapping[str, str]
     macros: Mapping[str, str] | None
+    filter_declined_settings: tuple[DeclinedSetting, ...] = ()
 
 
 @dataclass(frozen=True, slots=True)

{chtypes-2.0.0.dev3.dist-info → chtypes-2.0.0.dev4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: chtypes
-Version: 2.0.0.dev3
+Version: 2.0.0.dev4
 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
@@ -22,6 +22,8 @@ Description-Content-Type: text/markdown
 > **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. A dev SDK prefers the newest build of its own fingerprint: it resolves `<tag>--fp-<its fingerprint>` first and the tag only when no such build exists, and its cache lookups ignore another dev SDK's builds in a shared cache, so a newer dev fingerprint never strands it (§3 of [`docs/guides/fetch-v1.md`](../docs/guides/fetch-v1.md)). 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.
+>
+> <!-- remove-at-v2-lock -->v2-dev builds before the one that carries this contract (its release notice names it) can answer `ok` with `t` verdicts after a refused row. On those builds, when a body or block holds more than one row, treat every verdict as `d` if `errors` is non-empty.<!-- /remove-at-v2-lock -->
 
 **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.
 

{chtypes-2.0.0.dev3.dist-info → chtypes-2.0.0.dev4.dist-info}/RECORD

@@ -1,37 +1,38 @@
-chtypes/__init__.py,sha256=zKL5Y9XuiwZb-Ewfgvhr9IFxdpqpBS7Ub2ca68ZOxJc,5993
+chtypes/__init__.py,sha256=9xXEUgqnxJmAjUbz8X3coym4UyM01HShX7Lrds751VM,6177
 chtypes/__main__.py,sha256=XYGNTpTLXI1AUp7srvuNVv2SZAcfwLaXpoXRVInyhF4,14030
-chtypes/_decode.py,sha256=5f-OamDm8Qx17FAWOdHO7ng7r16ZRtYy6QKn1LlnVrc,22207
+chtypes/_decode.py,sha256=v5pdwphwAldVzgHg6saWsxqUFjMHqcMO-XOuDyuRVZg,22686
 chtypes/_ed25519.py,sha256=uwaAKWvgoc936e1ZfgLrtR47W87WWCL541kFaqBXrB0,4141
 chtypes/_guard.py,sha256=zTtwprCS0XvGWY7GDozo-IP6GwjMAWl-o-AjShdCSVI,1985
 chtypes/_input.py,sha256=i4OUmgmHxx618g0DVFYy8LmHhggfBT03NyMxH3ptZBI,6020
 chtypes/_setup.py,sha256=n84T0hFmXu_fdnXQIFhk3dMVL0_-yhfdRZsqCXTLzzg,6114
-chtypes/errors.py,sha256=9qv94rxbe7hm7lSVFG33Qri82FwDtCY-EnJiwnMfkp8,9501
+chtypes/errors.py,sha256=7gDi9Ij8yptrr9E0LZyA2XkeaFFVyZoQMVQjQj6mn0s,9936
 chtypes/library.py,sha256=G6DJFiRuv8--JARxfiSNEqeFLkafaMs_n9nG-IwoC74,17878
 chtypes/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-chtypes/registry.py,sha256=HTrzS_3HjOkH4rU90AVMNfFLsLoaut0jgNlt_BJ28QY,13727
-chtypes/results.py,sha256=6uvfkt8dLd-F9aXyxdzWU5_kDVRVirhwB3fcH5NhJDA,11037
+chtypes/registry.py,sha256=Q3LR7wBs7Ggy_5xG_-0bZrTRgvRWJO5OJbD92ecUlt4,13786
+chtypes/results.py,sha256=OnxFUNyhlNeA2jwsMVAqYjKjmqguvKtWzrCwi7F6CFM,12123
 chtypes/_abi2/__init__.py,sha256=d3i7_iUDMFT1jg49vRQz1SMH6oseYZHUR0oPt6aSTiY,1042
-chtypes/_abi2/_decls.py,sha256=ZFJUVXYIlyuKVRJyVh8KVxkT4GZjsY-CeCcohK4sWMQ,38454
-chtypes/_abi2/_errmap.py,sha256=uQZ_rMaUU-tk1rSJ5wq_EjOkjesGeF-BKDJOs00KK3I,2886
+chtypes/_abi2/_decls.py,sha256=X88Ylb33Sw5iJjikVTfVzdgCfjGvKpn4F3mT0qAnD7I,38454
+chtypes/_abi2/_errmap.py,sha256=vNPgHFV742Px2aTyYqJez7I3qXRq80AOUcMqDvyPGFI,2886
 chtypes/_abi2/_errors.py,sha256=wRE9M0oYtJz_9izQqpEBh5571M_1QzGWBoJ3pJTykWw,761
 chtypes/_abi2/_loader.py,sha256=VMWrbWMp9Uq3K-7a219lfqAmSmBlD2hcB6WDJgG8XG0,12514
-chtypes/_abi2/_vocab.py,sha256=kH58IzFHpK93ihNBo8UKMtJM6-umxbCaCZlFcqCk7Ro,15543
+chtypes/_abi2/_vocab.py,sha256=rzbenqXqDoWZkvpjRw0UUBEkgWoOtE462QUGyCE3cTw,16516
 chtypes/_ocifetch/__init__.py,sha256=enfPOKkqP4kqAKqckBGWXN1OQsiYo9ngDP-wzG0zn2I,1484
-chtypes/_ocifetch/_channel.py,sha256=yqnb35GGxdviipspR3B10t6ZgI8RJMFvW7AnB7zYYfs,15981
-chtypes/_ocifetch/_constants.py,sha256=UdOGIShDXaDP13NGbuftKZRE4u7VK8JfZmoeChw4GMU,5467
+chtypes/_ocifetch/_channel.py,sha256=2L-sSetXv4iF0mpsIX4-iTAhNbu9eY1IsGnb4WTptwM,17980
+chtypes/_ocifetch/_constants.py,sha256=IZtAK3oxnCELZysvrzRozJkntxKSQllGjxod5No-Kco,5644
 chtypes/_ocifetch/_dsse.py,sha256=0RaFJaG1jhXr1uPfuHxm7yAn6viNzYhfCRUf-sW5SvQ,9333
-chtypes/_ocifetch/_ensure.py,sha256=gbUSpWvdXP9f6dlFWPk67Cl_bPJ02ehTRLkDrSVNnHI,61565
-chtypes/_ocifetch/_errors.py,sha256=u0eIdrr3g00ugy8ZZoAXYIgUuZgEs6eMue2QkcWXC6w,6595
+chtypes/_ocifetch/_ensure.py,sha256=GtuYJJXhL0TbUypx94OPr3BhnkrQoHuWjZdPYrvpLgw,62597
+chtypes/_ocifetch/_errors.py,sha256=TTYpwhvZ7MyD9Ssg5js8_YB8Fl30rYBPlENyAetqEbQ,7129
 chtypes/_ocifetch/_faults.py,sha256=HpoB9tJW7aLRiJdCFnspzkwhpFATZ6f6hGi49Mbfnhs,7609
 chtypes/_ocifetch/_goldens.py,sha256=8MicgeJSRd4WZkaEsdujRnOa7twQvbT-wfSMPZaD-ms,4191
-chtypes/_ocifetch/_http.py,sha256=DGUW6ym9mrxOgn-9FcdqzuvVGcG9WJGlYyGHnkUvGRA,23817
+chtypes/_ocifetch/_http.py,sha256=e1zAWu-2gvBe3FNE5bZ7jmz2OPn1bzImPfHWvA10O_4,25179
 chtypes/_ocifetch/_layout.py,sha256=ezEoVrsSMhvDhQ4U04hsGdu1-_ISZQ4V6zg4gGIChTQ,21300
 chtypes/_ocifetch/_lock.py,sha256=14_uex9qXdOht-5FSrSvFvd99-gB7DmI3bDuxXs4YU8,5530
-chtypes/_ocifetch/_oci.py,sha256=YJi8y2iKIRh1_YI8lodWZXRxQfb_KrD5BhM-TQA1SCo,13595
+chtypes/_ocifetch/_oci.py,sha256=UdA8QGTh1O27DBYRf5UxsevjgI52IecQlEf9IO6Y0A4,13920
 chtypes/_ocifetch/_referrers.py,sha256=J2b4gN6vryz_IzYHxrd2Tp-tQO9Cz766rZtKgCVcKqA,6008
+chtypes/_ocifetch/_retired.py,sha256=MQ6nbWLJw50IZYY1VfM6AiCZ4BySK0GVkGVOtAXaq3Y,3060
 chtypes/_ocifetch/_unpack.py,sha256=Cn4-up63KL63L8pnkS5zwJ6VbbHPSigpCnmOdcHJ4RI,5609
-chtypes-2.0.0.dev3.dist-info/METADATA,sha256=pCbL5T3EMtLWBTmEaHMGlNSjnUUQOJwYEWF5k7ycUk0,10966
-chtypes-2.0.0.dev3.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-chtypes-2.0.0.dev3.dist-info/entry_points.txt,sha256=TdNcluWBR0VOt5mVFROsp-NiVPAdR3EHo0UsHlMC0r0,50
-chtypes-2.0.0.dev3.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-chtypes-2.0.0.dev3.dist-info/RECORD,,
+chtypes-2.0.0.dev4.dist-info/METADATA,sha256=xGAOsOpaNNPKh1cxhmBitwUrzSsCgiwBOqNltkBmWO0,11280
+chtypes-2.0.0.dev4.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+chtypes-2.0.0.dev4.dist-info/entry_points.txt,sha256=TdNcluWBR0VOt5mVFROsp-NiVPAdR3EHo0UsHlMC0r0,50
+chtypes-2.0.0.dev4.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+chtypes-2.0.0.dev4.dist-info/RECORD,,