client-query-cache 0.5.0__tar.gz → 0.6.0__tar.gz

{client_query_cache-0.5.0 → client_query_cache-0.6.0}/PKG-INFO

@@ -1,11 +1,17 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: client-query-cache
-Version: 0.5.0
+Version: 0.6.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>>
+License-Expression: Apache-2.0
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
 Requires-Dist: pymongo>=4.18.1
 Requires-Dist: opentelemetry-api>=1.45.0 ; extra == 'otel'
 Requires-Python: >=3.14
@@ -16,7 +22,10 @@ Description-Content-Type: text/markdown
 
 # Coherent client-side caching for PyMongo
 
-[![Supported Python versions on PyPI](https://img.shields.io/pypi/pyversions/client-query-cache.svg)](https://pypi.org/project/client-query-cache/)
+[![PyPI](https://img.shields.io/pypi/v/client-query-cache?color=lightgrey)](https://pypi.org/project/client-query-cache/)
+[![Python](https://img.shields.io/pypi/pyversions/client-query-cache)](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/alessio-locatelli/client-query-cache/actions/workflows/test.yml)
+[![Typing](https://img.shields.io/pypi/types/client-query-cache)](https://pypi.org/project/client-query-cache/)
 
 `client-query-cache` uses MongoDB change streams to keep cached reads coherent. It supports synchronous and asyncio applications without requiring a separate cache server.
 

{client_query_cache-0.5.0 → client_query_cache-0.6.0}/README.md

@@ -1,6 +1,9 @@
 # Coherent client-side caching for PyMongo
 
-[![Supported Python versions on PyPI](https://img.shields.io/pypi/pyversions/client-query-cache.svg)](https://pypi.org/project/client-query-cache/)
+[![PyPI](https://img.shields.io/pypi/v/client-query-cache?color=lightgrey)](https://pypi.org/project/client-query-cache/)
+[![Python](https://img.shields.io/pypi/pyversions/client-query-cache)](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/alessio-locatelli/client-query-cache/actions/workflows/test.yml)
+[![Typing](https://img.shields.io/pypi/types/client-query-cache)](https://pypi.org/project/client-query-cache/)
 
 `client-query-cache` uses MongoDB change streams to keep cached reads coherent. It supports synchronous and asyncio applications without requiring a separate cache server.
 

{client_query_cache-0.5.0 → client_query_cache-0.6.0}/pyproject.toml

@@ -1,12 +1,18 @@
 [project]
 name = "client-query-cache"
-version = "0.5.0"
+version = "0.6.0"
 description = "Client-side caching for PyMongo, kept coherent using MongoDB change streams."
 readme = "README.md"
 requires-python = ">=3.14"
+license = "Apache-2.0"
 classifiers = [
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
     "Programming Language :: Python :: 3.14",
     "Programming Language :: Python :: 3.15",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
 ]
 dependencies = ["pymongo>=4.18.1"]
 
@@ -46,6 +52,7 @@ dev = [
     "opentelemetry-api>=1.45.0",
     "opentelemetry-sdk>=1.45.0",
     "types-psutil>=7.2.2.20260906",
+    "psutil>=7.2.2",
     "dnspython>=2.8.0",
     "python-snappy>=0.7.3",
     "pytest-xdist[psutil]>=3.8.0",

{client_query_cache-0.5.0 → client_query_cache-0.6.0}/pyproject.toml.orig

@@ -1,15 +1,21 @@
 [project]
 name = "client-query-cache"
-version = "0.5.0"
+version = "0.6.0"
 description = "Client-side caching for PyMongo, kept coherent using MongoDB change streams."
 authors = [
   { name = "Alessio Locatelli", email = "<software.development@secure.mailbox.org>" },
 ]
 readme = "README.md"
 requires-python = ">=3.14"
+license = "Apache-2.0"
 classifiers = [
+  "Framework :: AsyncIO",
+  "Intended Audience :: Developers",
   "Programming Language :: Python :: 3.14",
   "Programming Language :: Python :: 3.15",
+  "Topic :: Database",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
 ]
 dependencies = ["pymongo>=4.18.1"]
 
@@ -45,6 +51,7 @@ dev = [
   "opentelemetry-api>=1.45.0",
   "opentelemetry-sdk>=1.45.0",
   "types-psutil>=7.2.2.20260906",
+  "psutil>=7.2.2",
   "dnspython>=2.8.0",
   "python-snappy>=0.7.3",
   "pytest-xdist[psutil]>=3.8.0",

{client_query_cache-0.5.0 → client_query_cache-0.6.0}/src/client_query_cache/_core/entries.py

@@ -32,3 +32,4 @@ class CacheEntry:
 class LookupResult:
     hit: bool
     value: Any = None
+    deferred_miss: bool = False

{client_query_cache-0.5.0 → client_query_cache-0.6.0}/src/client_query_cache/_core/manager.py

@@ -54,6 +54,8 @@ DEFAULT_MAX_ENTRY_BYTES = 1 * 1024 * 1024
 
 _NOT_INDEXED = object()
 _DEFAULT_DATABASE_AVAILABILITY = (True, 0)
+_MISS = LookupResult(hit=False)
+_DEFERRED_MISS = LookupResult(hit=False, deferred_miss=True)
 
 logger = logging.getLogger(__name__)
 
@@ -313,6 +315,9 @@ class _CacheCoreLifecycle(_CacheCoreBase):
             self._database_namespaces.clear()
         logger.info("cache manager closed")
 
+    def record_miss(self) -> None:
+        self._statistics.record_miss()
+
     def record_bypass(self, reason: BypassReason = BypassReason.UNSPECIFIED) -> None:
         self._statistics.record_bypass(reason)
 
@@ -908,6 +913,7 @@ class _CacheCoreLookup(_CacheCoreBase):
         discriminator: object,
         *,
         codec_options: CodecOptions[Any] | None = None,
+        defer_miss: bool = False,
     ) -> LookupResult:
         self._ensure_active()
         if not self._is_database_available(namespace.database):
@@ -917,18 +923,22 @@ class _CacheCoreLookup(_CacheCoreBase):
         key = NamespaceCacheKey(namespace, canonical_discriminator)
         entry = self._lru.peek(key)
         if entry is None:
-            self._statistics.record_miss()
-            return LookupResult(hit=False)
+            return self._namespace_miss(defer_miss=defer_miss)
         state = self._namespace(namespace)
         with self._namespace_section(state):
             valid = (state.generation,) == entry.generation_key
         if not valid:
-            self._statistics.record_miss()
-            return LookupResult(hit=False)
+            return self._namespace_miss(defer_miss=defer_miss)
         self._lru.touch(key)
         self._statistics.record_hit()
         return LookupResult(hit=True, value=decode_value(entry.value, codec_options))
 
+    def _namespace_miss(self, *, defer_miss: bool) -> LookupResult:
+        if defer_miss:
+            return _DEFERRED_MISS
+        self._statistics.record_miss()
+        return _MISS
+
     def resolve_alias(
         self,
         namespace: NamespaceId,

{client_query_cache-0.5.0 → client_query_cache-0.6.0}/src/client_query_cache/asynchronous/collection.py

@@ -209,15 +209,21 @@ class CachedCollection[DocumentType: Mapping[str, Any]]:
                     cache.current_index_generation(namespace),
                 )
             )
+            discovers_unique_keys = identity is NO_IDENTITY and known_keys is None
             lookup_result = cache.lookup_namespace(
-                namespace, discriminator, codec_options=codec_options
+                namespace,
+                discriminator,
+                codec_options=codec_options,
+                defer_miss=discovers_unique_keys,
             )
             if lookup_result.hit:
                 return cast("DocumentType | None", lookup_result.value)
-            if identity is NO_IDENTITY and known_keys is None:
+            if discovers_unique_keys:
                 unique_key_match = await self._match_unique_key(
                     filter_query, effective_collation
                 )
+                if unique_key_match is None and lookup_result.deferred_miss:
+                    cache.record_miss()
         if unique_key_match is not None:
             key_definition, key_values = unique_key_match
             return await self._find_one_by_unique_key(

{client_query_cache-0.5.0 → client_query_cache-0.6.0}/src/client_query_cache/synchronous/collection.py

@@ -209,15 +209,21 @@ class CachedCollection[DocumentType: Mapping[str, Any]]:
                     cache.current_index_generation(namespace),
                 )
             )
+            discovers_unique_keys = identity is NO_IDENTITY and known_keys is None
             lookup_result = cache.lookup_namespace(
-                namespace, discriminator, codec_options=codec_options
+                namespace,
+                discriminator,
+                codec_options=codec_options,
+                defer_miss=discovers_unique_keys,
             )
             if lookup_result.hit:
                 return cast("DocumentType | None", lookup_result.value)
-            if identity is NO_IDENTITY and known_keys is None:
+            if discovers_unique_keys:
                 unique_key_match = self._match_unique_key(
                     filter_query, effective_collation
                 )
+                if unique_key_match is None and lookup_result.deferred_miss:
+                    cache.record_miss()
         if unique_key_match is not None:
             key_definition, key_values = unique_key_match
             return self._find_one_by_unique_key(