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

{client_query_cache-0.1.0 → client_query_cache-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: client-query-cache
-Version: 0.1.0
+Version: 0.2.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>>
@@ -8,6 +8,7 @@ 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
 
@@ -41,7 +42,7 @@ Or with pip: `pip install client-query-cache`.
 
 ## Usage
 
-`CacheManager` wraps a `pymongo.MongoClient` (or `pymongo.AsyncMongoClient`) that you construct and own. Its database and collection facades cache a narrow set of PyMongo's own read methods — `find_one`, `find`, `aggregate`, `count_documents`, `estimated_document_count`, and `distinct` — and keep cached results coherent as the underlying data changes. Every other operation, including all writes, is called directly on the facade the same way you'd call it on the wrapped PyMongo object:
+`CacheManager` wraps a `pymongo.MongoClient` (or `pymongo.AsyncMongoClient`) that you construct and own. Keep using your PyMongo collection for writes and everything else, and ask the manager for a cached view of that collection for six reads — `find_one`, `find`, `aggregate`, `count_documents`, `estimated_document_count`, and `distinct`. The cache keeps those results coherent as the underlying data changes:
 
 ```python
 from pymongo import MongoClient
@@ -50,28 +51,45 @@ from client_query_cache import CacheManager
 
 with (
     MongoClient("mongodb://localhost:27017") as client,
-    CacheManager(client) as manager,
+    CacheManager(client) as cache_manager,
 ):
-    collection = manager["my_database"]["my_collection"]
+    collection = client["my_database"]["my_collection"]
+    cached_collection = cache_manager.cached(collection)
+
     collection.insert_one({"_id": "example", "value": 42})
 
-    collection.find_one({"_id": "example"})  # cache miss: reads from MongoDB
-    collection.find_one({"_id": "example"})  # cache hit: served from the cache
+    # Cache miss: reads from MongoDB.
+    cached_collection.find_one({"_id": "example"})
+    # Cache hit: served from the cache.
+    cached_collection.find_one({"_id": "example"})
 
-    # Bridge stats like this into OpenTelemetry:
+    # Prints 1. Bridge stats like this into OpenTelemetry:
     # docs/architecture.md#opentelemetry-metrics
-    print(manager.cache_core.snapshot().hits)  # 1
+    print(cache_manager.snapshot().hits)
 
     collection.create_index("email", unique=True)
     collection.insert_one({"_id": "user-1", "email": "a@example.com"})
-    collection.find_one({"email": "a@example.com"})  # also cached, like an `_id` lookup
+    # Also cached, like an `_id` lookup.
+    cached_collection.find_one({"email": "a@example.com"})
+```
+
+`collection` is PyMongo's own object, so your editor and type checker see PyMongo's real methods and signatures. `cached_collection` has only the six cached reads; `find` and `aggregate` on it return a list instead of a cursor. Use `cached_collection.raw` (the same `collection`) whenever you need PyMongo's own cursor behavior.
+
+`find_one` caches deterministic single-document queries, including compound filters, match-all reads and missing results. Use `sort` to choose the first matching document and `collation` to control string matching:
+
+```python
+cached_collection.find_one(
+    {"status": "active"},
+    sort=[("updated_at", -1)],
+    collation={"locale": "en", "strength": 2},
+)
 ```
 
-`find_one` caches a lookup by `_id` and by any other field the database enforces as unique, discovered automatically from the collection's own indexes — there's nothing to declare. Only a plain unique index qualifies: a partial, sparse, or hashed unique index, or a read whose collation doesn't match the index's collation, falls back to an uncached read instead.
+Exact `_id` lookups and qualifying unique indexes allow cached reads to survive writes to other documents. Other queries are refreshed after any write to the collection. Updates become visible after the manager processes their change-stream events; use the PyMongo collection for reads that must immediately observe a preceding write.
 
 `CacheManager` starts a background change-stream task the first time a read touches a database, so close it (or use it as a context manager, as above) alongside the client — closing only the client leaves that background task running against a closed connection.
 
-The same facades are available for `pymongo.AsyncMongoClient` under `client_query_cache.asynchronous`, with the same methods as coroutines:
+The same API is available for `pymongo.AsyncMongoClient` under `client_query_cache.asynchronous`, with the cached reads as coroutines:
 
 ```python
 import asyncio
@@ -84,13 +102,19 @@ from client_query_cache.asynchronous import CacheManager
 async def main() -> None:
     async with (
         AsyncMongoClient("mongodb://localhost:27017") as client,
-        CacheManager(client) as manager,
+        CacheManager(client) as cache_manager,
     ):
-        collection = manager["my_database"]["my_collection"]
+        collection = client["my_database"]["my_collection"]
+        cached_collection = cache_manager.cached(collection)
+
         await collection.insert_one({"_id": "example", "value": 42})
 
-        await collection.find_one({"_id": "example"})  # cache miss
-        await collection.find_one({"_id": "example"})  # cache hit
+        # Cache miss.
+        await cached_collection.find_one({"_id": "example"})
+        # Cache hit.
+        await cached_collection.find_one({"_id": "example"})
+        # A list, not a cursor.
+        await cached_collection.find({"value": 42})
 
 
 asyncio.run(main())
@@ -105,8 +129,11 @@ A read bypasses the cache instead of using it whenever caching it safely isn't p
 
 ## Documentation
 
+Browse the [documentation site](https://alessio-locatelli.github.io/client-query-cache/) for searchable guides to the current `main` branch.
+
 - [API reference](docs/api-reference.md) — the complete public surface: construction, configuration, limits, ownership, and raw fallback.
 - [Architecture and operations](docs/architecture.md) — system requirements, capacity planning, retry/error handling, observability, security, and recovery behavior.
+- [Examples](examples/README.md) — runnable programs that add the cache to real libraries that store data in MongoDB, such as requests-cache.
 - [Stream cost benchmarks](docs/stream-cost-benchmarks.md) — whether caching fits your workload, and the controlled benchmark reports backing that guidance.
 
 ---

{client_query_cache-0.1.0 → client_query_cache-0.2.0}/README.md

@@ -28,7 +28,7 @@ Or with pip: `pip install client-query-cache`.
 
 ## Usage
 
-`CacheManager` wraps a `pymongo.MongoClient` (or `pymongo.AsyncMongoClient`) that you construct and own. Its database and collection facades cache a narrow set of PyMongo's own read methods — `find_one`, `find`, `aggregate`, `count_documents`, `estimated_document_count`, and `distinct` — and keep cached results coherent as the underlying data changes. Every other operation, including all writes, is called directly on the facade the same way you'd call it on the wrapped PyMongo object:
+`CacheManager` wraps a `pymongo.MongoClient` (or `pymongo.AsyncMongoClient`) that you construct and own. Keep using your PyMongo collection for writes and everything else, and ask the manager for a cached view of that collection for six reads — `find_one`, `find`, `aggregate`, `count_documents`, `estimated_document_count`, and `distinct`. The cache keeps those results coherent as the underlying data changes:
 
 ```python
 from pymongo import MongoClient
@@ -37,28 +37,45 @@ from client_query_cache import CacheManager
 
 with (
     MongoClient("mongodb://localhost:27017") as client,
-    CacheManager(client) as manager,
+    CacheManager(client) as cache_manager,
 ):
-    collection = manager["my_database"]["my_collection"]
+    collection = client["my_database"]["my_collection"]
+    cached_collection = cache_manager.cached(collection)
+
     collection.insert_one({"_id": "example", "value": 42})
 
-    collection.find_one({"_id": "example"})  # cache miss: reads from MongoDB
-    collection.find_one({"_id": "example"})  # cache hit: served from the cache
+    # Cache miss: reads from MongoDB.
+    cached_collection.find_one({"_id": "example"})
+    # Cache hit: served from the cache.
+    cached_collection.find_one({"_id": "example"})
 
-    # Bridge stats like this into OpenTelemetry:
+    # Prints 1. Bridge stats like this into OpenTelemetry:
     # docs/architecture.md#opentelemetry-metrics
-    print(manager.cache_core.snapshot().hits)  # 1
+    print(cache_manager.snapshot().hits)
 
     collection.create_index("email", unique=True)
     collection.insert_one({"_id": "user-1", "email": "a@example.com"})
-    collection.find_one({"email": "a@example.com"})  # also cached, like an `_id` lookup
+    # Also cached, like an `_id` lookup.
+    cached_collection.find_one({"email": "a@example.com"})
+```
+
+`collection` is PyMongo's own object, so your editor and type checker see PyMongo's real methods and signatures. `cached_collection` has only the six cached reads; `find` and `aggregate` on it return a list instead of a cursor. Use `cached_collection.raw` (the same `collection`) whenever you need PyMongo's own cursor behavior.
+
+`find_one` caches deterministic single-document queries, including compound filters, match-all reads and missing results. Use `sort` to choose the first matching document and `collation` to control string matching:
+
+```python
+cached_collection.find_one(
+    {"status": "active"},
+    sort=[("updated_at", -1)],
+    collation={"locale": "en", "strength": 2},
+)
 ```
 
-`find_one` caches a lookup by `_id` and by any other field the database enforces as unique, discovered automatically from the collection's own indexes — there's nothing to declare. Only a plain unique index qualifies: a partial, sparse, or hashed unique index, or a read whose collation doesn't match the index's collation, falls back to an uncached read instead.
+Exact `_id` lookups and qualifying unique indexes allow cached reads to survive writes to other documents. Other queries are refreshed after any write to the collection. Updates become visible after the manager processes their change-stream events; use the PyMongo collection for reads that must immediately observe a preceding write.
 
 `CacheManager` starts a background change-stream task the first time a read touches a database, so close it (or use it as a context manager, as above) alongside the client — closing only the client leaves that background task running against a closed connection.
 
-The same facades are available for `pymongo.AsyncMongoClient` under `client_query_cache.asynchronous`, with the same methods as coroutines:
+The same API is available for `pymongo.AsyncMongoClient` under `client_query_cache.asynchronous`, with the cached reads as coroutines:
 
 ```python
 import asyncio
@@ -71,13 +88,19 @@ from client_query_cache.asynchronous import CacheManager
 async def main() -> None:
     async with (
         AsyncMongoClient("mongodb://localhost:27017") as client,
-        CacheManager(client) as manager,
+        CacheManager(client) as cache_manager,
     ):
-        collection = manager["my_database"]["my_collection"]
+        collection = client["my_database"]["my_collection"]
+        cached_collection = cache_manager.cached(collection)
+
         await collection.insert_one({"_id": "example", "value": 42})
 
-        await collection.find_one({"_id": "example"})  # cache miss
-        await collection.find_one({"_id": "example"})  # cache hit
+        # Cache miss.
+        await cached_collection.find_one({"_id": "example"})
+        # Cache hit.
+        await cached_collection.find_one({"_id": "example"})
+        # A list, not a cursor.
+        await cached_collection.find({"value": 42})
 
 
 asyncio.run(main())
@@ -92,8 +115,11 @@ A read bypasses the cache instead of using it whenever caching it safely isn't p
 
 ## Documentation
 
+Browse the [documentation site](https://alessio-locatelli.github.io/client-query-cache/) for searchable guides to the current `main` branch.
+
 - [API reference](docs/api-reference.md) — the complete public surface: construction, configuration, limits, ownership, and raw fallback.
 - [Architecture and operations](docs/architecture.md) — system requirements, capacity planning, retry/error handling, observability, security, and recovery behavior.
+- [Examples](examples/README.md) — runnable programs that add the cache to real libraries that store data in MongoDB, such as requests-cache.
 - [Stream cost benchmarks](docs/stream-cost-benchmarks.md) — whether caching fits your workload, and the controlled benchmark reports backing that guidance.
 
 ---

{client_query_cache-0.1.0 → client_query_cache-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "client-query-cache"
-version = "0.1.0"
+version = "0.2.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"]
@@ -45,6 +46,7 @@ dev = [
     "dnspython>=2.8.0",
     "python-snappy>=0.7.3",
 ]
+docs = ["zensical>=0.0.67"]
 
 [build-system]
 requires = ["uv_build>=0.12.18,<0.13.0"]
@@ -60,6 +62,7 @@ require-subclass = true
 exclude-modules = """
 (
   ^specifications
+  | ^examples
 )
 """
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "client-query-cache"
-version = "0.1.0"
+version = "0.2.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"]
@@ -44,6 +45,7 @@ dev = [
   "dnspython>=2.8.0",
   "python-snappy>=0.7.3",
 ]
+docs = ["zensical>=0.0.67"]
 
 [build-system]
 requires = ["uv_build>=0.12.18,<0.13.0"]
@@ -59,6 +61,7 @@ require-subclass = true
 exclude-modules = '''
 (
   ^specifications
+  | ^examples
 )
 '''
 

client_query_cache-0.2.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.2.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.2.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.1.0 → client_query_cache-0.2.0}/src/client_query_cache/_core/locking.py

