PyperCache 0.1.0__py3-none-any.whl

PyperCache/utils/profiling.py

@@ -0,0 +1,44 @@
+"""Lightweight wall-clock profiler."""
+
+import time
+from typing import Dict
+
+
+class Profiler:
+    """Lightweight label-based wall-clock profiler.
+
+    Usage::
+
+        profiler = Profiler()
+        profiler.start_profile("my_task")
+        do_work()
+        profiler.end_profile("my_task")  # prints elapsed time if > 1 ms
+    """
+
+    def __init__(self) -> None:
+        self.start_times: Dict[str, float] = {}
+
+    def start_profile(self, label: str) -> None:
+        """Record the start time for *label*.
+
+        Args:
+            label: An arbitrary string identifying the profiling session.
+        """
+        self.start_times[label] = time.time()
+
+    def end_profile(self, label: str) -> None:
+        """End the session for *label* and print the elapsed time.
+
+        Elapsed times below 1 ms are suppressed to reduce noise. If no
+        matching ``start_profile`` call exists a warning is printed instead.
+
+        Args:
+            label: The label passed to the corresponding ``start_profile`` call.
+        """
+        if label not in self.start_times:
+            print(f"No profiling session found for label '{label}'.")
+            return
+
+        elapsed = time.time() - self.start_times[label]
+        if elapsed > 0.001:
+            print(f"Time elapsed for '{label}': {elapsed:.4f} seconds")

PyperCache/utils/sentinel.py

@@ -0,0 +1,26 @@
+"""Shared sentinel value for distinguishing "no argument supplied" from None.
+
+A single definition lives here so every module in the package uses the same
+object identity, making ``is UNSET`` checks reliable across module boundaries.
+"""
+
+
+class _UnsetType:
+    """Singleton sentinel type.  Use the ``UNSET`` module-level instance."""
+
+    _instance: "_UnsetType | None" = None
+
+    def __new__(cls) -> "_UnsetType":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+    def __bool__(self) -> bool:
+        return False
+
+
+#: The canonical sentinel instance.  Test with ``value is UNSET``.
+UNSET = _UnsetType()

PyperCache/utils/serialization.py

