PyperCache 0.1.0__py3-none-any.whl

PyperCache/__init__.py

@@ -0,0 +1,25 @@
+"""PyperCache — API response cache with pluggable storage backends.
+
+Primary public surface::
+
+    from PyperCache import Cache, CacheRecord, RequestLogger
+    from PyperCache.query import JsonInjester
+
+Utility sub-packages are importable directly when needed::
+
+    from PyperCache.utils import DataSerializer, PickleStore
+    from PyperCache.storage import get_storage_mechanism
+"""
+
+from PyperCache.core.cache import Cache
+from PyperCache.core.cache_record import CacheRecord
+from PyperCache.core.request_logger import LogRecord, RequestLogger
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Cache",
+    "CacheRecord",
+    "LogRecord",
+    "RequestLogger",
+]

PyperCache/core/__init__.py

@@ -0,0 +1,7 @@
+"""PyperCache.core — Cache, CacheRecord, and RequestLogger."""
+
+from PyperCache.core.cache import Cache
+from PyperCache.core.cache_record import CacheRecord
+from PyperCache.core.request_logger import LogRecord, RequestLogger
+
+__all__ = ["Cache", "CacheRecord", "LogRecord", "RequestLogger"]

PyperCache/core/cache.py

@@ -0,0 +1,126 @@
+"""Cache: persistent caching of API responses with optional TTL and type casting."""
+
+import math
+import time
+from typing import Any, Optional
+
+from PyperCache.core.cache_record import CacheRecord
+from PyperCache.storage.factory import get_storage_mechanism
+from PyperCache.utils.patterns import ClassRepository
+from PyperCache.utils.sentinel import UNSET
+
+
+CACHE_FILE = 'api-cache.pkl'
+
+
+class Cache:
+    """Manages persistent caching of API responses with optional TTL and type casting."""
+
+    def __init__(self, filepath: Optional[str] = None):
+        """
+        Initialize the cache with a storage backend determined by file extension.
+
+        Args:
+            filepath: Path to the cache file. Defaults to CACHE_FILE ('api-cache.pkl').
+        """
+        self.classes = ClassRepository()
+
+        filepath = filepath or CACHE_FILE
+        StorageClass = get_storage_mechanism(filepath)
+        self.storage = StorageClass(filepath)
+
+    @staticmethod
+    def cached(cls):
+        """Class decorator that registers a class as cache-compatible.
+
+        Usage::
+
+            @Cache.cached
+            class MyAPIResponse:
+                ...
+        """
+        ClassRepository().add_class(cls)
+        return cls
+
+    def has(self, key: str) -> bool:
+        """Return True if a cache record exists for the given key."""
+        return key in self.storage.records
+
+    def is_data_fresh(self, key: str) -> bool:
+        """Return True if a non-stale cache record exists for the given key."""
+        if not self.has(key):
+            return False
+        return not self.storage.get_record(key).is_data_stale
+
+    def get(self, key: str) -> CacheRecord:
+        """Retrieve the raw CacheRecord for the given key.
+
+        Raises:
+            KeyError: If no record exists for the key.
+        """
+        if not self.has(key):
+            raise KeyError(f'No cache found for {key!r}!')
+        return self.storage.get_record(key)
+
+    def get_object(self, key: str, default_value: Any = UNSET) -> object:
+        """Retrieve the cached value for a key, cast to its registered type.
+
+        Args:
+            key:           Cache key to look up.
+            default_value: Returned if the key is missing. Raises KeyError if omitted.
+
+        Raises:
+            KeyError:       If the key is missing and no default was provided.
+            AttributeError: If the record has no cast type registered.
+        """
+        if not self.has(key):
+            if default_value is UNSET:
+                raise KeyError(f'No cache found for {key!r}!')
+            return default_value
+
+        record = self.storage.get_record(key)
+        if not record.should_convert_type:
+            raise AttributeError(f'No cast type provided for {key!r}!')
+        # Use the shared instantiation helper when converting types so
+        # generics and apimodels are hydrated correctly.
+        from ..utils.typing_cast import instantiate_type
+
+        return instantiate_type(record.cast, record.data)
+
+    def update(self, key: str, data: dict):
+        """Update the data payload of an existing cache record.
+
+        Raises:
+            KeyError: If no record exists for the key.
+        """
+        if not self.has(key):
+            raise KeyError(f'No cache found for {key!r}!')
+        self.storage.update_record(key, data)
+
+    def store(self, key: str, data: dict, expiry: int = math.inf, cast: type = None):
+        """Create or overwrite a cache record.
+
+        Args:
+            key:    Unique identifier for this cache entry.
+            data:   The payload to cache.
+            expiry: Seconds until the record is considered stale. Defaults to no expiry.
+            cast:   Optional type to register for deserialising the cached data.
+        """
+        serialisable_expiry = 'math.inf' if expiry == math.inf else expiry
+        # Store short builtin names for primitives, fqname for other classes.
+        if isinstance(cast, type) and getattr(cast, "__module__", None) == "builtins":
+            cast_str = cast.__name__
+        else:
+            cast_str = (f"{cast.__module__}.{cast.__name__}" if isinstance(cast, type) else None)
+
+        new_record = {
+            'cast': cast_str,
+            'expiry': serialisable_expiry,
+            'timestamp': time.time(),
+            'data': data,
+        }
+        self.storage.store_record(key, new_record)
+
+    def completely_erase_cache(self):
+        """Permanently delete all records from the cache storage."""
+        self.storage.erase_everything()

