client-query-cache 0.2.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.2.0 → client_query_cache-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "client-query-cache"
-version = "0.2.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"
@@ -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,16 +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 = ["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]
+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
@@ -90,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.2.0 → client_query_cache-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "client-query-cache"
-version = "0.2.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>" },
@@ -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,8 +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 = ["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"]
@@ -54,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
@@ -80,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.2.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.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.2.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_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,
+    )

{client_query_cache-0.2.0 → client_query_cache-0.3.0}/src/client_query_cache/_core/manager.py

@@ -4,7 +4,7 @@ import logging
 import threading
 from contextlib import contextmanager
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 from bson.errors import BSONError
 
@@ -16,6 +16,7 @@ from client_query_cache._core.errors import (
     CacheConfigurationError,
     UnsupportedCacheRequestError,
 )
+from client_query_cache._core.find_reads import find_discriminator
 from client_query_cache._core.keys import (
     IdentityCacheKey,
     NamespaceCacheKey,
@@ -45,6 +46,7 @@ if TYPE_CHECKING:
     from bson.codec_options import CodecOptions
 
     from client_query_cache._core.canonical import Canonical
+    from client_query_cache._core.find_reads import FindReadShape, FindSource
     from client_query_cache._core.keys import AliasKey, CacheKey, NamespaceId
 
 DEFAULT_SHARED_BUDGET_BYTES = 64 * 1024 * 1024
@@ -107,6 +109,16 @@ def _maybe_prune_identity_locked(
 
 def _discard_entry_locked(state: NamespaceState, entry: CacheEntry) -> None:
     was_indexed = state.entry_index.pop(entry, _NOT_INDEXED) is not _NOT_INDEXED
+    if entry.find_source is not None:
+        family = entry.find_source.family
+        try:
+            bucket = state.find_families[family]
+        except KeyError:
+            pass  # Invalidation can already have cleared the family.
+        else:
+            bucket.pop(entry, None)
+            if not bucket:
+                del state.find_families[family]
     if was_indexed and entry.identity is not None:
         identity_state = state.identities[entry.identity]
         identity_state.cached_ref_count -= 1
@@ -304,6 +316,9 @@ class _CacheCoreLifecycle(_CacheCoreBase):
     def record_bypass(self, reason: BypassReason = BypassReason.UNSPECIFIED) -> None:
         self._statistics.record_bypass(reason)
 
+    def record_oversized_bypass(self) -> None:
+        self._statistics.record_oversized_bypass()
+
     def snapshot(self) -> CacheSnapshot:
         used_bytes, entry_count = self._lru.snapshot_usage()
         hits, misses, evictions, bypasses, oversized_bypasses, bypass_reasons = (
@@ -361,6 +376,7 @@ class _CacheCoreNamespaceLifecycle(_CacheCoreBase):
         state = self._namespace(namespace)
         with self._namespace_section(state):
             state.generation += 1
+            state.find_families.clear()
             if not is_canonicalizable(identity):
                 return
             try:
@@ -389,6 +405,7 @@ class _CacheCoreNamespaceLifecycle(_CacheCoreBase):
             state.aliases = {}
             reclaimed = list(state.entry_index.items())
             state.entry_index.clear()
+            state.find_families.clear()
             for entry, _key in reclaimed:
                 if entry.identity is not None:
                     state.identities[entry.identity].cached_ref_count -= 1
@@ -472,13 +489,13 @@ class _CacheCoreIdentityAdmission(_CacheCoreBase):
     ) -> AdmissionOutcome:
         self._ensure_active()
         try:
-            canonical_shape = canonicalize(read_shape)
             try:
                 encoded = encode_value(value, codec_options)
             except BSONError:
                 return AdmissionOutcome.DECLINED_UNENCODABLE
             except OverflowError:
                 return AdmissionOutcome.DECLINED_UNENCODABLE
+            canonical_shape = canonicalize(read_shape)
             weight = len(encoded)
             with self._admission_section(
                 capture.namespace, capture.availability_generation, weight
@@ -595,15 +612,16 @@ class _CacheCoreNamespaceAdmission(_CacheCoreBase):
         value: object,
         *,
         codec_options: CodecOptions[Any] | None = None,
+        find_source: FindSource | None = None,
     ) -> AdmissionOutcome:
         self._ensure_active()
-        canonical_discriminator = canonicalize(discriminator)
         try:
             encoded = encode_value(value, codec_options)
         except BSONError:
             return AdmissionOutcome.DECLINED_UNENCODABLE
         except OverflowError:
             return AdmissionOutcome.DECLINED_UNENCODABLE
+        canonical_discriminator = canonicalize(discriminator)
         weight = len(encoded)
         with self._admission_section(
             capture.namespace, capture.availability_generation, weight
@@ -621,9 +639,15 @@ class _CacheCoreNamespaceAdmission(_CacheCoreBase):
                 value=encoded,
                 namespace=capture.namespace,
                 identity=None,
+                find_source=find_source,
             )
             admitted, displaced, evicted = self._lru.conditional_put(key, entry)
         self._process_evicted(evicted)
+
+        def publish_source() -> None:
+            if find_source is not None:
+                state.find_families.setdefault(find_source.family, {})[entry] = key
+
         return self._finalize_put(
             state,
             key,
@@ -631,7 +655,7 @@ class _CacheCoreNamespaceAdmission(_CacheCoreBase):
             admitted=admitted,
             displaced=displaced,
             is_still_valid=lambda: state.generation == capture.generation,
-            on_admit=lambda: None,
+            on_admit=publish_source,
         )
 
 
@@ -671,19 +695,19 @@ class _CacheCoreUniqueKeyAdmission(_CacheCoreBase):
         codec_options: CodecOptions[Any] | None = None,
     ) -> AdmissionOutcome:
         self._ensure_active()
-        namespace = namespace_capture.namespace
-        canonical_discriminator = canonicalize(discriminator)
         canonical_identity = canonicalize(order_sensitive_key(identity))
         if canonical_identity is None:
             message = "identity must not be None"
             raise UnsupportedCacheRequestError(message)
-        canonical_shape = canonicalize(read_shape)
         try:
             encoded = encode_value(value, codec_options)
         except BSONError:
             return AdmissionOutcome.DECLINED_UNENCODABLE
         except OverflowError:
             return AdmissionOutcome.DECLINED_UNENCODABLE
+        namespace = namespace_capture.namespace
+        canonical_discriminator = canonicalize(discriminator)
+        canonical_shape = canonicalize(read_shape)
         weight = len(encoded)
         with self._admission_section(
             namespace, namespace_capture.availability_generation, weight
@@ -779,9 +803,74 @@ class _CacheCoreUniqueKeyAdmission(_CacheCoreBase):
         return namespace_outcome
 
 
+def _find_candidate_order(
+    candidate: tuple[CacheEntry, NamespaceCacheKey],
+) -> tuple[bool, int]:
+    descriptor = candidate[0].find_source
+    assert descriptor is not None
+    # Zero denotes unlimited and sorts after every covering positive limit.
+    return descriptor.limit == 0, descriptor.limit
+
+
 class _CacheCoreLookup(_CacheCoreBase):
     __slots__ = ()
 
+    def _probe_namespace_entry(
+        self,
+        state: NamespaceState,
+        key: NamespaceCacheKey,
+        expected: CacheEntry | None = None,
+    ) -> CacheEntry | None:
+        entry = self._lru.peek(key)
+        if entry is None or (expected is not None and entry is not expected):
+            return None
+        with self._namespace_section(state):
+            valid = (state.generation,) == entry.generation_key
+        return entry if valid else None
+
+    def lookup_find(
+        self,
+        namespace: NamespaceId,
+        shape: FindReadShape,
+        *,
+        codec_options: CodecOptions[Any] | None = None,
+    ) -> LookupResult:
+        self._ensure_active()
+        if not self._is_database_available(namespace.database):
+            self._statistics.record_bypass(BypassReason.STREAM_UNAVAILABLE)
+            return LookupResult(hit=False)
+        state = self._namespace(namespace)
+        family = canonicalize(shape.family)
+        key = NamespaceCacheKey(namespace, find_discriminator(family, shape.limit))
+        entry = self._probe_namespace_entry(state, key)
+        if entry is None and not isinstance(shape.limit, bool) and shape.limit > 0:
+            with self._namespace_section(state):
+                try:
+                    candidates = tuple(state.find_families[hash(family)].items())
+                except KeyError:
+                    candidates = ()
+            for token, source_key in sorted(candidates, key=_find_candidate_order):
+                descriptor = token.find_source
+                assert descriptor is not None
+                limit = descriptor.limit
+                if limit != 0 and limit < shape.limit:
+                    continue
+                if source_key.discriminator != find_discriminator(family, limit):
+                    continue
+                candidate = self._probe_namespace_entry(state, source_key, token)
+                if candidate is not None:
+                    key, entry = source_key, candidate
+                    break
+        if entry is None:
+            self._statistics.record_miss()
+            return LookupResult(hit=False)
+        self._lru.touch(key)
+        self._statistics.record_hit()
+        documents = cast("list[object]", decode_value(entry.value, codec_options))
+        if not isinstance(shape.limit, bool) and shape.limit > 0:
+            documents = documents[: shape.limit]
+        return LookupResult(hit=True, value=documents)
+
     def lookup_identity(
         self,
         namespace: NamespaceId,

{client_query_cache-0.2.0 → client_query_cache-0.3.0}/src/client_query_cache/_core/namespace.py

@@ -7,7 +7,12 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from client_query_cache._core.canonical import Canonical
     from client_query_cache._core.entries import CacheEntry
-    from client_query_cache._core.keys import AliasKey, CacheKey, NamespaceId
+    from client_query_cache._core.keys import (
+        AliasKey,
+        CacheKey,
+        NamespaceCacheKey,
+        NamespaceId,
+    )
 
 
 @dataclass(slots=True)
@@ -32,4 +37,7 @@ class NamespaceState:
     identities: dict[Canonical, IdentityState] = field(default_factory=dict)
     aliases: dict[AliasKey, Canonical] = field(default_factory=dict)
     entry_index: dict[CacheEntry, CacheKey] = field(default_factory=dict)
+    find_families: dict[int, dict[CacheEntry, NamespaceCacheKey]] = field(
+        default_factory=dict  # Empty without compatible resident sources.
+    )
     identity_generation_watermark: int = 0