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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sg-query-cache
-Version: 0.1.0
+Version: 0.2.0
 Summary: Query caching for Autodesk Flow Production Tracking
 Project-URL: Documentation, https://github.com/dactylo/sg-query-cache/tree/main/docs
 Project-URL: Homepage, https://github.com/dactylo/sg-query-cache
@@ -27,8 +27,9 @@ Description-Content-Type: text/markdown
 sg-query-cache reduces repeated Autodesk Flow Production Tracking API reads from Python workers.
 When render jobs, pipeline tools, or services ask the same question many times, the cache answers
 the repeats from memory or from a shared Valkey service instead of sending another request to the
-site. It wraps your existing synchronous or native asynchronous client and keeps its method
-signatures, so your code changes only where it creates the client.
+site. It wraps your existing synchronous or native asynchronous client. The methods it wraps keep
+the client's signatures, and you call any other method or attribute on `raw_client`; see
+[which reads are cached](https://github.com/dactylo/sg-query-cache/blob/v0.2.0/docs/consistency.md#which-reads-are-cached).
 
 This documentation uses SG for Flow Production Tracking, formerly named Shotgun and ShotGrid.
 
@@ -36,7 +37,7 @@ Caching trades freshness for fewer requests. Every cached answer has a maximum a
 default for a single process. Writes made through the wrapper invalidate the cached answers they
 can affect, and a shared deployment also invalidates answers when SG reports a change. Until then,
 a change made elsewhere can be missing from a cached answer. When a read must reflect SG right now,
-bypass the cache for that read. The [consistency guide](https://github.com/dactylo/sg-query-cache/blob/v0.1.0/docs/consistency.md) states the guarantee
+bypass the cache for that read. The [consistency guide](https://github.com/dactylo/sg-query-cache/blob/v0.2.0/docs/consistency.md) states the guarantee
 in full.
 
 ## When to use it
@@ -68,7 +69,7 @@ sg-query-cache requires Python 3.11 or newer and an SG client in the same enviro
 
 The official package and sg-python-api both provide the `shotgun_api3` import name, so install only
 one of them. The shared and hierarchical layouts also need two Valkey services; see
-[service layout](https://github.com/dactylo/sg-query-cache/blob/v0.1.0/docs/operations.md#service-layout).
+[service layout](https://github.com/dactylo/sg-query-cache/blob/v0.2.0/docs/operations.md#service-layout).
 
 From a checkout, install the library into the environment that runs your SG client:
 
@@ -77,8 +78,8 @@ python -m pip install .
 ```
 
 For the shared or hierarchical layout, include the `valkey` extra. It adds the Valkey client that
-the cache and the `sg-query-cache` operator commands use. The extra accepts valkey-py 6.1.x, the
-release family this version is tested with:
+the cache and the `sg-query-cache` operator commands use. The extra requires valkey-py
+`>=6.1.1,<6.2`:
 
 ```sh
 python -m pip install '.[valkey]'
@@ -101,9 +102,6 @@ from sg_query_cache import (
     CachedShotgun,
     ClientContext,
     Identity,
-    LocalBackend,
-    NullMetrics,
-    QueryCache,
 )
 
 site_url = os.environ['SHOTGUN_URL']
@@ -112,7 +110,6 @@ raw_sg = Shotgun(site_url, script_name=script_name, api_key=os.environ['SHOTGUN_
 
 settings = CacheSettings()
 identity = Identity(kind='script', issuer='shotgun-script', namespace=script_name)
-cache = QueryCache(settings, identity, l1=LocalBackend(settings, monotonic, NullMetrics()))
 context = ClientContext(
     site_url=site_url,
     site_namespace=settings.site_namespace,
@@ -120,22 +117,21 @@ context = ClientContext(
     convert_datetimes_to_utc=raw_sg.config.convert_datetimes_to_utc,
     records_per_page=raw_sg.config.records_per_page,
 )
-sg = CachedShotgun(raw_sg, cache, context)
 
 
-def timed_read(label: str) -> None:
+def timed_read(sg: CachedShotgun, label: str) -> None:
     started = monotonic()
     assets = sg.find('Asset', [['sg_status_list', 'is', 'ip']], ['code'])
     print(f'{label}: {len(assets)} assets in {monotonic() - started:.3f} s')
 
 
 try:
-    timed_read('first read')
-    timed_read('second read')
-    with sg.bypass():
-        timed_read('bypass')
+    with CachedShotgun.open(raw_sg, settings, identity, context) as sg:
+        timed_read(sg, 'first read')
+        timed_read(sg, 'second read')
+        with sg.bypass():
+            timed_read(sg, 'bypass')
 finally:
-    cache.close()
     raw_sg.close()
 ```
 
@@ -155,13 +151,13 @@ local cache.
 The example sets up four pieces:
 
 - `CacheSettings()` selects the local layout with default limits. Shared layouts load their
-  settings from a TOML file; see [configuration](https://github.com/dactylo/sg-query-cache/blob/v0.1.0/docs/configuration.md).
+  settings from a TOML file; see [configuration](https://github.com/dactylo/sg-query-cache/blob/v0.2.0/docs/configuration.md).
 - `Identity` names the SG permission scope whose results may be reused. Here every process running
   this script shares one identity named after the script; give scripts with different permissions
   different identities. Use stable configuration values, never an API key, session token, or
   process ID, because identity values become part of every cache key.
-- `QueryCache` with a `LocalBackend` is the cache itself. The wrapper closes neither the cache nor
-  the SG client, so the example closes both.
+- `CachedShotgun.open()` builds the cache layers selected by the settings and closes them on
+  context exit. The SG client remains yours to close, as the `finally` block does here.
 - `ClientContext` records the raw client's response options, such as page size, so results fetched
   with different options are never mixed. Keep it matched to the raw client's configuration.
 
@@ -211,25 +207,25 @@ SG. `bypass()` is an ordinary `with` block, even in async code.
 
 Use each async cache on one event loop. `bypass()` and other policy scopes apply to the current
 task, and a task created inside a scope inherits it. Before you close caches in a service with
-long-running tasks, read [async shutdown](https://github.com/dactylo/sg-query-cache/blob/v0.1.0/docs/operations.md#async-deadlines-and-shutdown).
+long-running tasks, read [async shutdown](https://github.com/dactylo/sg-query-cache/blob/v0.2.0/docs/operations.md#async-deadlines-and-shutdown).
 
 ## Documentation
 
 | If you want to...                                   | Read                                                          |
 | --------------------------------------------------- | ------------------------------------------------------------- |
-| Understand how fresh results are and when to bypass | [Consistency](https://github.com/dactylo/sg-query-cache/blob/v0.1.0/docs/consistency.md)                            |
-| Choose a layout and write the settings file         | [Configuration](https://github.com/dactylo/sg-query-cache/blob/v0.1.0/docs/configuration.md)                        |
-| Cache reads for human users                         | [Identities](https://github.com/dactylo/sg-query-cache/blob/v0.1.0/docs/configuration.md#identities-and-trust)      |
-| Change how long results are kept                    | [Maximum age rules](https://github.com/dactylo/sg-query-cache/blob/v0.1.0/docs/configuration.md#maximum-age-rules)  |
-| Run Valkey and the invalidation plugin              | [Operations](https://github.com/dactylo/sg-query-cache/blob/v0.1.0/docs/operations.md)                              |
-| Flush cached results after an incident              | [Recovery](https://github.com/dactylo/sg-query-cache/blob/v0.1.0/docs/operations.md#flush-or-rotate-cached-results) |
-| Collect metrics and set alerts                      | [Metrics](https://github.com/dactylo/sg-query-cache/blob/v0.1.0/docs/operations.md#metrics-and-alerts)              |
-| Measure savings for your workload                   | [Benchmarks](https://github.com/dactylo/sg-query-cache/blob/v0.1.0/docs/benchmarks.md)                              |
-| See changes by version                              | [Changelog](https://github.com/dactylo/sg-query-cache/blob/v0.1.0/CHANGELOG.md)                                     |
+| Understand how fresh results are and when to bypass | [Consistency](https://github.com/dactylo/sg-query-cache/blob/v0.2.0/docs/consistency.md)                            |
+| Choose a layout and write the settings file         | [Configuration](https://github.com/dactylo/sg-query-cache/blob/v0.2.0/docs/configuration.md)                        |
+| Cache reads for human users                         | [Identities](https://github.com/dactylo/sg-query-cache/blob/v0.2.0/docs/configuration.md#identities-and-trust)      |
+| Change how long results are kept                    | [Maximum age rules](https://github.com/dactylo/sg-query-cache/blob/v0.2.0/docs/configuration.md#maximum-age-rules)  |
+| Run Valkey and the invalidation plugin              | [Operations](https://github.com/dactylo/sg-query-cache/blob/v0.2.0/docs/operations.md)                              |
+| Flush cached results after an incident              | [Recovery](https://github.com/dactylo/sg-query-cache/blob/v0.2.0/docs/operations.md#flush-or-rotate-cached-results) |
+| Collect metrics and set alerts                      | [Metrics](https://github.com/dactylo/sg-query-cache/blob/v0.2.0/docs/operations.md#metrics-and-alerts)              |
+| Measure savings for your workload                   | [Benchmarks](https://github.com/dactylo/sg-query-cache/blob/v0.2.0/docs/benchmarks.md)                              |
+| See changes by version                              | [Changelog](https://github.com/dactylo/sg-query-cache/blob/v0.2.0/CHANGELOG.md)                                     |
 
 ## Development
 
-See the [development guide](https://github.com/dactylo/sg-query-cache/blob/v0.1.0/docs/development.md) for the required tools, CI, and dependency locks.
+See the [development guide](https://github.com/dactylo/sg-query-cache/blob/v0.2.0/docs/development.md) for the required tools, CI, and dependency locks.
 With those tools installed, run:
 
 ```sh
@@ -242,6 +238,6 @@ disposable services.
 
 ## License
 
-sg-query-cache is available under the [MIT License](https://github.com/dactylo/sg-query-cache/blob/v0.1.0/LICENSE). It is an independent project and is
+sg-query-cache is available under the [MIT License](https://github.com/dactylo/sg-query-cache/blob/v0.2.0/LICENSE). It is an independent project and is
 not affiliated with or endorsed by Autodesk. Flow Production Tracking is a product of Autodesk,
 Inc.

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

@@ -3,8 +3,9 @@
 sg-query-cache reduces repeated Autodesk Flow Production Tracking API reads from Python workers.
 When render jobs, pipeline tools, or services ask the same question many times, the cache answers
 the repeats from memory or from a shared Valkey service instead of sending another request to the
-site. It wraps your existing synchronous or native asynchronous client and keeps its method
-signatures, so your code changes only where it creates the client.
+site. It wraps your existing synchronous or native asynchronous client. The methods it wraps keep
+the client's signatures, and you call any other method or attribute on `raw_client`; see
+[which reads are cached](docs/consistency.md#which-reads-are-cached).
 
 This documentation uses SG for Flow Production Tracking, formerly named Shotgun and ShotGrid.
 
@@ -53,8 +54,8 @@ python -m pip install .
 ```
 
 For the shared or hierarchical layout, include the `valkey` extra. It adds the Valkey client that
-the cache and the `sg-query-cache` operator commands use. The extra accepts valkey-py 6.1.x, the
-release family this version is tested with:
+the cache and the `sg-query-cache` operator commands use. The extra requires valkey-py
+`>=6.1.1,<6.2`:
 
 ```sh
 python -m pip install '.[valkey]'
@@ -77,9 +78,6 @@ from sg_query_cache import (
     CachedShotgun,
     ClientContext,
     Identity,
-    LocalBackend,
-    NullMetrics,
-    QueryCache,
 )
 
 site_url = os.environ['SHOTGUN_URL']
@@ -88,7 +86,6 @@ raw_sg = Shotgun(site_url, script_name=script_name, api_key=os.environ['SHOTGUN_
 
 settings = CacheSettings()
 identity = Identity(kind='script', issuer='shotgun-script', namespace=script_name)
-cache = QueryCache(settings, identity, l1=LocalBackend(settings, monotonic, NullMetrics()))
 context = ClientContext(
     site_url=site_url,
     site_namespace=settings.site_namespace,
@@ -96,22 +93,21 @@ context = ClientContext(
     convert_datetimes_to_utc=raw_sg.config.convert_datetimes_to_utc,
     records_per_page=raw_sg.config.records_per_page,
 )
-sg = CachedShotgun(raw_sg, cache, context)
 
 
-def timed_read(label: str) -> None:
+def timed_read(sg: CachedShotgun, label: str) -> None:
     started = monotonic()
     assets = sg.find('Asset', [['sg_status_list', 'is', 'ip']], ['code'])
     print(f'{label}: {len(assets)} assets in {monotonic() - started:.3f} s')
 
 
 try:
-    timed_read('first read')
-    timed_read('second read')
-    with sg.bypass():
-        timed_read('bypass')
+    with CachedShotgun.open(raw_sg, settings, identity, context) as sg:
+        timed_read(sg, 'first read')
+        timed_read(sg, 'second read')
+        with sg.bypass():
+            timed_read(sg, 'bypass')
 finally:
-    cache.close()
     raw_sg.close()
 ```
 
@@ -136,8 +132,8 @@ The example sets up four pieces:
   this script shares one identity named after the script; give scripts with different permissions
   different identities. Use stable configuration values, never an API key, session token, or
   process ID, because identity values become part of every cache key.
-- `QueryCache` with a `LocalBackend` is the cache itself. The wrapper closes neither the cache nor
-  the SG client, so the example closes both.
+- `CachedShotgun.open()` builds the cache layers selected by the settings and closes them on
+  context exit. The SG client remains yours to close, as the `finally` block does here.
 - `ClientContext` records the raw client's response options, such as page size, so results fetched
   with different options are never mixed. Keep it matched to the raw client's configuration.
 

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

@@ -10,7 +10,7 @@ requires = [ "editables~=0.3", "hatch-fancy-pypi-readme>=25.1", "hatchling>=1.27
 # ==========================================================
 [project]
 name = "sg-query-cache"
-version = "0.1.0"
+version = "0.2.0"
 description = "Query caching for Autodesk Flow Production Tracking"
 keywords = [ "cache", "flow-production-tracking", "queries", "shotgrid", "shotgun", "valkey" ]
 license = "MIT"
@@ -52,6 +52,7 @@ dev = [
   "pyproject-fmt",
   "pyright",
   "ruff",
+  "zizmor",
   { include-group = "test" },
 ]
 test = [
@@ -100,25 +101,13 @@ lint.ignore = [
   "Q003",   # Conflicts with the Ruff formatter
   "TRY003", # Avoid specifying long messages outside exception class
 ]
-# Same-file collaborators use private implementation members.
 lint.per-file-ignores."benchmarks/async_query_cache.py" = [
-  "SLF001",
-  "T201",   # print() found
+  "T201", # print() found
 ]
 lint.per-file-ignores."benchmarks/query_cache.py" = [
-  "SLF001",
-  "T201",   # print() found
+  "T201", # print() found
 ]
-lint.per-file-ignores."src/sg_query_cache/_async_cache.py" = [ "SLF001" ]
-lint.per-file-ignores."src/sg_query_cache/_async_client.py" = [ "SLF001" ]
-lint.per-file-ignores."src/sg_query_cache/_cache.py" = [ "SLF001" ]
 lint.per-file-ignores."src/sg_query_cache/_cli.py" = [ "T201" ]  # print() found
-lint.per-file-ignores."src/sg_query_cache/_dependencies.py" = [ "SLF001" ]
-lint.per-file-ignores."src/sg_query_cache/_event_mapping.py" = [ "SLF001" ]
-lint.per-file-ignores."src/sg_query_cache/_local_store.py" = [ "SLF001" ]
-lint.per-file-ignores."src/sg_query_cache/daemon_plugin.py" = [ "SLF001" ]
-lint.per-file-ignores."src/sg_query_cache/valkey.py" = [ "SLF001" ]
-lint.per-file-ignores."src/sg_query_cache/valkey_async.py" = [ "SLF001" ]
 lint.per-file-ignores."tests/**/*.py" = [
   "D",       # No docstrings required in tests
   "PLR2004", # Allow magic values in tests
@@ -140,6 +129,8 @@ max_supported_python = "3.15"
 # ==========================================================
 [tool.pyright]
 pythonVersion = "3.11"  # Keep in sync with tool.ruff.target-version
+venv = ".venv"  # Created by make setup
+venvPath = "."
 typeCheckingMode = "strict"
 extraPaths = [ ".", "src" ]
 executionEnvironments = [

sg_query_cache-0.2.0/src/sg_query_cache/_async_backend.py

@@ -0,0 +1,181 @@
+"""Define the backend-neutral asynchronous cache storage contract."""
+
+from typing import Protocol
+
+from sg_query_cache._model import (
+    CacheHit,
+    DependencyTag,
+    FillLease,
+    GenerationChange,
+    GenerationVector,
+)
+
+
+class AsyncCacheBackend(Protocol):
+    """Store opaque encoded results through loop-native coroutine methods.
+
+    Each method preserves the corresponding `CacheBackend` arguments, return
+    values, and backend errors while adding coroutine cancellation cooperation.
+    This protocol types the shipped backends; third-party implementations are
+    not yet a supported extension point.
+    """
+
+    async def change(self, changes: tuple[GenerationChange, ...]) -> None:
+        """Replace all applicable generations in caller order.
+
+        Args:
+            changes: Ordered generation replacements to acknowledge together.
+
+        Raises:
+            BackendCapacity: Required generation metadata cannot be retained.
+            BackendProtocolError: The ordered change tuple is malformed.
+            BackendUnavailable: The change cannot complete reliably.
+            StaleIncarnation: The backend incarnation is no longer current.
+            RuntimeError: The backend rejects the operation's lifecycle or
+                event-loop context.
+            CancelledError: The caller cancels the asynchronous operation.
+        """
+        ...
+
+    async def close(self) -> None:
+        """Release backend resources; repeated same-loop calls have no effect.
+
+        Backends with active asynchronous work join it before terminal cleanup.
+        Caller cancellation may be deferred until owned cleanup settles.
+
+        Raises:
+            RuntimeError: The close uses another event loop or would wait on
+                its own admitted operation.
+            BackendCapacity: Owned cleanup reports a capacity failure.
+            BackendProtocolError: Owned cleanup reports malformed client state.
+            BackendUnavailable: Owned cleanup cannot complete reliably.
+            CancelledError: Caller cancellation propagates after required
+                cleanup settlement.
+        """
+        ...
+
+    async def commit(self, lease: FillLease, payload: bytes, remaining_seconds: float) -> bool:
+        """Store encoded bytes only while the exact lease remains current.
+
+        Args:
+            lease: Exact key and token returned by `reserve`.
+            payload: Closed-codec bytes to retain.
+            remaining_seconds: Positive authoritative lifetime remaining.
+
+        Returns:
+            Whether the lease remained current and the result was admitted.
+
+        Raises:
+            BackendCapacity: Result-role preparation or oversized-payload lease
+                cleanup encounters a capacity failure.
+            BackendProtocolError: An argument is outside the backend contract.
+            BackendUnavailable: The commit cannot complete reliably.
+            StaleIncarnation: The backend incarnation is no longer current.
+            RuntimeError: The backend rejects the operation's lifecycle or
+                event-loop context.
+            CancelledError: The caller cancels the asynchronous operation.
+        """
+        ...
+
+    async def flush_site(self, site_namespace: str, reason: str) -> None:
+        """Replace one site's permanent site generation.
+
+        Args:
+            site_namespace: Stable configured site namespace.
+            reason: Short operator-facing reason code.
+
+        Raises:
+            BackendCapacity: Required global metadata cannot be retained.
+            BackendProtocolError: The site namespace or reason is malformed.
+            BackendUnavailable: The flush cannot complete reliably.
+            StaleIncarnation: The backend incarnation is no longer current.
+            RuntimeError: The backend rejects the operation's lifecycle or
+                event-loop context.
+            CancelledError: The caller cancels the asynchronous operation.
+        """
+        ...
+
+    async def lookup(self, key: str) -> CacheHit | None:
+        """Read valid encoded bytes with backend-authoritative remaining age.
+
+        Args:
+            key: Opaque generation-qualified result key.
+
+        Returns:
+            An isolated hit, optionally carrying the backend's fresh decoded
+            value, or `None` for absence, expiry, or corruption.
+
+        Raises:
+            BackendCapacity: The result role rejects required work for
+                capacity.
+            BackendProtocolError: The key or backend reply is malformed.
+            BackendUnavailable: The lookup cannot complete reliably.
+            StaleIncarnation: The backend incarnation is no longer current.
+            RuntimeError: The backend rejects the operation's lifecycle or
+                event-loop context.
+            CancelledError: The caller cancels the asynchronous operation.
+        """
+        ...
+
+    async def release(self, lease: FillLease) -> bool:
+        """Remove a fill lease only when its exact token remains current.
+
+        Args:
+            lease: Exact key and token returned by `reserve`.
+
+        Returns:
+            Whether the current lease was removed.
+
+        Raises:
+            BackendCapacity: The result role rejects required work for
+                capacity.
+            BackendProtocolError: The lease or backend reply is malformed.
+            BackendUnavailable: The release cannot complete reliably.
+            StaleIncarnation: The backend incarnation is no longer current.
+            RuntimeError: The backend rejects the operation's lifecycle or
+                event-loop context.
+            CancelledError: The caller cancels the asynchronous operation.
+        """
+        ...
+
+    async def reserve(self, key: str, lease_seconds: float) -> FillLease | None:
+        """Acquire temporary fill ownership for one opaque key.
+
+        Args:
+            key: Opaque generation-qualified result key.
+            lease_seconds: Positive ownership duration in seconds.
+
+        Returns:
+            A fresh lease, or `None` while another lease remains current.
+
+        Raises:
+            BackendCapacity: Metadata capacity cannot retain a new lease.
+            BackendProtocolError: An argument is outside the backend contract.
+            BackendUnavailable: The reservation cannot complete reliably.
+            StaleIncarnation: The backend incarnation is no longer current.
+            RuntimeError: The backend rejects the operation's lifecycle or
+                event-loop context.
+            CancelledError: The caller cancels the asynchronous operation.
+        """
+        ...
+
+    async def resolve(self, tags: tuple[DependencyTag, ...]) -> GenerationVector:
+        """Resolve one complete bounded dependency vector in request order.
+
+        Args:
+            tags: Ordered unique dependency tags.
+
+        Returns:
+            Every requested tag and current token under one incarnation.
+
+        Raises:
+            BackendCapacity: Metadata capacity cannot retain the vector.
+            BackendProtocolError: The vector is malformed or exceeds its
+                bounds.
+            BackendUnavailable: Resolution cannot complete reliably.
+            StaleIncarnation: The backend incarnation is no longer current.
+            RuntimeError: The backend rejects the operation's lifecycle or
+                event-loop context.
+            CancelledError: The caller cancels the asynchronous operation.
+        """
+        ...