PyperCache/core/cache_record.py

@@ -0,0 +1,217 @@
+"""CacheRecord: a single cached API response with expiry and optional type casting."""
+
+import inspect
+import math
+import time
+from typing import Callable, Optional
+
+from PyperCache.query import JsonInjester
+from PyperCache.utils.patterns import ClassRepository
+from PyperCache.utils.sentinel import UNSET
+
+
+# Maps primitive type name strings to their corresponding Python types.
+PRIMITIVE_TYPES_MAP = {
+    'bool': bool,
+    'bytearray': bytearray,
+    'bytes': bytes,
+    'complex': complex,
+    'dict': dict,
+    'float': float,
+    'frozenset': frozenset,
+    'int': int,
+    'list': list,
+    'object': object,
+    'set': set,
+    'str': str,
+    'tuple': tuple,
+    'type': type,
+}
+
+
+def look_up_class(class_name: str) -> type:
+    """Resolve a class by name, checking primitives first then the class repository.
+
+    Args:
+        class_name: The name of the class to look up.
+
+    Returns:
+        The resolved class type.
+
+    Raises:
+        NameError: If the class name is not registered.
+        TypeError: If the resolved object is not a class.
+    """
+    if class_name in PRIMITIVE_TYPES_MAP:
+        return PRIMITIVE_TYPES_MAP[class_name]
+
+    # Primitive types (short names) map directly to builtins.
+    if class_name in PRIMITIVE_TYPES_MAP:
+        return PRIMITIVE_TYPES_MAP[class_name]
+
+    classes = ClassRepository()
+    # Try resolving via the repository first (supports short and fqnames)
+    cls = classes.get_class(class_name)
+    if cls is not None and inspect.isclass(cls):
+        return cls
+
+    # If class_name looks like a fully-qualified path, try importing it.
+    if '.' in class_name:
+        module_name, _, attr = class_name.rpartition('.')
+        try:
+            module = __import__(module_name, fromlist=[attr])
+            obj = getattr(module, attr)
+            if inspect.isclass(obj):
+                return obj
+        except Exception:
+            pass
+
+    raise NameError(f'{class_name!r} is not defined')
+
+
+class CacheRecord:
+    """Represents a single cached API response with expiry and optional type casting.
+
+    Records are stored and serialized as plain dicts, with ``math.inf``
+    represented as the string ``'math.inf'`` to support JSON-safe serialization.
+
+    The :attr:`query` property exposes the cached data through a
+    :class:`~cache_module.query.JsonInjester`, enabling dotted-path access
+    and filter queries without altering the underlying data::
+
+        record = cache.get_record("org:acme")
+        record.query.get("meta.total_users")
+        record.query.get("users?role=admin")
+        record.query.has("users")
+
+    Args:
+        record:           Raw dict with keys ``timestamp``, ``expiry``, ``data``,
+                          and optionally ``cast``.
+        class_resolver:   Optional callable used to resolve the cast type name to
+                          an actual type.  Defaults to :func:`look_up_class`, which
+                          consults :class:`ClassRepository`.  Pass a custom resolver
+                          in tests to avoid touching the global registry.
+    """
+
+    def __init__(
+        self,
+        record: dict,
+        class_resolver: Optional[Callable[[str], type]] = None,
+    ) -> None:
+        self.__record_dict = record
+        self.__class_resolver = class_resolver or look_up_class
+
+        self.timestamp: float = record['timestamp']
+        self.data: dict = record['data']
+        self.expiry: float = math.inf if record['expiry'] == 'math.inf' else record['expiry']
+        self.cast_str: Optional[str] = record.get('cast')
+        self.__cast: object = UNSET   # Unresolved until first access.
+        self.__query: Optional[JsonInjester] = None  # Built lazily on first access.
+
+    @staticmethod
+    def from_data(data: dict, expiry: float = math.inf, cast: type = None) -> 'CacheRecord':
+        """Construct a new CacheRecord from raw data.
+
+        Args:
+            data:   The payload to cache.
+            expiry: Seconds until the record is considered stale. Defaults to never.
+            cast:   Optional type to cast the data to on retrieval.
+
+        Returns:
+            A new CacheRecord instance.
+        """
+        # Store short builtin names (e.g. 'dict') for primitive types to
+        # preserve compatibility with earlier cache files; otherwise store
+        # fully-qualified name for user classes.
+        if isinstance(cast, type) and cast.__module__ == 'builtins':
+            cast_str = cast.__name__
+        else:
+            cast_str = (f"{cast.__module__}.{cast.__name__}" if isinstance(cast, type) else None)
+
+        record = {
+            'cast': cast_str,
+            'expiry': expiry,
+            'timestamp': time.time(),
+            'data': data,
+        }
+        return CacheRecord(record)
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def cast(self) -> Optional[type]:
+        """Lazily resolve the cast type from its stored class name string."""
+        if self.__cast is UNSET:
+            self.__cast = (
+                self.__class_resolver(self.cast_str)
+                if isinstance(self.cast_str, str)
+                else None
+            )
+        return self.__cast
+
+    @property
+    def query(self) -> JsonInjester:
+        """A :class:`~cache_module.query.JsonInjester` view over :attr:`data`.
+
+        Built once on first access and reused.  Supports dotted-path lookup,
+        existence checks, filtered list queries, and default values — all
+        without modifying the underlying cached data.
+
+        Example::
+
+            record.query.get("meta.total_users")          # nested key
+            record.query.get("users?role=admin")          # filter list
+            record.query.get("users?dept.name=Engineering")
+            record.query.has("meta.total_users")          # existence check
+            record.query.get("missing_key", default_value=0)
+
+        Note: if :attr:`data` has been replaced via :meth:`update`, call
+        ``record.query`` again — the injester is rebuilt automatically because
+        :meth:`update` clears the cached instance.
+        """
+        if self.__query is None:
+            self.__query = JsonInjester(self.data)
+        return self.__query
+
+    @property
+    def should_convert_type(self) -> bool:
+        """True if a valid cast type is set and data should be converted on retrieval."""
+        return isinstance(self.cast, type)
+
+    @property
+    def is_data_stale(self) -> bool:
+        """True if the record has lived past its expiry window."""
+        return time.time() > self.timestamp + self.expiry
+
+    # ------------------------------------------------------------------
+    # Mutation
+    # ------------------------------------------------------------------
+
+    def update(self, data: dict):
+        """Replace the cached data and refresh the timestamp.
+
+        Also invalidates the cached :attr:`query` injester so the next access
+        reflects the new data.
+        """
+        self.data = data
+        self.timestamp = time.time()
+        self.__record_dict['data'] = data
+        self.__record_dict['timestamp'] = self.timestamp
+        self.__query = None   # invalidate so next .query access wraps new data
+
+    # ------------------------------------------------------------------
+    # Serialisation
+    # ------------------------------------------------------------------
+
+    def as_dict(self) -> dict:
+        """Serialize the record to a plain dict, encoding infinity as 'math.inf'."""
+        return {
+            k: ('math.inf' if v == math.inf else v)
+            for k, v in self.__record_dict.items()
+        }
+
+    def __repr__(self) -> str:
+        label = 'data_stale' if self.is_data_stale else 'data_fresh'
+        return f'<{self.cast_str}::{label}>'

