pfmsoft-api-request 0.1.3__tar.gz

pfmsoft_api_request-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chad Lowe
+
+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.

pfmsoft_api_request-0.1.3/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: pfmsoft-api-request
+Version: 0.1.3
+Summary: A command line api request tool with caching and rate limiting.
+Author: Chad Lowe
+Author-email: Chad Lowe <pfmsoft.dev@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: aiolimiter>=1.2.1
+Requires-Dist: httpx2>=2.5.0
+Requires-Dist: pfmsoft-eve-snippets>=0.1.4
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pydantic-settings>=2.14.2
+Requires-Dist: typer>=0.26.8
+Requires-Dist: whenever>=0.10.2
+Requires-Python: >=3.14
+Project-URL: Documentation, https://github.com/DonalChilde/pfmsoft-api-request#readme
+Project-URL: Issues, https://github.com/DonalChilde/pfmsoft-api-request/issues
+Project-URL: Source, https://github.com/DonalChilde/pfmsoft-api-request
+Description-Content-Type: text/markdown
+
+# api-request
+
+`api-request` is an API-first Python project for executing batched HTTP requests with:
+
+- async request orchestration
+- optional SQLite-backed caching
+- configurable rate limiting
+- JSON in / JSON out workflows
+
+It includes a simple CLI for running request batches from stdin or files, and a Python API for integrating the same behavior in application code.
+
+## Project Status
+
+- Package manager: `uv`
+- Distribution: source-only for now (no PyPI release yet)
+- Python: `>=3.14`
+
+## Installation
+
+Clone the repository and sync dependencies with `uv`:
+
+```bash
+uv sync
+```
+
+This creates/updates the local `.venv` and installs app + dev dependencies.
+
+## Quick Start (CLI)
+
+Show CLI help:
+
+```bash
+uv run api-request --help
+```
+
+Run a batch from stdin and print plain JSON to stdout:
+
+```bash
+cat requests.json | uv run api-request --from - --to - --plain --indent 2
+```
+
+Run from file and write to file:
+
+```bash
+uv run api-request --from requests.json --to responses.json --overwrite --indent 2
+```
+
+Show version and resolved runtime directories:
+
+```bash
+uv run api-request --version
+```
+
+### Input JSON Shape
+
+The CLI expects a JSON object keyed by request UUID. Each value is a request definition.
+
+Minimal example:
+
+```json
+{
+  "00000000-0000-0000-0000-000000000001": {
+		"url": "https://esi.evetech.net/status/",
+		"method": "GET"
+  }
+}
+```
+
+Supported request fields include:
+
+- `url` (required)
+- `method` (required)
+- `headers` (optional map)
+- `body` (optional)
+- `parameters` (optional query param map)
+- `cache_key` (optional UUID)
+- `rate_key` (optional string)
+
+### Output JSON Shape
+
+The CLI returns a JSON object with:
+
+- `successful`: map of request UUID -> response
+- `failed`: map of request UUID -> failed response
+
+## Python API Usage
+
+```python
+import asyncio
+from uuid import uuid4
+
+from api_request import ApiRequester, Request
+from api_request.cache import InMemoryCache
+from api_request.rate_limit import AiolimiterRateLimiterFactory
+
+
+async def main() -> None:
+    request = Request(
+        request_key=uuid4(),
+        method="GET",
+        url="https://esi.evetech.net/status/",
+        cache_key=uuid4(),
+        rate_key="esi-status",
+    )
+
+    async with ApiRequester(
+        cache_factory=InMemoryCache,
+        rate_limiter_factory=AiolimiterRateLimiterFactory(
+            max_rate=50.0,
+            time_period=60.0,
+        ),
+    ) as requester:
+        responses = await requester.process_requests({request.request_key: request})
+        print(responses)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Configuration
+
+Runtime settings use environment variables with the `API_REQUEST_` prefix.
+
+- `API_REQUEST_APPLICATION_DIRECTORY`: overrides the app directory used for cache and logs.
+
+You can also set this from the CLI with `--application-directory`.
+
+## Development
+
+Common commands:
+
+```bash
+uv sync
+uv run ruff format
+uv run ruff check
+uv run pytest
+```
+
+## Repository Layout
+
+- `src/api_request/`: package source
+- `src/api_request/cli/`: Typer CLI entrypoints
+- `src/api_request/request/`: request orchestration and models
+- `src/api_request/cache/`: cache implementations and protocols
+- `tests/`: test suite
+
+## License
+
+MIT. See `LICENSE`.

pfmsoft_api_request-0.1.3/README.md

@@ -0,0 +1,150 @@
+# api-request
+
+`api-request` is an API-first Python project for executing batched HTTP requests with:
+
+- async request orchestration
+- optional SQLite-backed caching
+- configurable rate limiting
+- JSON in / JSON out workflows
+
+It includes a simple CLI for running request batches from stdin or files, and a Python API for integrating the same behavior in application code.
+
+## Project Status
+
+- Package manager: `uv`
+- Distribution: source-only for now (no PyPI release yet)
+- Python: `>=3.14`
+
+## Installation
+
+Clone the repository and sync dependencies with `uv`:
+
+```bash
+uv sync
+```
+
+This creates/updates the local `.venv` and installs app + dev dependencies.
+
+## Quick Start (CLI)
+
+Show CLI help:
+
+```bash
+uv run api-request --help
+```
+
+Run a batch from stdin and print plain JSON to stdout:
+
+```bash
+cat requests.json | uv run api-request --from - --to - --plain --indent 2
+```
+
+Run from file and write to file:
+
+```bash
+uv run api-request --from requests.json --to responses.json --overwrite --indent 2
+```
+
+Show version and resolved runtime directories:
+
+```bash
+uv run api-request --version
+```
+
+### Input JSON Shape
+
+The CLI expects a JSON object keyed by request UUID. Each value is a request definition.
+
+Minimal example:
+
+```json
+{
+  "00000000-0000-0000-0000-000000000001": {
+		"url": "https://esi.evetech.net/status/",
+		"method": "GET"
+  }
+}
+```
+
+Supported request fields include:
+
+- `url` (required)
+- `method` (required)
+- `headers` (optional map)
+- `body` (optional)
+- `parameters` (optional query param map)
+- `cache_key` (optional UUID)
+- `rate_key` (optional string)
+
+### Output JSON Shape
+
+The CLI returns a JSON object with:
+
+- `successful`: map of request UUID -> response
+- `failed`: map of request UUID -> failed response
+
+## Python API Usage
+
+```python
+import asyncio
+from uuid import uuid4
+
+from api_request import ApiRequester, Request
+from api_request.cache import InMemoryCache
+from api_request.rate_limit import AiolimiterRateLimiterFactory
+
+
+async def main() -> None:
+    request = Request(
+        request_key=uuid4(),
+        method="GET",
+        url="https://esi.evetech.net/status/",
+        cache_key=uuid4(),
+        rate_key="esi-status",
+    )
+
+    async with ApiRequester(
+        cache_factory=InMemoryCache,
+        rate_limiter_factory=AiolimiterRateLimiterFactory(
+            max_rate=50.0,
+            time_period=60.0,
+        ),
+    ) as requester:
+        responses = await requester.process_requests({request.request_key: request})
+        print(responses)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Configuration
+
+Runtime settings use environment variables with the `API_REQUEST_` prefix.
+
+- `API_REQUEST_APPLICATION_DIRECTORY`: overrides the app directory used for cache and logs.
+
+You can also set this from the CLI with `--application-directory`.
+
+## Development
+
+Common commands:
+
+```bash
+uv sync
+uv run ruff format
+uv run ruff check
+uv run pytest
+```
+
+## Repository Layout
+
+- `src/api_request/`: package source
+- `src/api_request/cli/`: Typer CLI entrypoints
+- `src/api_request/request/`: request orchestration and models
+- `src/api_request/cache/`: cache implementations and protocols
+- `tests/`: test suite
+
+## License
+
+MIT. See `LICENSE`.

