dialcache 0.25.0__tar.gz → 0.26.0__tar.gz

{dialcache-0.25.0 → dialcache-0.26.0}/API-DESIGN.md

@@ -4,11 +4,22 @@ The Python binding was designed after reviewing [rungalileo/gcache at a688049](h
 
 DialCache's [Quint specification](../formal/SPEC.md) and TypeScript implementation define portable behavior. Gcache supplies useful Python interface ideas; its implementation is not a compatible DialCache backend.
 
+The primary decorator style selects identity explicitly with
+`cache_key=lambda user_id, locale: {"id": user_id, "args": {"locale": locale}}`
+and a stable `use_case`. This follows TypeScript's `cacheKey` while retaining
+Python decorator syntax. The selector makes result dimensions and their wire
+names explicit; it must include every input that affects the result.
+
+Selectors receive the loader's original `*args` and `**kwargs`. Match parameter
+names and defaults so positional, keyword, and omitted-default calls select
+the intended identity. Loader defaults are not injected into the selector;
+changing that behavior could change existing keys or break existing callbacks.
+
 | Gcache interface or behavior | Python DialCache decision |
 | --- | --- |
 | `with cache.enable(enabled=True)` | Retained, with per-instance context variables and explicit outer-scope lifetime. Also supports `async with` and `disable()`. |
-| `@cache.cached(key_type=..., id_arg=...)` | Retained. `id_arg` can be a parameter name or `(name, adapter)` pair. Signature binding includes defaults. |
-| `arg_adapters`, `ignore_args`, inferred use case | Retained; inferred names include module and qualified function name. Argument names use the portable UTF-16 ordering and scalar normalization. |
+| `@cache.cached(key_type=..., id_arg=...)` | Supported alternative to explicit `cache_key` selection. `id_arg` can be a parameter name or `(name, adapter)` pair. Signature binding includes defaults. |
+| `arg_adapters`, `ignore_args`, inferred use case | Inferred argument controls remain supported. Default use-case names include module and qualified function name; prefer explicit names for stability across refactors and languages. Argument names use the portable UTF-16 ordering and scalar normalization. |
 | Direct `aget(key, fallback)` | Retained as a structured-key convenience; `get_or_load` is the primary inline-loader API. |
 | `ainvalidate` | Retained as an alias for `invalidate_remote`; missing Redis and failed mutations raise. |
 | `GCacheKeyConfig` and per-use-case provider | `Policy` / `DialCacheKeyConfig` use sparse per-leaf inheritance and deterministic per-key cohorts. `Policy.enabled(ttl_sec)` is available. |

{dialcache-0.25.0 → dialcache-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dialcache
-Version: 0.25.0
+Version: 0.26.0
 Summary: Explicitly enabled async caching with runtime policies, coalescing, and tracked Redis invalidation.
 Project-URL: Repository, https://github.com/lan17/DialCache
 Project-URL: Documentation, https://github.com/lan17/DialCache/tree/main/python
@@ -21,6 +21,7 @@ Requires-Dist: redis<7,>=5; extra == 'redis'
 Provides-Extra: test
 Requires-Dist: coverage<8,>=7.11; extra == 'test'
 Requires-Dist: jsonschema<5,>=4.23; extra == 'test'
+Requires-Dist: mypy<2,>=1.15; extra == 'test'
 Requires-Dist: pytest-asyncio<2,>=0.24; extra == 'test'
 Requires-Dist: pytest<10,>=8; extra == 'test'
 Description-Content-Type: text/markdown
@@ -50,6 +51,9 @@ any Redis client connections.
 
 ## A cached function
 
+Select cache identity explicitly with `cache_key`. This API excerpt assumes an
+application `database`:
+
 ```python
 from dialcache import DialCache, Policy
 
@@ -59,20 +63,33 @@ cache = DialCache(namespace="my-service")
 @cache.cached(
     use_case="user-profile",
     key_type="user",
-    id_arg="user_id",
+    cache_key=lambda user_id, locale: {"id": user_id, "args": {"locale": locale}},
     default_config=Policy(ttl_sec={"local": 5}, request_local=True),
 )
-async def get_profile(user_id: str) -> dict:
-    return await database.fetch_profile(user_id)
+async def get_profile(user_id: str, locale: str) -> dict:
+    return await database.fetch_profile(user_id, locale)
 
 
-async def handle_request(user_id: str) -> dict:
+async def handle_request(user_id: str, locale: str) -> dict:
     async with cache.enable():
-        first = await get_profile(user_id)
-        second = await get_profile(user_id)  # Same request memo.
+        first = await get_profile(user_id, locale)
+        second = await get_profile(user_id, locale)  # Same request memo.
         return second
 ```
 
+The selector returns an entity ID, or `{"id": ..., "args": {...}}` when the
+result has additional dimensions. Here, `id` groups the user's tracked values
+for invalidation; `args` distinguishes locales within this use case. Include
+every input that affects the result, including tenant or authorization scope
+when relevant. Explicit `use_case` and argument names keep identity stable
+across function refactors and languages.
+
+The selector receives the same positional and keyword arguments as the loader.
+Match their parameter names and repeat any defaults the loader accepts; loader
+defaults are not filled in before calling the selector. For inferred identity,
+`id_arg`, `arg_adapters`, and `ignore_args` remain supported alternatives; see
+the [Python identity guide](https://lan17.github.io/DialCache/languages/python.html#identity-and-policy).
+
 Calls outside `enable()` go directly to the source. They do not construct cache
 keys, resolve policy, share concurrent work, or apply a DialCache source
 deadline. Both `with cache.enable():` and `async with cache.enable():` are valid;
@@ -157,7 +174,7 @@ cache = DialCache(redis=RedisAdapter(client))
 @cache.cached(
     use_case="user-profile",
     key_type="user",
-    id_arg="user_id",
+    cache_key=lambda user_id: user_id,
     track_for_invalidation=True,
     default_config=Policy(ttl_sec={"remote": 60}),
 )

{dialcache-0.25.0 → dialcache-0.26.0}/README.md

@@ -23,6 +23,9 @@ any Redis client connections.
 
 ## A cached function
 
+Select cache identity explicitly with `cache_key`. This API excerpt assumes an
+application `database`:
+
 ```python
 from dialcache import DialCache, Policy
 
@@ -32,20 +35,33 @@ cache = DialCache(namespace="my-service")
 @cache.cached(
     use_case="user-profile",
     key_type="user",
-    id_arg="user_id",
+    cache_key=lambda user_id, locale: {"id": user_id, "args": {"locale": locale}},
     default_config=Policy(ttl_sec={"local": 5}, request_local=True),
 )
-async def get_profile(user_id: str) -> dict:
-    return await database.fetch_profile(user_id)
+async def get_profile(user_id: str, locale: str) -> dict:
+    return await database.fetch_profile(user_id, locale)
 
 
-async def handle_request(user_id: str) -> dict:
+async def handle_request(user_id: str, locale: str) -> dict:
     async with cache.enable():
-        first = await get_profile(user_id)
-        second = await get_profile(user_id)  # Same request memo.
+        first = await get_profile(user_id, locale)
+        second = await get_profile(user_id, locale)  # Same request memo.
         return second
 ```
 
+The selector returns an entity ID, or `{"id": ..., "args": {...}}` when the
+result has additional dimensions. Here, `id` groups the user's tracked values
+for invalidation; `args` distinguishes locales within this use case. Include
+every input that affects the result, including tenant or authorization scope
+when relevant. Explicit `use_case` and argument names keep identity stable
+across function refactors and languages.
+
+The selector receives the same positional and keyword arguments as the loader.
+Match their parameter names and repeat any defaults the loader accepts; loader
+defaults are not filled in before calling the selector. For inferred identity,
+`id_arg`, `arg_adapters`, and `ignore_args` remain supported alternatives; see
+the [Python identity guide](https://lan17.github.io/DialCache/languages/python.html#identity-and-policy).
+
 Calls outside `enable()` go directly to the source. They do not construct cache
 keys, resolve policy, share concurrent work, or apply a DialCache source
 deadline. Both `with cache.enable():` and `async with cache.enable():` are valid;
@@ -130,7 +146,7 @@ cache = DialCache(redis=RedisAdapter(client))
 @cache.cached(
     use_case="user-profile",
     key_type="user",
-    id_arg="user_id",
+    cache_key=lambda user_id: user_id,
     track_for_invalidation=True,
     default_config=Policy(ttl_sec={"remote": 60}),
 )

{dialcache-0.25.0 → dialcache-0.26.0}/dialcache/__init__.py

@@ -12,7 +12,7 @@ from .errors import (
     UseCaseIsAlreadyRegisteredError,
     UseCaseNameIsReservedError,
 )
-from .key import Key, normalize_args
+from .key import CacheKeySpec, Key, KeyScalar, normalize_args
 from .serializer import UNDEFINED, JsonSerializer, Serializer
 
 __all__ = [
@@ -22,6 +22,8 @@ __all__ = [
     "DialCacheKeyConfig",
     "CacheLayer",
     "Key",
+    "CacheKeySpec",
+    "KeyScalar",
     "normalize_args",
     "Serializer",
     "JsonSerializer",

{dialcache-0.25.0 → dialcache-0.26.0}/dialcache/cache.py

@@ -14,9 +14,9 @@ import inspect
 import json
 import logging
 import math
-from collections.abc import Awaitable, Callable, Mapping
+from collections.abc import Awaitable, Callable, Coroutine, Mapping
 from dataclasses import dataclass, field
-from typing import Any, ParamSpec, TypeVar
+from typing import Any, ParamSpec, Protocol, TypeVar, overload
 
 from .clock import SystemClock
 from .config import UNSET, Policy, _valid_ramp, merge_policy, resolve_layer, validate_static_policy
@@ -29,7 +29,7 @@ from .errors import (
     UseCaseIsAlreadyRegisteredError,
     UseCaseNameIsReservedError,
 )
-from .key import Key, invalidation_prefix, normalize_args, ramp_sample
+from .key import Key, KeyScalar, invalidation_prefix, normalize_args, ramp_sample
 from .local import LocalCache
 from .metrics import Metrics, emit_metric
 from .protocol import Frame, Miss, compress_payload, decompress_payload, escape_raw_payload, utf8_bytes
@@ -41,6 +41,14 @@ P = ParamSpec("P")
 MAX_SAFE = 9_007_199_254_740_991
 
 
+class _CachedDecorator(Protocol):
+    @overload
+    def __call__(self, fn: Callable[P, Awaitable[T]], /) -> Callable[P, Coroutine[Any, Any, T]]: ...
+
+    @overload
+    def __call__(self, fn: Callable[P, T | Awaitable[T]], /) -> Callable[P, Coroutine[Any, Any, T]]: ...
+
+
 async def _await(value: Any) -> Any:
     return await value if inspect.isawaitable(value) else value
 
@@ -243,22 +251,31 @@ class DialCache:
         self,
         *,
         key_type: str,
-        cache_key: Callable[..., Any] | None = None,
+        cache_key: Callable[..., Mapping[str, object] | KeyScalar | Key] | None = None,
         id_arg: str | tuple[str, Callable[[Any], Any]] | None = None,
         use_case: str | None = None,
         arg_adapters: Mapping[str, Callable[[Any], Any]] | None = None,
         ignore_args: list[str] | tuple[str, ...] = (),
         **options: Any,
-    ) -> Callable[..., Any]:
-        """Decorate a loader using an explicit selector or gcache-style arguments.
+    ) -> _CachedDecorator:
+        """Decorate a loader with explicit cache_key selection (recommended) or id_arg.
 
         The wrapper is always awaitable, including for a synchronous loader.
         Key callbacks and argument adapters are never called while disabled.
+        An explicit selector receives the original positional and keyword
+        arguments, including self for methods. Loader defaults are not injected:
+        declare matching defaults on the selector when callers can omit them.
         """
         if (cache_key is None) == (id_arg is None):
             raise ConfigError("Supply exactly one of cache_key or id_arg")
 
-        def decorate(fn: Callable[P, T | Awaitable[T]]) -> Callable[P, Awaitable[T]]:
+        @overload
+        def decorate(fn: Callable[P, Awaitable[T]]) -> Callable[P, Coroutine[Any, Any, T]]: ...
+
+        @overload
+        def decorate(fn: Callable[P, T | Awaitable[T]]) -> Callable[P, Coroutine[Any, Any, T]]: ...
+
+        def decorate(fn: Callable[P, T | Awaitable[T]]) -> Callable[P, Coroutine[Any, Any, T]]:
             name = use_case or f"{fn.__module__}.{fn.__qualname__}"
             self._check_use_case(name)
             if name in self._registered:

{dialcache-0.25.0 → dialcache-0.26.0}/dialcache/key.py

@@ -5,9 +5,19 @@ from __future__ import annotations
 import math
 from collections.abc import Mapping, Sequence
 from dataclasses import dataclass, field
+from typing import NotRequired, TypeAlias, TypedDict
 from urllib.parse import quote
 
-from .serializer import UNDEFINED
+from .serializer import UNDEFINED, _Undefined
+
+KeyScalar: TypeAlias = str | int | float | bool | None
+
+
+class CacheKeySpec(TypedDict):
+    """An entity id and the explicit result dimensions selected for a cache key."""
+
+    id: KeyScalar
+    args: NotRequired[Mapping[str, KeyScalar | _Undefined]]
 
 
 def _integer_string(value: int) -> str:

{dialcache-0.25.0 → dialcache-0.26.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dialcache"
-version = "0.25.0"
+version = "0.26.0"
 description = "Explicitly enabled async caching with runtime policies, coalescing, and tracked Redis invalidation."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -24,7 +24,7 @@ classifiers = [
 
 [project.optional-dependencies]
 redis = ["redis>=5,<7"]
-test = ["pytest>=8,<10", "pytest-asyncio>=0.24,<2", "jsonschema>=4.23,<5", "coverage>=7.11,<8"]
+test = ["pytest>=8,<10", "pytest-asyncio>=0.24,<2", "jsonschema>=4.23,<5", "coverage>=7.11,<8", "mypy>=1.15,<2"]
 
 [project.urls]
 Repository = "https://github.com/lan17/DialCache"

{dialcache-0.25.0 → dialcache-0.26.0}/tests/run_integration.py

@@ -49,18 +49,27 @@ class Acceptance:
 
 
 root = Path(__file__).resolve().parents[2]
+suite = sys.argv[2:] or ["--suite", "native"]
+if suite not in (["--suite", "native"], ["--suite", "wire"]):
+    raise SystemExit("Expected report path followed by --suite native|wire")
+files = (
+    [root / "interop/test_wire_interop.py"]
+    if suite[1] == "wire"
+    else [root / "python/tests/test_redis_integration.py", root / "python/tests/test_docs_examples.py"]
+)
 gate = Acceptance()
 status = pytest.main(
     [
         "-c",
         str(root / "python/pyproject.toml"),
+        "--rootdir",
+        str(root),
         "-o",
         "addopts=",
         "--noconftest",
         "-p",
         "pytest_asyncio.plugin",
-        str(root / "python/tests/test_redis_integration.py"),
-        str(root / "python/tests/test_docs_examples.py"),
+        *map(str, files),
         "-m",
         "integration",
         "-q",

dialcache-0.26.0/tests/test_cached_keys.py

@@ -0,0 +1,123 @@
+"""Public explicit-selector semantics, including Python invocation conventions."""
+
+import pytest
+
+from dialcache import UNDEFINED, DialCache, Key, Policy
+
+
+async def test_selector_receives_original_positional_and_keyword_arguments():
+    cache = DialCache()
+    seen = []
+
+    def select(*args, **kwargs):
+        seen.append((args, kwargs))
+        return args[0] if args else kwargs["user_id"]
+
+    @cache.cached(key_type="user", cache_key=select, default_config=Policy(request_local=True))
+    async def load(user_id, locale="en"):
+        return user_id
+
+    # Disabled calls do not invoke the selector, even for defaulted parameters.
+    assert await load("42") == "42"
+    assert seen == []
+    with cache.enable():
+        assert await load("42") == "42"
+        assert await load(user_id="42") == "42"
+    assert seen == [(("42",), {}), ((), {"user_id": "42"})]
+
+
+async def test_explicit_selector_positional_only_keyword_only_and_variadic_arguments():
+    cache = DialCache()
+    calls = 0
+
+    def select(user_id, /, *roles, locale="en", **context):
+        return {"id": user_id, "args": {"roles": ",".join(roles), "locale": locale}}
+
+    @cache.cached(key_type="user", cache_key=select, default_config=Policy(request_local=True))
+    async def load(user_id, /, *roles, locale="en", **context):
+        nonlocal calls
+        calls += 1
+        return calls
+
+    with cache.enable():
+        assert await load("42", "reader", trace_id="first") == 1
+        assert await load("42", "reader", locale="en", trace_id="second") == 1
+        assert await load("42", "admin") == 2
+        assert await load("42", "reader", locale="fr") == 3
+    assert calls == 3
+
+
+async def test_method_selector_can_include_instance_identity():
+    cache = DialCache()
+    calls = []
+
+    class Users:
+        def __init__(self, tenant):
+            self.tenant = tenant
+
+        @cache.cached(
+            key_type="user",
+            cache_key=lambda self, user_id: {"id": user_id, "args": {"tenant": self.tenant}},
+            default_config=Policy(request_local=True),
+        )
+        async def load(self, user_id):
+            calls.append((self.tenant, user_id))
+            return self.tenant
+
+    first, second = Users("a"), Users("b")
+    with cache.enable():
+        assert await first.load("42") == "a"
+        assert await first.load(user_id="42") == "a"
+        assert await second.load("42") == "b"
+    assert calls == [("a", "42"), ("b", "42")]
+
+
+async def test_selector_missing_default_fails_open(caplog):
+    cache = DialCache()
+    calls = 0
+
+    @cache.cached(
+        key_type="user",
+        cache_key=lambda user_id, locale: {"id": user_id, "args": {"locale": locale}},
+        default_config=Policy(request_local=True),
+    )
+    async def load(user_id, locale="en"):
+        nonlocal calls
+        calls += 1
+        return calls
+
+    with cache.enable():
+        assert await load("42") == 1
+        assert await load("42") == 2
+        assert await load("42", "en") == 3
+        assert await load("42", "en") == 3
+    assert "Could not construct DialCache key" in caplog.text
+
+
+@pytest.mark.parametrize(
+    "selected",
+    [
+        "42",
+        {"id": "42", "args": {"locale": UNDEFINED}},
+        Key("urn", "user", "42", "GetUser"),
+    ],
+)
+async def test_existing_scalar_mapping_and_structured_key_selectors(selected):
+    cache = DialCache()
+    calls = 0
+
+    @cache.cached(
+        key_type="user",
+        use_case="GetUser",
+        cache_key=lambda user_id: selected,
+        default_config=Policy(request_local=True),
+    )
+    async def load(user_id):
+        nonlocal calls
+        calls += 1
+        return calls
+
+    with cache.enable():
+        assert await load("42") == 1
+        assert await load("42") == 1
+    assert calls == 1

{dialcache-0.25.0 → dialcache-0.26.0}/tests/test_docs_examples.py

@@ -9,6 +9,37 @@ from dialcache import DialCache, Policy
 from dialcache.redis import RedisAdapter
 
 
+async def test_explicit_key_identity():
+    cache = DialCache(namespace="users-api")
+    source_calls = []
+
+    @cache.cached(
+        key_type="user_id",
+        use_case="GetUser",
+        # Repeat the loader default so omitted and explicit locales agree.
+        cache_key=lambda user_id, locale="en", *, trace_id=None: {
+            "id": user_id,
+            "args": {"locale": locale},
+        },
+        default_config=Policy(request_local=True),
+    )
+    async def get_user(user_id: str, locale: str = "en", *, trace_id=None):
+        source_calls.append((user_id, locale, trace_id))
+        return {"id": user_id, "locale": locale}
+
+    async with cache.enable():
+        assert await get_user("123", trace_id="first") == {"id": "123", "locale": "en"}
+        assert await get_user(user_id="123", locale="en", trace_id="second") == {
+            "id": "123",
+            "locale": "en",
+        }
+        assert await get_user("123", "fr") == {"id": "123", "locale": "fr"}
+        assert await get_user("456") == {"id": "456", "locale": "en"}
+
+    # Trace metadata does not alter the result, so it is omitted from identity.
+    assert source_calls == [("123", "en", "first"), ("123", "fr", None), ("456", "en", None)]
+
+
 async def test_request_scope():
     # region request-scope
     cache = DialCache()
@@ -17,7 +48,7 @@ async def test_request_scope():
     @cache.cached(
         key_type="user",
         use_case="requestScope",
-        id_arg="id",
+        cache_key=lambda id: id,
         # Only request-local storage is enabled; shared layers stay off.
         default_config=Policy(request_local=True),
     )
@@ -49,7 +80,7 @@ async def test_runtime_policy():
     @cache.cached(
         key_type="user",
         use_case="runtimePolicy",
-        id_arg="id",
+        cache_key=lambda id: id,
         default_config=Policy(request_local=True, ttl_sec={"local": 60}, ramp={"local": 100}),
     )
     async def lookup(id):
@@ -92,7 +123,7 @@ async def test_tracked_invalidation():
         @cache.cached(
             key_type="user",
             use_case="profileVersion",
-            id_arg="id",
+            cache_key=lambda id: id,
             track_for_invalidation=True,
             # Keep local layers off so each request observes the watermark.
             default_config=Policy(ttl_sec={"remote": 60}, ramp={"remote": 100}),

{dialcache-0.25.0 → dialcache-0.26.0}/tests/test_integration_acceptance.py

@@ -50,6 +50,8 @@ def pytest_collection_modifyitems(session, config, items):
     mode = os.environ.get("PROBE_MODE")
     if mode == "subset":
         items[:] = [item for item in items if "inventory_only" in item.nodeid]
+    elif mode == "exclude_mixed_client":
+        items[:] = [item for item in items if "test_wire_interop.py" not in item.nodeid]
     elif mode == "duplicate":
         items.append(next(item for item in items if item.get_closest_marker("integration")))
     elif mode == "empty":
@@ -63,24 +65,33 @@ def pytest_runtestloop(session):
 """
 
 
+CHALLENGES = [
+    "baseline",
+    "inherited_keyword",
+    "configured_keyword",
+    "inherited_collect_only",
+    "external_plugin_ignored",
+    "subset",
+    "exclude_mixed_client",
+    "duplicate",
+    "empty",
+    "skip",
+    "fail",
+    "xpass",
+    "no_reports",
+]
+
+
 @pytest.mark.parametrize(
-    "challenge",
+    "suite,challenge",
     [
-        "baseline",
-        "inherited_keyword",
-        "configured_keyword",
-        "inherited_collect_only",
-        "external_plugin_ignored",
-        "subset",
-        "duplicate",
-        "empty",
-        "skip",
-        "fail",
-        "xpass",
-        "no_reports",
+        (suite, challenge)
+        for suite in ["native", "wire"]
+        for challenge in CHALLENGES
+        if suite == "wire" or challenge != "exclude_mixed_client"
     ],
 )
-def test_integration_coordinator_requires_complete_cases_on_each_backend(tmp_path, challenge):
+def test_integration_coordinator_requires_complete_cases_on_each_backend(tmp_path, suite, challenge):
     node = os.environ.get("NODE") or shutil.which("node")
     assert node, "Node 24 is required by Python validation"
     checkout = tmp_path
@@ -97,7 +108,7 @@ def test_integration_coordinator_requires_complete_cases_on_each_backend(tmp_pat
         'markers=["integration: required real-server case"]\n'
         f"addopts={json.dumps(configured)}\n"
     )
-    failures = {"subset", "duplicate", "empty", "skip", "fail", "xpass", "no_reports"}
+    failures = {"subset", "exclude_mixed_client", "duplicate", "empty", "skip", "fail", "xpass", "no_reports"}
     mode = challenge if challenge in failures else "pass"
     external_plugin = challenge == "external_plugin_ignored"
     if external_plugin:
@@ -106,6 +117,12 @@ def test_integration_coordinator_requires_complete_cases_on_each_backend(tmp_pat
         TEST.format(plugins='pytest_plugins = ["challenge_plugin"]' if challenge in failures else "")
     )
     (tests / "test_docs_examples.py").write_text(DOCS)
+    (checkout / "interop").mkdir()
+    (checkout / "interop/test_wire_interop.py").write_text(
+        TEST.format(plugins='pytest_plugins = ["challenge_plugin"]' if challenge in failures else "")
+        .replace('"雪"', '"wire雪"')
+        .replace('"<not-xml>"', '"wire<not-xml>"')
+    )
     (tests / "challenge_plugin.py").write_text(PLUGIN)
     coverage = checkout / "coverage/python"
     coverage.mkdir(parents=True)
@@ -130,7 +147,7 @@ def test_integration_coordinator_requires_complete_cases_on_each_backend(tmp_pat
         "PYTEST_PLUGINS": "challenge_plugin" if external_plugin else "",
     }
     result = subprocess.run(
-        [node, "formal/run-python-integration.mjs"],
+        [node, "formal/run-python-integration.mjs", "--suite", suite],
         cwd=checkout,
         env=environment,
         text=True,
@@ -140,14 +157,22 @@ def test_integration_coordinator_requires_complete_cases_on_each_backend(tmp_pat
     if challenge in failures:
         assert result.returncode != 0, result.stdout + result.stderr
         assert "Integration acceptance failed:" in result.stderr, result.stdout + result.stderr
-        assert not list(coverage.glob("*.lcov"))
+        if suite == "native":
+            assert not list(coverage.glob("*.lcov"))
     else:
         assert result.returncode == 0, result.stdout + result.stderr
         for backend in ["Redis", "Valkey"]:
-            report = (coverage / f"{backend}.lcov").read_text()
-            assert "SF:" in report and "stale report" not in report
+            if suite == "native":
+                report = (coverage / f"{backend}.lcov").read_text()
+                assert "SF:" in report and "stale report" not in report
+            else:
+                assert (checkout / f".formal-traces/wire-integration-{backend}.xml").is_file()
         assert log.read_text().splitlines() == [
             f"{url} {value}"
             for url in [environment["TEST_REDIS_URL"], environment["TEST_VALKEY_URL"]]
-            for value in ["雪", "<not-xml>"]
+            for value in (["雪", "<not-xml>"] if suite == "native" else ["wire雪", "wire<not-xml>"])
         ]
+    if suite == "wire":
+        # Wire evidence must not replace or clear native Python Codecov data.
+        for backend in ["Redis", "Valkey"]:
+            assert (coverage / f"{backend}.lcov").read_text() == "stale report must not survive a failed run"

dialcache-0.26.0/tests/test_typing.py

@@ -0,0 +1,33 @@
+"""Check the public decorator as a typed consumer, without checking engine internals."""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def test_cached_consumer_types(tmp_path):
+    source_root = Path(__file__).resolve().parents[1]
+    fixture = Path(__file__).with_name("typing") / "cached.py"
+    environment = os.environ.copy()
+    environment["MYPYPATH"] = os.pathsep.join(
+        filter(None, [str(source_root), environment.get("MYPYPATH")])
+    )
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "mypy",
+            "--strict",
+            "--follow-imports=silent",
+            "--python-version=3.11",
+            "--cache-dir",
+            str(tmp_path / "mypy"),
+            str(fixture),
+        ],
+        env=environment,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert result.returncode == 0, result.stdout + result.stderr

dialcache-0.26.0/tests/test_wire_suite.py

@@ -0,0 +1,38 @@
+"""Keep the cross-language inventory complete and its value assertions strict."""
+
+import importlib.util
+from itertools import permutations
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[2]
+spec = importlib.util.spec_from_file_location("wire_cases", ROOT / "interop/test_wire_interop.py")
+wire = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(wire)
+
+
+def test_all_directed_pairs_and_supported_value_domains_are_required():
+    languages = {"typescript", "go", "rust", "python"}
+    assert set(wire.LANGUAGES) == languages
+    assert set(wire.DIRECTIONS) == set(permutations(languages, 2))
+    assert len(wire.DIRECTIONS) == 12
+    assert len(wire.VALUE_CASES) == 69
+    common = {"json-raw", "json-zstd", "null", "binary-escaped", "binary-zstd"}
+    for writer, reader in wire.DIRECTIONS:
+        cases = {
+            case.id.removeprefix(f"{writer}-to-{reader}-")
+            for case in wire.VALUE_CASES
+            if case.values[:2] == (writer, reader)
+        }
+        assert cases == common | ({"undefined"} if writer != "rust" else set())
+
+
+@pytest.mark.parametrize("actual,expected", [(False, 0), (0, False), (True, 1), (1, True)])
+def test_json_equality_rejects_boolean_number_substitution(actual, expected):
+    with pytest.raises(AssertionError):
+        wire.assert_value({"nested": [actual]}, {"nested": [expected]})
+
+
+def test_json_equality_accepts_equivalent_native_number_representations():
+    wire.assert_value({"nested": [None, False, True, 1.0]}, {"nested": [None, False, True, 1]})

dialcache-0.26.0/tests/typing/cached.py

@@ -0,0 +1,115 @@
+"""Consumer type checks: unused ignores turn unexpectedly accepted bad calls into failures."""
+
+import asyncio
+from collections.abc import Awaitable, Coroutine, Mapping
+from typing import Any, assert_type
+
+from dialcache import UNDEFINED, CacheKeySpec, DialCache, Key, KeyScalar
+
+cache = DialCache()
+
+
+def select_user(user_id: str, *, locale: str = "en") -> CacheKeySpec:
+    return {"id": user_id, "args": {"locale": locale, "omitted": UNDEFINED}}
+
+
+@cache.cached(key_type="user", cache_key=select_user)
+async def get_user(user_id: str, *, locale: str = "en") -> str:
+    return user_id + locale
+
+
+@cache.cached(
+    key_type="number",
+    cache_key=lambda value, multiplier=2: {"id": value, "args": {"multiplier": multiplier}},
+)
+def get_number(value: int, /, multiplier: int = 2) -> int:
+    return value * multiplier
+
+
+@cache.cached(key_type="awaitable", cache_key=lambda value: value)
+def get_awaitable(value: str) -> Awaitable[str]:
+    return asyncio.sleep(0, result=value)
+
+
+@cache.cached(key_type="mixed", cache_key=lambda value, deferred=False: value)
+def get_mixed(value: str, *, deferred: bool = False) -> str | Awaitable[str]:
+    return asyncio.sleep(0, result=value) if deferred else value
+
+
+@cache.cached(key_type="user", id_arg="user_id")
+async def inferred_user(user_id: str) -> str:
+    return user_id
+
+
+@cache.cached(key_type="user", id_arg="user_id")
+def inferred_sync_user(user_id: str) -> str:
+    return user_id
+
+
+class Users:
+    @cache.cached(key_type="user", cache_key=lambda self, user_id: user_id)
+    async def get(self, user_id: str) -> str:
+        return user_id
+
+
+def select_key(user_id: str) -> Key:
+    return Key("urn", "user", user_id, "GetUser")
+
+
+def select_scalar(user_id: str) -> KeyScalar:
+    return user_id
+
+
+def select_dict(user_id: str) -> dict[str, str]:
+    return {"id": user_id}
+
+
+def select_mapping(user_id: str) -> Mapping[str, object]:
+    return {"id": user_id, "args": {"locale": "en"}}
+
+
+cache.cached(key_type="user", cache_key=select_key)
+cache.cached(key_type="user", cache_key=select_scalar)
+cache.cached(key_type="user", cache_key=select_dict)
+cache.cached(key_type="user", cache_key=select_mapping)
+cache.cached(key_type="user", cache_key=lambda user_id: {"id": user_id})
+cache.cached(key_type="user", cache_key=lambda user_id: {"id": user_id, "args": {"locale": "en"}})
+# Generic mappings retain runtime validation; opt into CacheKeySpec for field checks.
+cache.cached(key_type="user", cache_key=lambda user_id: {"id": user_id, "args": {"nested": []}})
+
+assert_type(get_user("42"), Coroutine[Any, Any, str]).close()
+assert_type(get_user(user_id="42", locale="fr"), Coroutine[Any, Any, str]).close()
+assert_type(get_number(2), Coroutine[Any, Any, int]).close()
+assert_type(get_number(2, multiplier=3), Coroutine[Any, Any, int]).close()
+assert_type(get_awaitable("42"), Coroutine[Any, Any, str]).close()
+assert_type(get_mixed("42"), Coroutine[Any, Any, str]).close()
+assert_type(get_mixed("42", deferred=True), Coroutine[Any, Any, str]).close()
+assert_type(inferred_user("42"), Coroutine[Any, Any, str]).close()
+assert_type(inferred_sync_user("42"), Coroutine[Any, Any, str]).close()
+assert_type(Users().get("42"), Coroutine[Any, Any, str]).close()
+
+
+async def check_awaited_results() -> None:
+    assert_type(await get_user("42"), str)
+    assert_type(await get_number(2), int)
+    assert_type(await get_awaitable("42"), str)
+    assert_type(await get_mixed("42"), str)
+    assert_type(await get_mixed("42", deferred=True), str)
+    assert_type(asyncio.create_task(get_user("42")), asyncio.Task[str])
+    assert_type(asyncio.create_task(get_number(2)), asyncio.Task[int])
+    assert_type(asyncio.create_task(get_mixed("42", deferred=True)), asyncio.Task[str])
+
+# These errors must remain errors: Any leaking from the decorator would hide them.
+get_user(42).close()  # type: ignore[arg-type]
+get_user("42", "fr").close()  # type: ignore[misc]
+get_user("42", unknown=True).close()  # type: ignore[call-arg]
+get_user().close()  # type: ignore[call-arg]
+get_number(value=2).close()  # type: ignore[call-arg]
+inferred_user(42).close()  # type: ignore[arg-type]
+inferred_sync_user(42).close()  # type: ignore[arg-type]
+Users().get(42).close()  # type: ignore[arg-type]
+wrong_result: Awaitable[int] = get_user("42")  # type: ignore[assignment]
+cache.cached(key_type="user", cache_key=lambda user_id: object())  # type: ignore[arg-type,return-value]
+missing_id: CacheKeySpec = {"args": {"locale": "en"}}  # type: ignore[typeddict-item]
+nested_args: CacheKeySpec = {"id": "42", "args": {"nested": []}}  # type: ignore[dict-item]
+invalid_id: CacheKeySpec = {"id": object()}  # type: ignore[typeddict-item]