pfmsoft-api-request 0.1.3__py3-none-any.whl

pfmsoft/api_request/__init__.py

@@ -0,0 +1,37 @@
+"""api-request: A command line first interface to the Eve Online API."""
+
+from importlib.metadata import version
+
+__project_namespace__ = "pfmsoft"
+__author__ = "Chad Lowe"
+__email__ = "pfmsoft.dev@gmail.com"
+__app_name__ = "pfmsoft-api-request"
+"""Name of this module is defined here for consitency, used in determining the app_dir 
+and other paths."""
+__description__ = "A command line first interface to the Eve Online API"
+__version__ = version(__app_name__)
+__release__ = __version__
+__url__ = "https://github.com/DonalChilde/pfmsoft-api-request"
+__license__ = "MIT"
+
+from .request.api_requester import ApiRequester
+from .request.models import (
+    FailedResponse,
+    Request,
+    Requests,
+    Response,
+    ResponseMetadata,
+    Responses,
+    Source,
+)
+
+__all__ = [
+    "ApiRequester",
+    "FailedResponse",
+    "Request",
+    "Requests",
+    "Response",
+    "ResponseMetadata",
+    "Responses",
+    "Source",
+]

pfmsoft/api_request/cache/__init__.py

@@ -0,0 +1,36 @@
+"""Cache implementations and helpers for request orchestration.
+
+Exports:
+        - `InMemoryCache` and `InMemoryCacheFactory` for ephemeral, process-local
+            caching.
+        - `SqliteCache` and `SqliteCacheFactory` for persistent SQLite-backed
+            caching.
+        - `merge_cached_revalidation_metadata` for `304 Not Modified`
+            revalidation merge semantics.
+
+Typical usage:
+
+```python
+from api_request import ApiRequester
+from api_request.cache import SqliteCacheFactory
+from api_request.rate_limit import AiolimiterRateLimiterFactory
+
+async with ApiRequester(
+    cache_factory=SqliteCacheFactory("./.cache/api-request.sqlite3"),
+    rate_limiter_factory=AiolimiterRateLimiterFactory(max_rate=100.0),
+) as requester:
+    ...
+```
+"""
+
+from .memory_cache import InMemoryCache, InMemoryCacheFactory
+from .metadata_helpers import merge_cached_revalidation_metadata
+from .sqlite_cache.sqlite_cache import SqliteCache, SqliteCacheFactory
+
+__all__ = [
+    "InMemoryCache",
+    "merge_cached_revalidation_metadata",
+    "SqliteCache",
+    "InMemoryCacheFactory",
+    "SqliteCacheFactory",
+]

pfmsoft/api_request/cache/memory_cache.py

