client-query-cache 0.8.1__tar.gz → 0.9.0__tar.gz

client_query_cache-0.9.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: client-query-cache
+Version: 0.9.0
+Classifier: Framework :: AsyncIO
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+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'
+Provides-Extra: otel
+License-File: LICENSE
+Summary: Sync and asyncio PyMongo query caching with change-stream invalidation and Rust-backed sharing across workers.
+Author-email: Alessio Locatelli <<software.development@secure.mailbox.org>>
+License-Expression: Apache-2.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Documentation, https://alessio-locatelli.github.io/client-query-cache/
+Project-URL: Repository, https://github.com/alessio-locatelli/client-query-cache
+
+# 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/)
+
+**Speed up read-heavy, high-throughput Python applications.** `client-query-cache` serves eligible repeated PyMongo reads from memory, reducing read latency and avoiding MongoDB round trips on cache hits.
+
+Add caching through an explicit [cached collection view](https://alessio-locatelli.github.io/client-query-cache/usage/cached-reads/). Keep your existing MongoDB queries and use PyMongo for writes.
+
+- **[Synchronous](https://alessio-locatelli.github.io/client-query-cache/getting-started/synchronous/) and [asyncio](https://alessio-locatelli.github.io/client-query-cache/getting-started/asyncio/) APIs** for long-lived Python applications.
+- **[MongoDB change streams](https://alessio-locatelli.github.io/client-query-cache/usage/consistency/)** invalidate affected results, including writes from other applications.
+- **[Shared caching across application workers](https://alessio-locatelli.github.io/client-query-cache/operations/shared-cache/)** on one [supported Linux host](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/#requirements) reduces duplicate cached documents and uses one change stream per active database.
+- **[A Rust-backed shared cache](https://alessio-locatelli.github.io/client-query-cache/benchmarks/shared-cache/)** serves eligible warm reads from native shared memory without a MongoDB round trip.
+
+Choose `CacheManager` for caching within one process, or `SharedCacheManager` to reuse eligible collection reads across trusted same-host workers. Both support sync and asyncio. See [which manager to choose](https://alessio-locatelli.github.io/client-query-cache/getting-started/choose-a-manager/).
+
+With shared caching, workers look up the same cache and use their own PyMongo clients for misses and bypasses:
+
+```mermaid
+flowchart TB
+    subgraph Application["Python application"]
+        Worker1["Python worker 1"] -->|"Cache lookup"| Cache["Rust-backed<br/>shared cache"]
+        Worker2["Python worker 2"] -->|"Cache lookup"| Cache
+    end
+    Worker1 -->|"Miss / bypass"| DB[("MongoDB")]
+    Worker2 -->|"Miss / bypass"| DB
+    DB -.->|"Change streams<br/>Async invalidation"| Cache
+```
+
+[Benchmarks](https://alessio-locatelli.github.io/client-query-cache/benchmarks/shared-cache/) compare direct reads, independent caches and shared caching. Sharing avoids duplicated values and streams, but its owner process and cache misses have costs. Rust does not guarantee a faster application or lower total memory for every workload.
+
+![Illustrative process-local read latency on a logarithmic scale: direct local MongoDB read, about 120 microseconds; direct Atlas M0 read, 79.4 milliseconds; cached reads in either deployment, about 61 microseconds.](docs/user/assets/benchmark-latency-light.svg)
+
+The graphic shows [process-local measurements from local MongoDB and Atlas deployments](https://alessio-locatelli.github.io/client-query-cache/benchmarks/#illustrative-read-latency); it is separate from the shared-cache comparison above.
+
+## Quick start
+
+```bash
+uv add client-query-cache
+```
+
+Or use `pip install client-query-cache`.
+
+```python
+from pymongo import MongoClient
+
+from client_query_cache import CacheManager
+
+with (
+    MongoClient("mongodb://localhost:27017") as client,
+    CacheManager(client) as cache_manager,
+):
+    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"})
+    cached_collection.find_one({"_id": "example"})  # Repeated reads can hit the cache.
+```
+
+Check the [platform and MongoDB requirements](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/#requirements) before installing. [Read eligibility](https://alessio-locatelli.github.io/client-query-cache/reference/api/#bypass-conditions) determines which requests can use the cache.
+
+Invalidation is asynchronous: cached reads can briefly return a preceding value after a write. Use direct PyMongo reads with suitable consistency controls for read-after-write and current authorization; see [consistency](https://alessio-locatelli.github.io/client-query-cache/usage/consistency/).
+
+## Run an application
+
+Start with the [synchronous](https://alessio-locatelli.github.io/client-query-cache/getting-started/synchronous/) or [asyncio](https://alessio-locatelli.github.io/client-query-cache/getting-started/asyncio/) tutorial. The [shared FastAPI example](https://alessio-locatelli.github.io/client-query-cache/examples/fastapi-shared/) runs real Granian workers and verifies cross-process hits, invalidation and graceful shutdown. The [compact FastAPI example](https://alessio-locatelli.github.io/client-query-cache/examples/fastapi-minimal/) demonstrates process-local caching.
+
+[Deployment](https://alessio-locatelli.github.io/client-query-cache/operations/) · [API reference](https://alessio-locatelli.github.io/client-query-cache/reference/api/) · [Examples](https://alessio-locatelli.github.io/client-query-cache/examples/)
+
+The library is tested against real MongoDB replica sets, including [concurrency stress tests](https://github.com/alessio-locatelli/client-query-cache/blob/main/docs/development/concurrency-stress-tests.md). Separate checks guard against [performance](https://github.com/alessio-locatelli/client-query-cache/blob/main/docs/development/performance-regression-guard.md) and [memory](https://github.com/alessio-locatelli/client-query-cache/blob/main/docs/development/memory-regression-tests.md) regressions.
+
+---
+
+> MongoDB is a registered trademark of MongoDB, Inc. This project is independent and is not affiliated with or endorsed by MongoDB, Inc.
+

client_query_cache-0.9.0/README.md

@@ -0,0 +1,78 @@
+# 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/)
+
+**Speed up read-heavy, high-throughput Python applications.** `client-query-cache` serves eligible repeated PyMongo reads from memory, reducing read latency and avoiding MongoDB round trips on cache hits.
+
+Add caching through an explicit [cached collection view](https://alessio-locatelli.github.io/client-query-cache/usage/cached-reads/). Keep your existing MongoDB queries and use PyMongo for writes.
+
+- **[Synchronous](https://alessio-locatelli.github.io/client-query-cache/getting-started/synchronous/) and [asyncio](https://alessio-locatelli.github.io/client-query-cache/getting-started/asyncio/) APIs** for long-lived Python applications.
+- **[MongoDB change streams](https://alessio-locatelli.github.io/client-query-cache/usage/consistency/)** invalidate affected results, including writes from other applications.
+- **[Shared caching across application workers](https://alessio-locatelli.github.io/client-query-cache/operations/shared-cache/)** on one [supported Linux host](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/#requirements) reduces duplicate cached documents and uses one change stream per active database.
+- **[A Rust-backed shared cache](https://alessio-locatelli.github.io/client-query-cache/benchmarks/shared-cache/)** serves eligible warm reads from native shared memory without a MongoDB round trip.
+
+Choose `CacheManager` for caching within one process, or `SharedCacheManager` to reuse eligible collection reads across trusted same-host workers. Both support sync and asyncio. See [which manager to choose](https://alessio-locatelli.github.io/client-query-cache/getting-started/choose-a-manager/).
+
+With shared caching, workers look up the same cache and use their own PyMongo clients for misses and bypasses:
+
+```mermaid
+flowchart TB
+    subgraph Application["Python application"]
+        Worker1["Python worker 1"] -->|"Cache lookup"| Cache["Rust-backed<br/>shared cache"]
+        Worker2["Python worker 2"] -->|"Cache lookup"| Cache
+    end
+    Worker1 -->|"Miss / bypass"| DB[("MongoDB")]
+    Worker2 -->|"Miss / bypass"| DB
+    DB -.->|"Change streams<br/>Async invalidation"| Cache
+```
+
+[Benchmarks](https://alessio-locatelli.github.io/client-query-cache/benchmarks/shared-cache/) compare direct reads, independent caches and shared caching. Sharing avoids duplicated values and streams, but its owner process and cache misses have costs. Rust does not guarantee a faster application or lower total memory for every workload.
+
+![Illustrative process-local read latency on a logarithmic scale: direct local MongoDB read, about 120 microseconds; direct Atlas M0 read, 79.4 milliseconds; cached reads in either deployment, about 61 microseconds.](docs/user/assets/benchmark-latency-light.svg)
+
+The graphic shows [process-local measurements from local MongoDB and Atlas deployments](https://alessio-locatelli.github.io/client-query-cache/benchmarks/#illustrative-read-latency); it is separate from the shared-cache comparison above.
+
+## Quick start
+
+```bash
+uv add client-query-cache
+```
+
+Or use `pip install client-query-cache`.
+
+```python
+from pymongo import MongoClient
+
+from client_query_cache import CacheManager
+
+with (
+    MongoClient("mongodb://localhost:27017") as client,
+    CacheManager(client) as cache_manager,
+):
+    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"})
+    cached_collection.find_one({"_id": "example"})  # Repeated reads can hit the cache.
+```
+
+Check the [platform and MongoDB requirements](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/#requirements) before installing. [Read eligibility](https://alessio-locatelli.github.io/client-query-cache/reference/api/#bypass-conditions) determines which requests can use the cache.
+
+Invalidation is asynchronous: cached reads can briefly return a preceding value after a write. Use direct PyMongo reads with suitable consistency controls for read-after-write and current authorization; see [consistency](https://alessio-locatelli.github.io/client-query-cache/usage/consistency/).
+
+## Run an application
+
+Start with the [synchronous](https://alessio-locatelli.github.io/client-query-cache/getting-started/synchronous/) or [asyncio](https://alessio-locatelli.github.io/client-query-cache/getting-started/asyncio/) tutorial. The [shared FastAPI example](https://alessio-locatelli.github.io/client-query-cache/examples/fastapi-shared/) runs real Granian workers and verifies cross-process hits, invalidation and graceful shutdown. The [compact FastAPI example](https://alessio-locatelli.github.io/client-query-cache/examples/fastapi-minimal/) demonstrates process-local caching.
+
+[Deployment](https://alessio-locatelli.github.io/client-query-cache/operations/) · [API reference](https://alessio-locatelli.github.io/client-query-cache/reference/api/) · [Examples](https://alessio-locatelli.github.io/client-query-cache/examples/)
+
+The library is tested against real MongoDB replica sets, including [concurrency stress tests](https://github.com/alessio-locatelli/client-query-cache/blob/main/docs/development/concurrency-stress-tests.md). Separate checks guard against [performance](https://github.com/alessio-locatelli/client-query-cache/blob/main/docs/development/performance-regression-guard.md) and [memory](https://github.com/alessio-locatelli/client-query-cache/blob/main/docs/development/memory-regression-tests.md) regressions.
+
+---
+
+> MongoDB is a registered trademark of MongoDB, Inc. This project is independent and is not affiliated with or endorsed by MongoDB, Inc.

{client_query_cache-0.8.1 → client_query_cache-0.9.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "client-query-cache"
-version = "0.8.1"
-description = "Client-side caching for PyMongo, kept coherent using MongoDB change streams."
+version = "0.9.0"
+description = "Sync and asyncio PyMongo query caching with change-stream invalidation and Rust-backed sharing across workers."
 authors = [
   { name = "Alessio Locatelli", email = "<software.development@secure.mailbox.org>" },
 ]

{client_query_cache-0.8.1 → client_query_cache-0.9.0}/src/client_query_cache/_core/codec.py

@@ -11,6 +11,8 @@ if TYPE_CHECKING:
     from bson.codec_options import TypeRegistry
 
 _ENVELOPE_FIELD = "v"
+# BSON length, document tag, UTF-8 field name, and its NUL terminator.
+_DOCUMENT_OFFSET = 4 + 1 + len(_ENVELOPE_FIELD.encode()) + 1
 
 
 class _TypeRegistryIdentity:
@@ -37,6 +39,13 @@ def encode_value(
     )
 
 
+def encode_document(
+    document: Mapping[str, Any], codec_options: CodecOptions[Mapping[str, Any]]
+) -> bytes:
+    # Embedded encoding preserves field order; top-level encoding promotes _id.
+    return encode_value(document, codec_options)[_DOCUMENT_OFFSET:-1]
+
+
 def decode_value(
     encoded: bytes, codec_options: CodecOptions[Mapping[str, Any]] | None = None
 ) -> object:

{client_query_cache-0.8.1 → client_query_cache-0.9.0}/src/client_query_cache/_core/collection_metadata.py

@@ -1,18 +1,16 @@
 from __future__ import annotations
 
-import threading
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 
 from client_query_cache._core.collation import normalize_collation
+from client_query_cache._core.namespace_metadata import NamespaceMetadataCache
 from client_query_cache._core.snapshots import BypassReason
-from client_query_cache._types import NonNegativeInt
+from client_query_cache._types import NonNegativeFloat, NonNegativeInt, PositiveInt
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
 
-    from client_query_cache._core.keys import NamespaceId
-
 
 _COLLECTION_REASONS = {
     "collection": None,
@@ -26,25 +24,15 @@ class CollectionMetadata:
     checked_epoch: NonNegativeInt
     bypass_reason: BypassReason | None
     default_collation: Mapping[str, Any] | None
+    epoch_bound: bool = True
+    expires_at: NonNegativeFloat | None = None
 
 
-class CollectionMetadataCache:
-    __slots__ = ("_entries", "_lock")
-
-    def __init__(self) -> None:
-        self._entries: dict[NamespaceId, CollectionMetadata] = {}
-        self._lock = threading.Lock()
-
-    def get(self, namespace: NamespaceId) -> CollectionMetadata | None:
-        with self._lock:
-            try:
-                return self._entries[namespace]
-            except KeyError:
-                return None
+class CollectionMetadataCache(NamespaceMetadataCache[CollectionMetadata]):
+    __slots__ = ()
 
-    def put(self, namespace: NamespaceId, metadata: CollectionMetadata) -> None:
-        with self._lock:
-            self._entries[namespace] = metadata
+    def __init__(self, max_namespaces: PositiveInt = 1024) -> None:
+        super().__init__(max_namespaces)
 
 
 @dataclass(frozen=True, slots=True)

{client_query_cache-0.8.1 → client_query_cache-0.9.0}/src/client_query_cache/_core/cursor_capture.py

@@ -4,7 +4,7 @@ from typing import TYPE_CHECKING, Any
 
 from bson.raw_bson import DEFAULT_RAW_BSON_OPTIONS, RawBSONDocument
 
-from client_query_cache._core.codec import encode_value
+from client_query_cache._core.codec import encode_document
 from client_query_cache._core.errors import CacheClosedError
 
 if TYPE_CHECKING:
@@ -46,7 +46,7 @@ class CursorCapture:
         self._discriminator = discriminator
         self._codec_options = codec_options
         self._find_source = find_source
-        self._max_entry_bytes = core.snapshot().max_entry_bytes
+        self._max_entry_bytes = core.max_entry_bytes
         self._documents: list[RawBSONDocument] = []  # An empty result is cacheable.
         self.retained_bytes = 0
         self._active = True
@@ -55,7 +55,7 @@ class CursorCapture:
         if not self._active:
             return
         try:
-            encoded = encode_value(document, self._codec_options)
+            encoded = encode_document(document, self._codec_options)
         except Exception:  # noqa: BLE001 - Application BSON encoders can raise arbitrary errors.
             self.abandon()
             return
@@ -63,9 +63,7 @@ class CursorCapture:
             self._core.record_oversized_bypass()
             self.abandon()
             return
-        # Access the envelope without replaying application codec transformations.
-        envelope = RawBSONDocument(encoded, DEFAULT_RAW_BSON_OPTIONS)
-        self._documents.append(envelope["v"])
+        self._documents.append(RawBSONDocument(encoded, DEFAULT_RAW_BSON_OPTIONS))
         self.retained_bytes += len(encoded)
 
     def abandon(self) -> None:

{client_query_cache-0.8.1 → client_query_cache-0.9.0}/src/client_query_cache/_core/find_reads.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import TYPE_CHECKING
 
 from client_query_cache._core.canonical import canonicalize
@@ -31,9 +31,29 @@ class FindReadShape:
 
     @property
     def source(self) -> FindSource | None:
-        if isinstance(self.limit, bool) or self.limit < 0:
-            return None
-        return FindSource(hash(canonicalize(self.family)), self.limit)
+        return _find_source(self.family, self.limit)
+
+
+@dataclass(frozen=True, slots=True)
+class PreparedFindRead:
+    family: Canonical
+    limit: int  # Negative and boolean limits retain exact identity.
+    discriminator: Canonical = field(init=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "discriminator", find_discriminator(self.family, self.limit)
+        )
+
+    @property
+    def source(self) -> FindSource | None:
+        return _find_source(self.family, self.limit)
+
+
+def _find_source(family: object, limit: int) -> FindSource | None:
+    if isinstance(limit, bool) or limit < 0:
+        return None
+    return FindSource(hash(canonicalize(family)), limit)
 
 
 def find_discriminator(