client-query-cache 0.1.0__tar.gz → 0.3.0__tar.gz

client_query_cache-0.3.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.3
+Name: client-query-cache
+Version: 0.3.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>>
+Requires-Dist: pymongo>=4.18.1
+Requires-Dist: opentelemetry-api>=1.45.0 ; extra == 'otel'
+Requires-Python: >=3.14.6
+Project-URL: Repository, https://github.com/alessio-locatelli/client-query-cache
+Project-URL: Documentation, https://alessio-locatelli.github.io/client-query-cache/
+Provides-Extra: otel
+Description-Content-Type: text/markdown
+
+# Coherent client-side caching for PyMongo
+
+[![Python 3.14.6+](https://img.shields.io/badge/python-3.14.6%2B-blue.svg)](https://www.python.org/downloads/)
+
+`client-query-cache` uses MongoDB change streams to keep cached reads coherent. 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.
+
+![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)
+
+Results vary by workload and deployment. [Measurements and methodology](https://alessio-locatelli.github.io/client-query-cache/benchmarks/).
+
+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.
+
+## 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,
+):
+    users = cache.cached(client["my_database"]["users"])
+    users.find_one({"_id": "alice"})  # Reads from MongoDB.
+    users.find_one({"_id": "alice"})  # Repeated reads can use the cache.
+```
+
+## References
+
+[Getting started](https://alessio-locatelli.github.io/client-query-cache/getting-started/synchronous/) · [Benchmarks](https://alessio-locatelli.github.io/client-query-cache/benchmarks/) · [Examples](https://alessio-locatelli.github.io/client-query-cache/examples/)
+
+---
+
+> 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.3.0/README.md

@@ -0,0 +1,45 @@
+# Coherent client-side caching for PyMongo
+
+[![Python 3.14.6+](https://img.shields.io/badge/python-3.14.6%2B-blue.svg)](https://www.python.org/downloads/)
+
+`client-query-cache` uses MongoDB change streams to keep cached reads coherent. 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.
+
+![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)
+
+Results vary by workload and deployment. [Measurements and methodology](https://alessio-locatelli.github.io/client-query-cache/benchmarks/).
+
+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.
+
+## 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,
+):
+    users = cache.cached(client["my_database"]["users"])
+    users.find_one({"_id": "alice"})  # Reads from MongoDB.
+    users.find_one({"_id": "alice"})  # Repeated reads can use the cache.
+```
+
+## References
+
+[Getting started](https://alessio-locatelli.github.io/client-query-cache/getting-started/synchronous/) · [Benchmarks](https://alessio-locatelli.github.io/client-query-cache/benchmarks/) · [Examples](https://alessio-locatelli.github.io/client-query-cache/examples/)
+
+---
+
+> 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.1.0 → client_query_cache-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "client-query-cache"
-version = "0.1.0"
+version = "0.3.0"
 description = "Client-side caching for PyMongo, kept coherent using MongoDB change streams."
 readme = "README.md"
 requires-python = ">=3.14.6"
@@ -12,6 +12,7 @@ email = "<software.development@secure.mailbox.org>"
 
 [project.urls]
 Repository = "https://github.com/alessio-locatelli/client-query-cache"
+Documentation = "https://alessio-locatelli.github.io/client-query-cache/"
 
 [project.optional-dependencies]
 otel = ["opentelemetry-api>=1.45.0"]
@@ -26,7 +27,6 @@ dev = [
     "types-pygments>=2.21.0.20260819",
     "types-pysocks>=1.7.1.20260518",
     "types-simplejson>=4.1.0.20260724",
-    "coverage>=7.16.1",
     "faker>=40.38.0",
     "hypothesis>=6.168.0",
     "pytest>=9.1.1",
@@ -44,15 +44,30 @@ dev = [
     "types-psutil>=7.2.2.20260906",
     "dnspython>=2.8.0",
     "python-snappy>=0.7.3",
+    "pytest-xdist[psutil]>=3.8.0",
+    "pytest-cov>=7.1.0",
 ]
+docs = [
+    "mike",
+    "tomli-w>=1.2.0",
+    "zensical>=0.0.68",
+]
+memory = ["pytest-memray>=1.11.0"]
 
 [build-system]
 requires = ["uv_build>=0.12.18,<0.13.0"]
 build-backend = "uv_build"
 
+[tool.uv]
+environments = ["sys_platform == 'linux'"]
+
 [tool.uv.build-backend]
 module-root = "src"
 
+[tool.uv.sources.mike]
+git = "https://github.com/squidfunk/mike.git"
+rev = "2d4ad799442f4592db8ad53b179bfb33db8c69ac"
+
 [tool.slotscheck]
 strict-imports = true
 require-superclass = true
@@ -60,6 +75,7 @@ require-subclass = true
 exclude-modules = """
 (
   ^specifications
+  | ^examples
 )
 """
 
@@ -87,3 +103,6 @@ level = "aggressive"
 
 [tool.ruff-extra-rules.redundant-dict-get]
 level = "aggressive"
+
+[tool.ruff-extra-rules.defined-far-from-use]
+level = "aggressive"

{client_query_cache-0.1.0 → client_query_cache-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "client-query-cache"
-version = "0.1.0"
+version = "0.3.0"
 description = "Client-side caching for PyMongo, kept coherent using MongoDB change streams."
 authors = [
   { name = "Alessio Locatelli", email = "<software.development@secure.mailbox.org>" },
@@ -11,6 +11,7 @@ dependencies = ["pymongo>=4.18.1"]
 
 [project.urls]
 Repository = "https://github.com/alessio-locatelli/client-query-cache"
+Documentation = "https://alessio-locatelli.github.io/client-query-cache/"
 
 [project.optional-dependencies]
 otel = ["opentelemetry-api>=1.45.0"]
@@ -25,7 +26,6 @@ dev = [
   "types-pygments>=2.21.0.20260819",
   "types-pysocks>=1.7.1.20260518",
   "types-simplejson>=4.1.0.20260724",
-  "coverage>=7.16.1",
   "faker>=40.38.0",
   "hypothesis>=6.168.0",
   "pytest>=9.1.1",
@@ -43,7 +43,11 @@ dev = [
   "types-psutil>=7.2.2.20260906",
   "dnspython>=2.8.0",
   "python-snappy>=0.7.3",
+  "pytest-xdist[psutil]>=3.8.0",
+  "pytest-cov>=7.1.0",
 ]
+docs = ["mike", "tomli-w>=1.2.0", "zensical>=0.0.68"]
+memory = ["pytest-memray>=1.11.0"]
 
 [build-system]
 requires = ["uv_build>=0.12.18,<0.13.0"]
@@ -52,6 +56,12 @@ build-backend = "uv_build"
 [tool.uv.build-backend]
 module-root = "src"
 
+[tool.uv]
+environments = ["sys_platform == 'linux'"]
+
+[tool.uv.sources]
+mike = { git = "https://github.com/squidfunk/mike.git", rev = "2d4ad799442f4592db8ad53b179bfb33db8c69ac" } # pragma: allowlist secret
+
 [tool.slotscheck]
 strict-imports = true
 require-superclass = true
@@ -59,6 +69,7 @@ require-subclass = true
 exclude-modules = '''
 (
   ^specifications
+  | ^examples
 )
 '''
 
@@ -77,3 +88,5 @@ level = "aggressive"
 level = "aggressive"
 [tool.ruff-extra-rules.redundant-dict-get]
 level = "aggressive"
+[tool.ruff-extra-rules.defined-far-from-use]
+level = "aggressive"

client_query_cache-0.3.0/src/client_query_cache/__init__.py

@@ -0,0 +1,37 @@
+from ._core.errors import (
+    CacheClosedError,
+    CacheConfigurationError,
+    CacheError,
+    UnsupportedCacheRequestError,
+)
+from .synchronous import (
+    BypassReason,
+    BypassReasonCount,
+    CacheCore,
+    CacheCoreConfig,
+    CachedCollection,
+    CachedDatabase,
+    CacheManager,
+    CacheSnapshot,
+    StreamCostSnapshot,
+    StreamHealthSnapshot,
+    StreamHealthStatus,
+)
+
+__all__ = [
+    "BypassReason",
+    "BypassReasonCount",
+    "CacheClosedError",
+    "CacheConfigurationError",
+    "CacheCore",
+    "CacheCoreConfig",
+    "CacheError",
+    "CacheManager",
+    "CacheSnapshot",
+    "CachedCollection",
+    "CachedDatabase",
+    "StreamCostSnapshot",
+    "StreamHealthSnapshot",
+    "StreamHealthStatus",
+    "UnsupportedCacheRequestError",
+]

{client_query_cache-0.1.0 → client_query_cache-0.3.0}/src/client_query_cache/_core/collation.py

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 
+from pymongo.collation import Collation
+
 if TYPE_CHECKING:
     from collections.abc import Mapping
 
@@ -20,3 +22,13 @@ def normalize_collation(
     if locale == _SIMPLE_LOCALE:
         return None
     return collation
+
+
+def collation_document(
+    collation: Collation | Mapping[str, Any] | None,
+) -> Mapping[str, Any] | None:
+    if collation is None:
+        return None
+    if isinstance(collation, Collation):
+        return collation.document
+    return dict(collation)

{client_query_cache-0.1.0 → client_query_cache-0.3.0}/src/client_query_cache/_core/collection_metadata.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 
 from client_query_cache._core.collation import normalize_collation
+from client_query_cache._core.snapshots import BypassReason
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
@@ -12,10 +13,17 @@ if TYPE_CHECKING:
     from client_query_cache._core.keys import NamespaceId
 
 
+_COLLECTION_REASONS = {
+    "collection": None,
+    "view": BypassReason.VIEW_COLLECTION,
+    "timeseries": BypassReason.TIME_SERIES_COLLECTION,
+}
+
+
 @dataclass(frozen=True, slots=True)
 class CollectionMetadata:
     checked_epoch: int
-    is_cacheable: bool
+    bypass_reason: BypassReason | None
     default_collation: Mapping[str, Any] | None
 
 
@@ -40,16 +48,24 @@ class CollectionMetadataCache:
 
 @dataclass(frozen=True, slots=True)
 class CollectionProbeResult:
-    is_cacheable: bool
+    bypass_reason: BypassReason | None
     default_collation: Mapping[str, Any] | None
 
+    @property
+    def is_cacheable(self) -> bool:
+        return self.bypass_reason is None
+
 
 def interpret_list_collections_entry(
     entry: Mapping[str, Any] | None,
-) -> CollectionProbeResult | None:
+) -> CollectionProbeResult:
     if entry is None:
-        return None
+        return CollectionProbeResult(BypassReason.MISSING_COLLECTION, None)
     collection_type = entry["type"]
+    try:
+        bypass_reason = _COLLECTION_REASONS[collection_type]
+    except KeyError:
+        bypass_reason = BypassReason.METADATA_UNAVAILABLE
     try:
         options = entry["options"]
     except KeyError:
@@ -60,6 +76,6 @@ def interpret_list_collections_entry(
         collation = None
     default_collation = normalize_collation(collation)
     return CollectionProbeResult(
-        is_cacheable=collection_type == "collection",
+        bypass_reason=bypass_reason,
         default_collation=default_collation,
     )

client_query_cache-0.3.0/src/client_query_cache/_core/count_reads.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypedDict
+
+from pymongo.collation import Collation
+
+from client_query_cache._core.collation import collation_document
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+_OMITTED = object()
+
+
+class CountReadOptions(TypedDict):
+    cache_options: tuple[object, object, object, object]
+    extra_options: dict[str, object]  # Can be empty for cacheable reads.
+
+
+def count_read_options(kwargs: Mapping[str, object]) -> CountReadOptions:
+    extra_options = dict(kwargs)
+    skip = extra_options.pop("skip", 0)
+    limit = extra_options.pop("limit", _OMITTED)
+    collation = extra_options.pop("collation", None)
+    hint = extra_options.pop("hint", _OMITTED)
+    if isinstance(collation, Collation):
+        collation = collation_document(collation)
+    cache_options = (skip, limit, collation, hint)
+    return {
+        "cache_options": cache_options,
+        "extra_options": extra_options,
+    }

client_query_cache-0.3.0/src/client_query_cache/_core/cursor_capture.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+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.errors import CacheClosedError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from bson.codec_options import CodecOptions
+
+    from client_query_cache._core.entries import AdmissionOutcome
+    from client_query_cache._core.find_reads import FindSource
+    from client_query_cache._core.manager import CacheCore, NamespaceCapture
+
+
+class CursorCapture:
+    """Own immutable document snapshots until consumption completes."""
+
+    __slots__ = (
+        "_active",
+        "_capture",
+        "_codec_options",
+        "_core",
+        "_discriminator",
+        "_documents",
+        "_find_source",
+        "_max_entry_bytes",
+        "retained_bytes",
+    )
+
+    def __init__(
+        self,
+        core: CacheCore,
+        capture: NamespaceCapture,
+        discriminator: object,
+        codec_options: CodecOptions[Mapping[str, Any]],
+        *,
+        find_source: FindSource | None = None,
+    ) -> None:
+        self._core = core
+        self._capture = capture
+        self._discriminator = discriminator
+        self._codec_options = codec_options
+        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._active = True
+
+    def append(self, document: Mapping[str, Any]) -> None:
+        if not self._active:
+            return
+        try:
+            encoded = encode_value(document, self._codec_options)
+        except Exception:  # noqa: BLE001 - Application BSON encoders can raise arbitrary errors.
+            self.abandon()
+            return
+        if self.retained_bytes + len(encoded) > self._max_entry_bytes:
+            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.retained_bytes += len(encoded)
+
+    def abandon(self) -> None:
+        self._active = False
+        self._documents.clear()
+        self.retained_bytes = 0
+
+    def finish(self) -> AdmissionOutcome | None:
+        if not self._active:
+            return None
+        self._active = False
+        try:
+            return self._core.admit_namespace(
+                self._capture,
+                self._discriminator,
+                self._documents,
+                codec_options=self._codec_options,
+                find_source=self._find_source,
+            )
+        except CacheClosedError:
+            # The cursor owns its native resources independently of the manager.
+            return None
+        finally:
+            self._documents.clear()
+            self.retained_bytes = 0

{client_query_cache-0.1.0 → client_query_cache-0.3.0}/src/client_query_cache/_core/entries.py

@@ -6,6 +6,7 @@ from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     from client_query_cache._core.canonical import Canonical
+    from client_query_cache._core.find_reads import FindSource
     from client_query_cache._core.keys import NamespaceId
 
 
@@ -24,6 +25,7 @@ class CacheEntry:
     value: bytes
     namespace: NamespaceId
     identity: Canonical | None
+    find_source: FindSource | None = None
 
 
 @dataclass(frozen=True, slots=True)

client_query_cache-0.3.0/src/client_query_cache/_core/find_one_reads.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from pymongo.collation import Collation
+
+from client_query_cache._core.collation import normalize_collation
+from client_query_cache._core.order_sensitive_keys import (
+    order_sensitive_discriminator_key,
+)
+
+type CollationInput = Collation | Mapping[str, Any]
+
+_COLLATION_FIELDS = frozenset(
+    {
+        "locale",
+        "caseLevel",
+        "caseFirst",
+        "strength",
+        "numericOrdering",
+        "alternate",
+        "maxVariable",
+        "normalization",
+        "backwards",
+    }
+)
+
+
+def normalize_find_one_filter(filter_query: object) -> Mapping[str, Any]:
+    if filter_query is None:
+        return {}
+    if isinstance(filter_query, Mapping):
+        return filter_query
+    return {"_id": filter_query}
+
+
+def find_one_options_cacheable(
+    sort: Sequence[tuple[str, int]] | None,
+    collation: CollationInput | None,
+) -> bool:
+    if sort is not None and (
+        not isinstance(sort, (list, tuple))
+        or any(
+            not isinstance(pair, (list, tuple))
+            or len(pair) != 2
+            or not isinstance(pair[0], str)
+            or type(pair[1]) is not int
+            or pair[1] not in {-1, 1}
+            for pair in sort
+        )
+    ):
+        return False
+    if collation is None:
+        return True
+    document = collation.document if isinstance(collation, Collation) else collation
+    if not isinstance(document, dict) or not document.keys() <= _COLLATION_FIELDS:
+        return False
+    try:
+        validated = Collation(**document).document
+    except TypeError:
+        return False
+    except ValueError:
+        return False
+    if not validated["locale"]:
+        return False
+    if validated["locale"] == "simple":
+        return len(validated) == 1
+    for field, choices in (
+        ("strength", (1, 2, 3, 4, 5)),
+        ("caseFirst", ("upper", "lower", "off")),
+        ("alternate", ("non-ignorable", "shifted")),
+        ("maxVariable", ("punct", "space")),
+    ):
+        if field in validated and validated[field] not in choices:
+            return False
+    return True
+
+
+def effective_find_one_collation(
+    collation: CollationInput | None,
+    default_collation: Mapping[str, Any] | None,
+) -> Mapping[str, Any] | None:
+    if collation is None:
+        return default_collation
+    document = collation.document if isinstance(collation, Collation) else collation
+    return normalize_collation(document)
+
+
+def find_one_read_shape(
+    projection: Mapping[str, Any] | Sequence[str] | None,
+    sort: Sequence[tuple[str, int]] | None,
+    effective_collation: Mapping[str, Any] | None,
+    codec_identity: object,
+) -> object:
+    return order_sensitive_discriminator_key(
+        ("find_one", projection, sort, effective_collation, codec_identity)
+    )
+
+
+def generic_find_one_discriminator(
+    filter_query: object,
+    read_shape: object,
+    index_generation: int,  # Can be zero.
+) -> object:
+    return order_sensitive_discriminator_key(
+        ("find_one_generic", filter_query, read_shape, index_generation)
+    )

client_query_cache-0.3.0/src/client_query_cache/_core/find_reads.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from client_query_cache._core.canonical import canonicalize
+from client_query_cache._core.order_sensitive_keys import (
+    order_sensitive_discriminator_key,
+)
+from client_query_cache._core.query_filters import find_filter_key
+
+if TYPE_CHECKING:
+    from client_query_cache._core.canonical import Canonical
+
+
+@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.
+
+
+@dataclass(frozen=True, slots=True)
+class FindReadShape:
+    family: object
+    limit: int  # Zero and negative limits retain exact-only lookup.
+
+    @property
+    def discriminator(self) -> object:
+        return (self.family, self.limit)
+
+    @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)
+
+
+def find_discriminator(
+    family: Canonical,
+    limit: int,  # Zero and negative limits retain exact identity.
+) -> Canonical:
+    # Reuse the already canonical family without copying its query tree.
+    return canonicalize((family, limit))
+
+
+def find_read_shape(
+    filter_document: object,
+    projection: object,
+    ordering: object,
+    skip: int,  # Zero means no skipped documents.
+    limit: int,  # Zero and negative limits use native semantics.
+    *,
+    collation: object,
+    codec: object,
+) -> FindReadShape:
+    return FindReadShape(
+        family=order_sensitive_discriminator_key(
+            (
+                "find",
+                find_filter_key(filter_document),
+                projection,
+                ordering,
+                skip,
+                collation,
+                codec,
+            )
+        ),
+        limit=limit,
+    )