@@ -0,0 +1,177 @@
+"""In-memory cache implementations for API requests.
+
+These caches are primarily intended for tests and local development where a
+persistent backing store is unnecessary.
+
+Behavior summary:
+    - Storage is process-local and non-durable.
+    - `set` performs upsert semantics.
+    - `update_304` preserves cached body text and merges metadata.
+    - `flush` is a no-op.
+"""
+
+from types import TracebackType
+from typing import Self
+from uuid import UUID
+
+from whenever import Instant
+
+from ..request.models import ResponseMetadata
+from .metadata_helpers import merge_cached_revalidation_metadata
+from .models import CachedResponse, CacheInfo
+from .protocols import CacheFactoryProtocol, CacheProtocol
+
+
+class InMemoryCache(CacheProtocol):
+    """Dictionary-backed cache implementation.
+
+    The cache stores `CachedResponse` objects in memory and performs no I/O.
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty in-memory cache."""
+        self._entries: dict[UUID, CachedResponse] = {}
+
+    async def __aenter__(self) -> Self:
+        """Enter the asynchronous context manager."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Exit the asynchronous context manager."""
+        _ = exc_type, exc_value, traceback
+
+    async def get(self, cache_key: UUID) -> CachedResponse | None:
+        """Get a cached response by key, or None when missing."""
+        return self._entries.get(cache_key)
+
+    @staticmethod
+    def _ensure_validators(metadata: ResponseMetadata) -> None:
+        """Ensure at least one cache validator is present."""
+        if metadata.etag is None and metadata.last_modified is None:
+            raise ValueError("Cached responses require etag or last_modified")
+
+    @staticmethod
+    def _build_cached_response(
+        *,
+        cache_key: UUID,
+        text: str,
+        metadata: ResponseMetadata,
+    ) -> CachedResponse:
+        """Build a CachedResponse from response text and metadata."""
+        InMemoryCache._ensure_validators(metadata)
+        return CachedResponse(
+            cache_key=cache_key,
+            response_text=text,
+            response_metadata_json=metadata.serialize(),
+            etag=metadata.etag,
+            last_modified=metadata.last_modified,
+            expires_at=metadata.expires_at,
+            cache_timestamp=Instant.now().timestamp_nanos(),
+        )
+
+    async def set(
+        self, cache_key: UUID, text: str, metadata: ResponseMetadata
+    ) -> CachedResponse:
+        """Create or replace a cached response entry.
+
+        Raises:
+            ValueError: If both metadata validators are absent.
+        """
+        cached_response = self._build_cached_response(
+            cache_key=cache_key,
+            text=text,
+            metadata=metadata,
+        )
+        self._entries[cache_key] = cached_response
+        return cached_response
+
+    async def update_304(
+        self, cache_key: UUID, metadata: ResponseMetadata
+    ) -> CachedResponse:
+        """Refresh a stale entry from 304 metadata while preserving body text.
+
+        Raises:
+            KeyError: If no existing entry is present.
+            ValueError: If merged metadata lacks both validators.
+        """
+        existing = self._entries.get(cache_key)
+        if existing is None:
+            raise KeyError(f"No cached response found for key {cache_key}")
+
+        existing_metadata = ResponseMetadata.deserialize(
+            existing.response_metadata_json
+        )
+        merged_metadata = merge_cached_revalidation_metadata(
+            cached=existing_metadata,
+            refreshed=metadata,
+        )
+
+        cached_response = self._build_cached_response(
+            cache_key=cache_key,
+            text=existing.response_text,
+            metadata=merged_metadata,
+        )
+        self._entries[cache_key] = cached_response
+        return cached_response
+
+    async def delete(self, cache_key: UUID) -> None:
+        """Delete a cached response from the cache.
+
+        This operation is idempotent and does not raise for missing keys.
+        """
+        self._entries.pop(cache_key, None)
+
+    async def clear(
+        self, only_expired: bool = False, age_limit: int | None = None
+    ) -> None:
+        """Clear cached entries matching the requested filters.
+
+        Args:
+            only_expired: When true, remove only expired entries.
+            age_limit: When provided, remove entries with `cache_age` greater
+                than or equal to this nanosecond threshold.
+
+        Notes:
+            When both filters are provided, entries must satisfy both.
+        """
+        if not only_expired and age_limit is None:
+            self._entries.clear()
+            return
+
+        removable_keys: list[UUID] = []
+        for cache_key, cached_response in self._entries.items():
+            is_expired_match = not only_expired or cached_response.is_expired
+            is_age_match = age_limit is None or cached_response.cache_age >= age_limit
+            if is_expired_match and is_age_match:
+                removable_keys.append(cache_key)
+
+        for cache_key in removable_keys:
+            del self._entries[cache_key]
+
+    async def flush(self) -> None:
+        """Flush the cache.
+
+        This implementation has no buffered writes, so flush is a no-op.
+        """
+        return None
+
+    async def cache_info(self) -> CacheInfo:
+        """Return summary information about the cache."""
+        return CacheInfo(size=len(self._entries))
+
+
+class InMemoryCacheFactory(CacheFactoryProtocol):
+    """Factory for creating InMemoryCache instances.
+
+    The InMemoryCache class takes no arguments, so this factory simply returns a new
+    instance of InMemoryCache.
+    """
+
+    def __call__(self) -> CacheProtocol:
+        """Create and return a new in-memory cache instance."""
+        return InMemoryCache()

pfmsoft/api_request/cache/metadata_helpers.py