PyperCache/core/request_logger.py

@@ -0,0 +1,107 @@
+"""RequestLogger: thread-safe API request log with JSONL append-mode writes."""
+
+from datetime import datetime
+import threading
+from typing import List
+from pathlib import Path
+import time
+import json
+
+from PyperCache.utils.fs import ensure_dirs_exist
+
+
+LOG_FILENAME = "api_logfile.log"
+
+
+class LogRecord:
+    """Represents a single API request log entry."""
+
+    def __init__(self, record: dict) -> None:
+        self._record_dict = record
+        self.timestamp: float = record["timestamp"]
+        self.data: dict = {"uri": record["uri"], "status": int(record["status"])}
+
+    def as_dict(self) -> dict:
+        return self._record_dict
+
+    def __repr__(self) -> str:
+        ts_str = datetime.fromtimestamp(self.timestamp).strftime(
+            "%d-%m-%Y %I:%M:%S,%f %p"
+        )
+        return f"{ts_str} - {self.data!r}"
+
+
+class RequestLogger:
+    """Persists API request logs to a JSON Lines file and provides
+    thread-safe read/write access.
+
+    File format: one JSON object per line (JSONL). Each call to ``log()``
+    appends a single line — an O(1) operation regardless of how many records
+    the file already contains. Legacy files written as a JSON array are
+    detected on load and migrated transparently.
+    """
+
+    def __init__(self, filepath: str | None = None) -> None:
+        self.lock = threading.Lock()
+        self.filepath: str = filepath or LOG_FILENAME
+        ensure_dirs_exist(self.filepath)
+        path = Path(self.filepath)
+        path.touch(exist_ok=True)
+        self.records: List[LogRecord] = self._load(path)
+
+    def log(self, uri: str, status: int) -> None:
+        """Append a new request record to the log file (O(1) per write)."""
+        new_record = {"uri": uri, "status": status, "timestamp": time.time()}
+        log_record = LogRecord(new_record)
+        with self.lock:
+            self.records.append(log_record)
+            self._append(log_record)
+
+    def get_logs_from_last_seconds(self, seconds: int = 60) -> List[LogRecord]:
+        """Return records from the last *seconds* seconds, sorted oldest-first."""
+        cutoff = time.time() - seconds
+        recent = [log for log in self.records if log.timestamp >= cutoff]
+        return sorted(recent, key=lambda log: log.timestamp)
+
+    def as_list(self) -> list[dict]:
+        return [r.as_dict() for r in self.records]
+
+    def _append(self, record: LogRecord) -> None:
+        """Write a single record as one JSON line (must be called under self.lock)."""
+        with open(self.filepath, "a") as fp:
+            fp.write(json.dumps(record.as_dict()))
+            fp.write("\n")
+
+    @staticmethod
+    def _load(path: Path) -> List[LogRecord]:
+        """Parse records from *path*, handling both JSONL and legacy JSON-array format."""
+        content = path.read_text().strip()
+        if not content:
+            return []
+
+        try:
+            records: list[dict] = []
+            for line in content.splitlines():
+                line = line.strip()
+                if line:
+                    parsed = json.loads(line)
+                    if not isinstance(parsed, dict):
+                        raise ValueError("Expected a JSON object per line.")
+                    records.append(parsed)
+            return [LogRecord(r) for r in records]
+        except (json.JSONDecodeError, ValueError):
+            pass
+
+        try:
+            records = json.loads(content)
+            if isinstance(records, list):
+                log_records = [LogRecord(r) for r in records if isinstance(r, dict)]
+                with open(path, "w") as fp:
+                    for lr in log_records:
+                        fp.write(json.dumps(lr.as_dict()))
+                        fp.write("\n")
+                return log_records
+        except json.JSONDecodeError:
+            pass
+
+        return []

