PyperCache 0.1.1__tar.gz → 0.1.3__tar.gz

pypercache-0.1.3/PKG-INFO

@@ -0,0 +1,295 @@
+Metadata-Version: 2.4
+Name: PyperCache
+Version: 0.1.3
+Summary: Durable file-backed caching for JSON-like data with pluggable storage backends
+Author-email: Brandon Bahret <your.email@example.com>
+Maintainer-email: Brandon Bahret <your.email@example.com>
+License: MIT License
+        
+        Copyright (c) 2026 Brandon Bahret
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/BrandonBahret/PyperCache
+Project-URL: Documentation, https://github.com/BrandonBahret/PyperCache/tree/master/docs
+Project-URL: Source, https://github.com/BrandonBahret/PyperCache
+Project-URL: Repository, https://github.com/BrandonBahret/PyperCache
+Project-URL: Issues, https://github.com/BrandonBahret/PyperCache/issues
+Project-URL: Changelog, https://github.com/BrandonBahret/PyperCache/blob/master/CHANGELOG.md
+Keywords: cache,persistence,json,pickle,sqlite,storage
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lark>=1.1.0
+Requires-Dist: jsonpickle>=3.0.0
+Requires-Dist: msgpack>=1.0.0
+Dynamic: license-file
+
+# PyperCache
+
+A Python library providing durable file-backed caching for JSON-like data with pluggable storage backends (pickle, JSON, chunked manifest, SQLite), optional TTL and staleness semantics, read-only query navigation, and append-only request logging.
+
+## Installation
+
+```bash
+pip install pypercache
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/BrandonBahret/PyperCache.git
+cd PyperCache
+pip install .
+```
+
+## Quick Start
+
+See the full documentation, examples, and API reference on GitHub:
+
+https://github.com/BrandonBahret/PyperCache/tree/master/docs
+
+## Features
+
+- **Pluggable Backends**: Choose storage by file extension (.pkl, .json, .manifest, .db)
+- **TTL & Staleness**: Optional expiry and acceptable staleness windows
+- **Typed Objects**: Decorate classes for automatic serialization/deserialization
+- **Query Navigation**: Safe, read-only JSON path queries with filters
+- **Request Logging**: Thread-safe JSONL audit trails
+
+## Testing
+
+```bash
+pytest
+```
+
+## Example
+ 
+The snippet below demonstrates every major feature in one pass: choosing a backend, TTL, typed objects, query navigation, and request logging.
+ 
+```python
+import math
+from PyperCache import Cache, RequestLogger
+from PyperCache.models.apimodel import apimodel
+ 
+# ── 1. Backend is chosen by file extension ──────────────────────────────────
+cache = Cache(filepath="api-cache.db")   # .pkl / .json / .manifest / .db
+log   = RequestLogger("api_requests.log")
+ 
+# ── 2. Define a typed model ──────────────────────────────────────────────────
+@apimodel
+class SearchResult:
+    total: int
+    hits:  list
+ 
+# ── 3. Fetch-or-cache pattern ────────────────────────────────────────────────
+KEY = "search:v1:python"
+ 
+if not cache.is_data_fresh(KEY):
+    payload = {
+        "total": 3,
+        "hits": [
+            {"name": "Alice", "role": "staff",  "score": 92},
+            {"name": "Bob",   "role": "guest",  "score": 74},
+            {"name": "Carol", "role": "staff",  "score": 88},
+        ],
+    }
+    cache.store(KEY, payload, expiry=3600, cast=SearchResult)
+    log.log(uri="/api/search?q=python", status=200)
+ 
+# ── 4. Retrieve a typed object ───────────────────────────────────────────────
+result = cache.get_object(KEY)          # SearchResult instance
+print(result.total)                     # 3
+ 
+# ── 5. Query without mutating the payload ───────────────────────────────────
+q = cache.get(KEY).query
+ 
+print(q.get("total"))                           # 3
+print(q.get("hits?role=staff.name"))            # [Alice, Carol]
+print(q.get("hits?name*"))                      # ['Alice', 'Bob', 'Carol']
+print(q.get("hits?role=staff", select_first=True)["name"])  # 'Alice'
+ 
+# ── 6. Inspect the request log ───────────────────────────────────────────────
+for entry in log.get_logs_from_last_seconds(60):
+    print(entry.data["uri"], entry.data["status"])
+```
+ 
+## Features
+ 
+- **Four backends** — `.pkl`, `.json`, `.manifest`, `.db` (SQLite with write-behind batching)
+- **TTL & staleness** — per-record expiry; `is_data_fresh` tells you whether to re-fetch
+- **Typed round-trips** — `@Cache.cached` / `@apimodel` + `cast=` on store; `get_object()` on retrieval
+- **Query navigation** — dotted paths, `?key=value` filters, `?key*` plucks, `?key` existence, `select_first`, defaults; all in memory over the loaded record
+- **Request logging** — thread-safe JSONL audit trail with time-window reads
+ 
+---
+
+## Query navigation
+ 
+`record.query` returns a `JsonInjester` — a lightweight, read-only selector language that runs in memory over the loaded payload. It never touches the storage backend.
+ 
+```python
+q = cache.get("search:v1:python").query
+```
+ 
+You can also instantiate it directly over any dict:
+ 
+```python
+from PyperCache.query import JsonInjester
+q = JsonInjester({"meta": {"total": 5}, "hits": [...]})
+```
+ 
+### Path navigation
+ 
+Dot-separated keys walk the dict. Returns `UNSET` if any key along the path is absent.
+ 
+```python
+q.get("meta.total")          # 5
+q.get("meta.page")           # 1
+q.get("meta.missing")        # UNSET
+q.has("meta.total")          # True  (shorthand for `get(...) is not UNSET`)
+```
+ 
+Keys containing hyphens or other non-identifier characters must be wrapped in double quotes inside the selector string:
+ 
+```python
+q.get('"content-type".value')
+```
+ 
+### `?key=value` — match filter
+ 
+Returns every element in a list where the key equals the value. A tail path after the operator plucks a field from each matched element.
+ 
+```python
+q.get("hits?role=staff")
+# [{"name": "Alice", ...}, {"name": "Carol", ...}]
+ 
+q.get("hits?role=staff.name")
+# ["Alice", "Carol"]
+ 
+q.get("hits?team.name=Engineering")
+# all dicts where hits[i].team.name == "Engineering"
+```
+ 
+Prefix the value with `#` to match numbers instead of strings:
+ 
+```python
+q.get("hits?score=#92")    # integer match
+q.get("hits?ratio=#0.75")  # float match
+```
+ 
+No matches returns an empty list, not `UNSET`.
+ 
+### `?key*` — pluck
+ 
+Extracts a field from every element in the list. Non-missing results are collected; missing ones are silently skipped. Plucks can be chained.
+ 
+```python
+q.get("hits?name*")
+# ["Alice", "Bob", "Carol"]
+ 
+q.get("hits?team.name*")
+# ["Engineering", "Marketing", "Engineering"]
+ 
+q.get("hits?role*?label*")
+# chained: pluck role objects, then pluck label from each
+```
+ 
+On a dict cursor (rather than a list), pluck navigates to the key and returns its value or `UNSET`.
+ 
+### `?key` — exists filter
+ 
+Does not extract values. On a list cursor, returns only elements that contain the key. On a dict cursor, returns the cursor unchanged if the key is present, or `UNSET` if absent.
+ 
+```python
+# list cursor — filter to elements that have a "team" key
+q.get("hits?team")
+ 
+# dict cursor — gate on key presence
+q.get("meta?total")          # returns the meta dict (key exists)
+q.get("meta?ghost")          # UNSET
+q.get("meta?ghost", default_value=0)  # 0
+```
+ 
+### `select_first` and `default_value`
+ 
+`select_first=True` unwraps the first element of a list result. Returns `UNSET` if the list is empty.
+ 
+```python
+from PyperCache.query.json_injester import UNSET
+ 
+first = q.get("hits?role=staff", select_first=True)
+print(first["name"])   # "Alice"
+ 
+empty = q.get("hits?role=contractor", select_first=True)
+print(empty is UNSET)  # True
+```
+ 
+`default_value` is returned when the path is missing or resolves to `None`. Falsy non-`None` values (`False`, `0`, `""`) pass through unchanged.
+ 
+```python
+q.get("meta.missing", default_value=0)   # 0
+q.get("flags.debug", default_value=False) # False (returned as-is, not default)
+```
+ 
+### `cast`
+ 
+When the result is a dict, `cast` passes it to the given type before returning.
+ 
+```python
+q.get("hits?role=staff", select_first=True, cast=StaffMember)
+# StaffMember instance
+```
+ 
+### Known limitations
+ 
+`JsonInjester` is intentionally scoped and simple. A few things it does not do:
+ 
+- **Integer list indexing** — `"hits.0.name"` is not supported. Use a filter or pluck to reach list elements.
+- **Cross-key queries** — `record.query` operates on a single loaded payload. It does not scan multiple records or touch the backend.
+- **Non-ASCII keys** — unquoted non-ASCII key names raise a parse error. Wrap them in double quotes: `'"héros".name'`.
+ 
+For the complete selector reference see [QUERY.md](QUERY.md).
+ 
+---
+ 
+## Documentation
+ 
+| Topic | File |
+|---|---|
+| `Cache`, `CacheRecord`, TTL, typed objects | [CACHE.md](CACHE.md) |
+| `JsonInjester` / `record.query` selector syntax | [QUERY.md](QUERY.md) |
+| Storage backends, `RequestLogger`, SQLite internals | [STORAGE.md](STORAGE.md) |
+ 
+Full docs and examples: https://github.com/BrandonBahret/PyperCache/tree/master/docs
+ 
+## License
+ 
+MIT

