dialcache 0.25.0__tar.gz

dialcache-0.25.0/.gitignore

@@ -0,0 +1,25 @@
+node_modules/
+dist/
+coverage/
+/go/coverage-*.out
+.formal-traces/
+docs/.vitepress/cache/
+docs/public/reference/
+docs/generated/
+*.tgz
+.env
+.env.*
+!.env.example
+.DS_Store
+.idea/
+.vscode/
+*.log
+rust/target/
+python/.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+python/build/
+python/dist/

dialcache-0.25.0/API-DESIGN.md

@@ -0,0 +1,28 @@
+# Python API design and gcache lineage
+
+The Python binding was designed after reviewing [rungalileo/gcache at a688049](https://github.com/rungalileo/gcache/tree/a68804986782cb0b7e8b7dc6bfc34c718c177189), including `src/gcache/gcache.py`, `config.py`, `proto_serializer.py`, and the context, layer wrappers, local cache, Redis cache, and event-loop thread implementations under `_internal/`.
+
+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.
+
+| 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. |
+| 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. |
+| Async `Serializer.dump/load` | Retained; synchronous implementations are also accepted. Default JSON supports the portable top-level `UNDEFINED` value. |
+| Synchronous wrapper and background event-loop pool | The binding is asyncio based. Every cached wrapper is awaitable; synchronous loaders execute on the caller's event loop. One cache belongs to one event loop. No implicit threads or client factories are created. |
+| Singleton, global namespace, global metrics | Instances own their namespace, request scopes, local capacity, flights and observer. The application owns its Redis client. |
+| Pickle / JSON / protobuf envelope choice | DialCache always uses the portable version-1 frame and compression wrapper. A custom serializer can produce text or binary payloads, including protobuf. There is no pickle fallback or gcache envelope compatibility. |
+| `aput`, `adelete`, `aflushall` and their synchronous counterparts | These are not part of the existing DialCache public contract and are not added by this port. Tracked invalidation is the explicit maintenance API. |
+| Random sampling and per-use-case local TTL cache | Replaced by DialCache's deterministic key cohorts and a bounded per-instance LRU, with expiry captured at each insertion. |
+
+Disabled calls bypass key selection, argument adaptation, policy resolution, deadlines and coalescing. Redis reads acquire the value and watermark atomically from a primary; writes use one native `SET` of a complete frame. None of these rules are inherited from gcache's implementation.
+
+Method decorators omit `self` from inferred key arguments by default. An explicit
+`arg_adapters={"self": ...}` includes the adapted instance identity, for example
+its tenant ID. `ignore_args` takes precedence over argument adapters.
+
+The Python API is a binding of the existing behavior, not a migration that reads existing gcache keys or envelopes. Applications sharing entries across ports must use the same namespace, entity identity, use case, argument order and payload schema.

dialcache-0.25.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Galileo Technologies Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dialcache-0.25.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.5
+Name: dialcache
+Version: 0.25.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
+Author: Lev Neiman
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: zstandard<1,>=0.23
+Provides-Extra: redis
+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: pytest-asyncio<2,>=0.24; extra == 'test'
+Requires-Dist: pytest<10,>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# DialCache for Python
+
+An asyncio port of DialCache for Python 3.11 and later. Each use case declares
+its identity and policy; an enabled request scope opts into request memoization,
+local storage, Redis, and concurrent request sharing. The behavioral contract is
+the repository's [portable specification](https://github.com/lan17/DialCache/blob/main/formal/SPEC.md).
+
+Once the first PyPI release is available, install it with:
+
+```sh
+python3 -m pip install 'dialcache[redis]'
+```
+
+Until that release is published, install from the root of a repository checkout:
+
+```sh
+python3 -m pip install './python[redis]'
+```
+
+For local-only caching, omit the `redis` extra. Zstandard is included for the
+portable Redis payload format. The application owns the asyncio event loop and
+any Redis client connections.
+
+## A cached function
+
+```python
+from dialcache import DialCache, Policy
+
+cache = DialCache(namespace="my-service")
+
+
+@cache.cached(
+    use_case="user-profile",
+    key_type="user",
+    id_arg="user_id",
+    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 handle_request(user_id: str) -> dict:
+    async with cache.enable():
+        first = await get_profile(user_id)
+        second = await get_profile(user_id)  # Same request memo.
+        return second
+```
+
+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;
+the wrapped function is always awaitable. Synchronous loaders are accepted and
+run on the event loop, so use async loaders for blocking I/O.
+
+Nested enabled scopes share the live outer request memo. A nested
+`cache.disable()` temporarily bypasses caching without deleting that memo.
+Closing the outer scope clears the memo and prevents late publication. Async
+tasks that inherited a scope use pass-through behavior for calls made after
+that scope closes. Cache instances keep independent contexts.
+
+## Policies and runtime changes
+
+No layer is enabled by default. A positive TTL enables that shared layer, with
+a default rollout percentage of 100. Request memoization defaults to false;
+concurrent same-key sharing defaults to true.
+
+```python
+policy = Policy(
+    ttl_sec={"local": 5, "remote": 60},
+    ramp={"remote": 25},
+    request_local=True,
+    coalesce=True,
+    remote_read_timeout_ms=50,
+    stale_on_error_max_age_sec=120,
+)
+```
+
+TTLs are integer seconds from 1 through 31,536,000. Rollout percentages are
+finite numbers from 0 through 100. Sampling is stable per exact key and layer,
+using the same cohort algorithm as the TypeScript, Go, and Rust ports.
+
+Pass a synchronous or asynchronous `policy_provider` to `DialCache` to resolve
+runtime settings once per enabled invocation. It receives the structured key
+and returns a `Policy`, a mapping, or `None`:
+
+```python
+async def policy_provider(key):
+    if key.use_case == "user-profile":
+        return {"ramp": {"remote": 50}}
+    return None
+
+
+cache = DialCache(policy_provider=policy_provider)
+```
+
+Runtime replies are sparse: an omitted field inherits the operation default.
+A whole reply of `None` inherits the complete operation policy. An explicit
+`None` leaf is malformed and cannot silently inherit a valid setting. Python
+snake_case names and the shared corpus's camelCase mapping names are accepted.
+Policy objects snapshot their input maps so later mutation cannot alter an
+already admitted invocation.
+
+`Policy.disabled()` explicitly disables inherited request memoization, local
+and remote serving, recovery, and shadow work. It does not cancel work that
+was already admitted or disable explicit invalidation. `Policy.enabled(ttl)`
+enables local and remote TTLs; it does not opt into request memoization.
+
+Invalid static defaults raise `ConfigError` at registration. At runtime,
+invalid TTLs or ramps disable their own layer; malformed boolean switches,
+read deadlines, containers, or provider failures bypass caching for that
+enabled invocation. Optional recovery and shadow failures leave ordinary
+serving available.
+
+## Redis and tracked invalidation
+
+```python
+from redis.asyncio import Redis
+from dialcache import DialCache, Policy
+from dialcache.redis import RedisAdapter
+
+client = Redis.from_url(
+    "redis://localhost:6379",
+    decode_responses=False,
+    socket_connect_timeout=0.5,
+    socket_timeout=0.5,
+)
+cache = DialCache(redis=RedisAdapter(client))
+
+
+@cache.cached(
+    use_case="user-profile",
+    key_type="user",
+    id_arg="user_id",
+    track_for_invalidation=True,
+    default_config=Policy(ttl_sec={"remote": 60}),
+)
+async def get_profile(user_id):
+    return await database.fetch_profile(user_id)
+
+
+async def update_profile(user_id, changes):
+    await database.update_profile(user_id, changes)
+    await cache.invalidate_remote("user", user_id)
+```
+
+The adapter borrows a `redis.asyncio.Redis` or `RedisCluster` client; close it
+with `await client.aclose()` when your application shuts down. Configure
+finite connection, socket, and retry budgets on the client. Tracked reads
+atomically read the value and watermark from a primary. For tracked Cluster
+reads, use a dedicated client constructed with primary-only defaults:
+`read_from_replicas=False`, `load_balancing_strategy=None` where supported, and no custom
+connection hook. Keep its configuration and connection mode unchanged while
+borrowed. Do not repurpose a previously `READONLY` pool by resetting flags;
+create a new primary-only client. Unsafe tracked reads raise `RedisProtocolError`
+at the adapter boundary and ordinary cache calls fail open to the source.
+Replica-enabled clients remain usable for untracked reads and maintenance.
+Keys for one tracked entity share a Redis Cluster hash tag.
+
+Each write stores a complete version-1 frame using one native `SET`. A tracked
+frame is readable only if its writer timestamp is strictly greater than the
+invalidation watermark. Value writes never create or extend watermarks.
+Tracked physical value TTLs are capped at one hour. Invalidation raises on
+mutation failure; ordinary cache plumbing fails open to the source.
+
+Local storage is process-local. Remote invalidation does not synchronously
+clear already warmed local entries or request memos on any instance. Choose
+local TTLs with that explicit consistency limit in mind.
+
+## Deadlines, recovery, and observability
+
+The default source deadline is 60,000 ms for enabled calls. The default Redis
+read deadline is 50 ms and can be overridden by operation or runtime policy.
+Deadline budgets are integer milliseconds from 1 through 2,147,483,647; an
+explicit `fallback_timeout_ms=None` disables the source deadline. Timing uses
+the monotonic clock, while Redis frames and invalidation use wall time.
+
+Deadline expiration stops the caller's wait. It cannot retract a source
+operation or a Redis command that already started. Late results cannot
+publish through an expired source execution. Caller cancellation likewise
+must not cancel another caller's shared execution.
+
+Stale recovery is optional and requires a maximum age strictly greater than
+the remote TTL. A valid candidate is retained from the original remote read;
+an eligible source rejection can use it only before the exclusive maximum
+age. The default recovery predicate admits DialCache's own
+`FallbackTimeoutError`. Recovered values may memoize in still-open request
+scopes; recovery does not refresh Redis or local storage.
+
+Pass a synchronous `metrics` callback or an object with `observe(event)` to
+receive the backend-neutral diagnostic event dictionaries. Their label names
+match the shared contract, including `cacheNamespace`, `useCase`, `keyType`,
+and `layer`. Observer failures do not alter cache results. Local capacity
+defaults to 10,000 entries; zero capacity disables storage while preserving
+eligible concurrent sharing.
+
+## Relationship to gcache
+
+The Python API takes inspiration from [Galileo gcache](https://github.com/rungalileo/gcache):
+decorated functions, argument-based identity, explicit context managers, and
+pluggable serializers. DialCache follows its own portable
+specification for behavior and wire compatibility.
+The [API design notes](https://github.com/lan17/DialCache/blob/main/python/API-DESIGN.md) record the source-reviewed gcache revision
+and the native API choices made for this port.
+
+This binding exposes awaitable operations. It does not introduce a global
+singleton, implicitly run synchronous I/O in a thread pool, serialize with
+pickle, take ownership of Redis connections, or change the rollout cohort
+randomly. Direct `put`, `delete`, and `flush` cache APIs from gcache are outside
+DialCache's portable contract; writes come from successful source loads and
+entity-level invalidation is explicit.
+
+## Development and conformance
+
+From the repository root:
+
+```sh
+python3 -m venv python/.venv
+python/.venv/bin/python -m pip install -e './python[test,redis]'
+python/.venv/bin/python -m pytest python/tests
+```
+
+The native tests cover Python API behavior, policy validation, scope lifetime,
+local expiry, cancellation, and wire boundaries. Shared replay runs the real
+Python API through the repository's Node coordinator. Its inputs and expected
+observations come from the same Quint-generated histories used by the other
+ports; Node is a development dependency, not a runtime dependency of the
+Python library. See [the porting guide](https://github.com/lan17/DialCache/blob/main/formal/PORTING.md) for the completion
+and settlement requirements and [the feature map](https://github.com/lan17/DialCache/blob/main/formal/FEATURE-COVERAGE.md)
+for portable behavior versus native adapter obligations.

dialcache-0.25.0/README.md

@@ -0,0 +1,229 @@
+# DialCache for Python
+
+An asyncio port of DialCache for Python 3.11 and later. Each use case declares
+its identity and policy; an enabled request scope opts into request memoization,
+local storage, Redis, and concurrent request sharing. The behavioral contract is
+the repository's [portable specification](https://github.com/lan17/DialCache/blob/main/formal/SPEC.md).
+
+Once the first PyPI release is available, install it with:
+
+```sh
+python3 -m pip install 'dialcache[redis]'
+```
+
+Until that release is published, install from the root of a repository checkout:
+
+```sh
+python3 -m pip install './python[redis]'
+```
+
+For local-only caching, omit the `redis` extra. Zstandard is included for the
+portable Redis payload format. The application owns the asyncio event loop and
+any Redis client connections.
+
+## A cached function
+
+```python
+from dialcache import DialCache, Policy
+
+cache = DialCache(namespace="my-service")
+
+
+@cache.cached(
+    use_case="user-profile",
+    key_type="user",
+    id_arg="user_id",
+    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 handle_request(user_id: str) -> dict:
+    async with cache.enable():
+        first = await get_profile(user_id)
+        second = await get_profile(user_id)  # Same request memo.
+        return second
+```
+
+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;
+the wrapped function is always awaitable. Synchronous loaders are accepted and
+run on the event loop, so use async loaders for blocking I/O.
+
+Nested enabled scopes share the live outer request memo. A nested
+`cache.disable()` temporarily bypasses caching without deleting that memo.
+Closing the outer scope clears the memo and prevents late publication. Async
+tasks that inherited a scope use pass-through behavior for calls made after
+that scope closes. Cache instances keep independent contexts.
+
+## Policies and runtime changes
+
+No layer is enabled by default. A positive TTL enables that shared layer, with
+a default rollout percentage of 100. Request memoization defaults to false;
+concurrent same-key sharing defaults to true.
+
+```python
+policy = Policy(
+    ttl_sec={"local": 5, "remote": 60},
+    ramp={"remote": 25},
+    request_local=True,
+    coalesce=True,
+    remote_read_timeout_ms=50,
+    stale_on_error_max_age_sec=120,
+)
+```
+
+TTLs are integer seconds from 1 through 31,536,000. Rollout percentages are
+finite numbers from 0 through 100. Sampling is stable per exact key and layer,
+using the same cohort algorithm as the TypeScript, Go, and Rust ports.
+
+Pass a synchronous or asynchronous `policy_provider` to `DialCache` to resolve
+runtime settings once per enabled invocation. It receives the structured key
+and returns a `Policy`, a mapping, or `None`:
+
+```python
+async def policy_provider(key):
+    if key.use_case == "user-profile":
+        return {"ramp": {"remote": 50}}
+    return None
+
+
+cache = DialCache(policy_provider=policy_provider)
+```
+
+Runtime replies are sparse: an omitted field inherits the operation default.
+A whole reply of `None` inherits the complete operation policy. An explicit
+`None` leaf is malformed and cannot silently inherit a valid setting. Python
+snake_case names and the shared corpus's camelCase mapping names are accepted.
+Policy objects snapshot their input maps so later mutation cannot alter an
+already admitted invocation.
+
+`Policy.disabled()` explicitly disables inherited request memoization, local
+and remote serving, recovery, and shadow work. It does not cancel work that
+was already admitted or disable explicit invalidation. `Policy.enabled(ttl)`
+enables local and remote TTLs; it does not opt into request memoization.
+
+Invalid static defaults raise `ConfigError` at registration. At runtime,
+invalid TTLs or ramps disable their own layer; malformed boolean switches,
+read deadlines, containers, or provider failures bypass caching for that
+enabled invocation. Optional recovery and shadow failures leave ordinary
+serving available.
+
+## Redis and tracked invalidation
+
+```python
+from redis.asyncio import Redis
+from dialcache import DialCache, Policy
+from dialcache.redis import RedisAdapter
+
+client = Redis.from_url(
+    "redis://localhost:6379",
+    decode_responses=False,
+    socket_connect_timeout=0.5,
+    socket_timeout=0.5,
+)
+cache = DialCache(redis=RedisAdapter(client))
+
+
+@cache.cached(
+    use_case="user-profile",
+    key_type="user",
+    id_arg="user_id",
+    track_for_invalidation=True,
+    default_config=Policy(ttl_sec={"remote": 60}),
+)
+async def get_profile(user_id):
+    return await database.fetch_profile(user_id)
+
+
+async def update_profile(user_id, changes):
+    await database.update_profile(user_id, changes)
+    await cache.invalidate_remote("user", user_id)
+```
+
+The adapter borrows a `redis.asyncio.Redis` or `RedisCluster` client; close it
+with `await client.aclose()` when your application shuts down. Configure
+finite connection, socket, and retry budgets on the client. Tracked reads
+atomically read the value and watermark from a primary. For tracked Cluster
+reads, use a dedicated client constructed with primary-only defaults:
+`read_from_replicas=False`, `load_balancing_strategy=None` where supported, and no custom
+connection hook. Keep its configuration and connection mode unchanged while
+borrowed. Do not repurpose a previously `READONLY` pool by resetting flags;
+create a new primary-only client. Unsafe tracked reads raise `RedisProtocolError`
+at the adapter boundary and ordinary cache calls fail open to the source.
+Replica-enabled clients remain usable for untracked reads and maintenance.
+Keys for one tracked entity share a Redis Cluster hash tag.
+
+Each write stores a complete version-1 frame using one native `SET`. A tracked
+frame is readable only if its writer timestamp is strictly greater than the
+invalidation watermark. Value writes never create or extend watermarks.
+Tracked physical value TTLs are capped at one hour. Invalidation raises on
+mutation failure; ordinary cache plumbing fails open to the source.
+
+Local storage is process-local. Remote invalidation does not synchronously
+clear already warmed local entries or request memos on any instance. Choose
+local TTLs with that explicit consistency limit in mind.
+
+## Deadlines, recovery, and observability
+
+The default source deadline is 60,000 ms for enabled calls. The default Redis
+read deadline is 50 ms and can be overridden by operation or runtime policy.
+Deadline budgets are integer milliseconds from 1 through 2,147,483,647; an
+explicit `fallback_timeout_ms=None` disables the source deadline. Timing uses
+the monotonic clock, while Redis frames and invalidation use wall time.
+
+Deadline expiration stops the caller's wait. It cannot retract a source
+operation or a Redis command that already started. Late results cannot
+publish through an expired source execution. Caller cancellation likewise
+must not cancel another caller's shared execution.
+
+Stale recovery is optional and requires a maximum age strictly greater than
+the remote TTL. A valid candidate is retained from the original remote read;
+an eligible source rejection can use it only before the exclusive maximum
+age. The default recovery predicate admits DialCache's own
+`FallbackTimeoutError`. Recovered values may memoize in still-open request
+scopes; recovery does not refresh Redis or local storage.
+
+Pass a synchronous `metrics` callback or an object with `observe(event)` to
+receive the backend-neutral diagnostic event dictionaries. Their label names
+match the shared contract, including `cacheNamespace`, `useCase`, `keyType`,
+and `layer`. Observer failures do not alter cache results. Local capacity
+defaults to 10,000 entries; zero capacity disables storage while preserving
+eligible concurrent sharing.
+
+## Relationship to gcache
+
+The Python API takes inspiration from [Galileo gcache](https://github.com/rungalileo/gcache):
+decorated functions, argument-based identity, explicit context managers, and
+pluggable serializers. DialCache follows its own portable
+specification for behavior and wire compatibility.
+The [API design notes](https://github.com/lan17/DialCache/blob/main/python/API-DESIGN.md) record the source-reviewed gcache revision
+and the native API choices made for this port.
+
+This binding exposes awaitable operations. It does not introduce a global
+singleton, implicitly run synchronous I/O in a thread pool, serialize with
+pickle, take ownership of Redis connections, or change the rollout cohort
+randomly. Direct `put`, `delete`, and `flush` cache APIs from gcache are outside
+DialCache's portable contract; writes come from successful source loads and
+entity-level invalidation is explicit.
+
+## Development and conformance
+
+From the repository root:
+
+```sh
+python3 -m venv python/.venv
+python/.venv/bin/python -m pip install -e './python[test,redis]'
+python/.venv/bin/python -m pytest python/tests
+```
+
+The native tests cover Python API behavior, policy validation, scope lifetime,
+local expiry, cancellation, and wire boundaries. Shared replay runs the real
+Python API through the repository's Node coordinator. Its inputs and expected
+observations come from the same Quint-generated histories used by the other
+ports; Node is a development dependency, not a runtime dependency of the
+Python library. See [the porting guide](https://github.com/lan17/DialCache/blob/main/formal/PORTING.md) for the completion
+and settlement requirements and [the feature map](https://github.com/lan17/DialCache/blob/main/formal/FEATURE-COVERAGE.md)
+for portable behavior versus native adapter obligations.

dialcache-0.25.0/dialcache/__init__.py

@@ -0,0 +1,38 @@
+"""DialCache: explicit scopes, layered caching, and portable Redis frames."""
+
+from .cache import DialCache
+from .config import UNSET, CacheLayer, DialCacheKeyConfig, KeyConfig, Policy
+from .errors import (
+    ConfigError,
+    DialCacheError,
+    FallbackTimeoutError,
+    MissingRemoteError,
+    RedisReadTimeoutError,
+    RemoteReadTimeoutError,
+    UseCaseIsAlreadyRegisteredError,
+    UseCaseNameIsReservedError,
+)
+from .key import Key, normalize_args
+from .serializer import UNDEFINED, JsonSerializer, Serializer
+
+__all__ = [
+    "DialCache",
+    "Policy",
+    "KeyConfig",
+    "DialCacheKeyConfig",
+    "CacheLayer",
+    "Key",
+    "normalize_args",
+    "Serializer",
+    "JsonSerializer",
+    "UNDEFINED",
+    "UNSET",
+    "DialCacheError",
+    "ConfigError",
+    "FallbackTimeoutError",
+    "RemoteReadTimeoutError",
+    "RedisReadTimeoutError",
+    "MissingRemoteError",
+    "UseCaseIsAlreadyRegisteredError",
+    "UseCaseNameIsReservedError",
+]