@@ -0,0 +1,175 @@
+"""Pickle-based persistence and zlib-backed dict compression."""
+
+import concurrent.futures
+import json
+import pickle
+import zlib
+from pathlib import Path
+from typing import Any, Dict
+
+from PyperCache.utils.fs import ensure_dirs_exist
+
+
+class PickleStore:
+    """Static helpers for persisting arbitrary Python objects via ``pickle``."""
+
+    @staticmethod
+    def touch_file(default_obj: Any, filename: str) -> None:
+        """Ensure *filename* exists, creating it with *default_obj* if absent.
+
+        Args:
+            default_obj: The object to pickle if the file does not yet exist.
+            filename:    Path to the target pickle file.
+        """
+        if not Path(filename).exists():
+            PickleStore.save_object(default_obj, filename)
+
+    @staticmethod
+    def save_object(obj: Any, filename: str) -> None:
+        """Serialise *obj* to *filename* using pickle.
+
+        Intermediate directories are created automatically.
+
+        Args:
+            obj:      The Python object to serialise.
+            filename: Destination file path.
+        """
+        try:
+            ensure_dirs_exist(filename)
+            with open(filename, "wb") as fh:
+                pickle.dump(obj, fh)
+        except Exception as exc:
+            print(f"Failed to save object to {filename}: {exc}")
+
+    @staticmethod
+    def load_object(filename: str) -> Any | None:
+        """Deserialise and return the object stored in *filename*.
+
+        Args:
+            filename: Path to a pickle file created by :meth:`save_object`.
+
+        Returns:
+            The deserialised object, or ``None`` if the file is missing or
+            an error occurs.
+        """
+        try:
+            with open(filename, "rb") as fh:
+                return pickle.load(fh)
+        except FileNotFoundError:
+            print(f"No such file: {filename}")
+        except Exception as exc:
+            print(f"Failed to load object from {filename}: {exc}")
+        return None
+
+
+class DataSerializer:
+    """Compress, encode, and JSON-serialise dictionaries whose values are
+    strings or nested dicts.
+
+    Compression uses zlib; the compressed bytes are hex-encoded so they can
+    be safely embedded in JSON. Serialisation and deserialisation of
+    individual keys are parallelised with a ``ThreadPoolExecutor`` —
+    ``zlib.compress`` releases the GIL, so threads achieve true parallelism
+    here without the IPC overhead of a process pool.
+
+    Supported value types: ``str``, ``dict``.
+    """
+
+    @staticmethod
+    def compress_text(text: str, level: int = 6) -> str:
+        """Compress *text* with zlib and return the result as a hex string.
+
+        Args:
+            text:  UTF-8 text to compress.
+            level: zlib compression level (0–9). Default is 6.
+
+        Returns:
+            Hex-encoded compressed bytes.
+        """
+        compressed = zlib.compress(text.encode("utf-8"), level)
+        return compressed.hex()
+
+    @staticmethod
+    def decompress_text(hex_encoded: str) -> str:
+        """Decompress a hex string produced by :meth:`compress_text`.
+
+        Args:
+            hex_encoded: Hex-encoded compressed bytes.
+
+        Returns:
+            The original UTF-8 text.
+        """
+        compressed = bytes.fromhex(hex_encoded)
+        return zlib.decompress(compressed).decode("utf-8")
+
+    @staticmethod
+    def serialize_dict(data: Dict[str, Any], level: int = 6) -> str:
+        """Compress each value in *data* and serialise the result to a JSON string.
+
+        Each value is replaced by a ``(type_tag, compressed_hex)`` tuple so
+        that the correct deserialisation path can be chosen later.
+
+        Args:
+            data:  A flat dictionary whose values are ``str`` or ``dict``.
+            level: zlib compression level passed to :meth:`compress_text`.
+
+        Returns:
+            A JSON string representing the compressed dictionary.
+
+        Raises:
+            ValueError: If a value's type is not ``str`` or ``dict``.
+        """
+        def compress_entry(key: str, value: Any) -> tuple[str, Any]:
+            if isinstance(value, str):
+                return key, ("str", DataSerializer.compress_text(value, level))
+            elif isinstance(value, dict):
+                return key, ("dict", DataSerializer.compress_text(json.dumps(value), level))
+            else:
+                raise ValueError(f"Serialisation not supported for type {type(value)}.")
+
+        compressed: Dict[str, Any] = {}
+        with concurrent.futures.ThreadPoolExecutor() as executor:
+            futures = {
+                executor.submit(compress_entry, key, value): key
+                for key, value in data.items()
+            }
+            for future in concurrent.futures.as_completed(futures):
+                key, result = future.result()
+                compressed[key] = result
+
+        return json.dumps(compressed)
+
+    @staticmethod
+    def deserialize_dict(json_str: str) -> Dict[str, Any]:
+        """Deserialise a JSON string produced by :meth:`serialize_dict`.
+
+        Each ``(type_tag, compressed_hex)`` pair is decompressed and
+        converted back to its original type.
+
+        Args:
+            json_str: A JSON string as returned by :meth:`serialize_dict`.
+
+        Returns:
+            The reconstructed dictionary with original value types restored.
+        """
+        data: Dict[str, Any] = json.loads(json_str)
+
+        def decompress_entry(key: str, value: Any) -> tuple[str, Any]:
+            type_tag, compressed_hex = value
+            if type_tag == "str":
+                return key, DataSerializer.decompress_text(compressed_hex)
+            elif type_tag == "dict":
+                return key, json.loads(DataSerializer.decompress_text(compressed_hex))
+            raise ValueError(f"Unknown type tag: {type_tag!r}")
+
+        result: Dict[str, Any] = {}
+        with concurrent.futures.ThreadPoolExecutor() as executor:
+            futures = {
+                executor.submit(decompress_entry, key, value): key
+                for key, value in data.items()
+            }
+            for future in concurrent.futures.as_completed(futures):
+                key, decompressed = future.result()
+                result[key] = decompressed
+
+        return result

PyperCache/utils/typing_cast.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import dataclasses
+import typing
+from typing import Any
+
+
+def _is_generic_alias(obj: Any) -> bool:
+    try:
+        from typing import get_origin
+
+        return get_origin(obj) is not None
+    except Exception:
+        return hasattr(obj, "__origin__") and hasattr(obj, "__args__")
+
+
+def instantiate_type(target_type: Any, data: Any) -> Any:
+    """Instantiate or cast *data* into *target_type*.
+
+    Supports simple classes (preferring ``from_dict``), dataclasses, and
+    basic generics: ``list[T]`` and ``dict[K, V]``. Falls back to returning
+    the original *data* when no casting is possible.
+    """
+    if data is None:
+        return None
+
+    # Generic aliases (e.g., list[User], typing.List[User])
+    origin = None
+    args = ()
+    try:
+        origin = typing.get_origin(target_type)
+        args = typing.get_args(target_type)
+    except Exception:
+        pass
+
+    if origin is list or origin is typing.List:
+        item_type = args[0] if args else Any
+        return [instantiate_type(item_type, item) for item in (data or [])]
+
+    if origin is dict or origin is typing.Dict:
+        key_type, val_type = (args + (Any, Any))[:2]
+        return {k: instantiate_type(val_type, v) for k, v in (data or {}).items()}
+
+    # If a typing alias without origin (fallback), try basic handling
+    if _is_generic_alias(target_type):
+        # best-effort for simple single-arg generics
+        try:
+            inner = target_type.__args__[0]
+            if target_type.__origin__ is list:
+                return [instantiate_type(inner, item) for item in (data or [])]
+        except Exception:
+            pass
+
+    # Concrete class handling
+    if isinstance(target_type, type):
+        # Prefer explicit from_dict constructor
+        if hasattr(target_type, "from_dict") and callable(getattr(target_type, "from_dict")):
+            return target_type.from_dict(data)
+
+        # dataclass support
+        if dataclasses.is_dataclass(target_type):
+            if isinstance(data, dict):
+                return target_type(**data)
+
+        # Last resort: try calling the type with the data as positional arg
+        try:
+            return target_type(data)
+        except Exception:
+            return data
+
+    # Not a class or supported generic — return as-is.
+    return data

