dialcache 0.25.0__py3-none-any.whl

dialcache-0.25.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,17 @@
+dialcache/__init__.py,sha256=yq0319rG7aQnOIDXOClAfXdhWJwmPj8htcMcDp9loKo,956
+dialcache/cache.py,sha256=68rfJwgHl-OGU5ueRhlwj6ptIm4R4x0LEU6sQH1zo0g,48995
+dialcache/clock.py,sha256=U70P4pSlmDPUImK2NZTX9-dbtun5o8VFMdXOUZT4HS4,1603
+dialcache/config.py,sha256=lnzlk4BppycDYgVaLO5DFXHdOkYpxOXrwYo6nnHevjo,10868
+dialcache/context.py,sha256=5vRqEEAAaQ0abwelqUfEPMdrOxi0h6FbEjic_reWppg,4092
+dialcache/errors.py,sha256=a95vzZCQGF7KdH59sJ4grlg_meKqt5oYF0gXfJ7aEUY,1580
+dialcache/key.py,sha256=RBFPwX2gYEUaahkb8Aec7vBR0hMNta_R4vinAJF6uy4,5845
+dialcache/local.py,sha256=y5hom-IVgaRY31N79RJjIiSkUSJNMG2LeNQ5RguW-8U,2526
+dialcache/metrics.py,sha256=E9ufl9y1pmsMDkB0IjoMhzCfVR3Lz3aknnwxm5S9fhg,1290
+dialcache/protocol.py,sha256=VFVfvE2dKil9G6IijpOIC_Q80VZNmA_2KqTn8jiDcJg,10510
+dialcache/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dialcache/redis.py,sha256=nhViSD9dV5BWM0_wglTWWHCvx0-nhCMgTWFHKRls1G0,8011
+dialcache/serializer.py,sha256=kAXE6vv_OAPXW1ZN-ZtGliqQTUGLQR3mtKstrBJ4iVQ,1881
+dialcache-0.25.0.dist-info/METADATA,sha256=8e-Lfv4cW1RRgP2ThHoSRVYgm38icTB9yk7ovOorBLk,10913
+dialcache-0.25.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+dialcache-0.25.0.dist-info/licenses/LICENSE,sha256=I4t1F0sQnk9jCP2lTvTijI388Y-gGwHwXRcKCNp35tM,1082
+dialcache-0.25.0.dist-info/RECORD,,

dialcache-0.25.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

dialcache-0.25.0.dist-info/licenses/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.