PyperCache/models/apimodel.py

@@ -0,0 +1,49 @@
+"""Small `@apimodel` decorator for simple API models.
+
+This module provides a light-weight decorator that:
+- registers the class with `ClassRepository` (short name and fqname)
+- injects a constructor that accepts a raw dict and hydrates annotated
+  fields (using `instantiate_type` for nested types)
+- provides `from_dict` and `as_dict` helpers
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ..utils.patterns import ClassRepository
+from ..query.json_injester import JsonInjester
+from ..utils.typing_cast import instantiate_type
+
+
+def apimodel(cls: type) -> type:
+    """Decorator that makes a simple model from annotated fields.
+
+    The generated constructor accepts a single positional ``data`` dict.
+    Registered classes expose ``from_dict`` and ``as_dict`` for symmetry
+    with other parts of the codebase.
+    """
+    ClassRepository().add_class(cls)
+
+    annotations = getattr(cls, "__annotations__", {})
+
+    def __init__(self, data: dict) -> None:
+        ji = JsonInjester(data)
+        object.__setattr__(self, "_Initial__Data", data)
+
+        for field, annotated in annotations.items():
+            raw = ji.get(field, default_value=None)
+            value = instantiate_type(annotated, raw)
+            setattr(self, field, value)
+
+    def as_dict(self) -> dict:
+        return getattr(self, "_Initial__Data")
+
+    @classmethod
+    def from_dict(cls2, data: dict) -> Any:
+        return cls2(data)
+
+    cls.__init__ = __init__
+    cls.as_dict = as_dict
+    cls.from_dict = from_dict
+
+    return cls

PyperCache/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561

PyperCache/query/__init__.py

@@ -0,0 +1,10 @@
+"""
+Query submodule: provides dictionary object searching utilities.
+"""
+
+
+from .json_injester import JsonInjester
+
+__all__ = [
+    "JsonInjester"
+]