pypercache-0.1.0.dist-info/METADATA

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: PyperCache
+Version: 0.1.0
+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#readme
+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 [docs/README.md](docs/README.md) for detailed documentation, examples, and API reference.
+
+## 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
+```
+
+## License
+
+MIT License (see LICENSE file)

pypercache-0.1.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+PyperCache/__init__.py,sha256=U8Xw6bNZ-VeULGE-E-Z5OvnrZ0HPXEVAGRtIn4RCJiY,657
+PyperCache/py.typed,sha256=8ZJUsxZiuOy1oJeVhsTWQhTG_6pTVHVXk5hJL79ebTk,25
+PyperCache/core/__init__.py,sha256=0zQA6ycgsWsk4aYtQRaJdfzavkjWYmDeM1cwHgP02E8,298
+PyperCache/core/cache.py,sha256=WkFqRHFLSRKJzTWo93eU8q3BFi-88jXMp7DT7gCAkB8,4513
+PyperCache/core/cache_record.py,sha256=QBv75MZMZ0lbUFKLC6YFQFDYBEF1Z25vStl68NBfqZs,7859
+PyperCache/core/request_logger.py,sha256=h1yIs05NGXftY5nvbS_71MhKeVcx6YAOAZ5X4BlYwC0,3815
+PyperCache/models/apimodel.py,sha256=WGJaosVwpVNfveVayOPy00u4O69q-zgFV-k_C61ywY0,1586
+PyperCache/query/__init__.py,sha256=oNrrJY8JjY9CykEAxSUvtXHClXXbNLDl645xc9WA8cI,157
+PyperCache/query/json_injester.py,sha256=Gv7CH-hfia5SU7kvtf0Dw_9yRa6pfcYq5l-sq1dYwxI,16149
+PyperCache/storage/__init__.py,sha256=93Bb-IS5RDA-A3ScwBEa7Ow4at26h0yEm8ryG4j3q1w,616
+PyperCache/storage/backends.py,sha256=BNwpSFh-644zsSccwpAqPACo754qYabThdp8XryQbmA,3845
+PyperCache/storage/base.py,sha256=gGupofw3HrnQyxiLpR0etP74_kyYHyYrLZaX30t8NkM,3961
+PyperCache/storage/chunked_dictionary.py,sha256=oWWif-WSNNeMSBwNibWXeop8f9zQZu0ztuo9tv2lrDw,10934
+PyperCache/storage/factory.py,sha256=HXPpX6qS4UrlD7RrGMolCgGnnaTvd9id568rayrJrAQ,1354
+PyperCache/storage/sqlite_storage.py,sha256=K_PIZSEJyjaSEpHNzZr35DcaoKTiBM_28PRxXe6uRKk,18293
+PyperCache/utils/__init__.py,sha256=_f4hwfeYB7j-lmLZ5CmWNq84z33rjzkFiMK9CIgFC5A,839
+PyperCache/utils/collections.py,sha256=nAh4vPLPtgFvEX5BBuLIUseMjjB_F5lAhILXluQYUio,832
+PyperCache/utils/fs.py,sha256=fYAVYwXOKKOHTkMVO7qA-1UnhlDNs8tNEnSJW5-famE,1354
+PyperCache/utils/patterns.py,sha256=pJ9qoGdDGz53GPJALXXzkaPSeH1KrLeBWfkoMoaaePs,3104
+PyperCache/utils/profiling.py,sha256=aSlkwlJzCqOAUnrNj9mV8IW_nUSrjwemzAPV_BDYFlE,1315
+PyperCache/utils/sentinel.py,sha256=26B54gYedOe64NIDMv1-jeYE0BBZjCL9m_2qQkbADmA,728
+PyperCache/utils/serialization.py,sha256=ZdjfekUlyCXXyPzSJEVZ36b5Y2RzWXGYw4btDgjBCJY,6233
+PyperCache/utils/typing_cast.py,sha256=CmLy6OYDcpn_3AzBTeYt_dmvx4oHqjf5YaxEawY-1r0,2401
+pypercache-0.1.0.dist-info/licenses/LICENSE,sha256=PxfCf-1Xl_lqG-cfZfSN9sc6OBOs2OqaZSyx04G40ZQ,1090
+pypercache-0.1.0.dist-info/METADATA,sha256=d6Nb3EXTDmOKGyBPJOirpMq-DvqVeM5dHrITJ8Gtw_s,3838
+pypercache-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pypercache-0.1.0.dist-info/top_level.txt,sha256=HzL4WBDoVJe-T-2AuMgzNBlpYRENZ2MUirlkF1yxcjA,11
+pypercache-0.1.0.dist-info/RECORD,,

pypercache-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pypercache-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+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.

pypercache-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+PyperCache