@@ -0,0 +1,55 @@
+"""Helpers for cache-specific response metadata handling.
+
+The primary helper in this module preserves cached-body semantics when a stale
+entry is revalidated with a `304 Not Modified` network response.
+"""
+
+from pfmsoft.api_request.request.models import ResponseMetadata
+
+
+def merge_cached_revalidation_metadata(
+    *,
+    cached: ResponseMetadata,
+    refreshed: ResponseMetadata,
+) -> ResponseMetadata:
+    """Merge a 304 revalidation response into cached response metadata.
+
+    The returned metadata continues to describe the cached body representation,
+    so it preserves cached success/body fields while applying newer header and
+    timing fields from the `304` revalidation response.
+
+    Field precedence:
+            - Preserved from `cached`: `status_code`, `reason_phrase`,
+                `bytes_downloaded`.
+            - Taken from `refreshed`: `url`, `elapsed`, `received_timestamp`.
+            - Headers: merged case-insensitively where refreshed header values
+                overwrite matching cached header names.
+
+    Args:
+            cached: Metadata associated with the currently stored cached body.
+            refreshed: Metadata from a `304 Not Modified` revalidation response.
+
+    Returns:
+            A merged metadata value that still represents a successful cached body.
+    """
+    merged_headers = list(cached.headers)
+    header_indexes = {
+        key.lower(): index for index, (key, _) in enumerate(merged_headers)
+    }
+    for key, value in refreshed.headers:
+        lower_key = key.lower()
+        if lower_key in header_indexes:
+            merged_headers[header_indexes[lower_key]] = (key, value)
+            continue
+        header_indexes[lower_key] = len(merged_headers)
+        merged_headers.append((key, value))
+
+    return ResponseMetadata(
+        status_code=cached.status_code,
+        reason_phrase=cached.reason_phrase,
+        url=refreshed.url,
+        elapsed=refreshed.elapsed,
+        bytes_downloaded=cached.bytes_downloaded,
+        headers=tuple(merged_headers),
+        received_timestamp=refreshed.received_timestamp,
+    )

pfmsoft/api_request/cache/models.py

@@ -0,0 +1,83 @@
+"""Immutable cache model types used by cache implementations.
+
+Time unit conventions:
+    - `expires_at` uses Unix seconds.
+    - `cache_timestamp` and `cache_age` use Unix nanoseconds.
+"""
+
+from dataclasses import dataclass
+from enum import StrEnum
+from uuid import UUID
+
+from whenever import Instant
+
+
+@dataclass(slots=True, kw_only=True, frozen=True)
+class CachedResponse:
+    """Represents one cached HTTP response payload and metadata snapshot.
+
+    Instances are immutable so cache providers can safely return shared values
+    without defensive copies.
+    """
+
+    cache_key: UUID
+    """Unique cache key associated with the stored response."""
+    response_text: str
+    """Serialized response body text."""
+    response_metadata_json: str
+    """JSON-encoded ResponseMetadata document for the cached body."""
+    etag: str | None = None
+    """Cached ETag validator, if present."""
+    last_modified: str | None = None
+    """Cached Last-Modified validator, if present."""
+    expires_at: int | None = None
+    """Expiration instant in Unix seconds, or None when unknown."""
+    cache_timestamp: int
+    """Write/update instant in Unix nanoseconds."""
+
+    @property
+    def is_expired(self) -> bool:
+        """Return True when the cached entry is expired.
+
+        Entries with `expires_at=None` are treated as not expired.
+        """
+        if self.expires_at is None:
+            return False
+        return Instant.now().timestamp() >= self.expires_at
+
+    @property
+    def cache_age(self) -> int:
+        """Return cache entry age in nanoseconds."""
+        return Instant.now().timestamp_nanos() - self.cache_timestamp
+
+
+class CachedResponseStatus(StrEnum):
+    """Categorization for cache lookup outcomes."""
+
+    HIT = "HIT"
+    """A cache entry existed and was used without revalidation."""
+    MISS = "MISS"
+    """No cache entry existed for the requested key."""
+    STALE = "STALE"
+    """A cache entry existed but required revalidation."""
+
+
+class CacheAction(StrEnum):
+    """Lifecycle actions emitted by cache-aware request flows."""
+
+    ADDED_TO_CACHE = "ADDED_TO_CACHE"
+    """A response was written to cache for the first time or as replacement."""
+    CACHED_RESPONSE_USED = "CACHED_RESPONSE_USED"
+    """A previously cached response was returned directly."""
+    CACHE_304_REFRESH_METADATA = "CACHE_304_REFRESH_METADATA"
+    """A stale cache entry was refreshed from a 304 revalidation."""
+    CACHE_304_UPDATE_RESPONSE = "CACHE_304_UPDATE_RESPONSE"
+    """A stale cache entry was replaced by fresh response content."""
+
+
+@dataclass(slots=True, kw_only=True, frozen=True)
+class CacheInfo:
+    """Summary information returned by cache providers."""
+
+    size: int = -1
+    """Number of stored entries, or -1 when unavailable."""

pfmsoft/api_request/cache/protocols.py

