client-query-cache 0.2.0__tar.gz → 0.4.0__tar.gz

client_query_cache-0.4.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.3
+Name: client-query-cache
+Version: 0.4.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.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.
+```
+
+## 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.4.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.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.
+```
+
+## 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.2.0 → client_query_cache-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "client-query-cache"
-version = "0.2.0"
+version = "0.4.0"
 description = "Client-side caching for PyMongo, kept coherent using MongoDB change streams."
 readme = "README.md"
 requires-python = ">=3.14.6"
@@ -27,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",
@@ -45,19 +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",
+    "pyyaml>=6.0.3",
+    "types-pyyaml>=6.0.12.20260906",
 ]
-docs = ["zensical>=0.0.67"]
+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.build-backend]
-module-root = "src"
+[tool.uv]
+environments = ["sys_platform == 'linux'"]
+
+[tool.uv.sources.mike]
+git = "https://github.com/squidfunk/mike.git"
+rev = "2d4ad799442f4592db8ad53b179bfb33db8c69ac"
 
 [tool.slotscheck]
-strict-imports = true
-require-superclass = true
 require-subclass = true
 exclude-modules = """
 (
@@ -90,3 +100,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.2.0 → client_query_cache-0.4.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "client-query-cache"
-version = "0.2.0"
+version = "0.4.0"
 description = "Client-side caching for PyMongo, kept coherent using MongoDB change streams."
 authors = [
   { name = "Alessio Locatelli", email = "<software.development@secure.mailbox.org>" },
@@ -26,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",
@@ -44,19 +43,29 @@ 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",
+  "pyyaml>=6.0.3",
+  "types-pyyaml>=6.0.12.20260906",
 ]
-docs = ["zensical>=0.0.67"]
+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.build-backend]
-module-root = "src"
+[tool.uv]
+# uv 0.12.9 / lock context: https://docs.astral.sh/uv/reference/settings/#environments
+# The default is all environments. We override it because development dependencies and their lock resolution target Linux.
+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
+# slotscheck 0.21.0: https://github.com/ariebovenberg/slotscheck/blob/v0.21.0/src/slotscheck/config.py
+# require-subclass: The default is false. We override it because subclasses must preserve their slotted parent's memory contract.
 require-subclass = true
 exclude-modules = '''
 (
@@ -69,10 +78,15 @@ exclude-modules = '''
 paths = ["src", "tests", "benchmarks", ".vulture_whitelist"]
 
 [tool.ruff-extra-rules]
+# ruff-extra-rules v0.5.0: https://github.com/alessio-locatelli/ruff-extra-rules/blob/v0.5.0/README.md
+# The default is false. We override it because hook runs should apply available repairs.
 fix = true
 exclude = ["specifications"]
 extend-select = ["unused-pytriage"]
 [tool.ruff-extra-rules.meaningless-vars]
+# ruff-extra-rules v0.5.0: https://github.com/alessio-locatelli/ruff-extra-rules/tree/v0.5.0/src/pre_commit_hooks/ast_checks
+# For meaningless-vars, redundant-assignment, redundant-type-conversion, redundant-dict-get, and defined-far-from-use level:
+# The default is conservative. We override it because repository quality checks must include the broader supported simplifications and naming diagnostics.
 level = "aggressive"
 [tool.ruff-extra-rules.redundant-assignment]
 level = "aggressive"
@@ -80,3 +94,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.2.0 → client_query_cache-0.4.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.4.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.4.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.2.0 → client_query_cache-0.4.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.4.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,
+    )