@@ -5,7 +5,7 @@ from contextlib import contextmanager
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Generator
 
 
 class LockOrderViolationError(RuntimeError):
@@ -19,17 +19,17 @@ class LockOrderGuard:
         self._state = threading.local()
 
     @contextmanager
-    def namespace_section(self) -> Iterator[None]:
+    def namespace_section(self) -> Generator[None]:
         with self._section(entering="in_namespace", forbidden="in_lru"):
             yield
 
     @contextmanager
-    def lru_section(self) -> Iterator[None]:
+    def lru_section(self) -> Generator[None]:
         with self._section(entering="in_lru", forbidden="in_namespace"):
             yield
 
     @contextmanager
-    def _section(self, *, entering: str, forbidden: str) -> Iterator[None]:
+    def _section(self, *, entering: str, forbidden: str) -> Generator[None]:
         if getattr(self._state, forbidden, False):
             message = f"cannot enter {entering!r} section while holding {forbidden!r}"
             raise LockOrderViolationError(message)

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

@@ -26,7 +26,11 @@ from client_query_cache._core.locking import LockOrderGuard
 from client_query_cache._core.lru import WeightedLru
 from client_query_cache._core.namespace import IdentityState, NamespaceState
 from client_query_cache._core.order_sensitive_keys import order_sensitive_key