{pypercache-0.1.1 → pypercache-0.1.3}/PyperCache/__init__.py

@@ -15,7 +15,7 @@ from PyperCache.core.cache import Cache
 from PyperCache.core.cache_record import CacheRecord
 from PyperCache.core.request_logger import LogRecord, RequestLogger
 
-__version__ = "0.1.1"
+__version__ = "0.1.3"
 
 __all__ = [
     "Cache",

{pypercache-0.1.1 → pypercache-0.1.3}/PyperCache/models/apimodel.py

@@ -8,14 +8,16 @@ This module provides a light-weight decorator that:
 """
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, TypeVar
 
 from ..utils.patterns import ClassRepository
 from ..query.json_injester import JsonInjester
 from ..utils.typing_cast import instantiate_type
 
 
-def apimodel(cls: type) -> type:
+T = TypeVar("T")
+
+def apimodel(cls: T) -> T:
     """Decorator that makes a simple model from annotated fields.
 
     The generated constructor accepts a single positional ``data`` dict.

{pypercache-0.1.1 → pypercache-0.1.3}/PyperCache/query/json_injester.py

@@ -9,31 +9,6 @@ from lark import Lark, Transformer
 from ..utils.sentinel import UNSET
 from ..utils.typing_cast import instantiate_type
 
-# # ---------------------------------------------------------------------------
-# # Sentinel
-# # ---------------------------------------------------------------------------
-
-# class UNSET:
-#     """Sentinel type representing a missing or unresolved value.
-
-#     Used instead of None so that None can be a legitimate return value
-#     from a query.
-#     """
-
-#     _instance: Optional[UNSET] = None
-
-#     def __new__(cls) -> UNSET:
-#         # Singleton — there is only ever one UNSET instance.
-#         if cls._instance is None:
-#             cls._instance = super().__new__(cls)
-#         return cls._instance
-
-#     def __repr__(self) -> str:
-#         return "JsonInjest.UNSET"
-
-
-# # Convenience singleton so callers can write `is UNSET` rather than `== UNSET`.
-# UNSET = UNSET()
 
 T = TypeVar("T")
 

{pypercache-0.1.1 → pypercache-0.1.3}/PyperCache/utils/typing_cast.py

@@ -2,9 +2,11 @@ from __future__ import annotations
 
 import dataclasses
 import typing
-from typing import Any
+from typing import Any, Type
 
 
+T = typing.TypeVar("T")
+
 def _is_generic_alias(obj: Any) -> bool:
     try:
         from typing import get_origin
@@ -14,7 +16,7 @@ def _is_generic_alias(obj: Any) -> bool:
         return hasattr(obj, "__origin__") and hasattr(obj, "__args__")
 
 
-def instantiate_type(target_type: Any, data: Any) -> Any:
+def instantiate_type(target_type: Type[T], data: Any) -> T:
     """Instantiate or cast *data* into *target_type*.
 
     Supports simple classes (preferring ``from_dict``), dataclasses, and

pypercache-0.1.3/PyperCache.egg-info/PKG-INFO

@@ -0,0 +1,295 @@
+Metadata-Version: 2.4
+Name: PyperCache
+Version: 0.1.3
+Summary: Durable file-backed caching for JSON-like data with pluggable storage backends
+Author-email: Brandon Bahret <your.email@example.com>
+Maintainer-email: Brandon Bahret <your.email@example.com>
+License: MIT License
+        
+        Copyright (c) 2026 Brandon Bahret
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/BrandonBahret/PyperCache
+Project-URL: Documentation, https://github.com/BrandonBahret/PyperCache/tree/master/docs
+Project-URL: Source, https://github.com/BrandonBahret/PyperCache
+Project-URL: Repository, https://github.com/BrandonBahret/PyperCache
+Project-URL: Issues, https://github.com/BrandonBahret/PyperCache/issues
+Project-URL: Changelog, https://github.com/BrandonBahret/PyperCache/blob/master/CHANGELOG.md
+Keywords: cache,persistence,json,pickle,sqlite,storage
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lark>=1.1.0
+Requires-Dist: jsonpickle>=3.0.0
+Requires-Dist: msgpack>=1.0.0
+Dynamic: license-file
+
+# PyperCache
+
+A Python library providing durable file-backed caching for JSON-like data with pluggable storage backends (pickle, JSON, chunked manifest, SQLite), optional TTL and staleness semantics, read-only query navigation, and append-only request logging.
+
+## Installation
+
+```bash
+pip install pypercache
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/BrandonBahret/PyperCache.git
+cd PyperCache
+pip install .
+```
+
+## Quick Start
+
+See the full documentation, examples, and API reference on GitHub:
+
+https://github.com/BrandonBahret/PyperCache/tree/master/docs
+
+## Features
+
+- **Pluggable Backends**: Choose storage by file extension (.pkl, .json, .manifest, .db)
+- **TTL & Staleness**: Optional expiry and acceptable staleness windows
+- **Typed Objects**: Decorate classes for automatic serialization/deserialization
+- **Query Navigation**: Safe, read-only JSON path queries with filters
+- **Request Logging**: Thread-safe JSONL audit trails
+
+## Testing
+
+```bash
+pytest
+```
+
+## Example
+ 
+The snippet below demonstrates every major feature in one pass: choosing a backend, TTL, typed objects, query navigation, and request logging.
+ 
+```python
+import math
+from PyperCache import Cache, RequestLogger
+from PyperCache.models.apimodel import apimodel
+ 
+# ── 1. Backend is chosen by file extension ──────────────────────────────────
+cache = Cache(filepath="api-cache.db")   # .pkl / .json / .manifest / .db
+log   = RequestLogger("api_requests.log")
+ 
+# ── 2. Define a typed model ──────────────────────────────────────────────────
+@apimodel
+class SearchResult:
+    total: int
+    hits:  list
+ 
+# ── 3. Fetch-or-cache pattern ────────────────────────────────────────────────
+KEY = "search:v1:python"
+ 
+if not cache.is_data_fresh(KEY):
+    payload = {
+        "total": 3,
+        "hits": [
+            {"name": "Alice", "role": "staff",  "score": 92},
+            {"name": "Bob",   "role": "guest",  "score": 74},
+            {"name": "Carol", "role": "staff",  "score": 88},
+        ],
+    }
+    cache.store(KEY, payload, expiry=3600, cast=SearchResult)
+    log.log(uri="/api/search?q=python", status=200)
+ 
+# ── 4. Retrieve a typed object ───────────────────────────────────────────────
+result = cache.get_object(KEY)          # SearchResult instance
+print(result.total)                     # 3
+ 
+# ── 5. Query without mutating the payload ───────────────────────────────────
+q = cache.get(KEY).query
+ 
+print(q.get("total"))                           # 3
+print(q.get("hits?role=staff.name"))            # [Alice, Carol]
+print(q.get("hits?name*"))                      # ['Alice', 'Bob', 'Carol']
+print(q.get("hits?role=staff", select_first=True)["name"])  # 'Alice'
+ 
+# ── 6. Inspect the request log ───────────────────────────────────────────────
+for entry in log.get_logs_from_last_seconds(60):
+    print(entry.data["uri"], entry.data["status"])
+```
+ 
+## Features
+ 
+- **Four backends** — `.pkl`, `.json`, `.manifest`, `.db` (SQLite with write-behind batching)
+- **TTL & staleness** — per-record expiry; `is_data_fresh` tells you whether to re-fetch
+- **Typed round-trips** — `@Cache.cached` / `@apimodel` + `cast=` on store; `get_object()` on retrieval
+- **Query navigation** — dotted paths, `?key=value` filters, `?key*` plucks, `?key` existence, `select_first`, defaults; all in memory over the loaded record
+- **Request logging** — thread-safe JSONL audit trail with time-window reads
+ 
+---
+
+## Query navigation
+ 
+`record.query` returns a `JsonInjester` — a lightweight, read-only selector language that runs in memory over the loaded payload. It never touches the storage backend.
+ 
+```python
+q = cache.get("search:v1:python").query
+```
+ 
+You can also instantiate it directly over any dict:
+ 
+```python
+from PyperCache.query import JsonInjester
+q = JsonInjester({"meta": {"total": 5}, "hits": [...]})
+```
+ 
+### Path navigation
+ 
+Dot-separated keys walk the dict. Returns `UNSET` if any key along the path is absent.
+ 
+```python
+q.get("meta.total")          # 5
+q.get("meta.page")           # 1
+q.get("meta.missing")        # UNSET
+q.has("meta.total")          # True  (shorthand for `get(...) is not UNSET`)
+```
+ 
+Keys containing hyphens or other non-identifier characters must be wrapped in double quotes inside the selector string:
+ 
+```python
+q.get('"content-type".value')
+```
+ 
+### `?key=value` — match filter
+ 
+Returns every element in a list where the key equals the value. A tail path after the operator plucks a field from each matched element.
+ 
+```python
+q.get("hits?role=staff")
+# [{"name": "Alice", ...}, {"name": "Carol", ...}]
+ 
+q.get("hits?role=staff.name")
+# ["Alice", "Carol"]
+ 
+q.get("hits?team.name=Engineering")
+# all dicts where hits[i].team.name == "Engineering"
+```
+ 
+Prefix the value with `#` to match numbers instead of strings:
+ 
+```python
+q.get("hits?score=#92")    # integer match
+q.get("hits?ratio=#0.75")  # float match
+```
+ 
+No matches returns an empty list, not `UNSET`.
+ 
+### `?key*` — pluck
+ 
+Extracts a field from every element in the list. Non-missing results are collected; missing ones are silently skipped. Plucks can be chained.
+ 
+```python
+q.get("hits?name*")
+# ["Alice", "Bob", "Carol"]
+ 
+q.get("hits?team.name*")
+# ["Engineering", "Marketing", "Engineering"]
+ 
+q.get("hits?role*?label*")
+# chained: pluck role objects, then pluck label from each
+```
+ 
+On a dict cursor (rather than a list), pluck navigates to the key and returns its value or `UNSET`.
+ 
+### `?key` — exists filter
+ 
+Does not extract values. On a list cursor, returns only elements that contain the key. On a dict cursor, returns the cursor unchanged if the key is present, or `UNSET` if absent.
+ 
+```python
+# list cursor — filter to elements that have a "team" key
+q.get("hits?team")
+ 
+# dict cursor — gate on key presence
+q.get("meta?total")          # returns the meta dict (key exists)
+q.get("meta?ghost")          # UNSET
+q.get("meta?ghost", default_value=0)  # 0
+```
+ 
+### `select_first` and `default_value`
+ 
+`select_first=True` unwraps the first element of a list result. Returns `UNSET` if the list is empty.
+ 
+```python
+from PyperCache.query.json_injester import UNSET
+ 
+first = q.get("hits?role=staff", select_first=True)
+print(first["name"])   # "Alice"
+ 
+empty = q.get("hits?role=contractor", select_first=True)
+print(empty is UNSET)  # True
+```
+ 
+`default_value` is returned when the path is missing or resolves to `None`. Falsy non-`None` values (`False`, `0`, `""`) pass through unchanged.
+ 
+```python
+q.get("meta.missing", default_value=0)   # 0
+q.get("flags.debug", default_value=False) # False (returned as-is, not default)
+```
+ 
+### `cast`
+ 
+When the result is a dict, `cast` passes it to the given type before returning.
+ 
+```python
+q.get("hits?role=staff", select_first=True, cast=StaffMember)
+# StaffMember instance
+```
+ 
+### Known limitations
+ 
+`JsonInjester` is intentionally scoped and simple. A few things it does not do:
+ 
+- **Integer list indexing** — `"hits.0.name"` is not supported. Use a filter or pluck to reach list elements.
+- **Cross-key queries** — `record.query` operates on a single loaded payload. It does not scan multiple records or touch the backend.
+- **Non-ASCII keys** — unquoted non-ASCII key names raise a parse error. Wrap them in double quotes: `'"héros".name'`.
+ 
+For the complete selector reference see [QUERY.md](QUERY.md).
+ 
+---
+ 
+## Documentation
+ 
+| Topic | File |
+|---|---|
+| `Cache`, `CacheRecord`, TTL, typed objects | [CACHE.md](CACHE.md) |
+| `JsonInjester` / `record.query` selector syntax | [QUERY.md](QUERY.md) |
+| Storage backends, `RequestLogger`, SQLite internals | [STORAGE.md](STORAGE.md) |
+ 
+Full docs and examples: https://github.com/BrandonBahret/PyperCache/tree/master/docs
+ 
+## License
+ 
+MIT

{pypercache-0.1.1 → pypercache-0.1.3}/PyperCache.egg-info/SOURCES.txt

@@ -33,8 +33,8 @@ PyperCache/utils/sentinel.py
 PyperCache/utils/serialization.py
 PyperCache/utils/typing_cast.py
 docs/CACHE.md
+docs/DOCS.md
 docs/QUERY.md
-docs/README.md
 docs/STORAGE.md
 tests/test_apimodel.py
 tests/test_cache.py