pfmsoft_api_request-0.1.3/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "pfmsoft-api-request"
+version = "0.1.3"
+description = "A command line api request tool with caching and rate limiting."
+readme = "README.md"
+authors = [{ name = "Chad Lowe", email = "pfmsoft.dev@gmail.com" }]
+requires-python = ">=3.14"
+dependencies = [
+    "aiolimiter>=1.2.1",
+    "httpx2>=2.5.0",
+    "pfmsoft-eve-snippets>=0.1.4",
+    "pydantic>=2.13.4",
+    "pydantic-settings>=2.14.2",
+    "typer>=0.26.8",
+    "whenever>=0.10.2",
+]
+# https://packaging.python.org/en/latest/specifications/license-expression/#specification
+license = "MIT"
+# https://packaging.python.org/en/latest/specifications/pyproject-toml/#license-files
+license-files = ["LICENSE"]
+
+
+[project.scripts]
+# script entry-points
+# COMMAND_NAME = "PATH.TO.ENTRY.MODULE:ENTRY_FUNCTION"
+
+api-request = "pfmsoft.api_request.cli.main_typer:app"
+
+
+[build-system]
+requires = ["uv_build>=0.11.21,<0.12.0"]
+build-backend = "uv_build"
+
+# For a namespaced project
+[tool.uv.build-backend]
+module-name = "pfmsoft.api_request"
+
+# Don't wait for internal package updates.
+[tool.uv.exclude-newer-package]
+pfmsoft-eve-snippets = false
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.21",
+]
+[project.urls]
+Documentation = "https://github.com/DonalChilde/pfmsoft-api-request#readme"
+# Documentation_rtd = "https://esi-link.readthedocs.io"
+Issues = "https://github.com/DonalChilde/pfmsoft-api-request/issues"
+Source = "https://github.com/DonalChilde/pfmsoft-api-request"
+
+[tool.uv]
+exclude-newer = "1 week"
+
+[tool.pytest.ini_options]
+pythonpath = "src"
+log_file = "dev/pytest-logs/tests.log"
+log_file_date_format = "%Y-%m-%dT%H:%M:%S.%f%z"
+log_file_format = "%(asctime)s %(levelname)s:%(funcName)s: %(message)s [in %(pathname)s:%(lineno)d]"
+log_file_level = "INFO"
+
+[tool.coverage.run]
+branch = true
+parallel = true
+
+[tool.ruff.lint]
+select = ["B", "UP", "D", "FIX", "I", "F401"]
+# non-imperative-mood (D401)
+ignore = ["D401", "D101", "D421"]
+# extend-select = ["I"]
+
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+docstring-code-format = true
+docstring-code-line-length = 88

pfmsoft_api_request-0.1.3/src/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-0.1.3/src/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-0.1.3/src/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()