@@ -0,0 +1,166 @@
+"""Cache protocols and factory contracts for API requests.
+
+The protocol in this module defines the behavioral contract shared by cache
+implementations such as in-memory and SQLite providers.
+
+Typical usage:
+
+```python
+cache_factory: CacheFactory = ...
+cache = cache_factory()
+async with cache:
+    cached = await cache.get(cache_key)
+    if cached is None:
+        cached = await cache.set(cache_key, text, metadata)
+```
+"""
+
+from collections.abc import Callable
+from types import TracebackType
+from typing import Protocol, Self
+from uuid import UUID
+
+from pfmsoft.api_request.cache.models import CachedResponse, CacheInfo
+from pfmsoft.api_request.request.models import ResponseMetadata
+
+
+class CacheProtocol(Protocol):
+    """Behavioral contract for cache providers used by request execution.
+
+    Implementations are expected to support async context management for
+    lifecycle concerns (for example, opening and closing database connections).
+    """
+
+    async def __aenter__(self) -> Self:
+        """Enter the asynchronous context manager."""
+        ...
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Exit the asynchronous context manager."""
+        ...
+
+    async def get(self, cache_key: UUID) -> CachedResponse | None:
+        """Get a cached response by key.
+
+        Returns `None` when no entry exists.
+        """
+        ...
+
+    async def set(
+        self, cache_key: UUID, text: str, metadata: ResponseMetadata
+    ) -> CachedResponse:
+        """Create or replace a cached response for a key.
+
+        Implementations must treat inputs as immutable and build a new
+        `CachedResponse` from the provided values.
+
+        Contract:
+            - Upsert behavior: create when missing, replace when present.
+            - `cache_timestamp` is set to the current update time in nanoseconds.
+            - `etag` and `last_modified` are derived from `metadata`.
+            - At least one validator (`etag` or `last_modified`) must be present;
+              raise `ValueError` if both are missing.
+
+        Args:
+            cache_key: Cache entry key.
+            text: Response body text to store.
+            metadata: Response metadata used to populate validator/expiry fields.
+
+        Returns:
+            The stored `CachedResponse`.
+
+        Raises:
+            ValueError: If both `metadata.etag` and `metadata.last_modified` are missing.
+        """
+        ...
+
+    async def update_304(
+        self, cache_key: UUID, metadata: ResponseMetadata
+    ) -> CachedResponse:
+        """Refresh an existing cached response from a 304 revalidation.
+
+        This operation updates metadata fields while preserving the existing
+        cached body text and cached-success representation.
+
+        Contract:
+            - Entry must already exist for `cache_key`.
+            - Response text is preserved from the existing entry.
+            - Stored and returned metadata must continue to represent the cached body
+              as a successful response rather than a raw `304 Not Modified`
+              response.
+                        - Metadata-derived fields are refreshed by merging the existing
+                            cached metadata with the revalidation response headers and timing
+                            data.
+            - The merged result is then used to populate `response_metadata_json`,
+              `etag`, `last_modified`, and `expires_at`.
+            - `cache_timestamp` is set to the current update time in nanoseconds.
+            - At least one validator (`etag` or `last_modified`) must be present in
+              `metadata`; raise `ValueError` if both are missing.
+
+        Args:
+            cache_key: Cache entry key.
+            metadata: Fresh metadata returned from a `304 Not Modified`
+                revalidation request. Implementations merge this with the
+                existing cached metadata so the stored representation remains a
+                successful cached response.
+
+        Returns:
+            The updated `CachedResponse`.
+
+        Raises:
+            KeyError: If `cache_key` does not exist.
+            ValueError: If both `metadata.etag` and `metadata.last_modified` are missing.
+        """
+        ...
+
+    async def delete(self, cache_key: UUID) -> None:
+        """Delete a cached response.
+
+        This operation is idempotent: deleting a missing key does not raise.
+        """
+        ...
+
+    async def clear(
+        self, only_expired: bool = False, age_limit: int | None = None
+    ) -> None:
+        """Clear cache entries matching filter criteria.
+
+        Filter behavior:
+            - `only_expired=True`: remove only expired entries.
+                        - `age_limit` set: remove entries whose age is greater than or equal
+                            to the provided nanosecond age threshold.
+            - both set: remove entries that satisfy both criteria.
+            - neither set: remove all entries.
+        """
+        ...
+
+    async def flush(self) -> None:
+        """Flush pending cache writes to durable storage.
+
+        Implementations that do not buffer writes may treat this as a no-op.
+        """
+        ...
+
+    async def cache_info(self) -> CacheInfo:
+        """Get cache information such as size and number of entries."""
+        ...
+
+
+CacheFactory = Callable[[], CacheProtocol]
+
+
+class CacheFactoryProtocol(Protocol):
+    """Callable contract for building `CacheProtocol` instances.
+
+    Factories return a new cache provider instance that can be used by request
+    execution components.
+    """
+
+    def __call__(self) -> CacheProtocol:
+        """Build and return a configured cache instance."""
+        ...

pfmsoft/api_request/cache/sqlite_cache/__init__.py

@@ -0,0 +1,7 @@
+"""SQLite cache backend implementation details.
+
+This package contains:
+        - `sqlite_cache.py`: `CacheProtocol` implementation backed by SQLite.
+        - `connection_helpers.py`: connection/URI/schema bootstrapping helpers.
+        - `query_helpers.py`: SQL CRUD helpers for `CachedResponse` rows.
+"""

pfmsoft/api_request/cache/sqlite_cache/connection_helpers.py

@@ -0,0 +1,126 @@
+"""SQLite connection and schema bootstrap helpers.
+
+These helpers centralize URI construction and consistent connection setup for
+cache backends and tests.
+"""
+
+import logging
+import sqlite3
+from collections.abc import Iterator
+from contextlib import contextmanager
+from importlib.resources import files as resource_files
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_table_def_parent = "pfmsoft.api_request.cache.sqlite_cache"
+_table_def_sql = "table_definitions.sql"
+
+
+def read_only_uri(db_path: str) -> str:
+    """Build a read-only SQLite URI for use with sqlite3.connect(uri=True).
+
+    Args:
+        db_path: Filesystem path to the SQLite database.
+
+    Returns:
+        URI string with mode=ro.
+    """
+    return f"file:{db_path}?mode=ro"
+
+
+def read_write_uri(db_path: str) -> str:
+    """Build a read-write/create SQLite URI for sqlite3.connect(uri=True).
+
+    Args:
+        db_path: Filesystem path to the SQLite database.
+
+    Returns:
+        URI string with mode=rwc.
+    """
+    return f"file:{db_path}?mode=rwc"
+
+
+def create_read_only_connection(db_path: str | Path) -> sqlite3.Connection:
+    """Create a read-only SQLite connection for an existing database.
+
+    The caller is responsible for closing the connection when done.
+
+    Args:
+        db_path: Path to an existing SQLite database file.
+
+    Returns:
+        Open SQLite connection configured with sqlite3.Row row factory.
+
+    Notes:
+        The target database is expected to already contain the required schema.
+        Read-only connections cannot modify schema or persisted rows.
+    """
+    if isinstance(db_path, Path):
+        db_path = str(db_path.resolve())
+    uri = read_only_uri(db_path)
+    connection = sqlite3.connect(uri, uri=True)
+    connection.row_factory = sqlite3.Row
+    return connection
+
+
+def create_read_write_connection(db_path: str | Path) -> sqlite3.Connection:
+    """Create a read-write SQLite connection and ensure the packaged schema exists.
+
+    The caller is responsible for closing the connection when done.
+
+    Args:
+        db_path: Path to the SQLite database file.
+
+    Returns:
+        Open SQLite connection configured with sqlite3.Row row factory.
+
+    Notes:
+        Missing tables and other schema objects defined in the packaged SQL
+        script are created before the connection is returned.
+    """
+    if isinstance(db_path, Path):
+        db_path.parent.mkdir(parents=True, exist_ok=True)
+        db_path = str(db_path.resolve())
+    else:
+        Path(db_path).parent.mkdir(parents=True, exist_ok=True)
+        db_path = str(Path(db_path).resolve())
+    uri = read_write_uri(db_path)
+    connection = sqlite3.connect(uri, uri=True)
+    logger.info(f"Created read-write connection to database at {db_path}")
+    connection.row_factory = sqlite3.Row
+    table_defs = resource_files(_table_def_parent).joinpath(_table_def_sql).read_text()
+    with connection:
+        connection.executescript(table_defs)
+        logger.info("Ensured database schema is created.")
+    return connection
+
+
+@contextmanager
+def db_connection_manager(
+    db_path: str | Path, read_only: bool = True
+) -> Iterator[sqlite3.Connection]:
+    """Yield a SQLite connection and close it automatically on exit.
+
+    Delegates to the read-only or read-write connection factory based on the
+    `read_only` flag.
+
+    Args:
+        db_path: Path to the SQLite database file.
+        read_only: Whether to open the connection in read-only mode.
+
+    Yields:
+        Open SQLite connection configured with sqlite3.Row row factory.
+    """
+    connection: sqlite3.Connection | None = None
+    try:
+        if read_only:
+            logger.info(f"Opening read-only connection to database at {db_path}")
+            connection = create_read_only_connection(db_path)
+        else:
+            logger.info(f"Opening read-write connection to database at {db_path}")
+            connection = create_read_write_connection(db_path)
+        yield connection
+    finally:
+        if connection is not None:
+            connection.close()