-from client_query_cache._core.snapshots import CacheSnapshot, CacheStatistics
+from client_query_cache._core.snapshots import (
+    BypassReason,
+    CacheSnapshot,
+    CacheStatistics,
+)
 from client_query_cache._core.stream_cost import (
     DEFAULT_LAG_CAPTURE_WINDOW_CONFIG,
     LagCaptureWindowConfig,
@@ -35,7 +39,7 @@ from client_query_cache._core.stream_cost import (
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterator
+    from collections.abc import Callable, Generator
     from typing import Any
 
     from bson.codec_options import CodecOptions
@@ -183,7 +187,7 @@ class _CacheCoreBase:
         namespace: NamespaceId,
         availability_generation: int,
         weight: int,
-    ) -> Iterator[AdmissionOutcome | None]:
+    ) -> Generator[AdmissionOutcome | None]:
         with self._availability_lock:
             try:
                 available, current_generation = self._database_availability[
@@ -192,7 +196,11 @@ class _CacheCoreBase:
             except KeyError:
                 available, current_generation = _DEFAULT_DATABASE_AVAILABILITY
             if not available or availability_generation != current_generation:
-                self._statistics.record_bypass()
+                self._statistics.record_bypass(
+                    BypassReason.STREAM_UNAVAILABLE
+                    if not available
+                    else BypassReason.ADMISSION_INVALIDATED
+                )
                 yield AdmissionOutcome.DECLINED_UNAVAILABLE
                 return
             if self._lru.is_oversize(weight):
@@ -220,7 +228,7 @@ class _CacheCoreBase:
             return state
 
     @contextmanager
-    def _namespace_section(self, state: NamespaceState) -> Iterator[None]:
+    def _namespace_section(self, state: NamespaceState) -> Generator[None]:
         with self._guard.namespace_section(), state.lock:
             yield
 
@@ -293,12 +301,12 @@ class _CacheCoreLifecycle(_CacheCoreBase):
             self._database_namespaces.clear()
         logger.info("cache manager closed")
 
-    def record_bypass(self) -> None:
-        self._statistics.record_bypass()
+    def record_bypass(self, reason: BypassReason = BypassReason.UNSPECIFIED) -> None:
+        self._statistics.record_bypass(reason)
 
     def snapshot(self) -> CacheSnapshot:
         used_bytes, entry_count = self._lru.snapshot_usage()
-        hits, misses, evictions, bypasses, oversized_bypasses = (
+        hits, misses, evictions, bypasses, oversized_bypasses, bypass_reasons = (
             self._statistics.snapshot()
         )
         return CacheSnapshot(
@@ -312,6 +320,7 @@ class _CacheCoreLifecycle(_CacheCoreBase):
             evictions=evictions,
             bypasses=bypasses,
             oversized_bypasses=oversized_bypasses,
+            bypass_reasons=bypass_reasons,
         )
 
 
@@ -466,7 +475,9 @@ class _CacheCoreIdentityAdmission(_CacheCoreBase):
             canonical_shape = canonicalize(read_shape)
             try:
                 encoded = encode_value(value, codec_options)
-            except BSONError, OverflowError:
+            except BSONError:
+                return AdmissionOutcome.DECLINED_UNENCODABLE
+            except OverflowError:
                 return AdmissionOutcome.DECLINED_UNENCODABLE
             weight = len(encoded)
             with self._admission_section(
@@ -589,7 +600,9 @@ class _CacheCoreNamespaceAdmission(_CacheCoreBase):
         canonical_discriminator = canonicalize(discriminator)
         try:
             encoded = encode_value(value, codec_options)
-        except BSONError, OverflowError:
+        except BSONError:
+            return AdmissionOutcome.DECLINED_UNENCODABLE
+        except OverflowError:
             return AdmissionOutcome.DECLINED_UNENCODABLE
         weight = len(encoded)
         with self._admission_section(
@@ -667,7 +680,9 @@ class _CacheCoreUniqueKeyAdmission(_CacheCoreBase):
         canonical_shape = canonicalize(read_shape)
         try:
             encoded = encode_value(value, codec_options)
-        except BSONError, OverflowError:
+        except BSONError:
+            return AdmissionOutcome.DECLINED_UNENCODABLE
+        except OverflowError:
             return AdmissionOutcome.DECLINED_UNENCODABLE
         weight = len(encoded)
         with self._admission_section(
@@ -777,7 +792,7 @@ class _CacheCoreLookup(_CacheCoreBase):
     ) -> LookupResult:
         self._ensure_active()
         if not self._is_database_available(namespace.database):
-            self._statistics.record_bypass()
+            self._statistics.record_bypass(BypassReason.STREAM_UNAVAILABLE)
             return LookupResult(hit=False)
         canonical_identity = canonicalize(order_sensitive_key(identity))
         key = IdentityCacheKey(namespace, canonical_identity, canonicalize(read_shape))
@@ -807,7 +822,7 @@ class _CacheCoreLookup(_CacheCoreBase):
     ) -> LookupResult:
         self._ensure_active()
         if not self._is_database_available(namespace.database):
-            self._statistics.record_bypass()
+            self._statistics.record_bypass(BypassReason.STREAM_UNAVAILABLE)
             return LookupResult(hit=False)
         canonical_discriminator = canonicalize(discriminator)
         key = NamespaceCacheKey(namespace, canonical_discriminator)
@@ -834,7 +849,7 @@ class _CacheCoreLookup(_CacheCoreBase):
     ) -> Canonical | None:
         self._ensure_active()
         if not self._is_database_available(namespace.database):
-            self._statistics.record_bypass()
+            self._statistics.record_bypass(BypassReason.STREAM_UNAVAILABLE)
             return None
         alias_key = canonical_alias_key(definition, value, collation)
         state = self._namespace(namespace)

{client_query_cache-0.1.0 → client_query_cache-0.2.0}/src/client_query_cache/_core/projection.py

@@ -29,7 +29,9 @@ def without_id(
             bson.encode(stripped, codec_options=codec_options),
             codec_options=codec_options,
         )
-    except BSONError, OverflowError:
+    except BSONError:
+        return stripped
+    except OverflowError:
         return stripped