client-query-cache 0.6.0__tar.gz → 0.7.0__tar.gz

{client_query_cache-0.6.0 → client_query_cache-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: client-query-cache
-Version: 0.6.0
+Version: 0.7.0
 Summary: Client-side caching for PyMongo, kept coherent using MongoDB change streams.
 Author: Alessio Locatelli
 Author-email: Alessio Locatelli <<software.development@secure.mailbox.org>>
@@ -12,6 +12,7 @@ Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Database
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
+Requires-Dist: annotated-types>=0.8.0
 Requires-Dist: pymongo>=4.18.1
 Requires-Dist: opentelemetry-api>=1.45.0 ; extra == 'otel'
 Requires-Python: >=3.14
@@ -20,16 +21,26 @@ Project-URL: Documentation, https://alessio-locatelli.github.io/client-query-cac
 Provides-Extra: otel
 Description-Content-Type: text/markdown
 
-# Coherent client-side caching for PyMongo
+# Client-side query caching for PyMongo
 
 [![PyPI](https://img.shields.io/pypi/v/client-query-cache?color=lightgrey)](https://pypi.org/project/client-query-cache/)
 [![Python](https://img.shields.io/pypi/pyversions/client-query-cache)](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/)
 [![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/alessio-locatelli/client-query-cache/actions/workflows/test.yml)
 [![Typing](https://img.shields.io/pypi/types/client-query-cache)](https://pypi.org/project/client-query-cache/)
 
-`client-query-cache` uses MongoDB change streams to keep cached reads coherent. It supports synchronous and asyncio applications without requiring a separate cache server.
+`client-query-cache` uses MongoDB change streams to asynchronously invalidate cached query results. It supports synchronous and asyncio applications without requiring a separate cache server.
 
-**Built for production:** Designed for high-traffic, read-heavy applications, with cache hits served from memory to reduce latency and database load. Quality is backed by a 100% test-coverage requirement, real MongoDB integration and concurrency stress tests, and automated performance and memory regression checks.
+```mermaid
+%%{init: {"flowchart": {"diagramPadding": 75}}}%%
+flowchart LR
+    App["Python<br/>application"] -->|"Reads"| Cache["Client-side<br/>caching"]
+    Cache -->|"Miss / bypass"| DB[("MongoDB")]
+    DB -.->|"Change streams<br/>Async invalidation"| Cache
+```
+
+Cache hits are served from client-side memory, reducing read latency and database load in read-heavy applications.
+
+The library is tested against real MongoDB replica sets, including concurrency stress tests, and automated checks guard its performance and memory use against regressions.
 
 ![Illustrative read latency on a logarithmic scale: direct local MongoDB read, 120 microseconds; direct Atlas M0 read, 79.4 milliseconds; cached read in either deployment, about 61 microseconds.](docs/user/assets/benchmark-latency-light.svg)
 
@@ -37,7 +48,9 @@ Results vary by workload and deployment. [Measurements and methodology](https://
 
 Caching requires [MongoDB 8.0+ on a replica set or sharded cluster](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/#requirements). Reads on standalone servers and older MongoDB versions run through PyMongo without caching.
 
-Invalidation is asynchronous: a cached read can return a preceding value until the write's change-stream event is processed. Use PyMongo directly when a read must immediately observe a preceding write.
+Invalidation is asynchronous: a cached read can return a preceding value until the write's change-stream event is processed. Use PyMongo directly when a read must immediately observe a preceding write; see [consistency](https://alessio-locatelli.github.io/client-query-cache/usage/consistency/).
+
+Eligible cache misses read from the primary with `majority` read concern, even when the collection leaves read concern unspecified, so only majority-committed results enter the cache. Uncached PyMongo reads use the deployment's default read concern, normally `local`. The two usually perform alike, but while replication lags or data-bearing members are unavailable, a miss can return older data or fail where an uncached read would not. Majority admission does not make cache hits current: invalidation remains asynchronous. See [bypass conditions](https://alessio-locatelli.github.io/client-query-cache/reference/api/#bypass-conditions).
 
 ## Quick start
 
@@ -54,11 +67,15 @@ from client_query_cache import CacheManager
 
 with (
     MongoClient("mongodb://localhost:27017") as client,
-    CacheManager(client) as cache,
+    CacheManager(client) as cache_manager,
 ):
-    users = cache.get_cached_collection(client["my_database"]["users"])
-    users.find_one({"_id": "alice"})  # Reads from MongoDB.
-    users.find_one({"_id": "alice"})  # Repeated reads can use the cache.
+    collection = client["client_query_cache_tutorial"]["items"]
+    cached_collection = cache_manager.get_cached_collection(collection)
+    collection.replace_one(
+        {"_id": "example"}, {"_id": "example", "value": 42}, upsert=True
+    )
+    cached_collection.find_one({"_id": "example"})  # Reads from MongoDB.
+    cached_collection.find_one({"_id": "example"})  # Repeated reads can use the cache.
 ```
 
 ## References

{client_query_cache-0.6.0 → client_query_cache-0.7.0}/README.md

@@ -1,13 +1,23 @@
-# Coherent client-side caching for PyMongo
+# Client-side query caching for PyMongo
 
 [![PyPI](https://img.shields.io/pypi/v/client-query-cache?color=lightgrey)](https://pypi.org/project/client-query-cache/)
 [![Python](https://img.shields.io/pypi/pyversions/client-query-cache)](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/)
 [![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/alessio-locatelli/client-query-cache/actions/workflows/test.yml)
 [![Typing](https://img.shields.io/pypi/types/client-query-cache)](https://pypi.org/project/client-query-cache/)
 
-`client-query-cache` uses MongoDB change streams to keep cached reads coherent. It supports synchronous and asyncio applications without requiring a separate cache server.
+`client-query-cache` uses MongoDB change streams to asynchronously invalidate cached query results. It supports synchronous and asyncio applications without requiring a separate cache server.
 
-**Built for production:** Designed for high-traffic, read-heavy applications, with cache hits served from memory to reduce latency and database load. Quality is backed by a 100% test-coverage requirement, real MongoDB integration and concurrency stress tests, and automated performance and memory regression checks.
+```mermaid
+%%{init: {"flowchart": {"diagramPadding": 75}}}%%
+flowchart LR
+    App["Python<br/>application"] -->|"Reads"| Cache["Client-side<br/>caching"]
+    Cache -->|"Miss / bypass"| DB[("MongoDB")]
+    DB -.->|"Change streams<br/>Async invalidation"| Cache
+```
+
+Cache hits are served from client-side memory, reducing read latency and database load in read-heavy applications.
+
+The library is tested against real MongoDB replica sets, including concurrency stress tests, and automated checks guard its performance and memory use against regressions.
 
 ![Illustrative read latency on a logarithmic scale: direct local MongoDB read, 120 microseconds; direct Atlas M0 read, 79.4 milliseconds; cached read in either deployment, about 61 microseconds.](docs/user/assets/benchmark-latency-light.svg)
 
@@ -15,7 +25,9 @@ Results vary by workload and deployment. [Measurements and methodology](https://
 
 Caching requires [MongoDB 8.0+ on a replica set or sharded cluster](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/#requirements). Reads on standalone servers and older MongoDB versions run through PyMongo without caching.
 
-Invalidation is asynchronous: a cached read can return a preceding value until the write's change-stream event is processed. Use PyMongo directly when a read must immediately observe a preceding write.
+Invalidation is asynchronous: a cached read can return a preceding value until the write's change-stream event is processed. Use PyMongo directly when a read must immediately observe a preceding write; see [consistency](https://alessio-locatelli.github.io/client-query-cache/usage/consistency/).
+
+Eligible cache misses read from the primary with `majority` read concern, even when the collection leaves read concern unspecified, so only majority-committed results enter the cache. Uncached PyMongo reads use the deployment's default read concern, normally `local`. The two usually perform alike, but while replication lags or data-bearing members are unavailable, a miss can return older data or fail where an uncached read would not. Majority admission does not make cache hits current: invalidation remains asynchronous. See [bypass conditions](https://alessio-locatelli.github.io/client-query-cache/reference/api/#bypass-conditions).
 
 ## Quick start
 
@@ -32,11 +44,15 @@ from client_query_cache import CacheManager
 
 with (
     MongoClient("mongodb://localhost:27017") as client,
-    CacheManager(client) as cache,
+    CacheManager(client) as cache_manager,
 ):
-    users = cache.get_cached_collection(client["my_database"]["users"])
-    users.find_one({"_id": "alice"})  # Reads from MongoDB.
-    users.find_one({"_id": "alice"})  # Repeated reads can use the cache.
+    collection = client["client_query_cache_tutorial"]["items"]
+    cached_collection = cache_manager.get_cached_collection(collection)
+    collection.replace_one(
+        {"_id": "example"}, {"_id": "example", "value": 42}, upsert=True
+    )
+    cached_collection.find_one({"_id": "example"})  # Reads from MongoDB.
+    cached_collection.find_one({"_id": "example"})  # Repeated reads can use the cache.
 ```
 
 ## References

{client_query_cache-0.6.0 → client_query_cache-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "client-query-cache"
-version = "0.6.0"
+version = "0.7.0"
 description = "Client-side caching for PyMongo, kept coherent using MongoDB change streams."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -14,7 +14,10 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Typing :: Typed",
 ]
-dependencies = ["pymongo>=4.18.1"]
+dependencies = [
+    "annotated-types>=0.8.0",
+    "pymongo>=4.18.1",
+]
 
 [[project.authors]]
 name = "Alessio Locatelli"
@@ -59,6 +62,7 @@ dev = [
     "pytest-cov>=7.1.0",
     "pyyaml>=6.0.3",
     "types-pyyaml>=6.0.12.20260906",
+    "filelock>=4.1.0",
 ]
 docs = [
     "mike",

{client_query_cache-0.6.0 → client_query_cache-0.7.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "client-query-cache"
-version = "0.6.0"
+version = "0.7.0"
 description = "Client-side caching for PyMongo, kept coherent using MongoDB change streams."
 authors = [
   { name = "Alessio Locatelli", email = "<software.development@secure.mailbox.org>" },
@@ -17,7 +17,7 @@ classifiers = [
   "Topic :: Software Development :: Libraries :: Python Modules",
   "Typing :: Typed",
 ]
-dependencies = ["pymongo>=4.18.1"]
+dependencies = ["annotated-types>=0.8.0", "pymongo>=4.18.1"]
 
 [project.urls]
 Repository = "https://github.com/alessio-locatelli/client-query-cache"
@@ -58,6 +58,7 @@ dev = [
   "pytest-cov>=7.1.0",
   "pyyaml>=6.0.3",
   "types-pyyaml>=6.0.12.20260906",
+  "filelock>=4.1.0",
 ]
 docs = ["mike", "tomli-w>=1.2.0", "zensical>=0.0.68"]
 memory = ["pytest-memray>=1.11.0"]

{client_query_cache-0.6.0 → client_query_cache-0.7.0}/src/client_query_cache/_core/canonical.py

@@ -17,26 +17,35 @@ class _CanonicalTag:
         return f"<canonical:{self._name}>"
 
 
+class _PendingTag:
+    __slots__ = ("canonical", "items")
+
+    def __init__(self, name: str, *, items: bool) -> None:
+        self.canonical = _CanonicalTag(name)
+        self.items = items
+
+
 _MAPPING_TAG = _CanonicalTag("map")
 _SEQUENCE_TAG = _CanonicalTag("seq")
 _BOOL_TAG = _CanonicalTag("bool")
-_OWN_TAGS = (_MAPPING_TAG, _SEQUENCE_TAG, _BOOL_TAG)
 _TAGGED_TUPLE_SIZE = 2
 
 
 def canonicalize(value: object) -> Canonical:
-    if (
-        isinstance(value, tuple)
-        and len(value) == _TAGGED_TUPLE_SIZE
-        and any(value[0] is tag for tag in _OWN_TAGS)
-    ):
-        return value
+    if isinstance(value, tuple) and len(value) == _TAGGED_TUPLE_SIZE:
+        tag, payload = value
+        if type(tag) is _CanonicalTag:
+            return value
+        if type(tag) is _PendingTag:
+            if tag.items:
+                return (tag.canonical, tuple([canonicalize(item) for item in payload]))
+            return (tag.canonical, canonicalize(payload))
     if isinstance(value, Mapping):
         pairs = [(canonicalize(key), canonicalize(item)) for key, item in value.items()]
         items = tuple(sorted(pairs, key=lambda pair: repr(pair[0])))
         return (_MAPPING_TAG, items)
     if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
-        return (_SEQUENCE_TAG, tuple(canonicalize(item) for item in value))
+        return (_SEQUENCE_TAG, tuple([canonicalize(item) for item in value]))
     if isinstance(value, bool):
         return (_BOOL_TAG, value)
     try:

{client_query_cache-0.6.0 → client_query_cache-0.7.0}/src/client_query_cache/_core/collection_metadata.py

@@ -6,6 +6,7 @@ from typing import TYPE_CHECKING, Any
 
 from client_query_cache._core.collation import normalize_collation
 from client_query_cache._core.snapshots import BypassReason
+from client_query_cache._types import NonNegativeInt
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
@@ -22,7 +23,7 @@ _COLLECTION_REASONS = {
 
 @dataclass(frozen=True, slots=True)
 class CollectionMetadata:
-    checked_epoch: int
+    checked_epoch: NonNegativeInt
     bypass_reason: BypassReason | None
     default_collation: Mapping[str, Any] | None
 

{client_query_cache-0.6.0 → client_query_cache-0.7.0}/src/client_query_cache/_core/count_reads.py

@@ -14,7 +14,7 @@ _OMITTED = object()
 
 class CountReadOptions(TypedDict):
     cache_options: tuple[object, object, object, object]
-    extra_options: dict[str, object]  # Can be empty for cacheable reads.
+    extra_options: dict[str, object]
 
 
 def count_read_options(kwargs: Mapping[str, object]) -> CountReadOptions:

{client_query_cache-0.6.0 → client_query_cache-0.7.0}/src/client_query_cache/_core/cursor_capture.py

@@ -48,7 +48,7 @@ class CursorCapture:
         self._find_source = find_source
         self._max_entry_bytes = core.snapshot().max_entry_bytes
         self._documents: list[RawBSONDocument] = []  # An empty result is cacheable.
-        self.retained_bytes = 0  # Empty and abandoned captures retain no payload.
+        self.retained_bytes = 0
         self._active = True
 
     def append(self, document: Mapping[str, Any]) -> None:

{client_query_cache-0.6.0 → client_query_cache-0.7.0}/src/client_query_cache/_core/entries.py

@@ -4,6 +4,8 @@ import enum
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 
+from client_query_cache._types import NonNegativeInt
+
 if TYPE_CHECKING:
     from client_query_cache._core.canonical import Canonical
     from client_query_cache._core.find_reads import FindSource
@@ -20,8 +22,8 @@ class AdmissionOutcome(enum.Enum):
 
 @dataclass(eq=False, slots=True)
 class CacheEntry:
-    generation_key: tuple[int, ...]
-    weight: int
+    generation_key: tuple[NonNegativeInt, ...]
+    weight: NonNegativeInt
     value: bytes
     namespace: NamespaceId
     identity: Canonical | None

{client_query_cache-0.6.0 → client_query_cache-0.7.0}/src/client_query_cache/_core/find_one_reads.py

@@ -9,6 +9,7 @@ from client_query_cache._core.collation import normalize_collation
 from client_query_cache._core.order_sensitive_keys import (
     order_sensitive_discriminator_key,
 )
+from client_query_cache._types import NonNegativeInt
 
 type CollationInput = Collation | Mapping[str, Any]
 
@@ -92,16 +93,18 @@ def find_one_read_shape(
     sort: Sequence[tuple[str, int]] | None,
     effective_collation: Mapping[str, Any] | None,
     codec_identity: object,
+    remainder: Mapping[str, Any] | None = None,
 ) -> object:
+    shape = ("find_one", projection, sort, effective_collation, codec_identity)
     return order_sensitive_discriminator_key(
-        ("find_one", projection, sort, effective_collation, codec_identity)
+        (*shape, remainder) if remainder else shape
     )
 
 
 def generic_find_one_discriminator(
     filter_query: object,
     read_shape: object,
-    index_generation: int,  # Can be zero.
+    index_generation: NonNegativeInt,
 ) -> object:
     return order_sensitive_discriminator_key(
         ("find_one_generic", filter_query, read_shape, index_generation)

{client_query_cache-0.6.0 → client_query_cache-0.7.0}/src/client_query_cache/_core/find_reads.py

@@ -8,6 +8,7 @@ from client_query_cache._core.order_sensitive_keys import (
     order_sensitive_discriminator_key,
 )
 from client_query_cache._core.query_filters import find_filter_key
+from client_query_cache._types import NonNegativeInt
 
 if TYPE_CHECKING:
     from client_query_cache._core.canonical import Canonical
@@ -15,8 +16,8 @@ if TYPE_CHECKING:
 
 @dataclass(frozen=True, slots=True)
 class FindSource:
-    family: int  # A compact hash, possibly zero; collisions require key equality.
-    limit: int  # Zero denotes unlimited; negative and boolean limits are excluded.
+    family: int  # A compact hash; collisions require key equality.
+    limit: NonNegativeInt  # Zero denotes unlimited; boolean limits are excluded.
 
 
 @dataclass(frozen=True, slots=True)
@@ -47,7 +48,7 @@ def find_read_shape(
     filter_document: object,
     projection: object,
     ordering: object,
-    skip: int,  # Zero means no skipped documents.
+    skip: NonNegativeInt,  # Zero means no skipped documents.
     limit: int,  # Zero and negative limits use native semantics.
     *,
     collation: object,

{client_query_cache-0.6.0 → client_query_cache-0.7.0}/src/client_query_cache/_core/identity_reads.py

@@ -40,16 +40,18 @@ def extract_equality_value(value: object) -> object:
     return value
 
 
-def extract_id_identity(filter_query: object) -> object:
-    if filter_query is None:
-        return NO_IDENTITY
+def extract_id_anchor(filter_query: object) -> tuple[object, Mapping[str, Any]]:
     if not isinstance(filter_query, Mapping):
-        if _is_regex(filter_query):
-            return NO_IDENTITY
-        return filter_query
-    if set(filter_query) != {_ID_FIELD}:
-        return NO_IDENTITY
-    return extract_equality_value(filter_query[_ID_FIELD])
+        return extract_equality_value(filter_query), {}
+    try:
+        identity = extract_equality_value(filter_query[_ID_FIELD])
+    except KeyError:
+        return NO_IDENTITY, {}
+    if identity is NO_IDENTITY:
+        return NO_IDENTITY, {}
+    return identity, {
+        key: value for key, value in filter_query.items() if key != _ID_FIELD
+    }
 
 
 def normalize_identity_for_cache_key(

{client_query_cache-0.6.0 → client_query_cache-0.7.0}/src/client_query_cache/_core/lru.py

@@ -4,6 +4,8 @@ import threading
 from collections import OrderedDict
 from typing import TYPE_CHECKING
 
+from client_query_cache._types import NonNegativeInt, PositiveInt
+
 if TYPE_CHECKING:
     from client_query_cache._core.entries import CacheEntry
     from client_query_cache._core.keys import CacheKey
@@ -23,8 +25,8 @@ class WeightedLru:
     def __init__(
         self,
         *,
-        shared_budget_bytes: int,
-        max_entry_bytes: int,
+        shared_budget_bytes: PositiveInt,
+        max_entry_bytes: PositiveInt,
         guard: LockOrderGuard,
     ) -> None:
         self._shared_budget_bytes = shared_budget_bytes
@@ -35,17 +37,17 @@ class WeightedLru:
         self._lock = threading.Lock()
 
     @property
-    def max_entry_bytes(self) -> int:
+    def max_entry_bytes(self) -> PositiveInt:
         return self._max_entry_bytes
 
     @property
-    def shared_budget_bytes(self) -> int:
+    def shared_budget_bytes(self) -> PositiveInt:
         return self._shared_budget_bytes
 
-    def is_oversize(self, weight: int) -> bool:
+    def is_oversize(self, weight: NonNegativeInt) -> bool:
         return weight > self._max_entry_bytes
 
-    def snapshot_usage(self) -> tuple[int, int]:
+    def snapshot_usage(self) -> tuple[NonNegativeInt, NonNegativeInt]:
         with self._guard.lru_section(), self._lock:
             return self._used_bytes, len(self._order)