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

pfmsoft/api_request/logging_config.py

@@ -0,0 +1,202 @@
+"""Logging configuration helpers for Eve Auth Manager.
+
+Provides the default dictConfig-based logging setup used by the application,
+including console output and rotating file handlers.
+
+Notes:
+    The logging configuration dictionary is intended to be customized in the
+    handlers and loggers sections if the application needs different output
+    destinations or verbosity.
+"""
+
+import logging
+import logging.config
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+
+def setup_logging(log_dir: Path) -> None:
+    """Configure application logging handlers and formatters.
+
+    Creates the target log directory when needed, then installs the default
+    dictConfig-based logging setup for console and rotating file output.
+
+    Args:
+        log_dir: Directory where log files should be created.
+
+    Notes:
+        The configured root logger writes DEBUG-and-above messages to the info
+        rotating file, WARNING-and-above messages to the warning rotating
+        file, and CRITICAL-and-above messages to the console handler.
+    """
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    # dictConfig replaces root handlers; keep deferred buffers so they can be
+    # flushed after real handlers are installed.
+    root_logger = logging.getLogger()
+    deferred_handlers = [
+        h for h in root_logger.handlers if isinstance(h, DeferredHandler)
+    ]
+
+    log_config: dict[str, Any] = {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "formatters": {
+            "consoleFormatter": {
+                "format": "%(asctime)s | %(name)s | %(levelname)s : %(message)s",
+            },
+            "fileFormatter": {
+                "format": "%(asctime)s | %(name)s | %(levelname)-8s : %(message)s",
+            },
+            "brief": {
+                "datefmt": "%H:%M:%S",
+                "format": "%(levelname)-8s; %(name)s; %(message)s;",
+            },
+            "single-line": {
+                "datefmt": "%H:%M:%S",
+                "format": "%(levelname)-8s; %(asctime)s; %(name)s; %(module)s:%(funcName)s;%(lineno)d: %(message)s",
+            },
+            "multi-process": {
+                "datefmt": "%H:%M:%S",
+                "format": "%(levelname)-8s; [%(process)d]; %(name)s; %(module)s:%(funcName)s;%(lineno)d: %(message)s",
+            },
+            "multi-thread": {
+                "datefmt": "%H:%M:%S",
+                "format": "%(levelname)-8s; %(threadName)s; %(name)s; %(module)s:%(funcName)s;%(lineno)d: %(message)s",
+            },
+            "verbose": {
+                "format": "%(levelname)-8s; [%(process)d]; %(threadName)s; %(name)s; %(module)s:%(funcName)s;%(lineno)d"
+                ": %(message)s"
+            },
+            "multiline": {
+                "format": "Level: %(levelname)s\nTime: %(asctime)s\nProcess: %(process)d\nThread: %(threadName)s\nLogger"
+                ": %(name)s\nPath: %(module)s:%(lineno)d\nFunction :%(funcName)s\nMessage: %(message)s\n"
+            },
+            "mine": {
+                "format": "%(asctime)s | %(levelname)-8s | %(funcName)s | %(message)s | [in %(pathname)s | %(lineno)d]"
+            },
+            "mine-multi": {
+                "format": "%(asctime)s | %(levelname)-8s | %(funcName)s | [in %(pathname)s | %(lineno)d]\n\t %(message)s"
+            },
+        },
+        "handlers": {
+            "file": {
+                "filename": log_dir / "debug.log",
+                "level": "DEBUG",
+                "class": "logging.FileHandler",
+                "formatter": "mine",
+            },
+            "console": {
+                "level": "CRITICAL",
+                "class": "logging.StreamHandler",
+                "formatter": "consoleFormatter",
+            },
+            "rot_file_info": {
+                "class": "logging.handlers.RotatingFileHandler",
+                "formatter": "mine-multi",
+                "level": "INFO",
+                "filename": log_dir / "rotating_info.log",
+                "mode": "a",
+                "encoding": "utf-8",
+                "maxBytes": 10000000,
+                "backupCount": 10,
+            },
+            "rot_file_warn": {
+                "class": "logging.handlers.RotatingFileHandler",
+                "formatter": "mine-multi",
+                "level": "WARNING",
+                "filename": log_dir / "rotating_warn.log",
+                "mode": "a",
+                "encoding": "utf-8",
+                "maxBytes": 500000,
+                "backupCount": 4,
+            },
+        },
+        "loggers": {
+            "": {
+                "handlers": ["rot_file_info", "rot_file_warn", "console"],
+                "level": "DEBUG",
+            },
+        },
+    }
+    logging.config.dictConfig(log_config)
+
+    for deferred in deferred_handlers:
+        if deferred not in root_logger.handlers:
+            root_logger.addHandler(deferred)
+
+
+class DeferredHandler(logging.Handler):
+    """Buffers log records until real handlers are ready, then replays them."""
+
+    def __init__(self, level: int = logging.NOTSET) -> None:
+        """Initialize an in-memory record buffer."""
+        super().__init__(level)
+        self.buffer: list[logging.LogRecord] = []
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Store records until configured handlers are available."""
+        self.buffer.append(record)
+
+    def flush_to(self, handlers: list[logging.Handler]) -> None:
+        """Replay buffered records through the given handlers, then clear."""
+        for record in self.buffer:
+            for handler in handlers:
+                if record.levelno >= handler.level:
+                    handler.handle(record)
+        self.buffer.clear()
+
+
+def init_deferred_handler() -> None:
+    """Initialize a deferred handler for logging.
+
+    This funtion sets up a deferred handler that can be used to buffer log messages in
+    memory before they are flushed to the appropriate handlers.
+
+    This is useful for capturing log messages emitted before the logging configuration
+    is fully set up. The deferred handler will buffer these messages in memory and can
+    be flushed to the appropriate handlers once they are configured.
+
+    DeferredHandler is added to the root logger, and it captures all log messages at
+    DEBUG level and above.
+
+    It must be flushed to the appropriate handlers once they are configured to log the
+    buffered messages.
+    """
+    root_logger = logging.getLogger()
+    if any(isinstance(h, DeferredHandler) for h in root_logger.handlers):
+        return
+    root_logger.setLevel(logging.DEBUG)  # capture everything; filter at handler level
+    deferred = DeferredHandler()
+    root_logger.addHandler(deferred)
+
+
+def flush_deferred_handler() -> None:
+    """Replay buffered records into whatever handlers are currently configured.
+
+    Call this after your real logging setup (dictConfig, basicConfig, manual
+    addHandler calls, etc.) has run. Finds any DeferredHandler on the root
+    logger, replays its buffer into all *other* handlers currently attached,
+    then removes itself.
+
+    Safe to call multiple times or when no DeferredHandler is present — it's
+    a no-op in that case rather than an error.
+    """
+    root_logger = logging.getLogger()
+
+    deferred_handlers = [
+        h for h in root_logger.handlers if isinstance(h, DeferredHandler)
+    ]
+    if not deferred_handlers:
+        return  # nothing to flush, or already finalized
+
+    real_handlers = [
+        h for h in root_logger.handlers if not isinstance(h, DeferredHandler)
+    ]
+
+    for deferred in deferred_handlers:
+        deferred.flush_to(real_handlers)
+        root_logger.removeHandler(deferred)

pfmsoft/api_request/rate_limit/__init__.py

@@ -0,0 +1,24 @@
+"""Rate-limiter implementations used by request orchestration.
+
+Exports:
+                - `AiolimiterRateLimiter`: concrete limiter wrapper around
+                        `aiolimiter.AsyncLimiter`.
+                - `AiolimiterRateLimiterFactory`: dependency-injection factory used by
+                        requester construction.
+
+Typical usage:
+
+```python
+from api_request.rate_limit import AiolimiterRateLimiterFactory
+
+factory = AiolimiterRateLimiterFactory(max_rate=100.0, time_period=60.0)
+limiter = factory()
+
+async with limiter.limit("market/orders"):
+    ...
+```
+"""
+
+from .aio_limiter import AiolimiterRateLimiter, AiolimiterRateLimiterFactory
+
+__all__ = ["AiolimiterRateLimiter", "AiolimiterRateLimiterFactory"]

pfmsoft/api_request/rate_limit/aio_limiter.py

@@ -0,0 +1,89 @@
+"""Rate limiter implementation using aiolimiter.
+
+This module provides a protocol-compatible wrapper around one shared
+`aiolimiter.AsyncLimiter` and a small factory for requester construction.
+"""
+
+from contextlib import AbstractAsyncContextManager
+from dataclasses import dataclass
+
+from aiolimiter import AsyncLimiter
+
+from pfmsoft.api_request.rate_limit.protocols import (
+    RateLimiterFactoryProtocol,
+    RateLimiterProtocol,
+)
+
+
+@dataclass(slots=True)
+class AiolimiterRateLimiter(RateLimiterProtocol):
+    """Shared rate limiter backed by one AsyncLimiter instance.
+
+    This implementation enforces a single global bucket for all operations.
+    The provided `subject` value is currently ignored.
+
+    """
+
+    limiter: AsyncLimiter
+    """The shared AsyncLimiter used by all gated operations."""
+
+    def limit(self, subject: str | None) -> AbstractAsyncContextManager[None]:
+        """Return the shared AsyncLimiter as an async context manager.
+
+        NOTE: `subject` is accepted for protocol compatibility and future
+        extensibility. It is currently ignored.
+
+        Args:
+            subject: Domain input for the gated operation.
+
+        Returns:
+            An async context manager that acquires capacity from the shared limiter.
+        """
+        return self.limiter
+
+
+@dataclass(slots=True, frozen=True)
+class AiolimiterRateLimiterFactory(RateLimiterFactoryProtocol):
+    """Factory that builds shared aiolimiter-backed rate limiters.
+
+    Use one factory per limiter configuration and one produced limiter per
+    requester/task-group that should share budget.
+
+    This factory is designed to be passed into requester constructors that build
+    their shared limiter in `__aenter__`.
+
+    Example:
+        ```python
+        from api_request.rate_limit import AiolimiterRateLimiterFactory
+
+        factory = AiolimiterRateLimiterFactory(max_rate=100.0, time_period=60.0)
+        limiter = factory()
+        async with limiter.limit("esi-status"):
+            ...
+        ```
+    """
+
+    max_rate: float
+    """The maximum acquisitions allowed within `time_period`.
+
+    This should be greater than zero.
+    """
+    time_period: float = 60.0
+    """The limiting window length in seconds.
+
+    This should be greater than zero.
+    """
+
+    def __call__(self) -> AiolimiterRateLimiter:
+        """Build a shared rate limiter instance.
+
+        Returns:
+            A shared rate limiter backed by one configured AsyncLimiter.
+
+        Raises:
+            ValueError: Propagated from `AsyncLimiter` for invalid constructor
+                arguments.
+        """
+        return AiolimiterRateLimiter(
+            limiter=AsyncLimiter(self.max_rate, self.time_period)
+        )

pfmsoft/api_request/rate_limit/protocols.py

@@ -0,0 +1,101 @@
+"""Rate-limiter protocol contracts.
+
+This module defines the protocol shape used to gate outbound request work.
+Concrete implementations live in sibling modules.
+
+Protocol contract:
+        - Each `limit(subject)` call returns an async context manager used to gate
+            one operation.
+        - Implementations may choose how `subject` influences behavior.
+
+The default concrete implementation in this package currently uses one shared
+bucket and ignores `subject`.
+
+Typical usage:
+    limiter = AiolimiterRateLimiterFactory(max_rate=100.0, time_period=60.0)()
+    async with limiter.limit("market/orders"):
+        # perform one rate-limited operation
+        ...
+
+Typed construction with ApiRequester:
+    from uuid import UUID, uuid4
+
+    from api_request import ApiRequester, Request
+    from api_request.rate_limit import AiolimiterRateLimiterFactory
+
+    # Replace with your chosen cache factory.
+    cache_factory = ...
+    rate_limiter_factory = AiolimiterRateLimiterFactory(
+        max_rate=100.0,
+        time_period=60.0,
+    )
+
+    requests: dict[UUID, Request] = {
+        uuid4(): Request(
+            request_key=uuid4(),
+            url="https://esi.evetech.net/latest/status/",
+            method="GET",
+            rate_key="public-status",
+        )
+    }
+
+
+    async def run() -> None:
+        async with ApiRequester(
+            cache_factory=cache_factory,
+            rate_limiter_factory=rate_limiter_factory,
+        ) as requester:
+            await requester.process_requests(requests)
+"""
+
+from contextlib import AbstractAsyncContextManager
+from typing import Protocol
+
+
+class RateLimiterProtocol(Protocol):
+    """Protocol for a rate limiter that gates async work.
+
+    Implementations may produce one-shot limiters for each operation or may
+    return a shared limiter context that gates all operations.
+
+    The protocol does not require any grouping strategy. Implementations may
+    ignore `subject`, or they may use it to select or derive limiter behavior.
+    """
+
+    def limit(self, subject: str | None) -> AbstractAsyncContextManager[None]:
+        """Create an async gate for one operation.
+
+        Depending on implementation, `subject` may influence behavior. For
+        example, a limiter might group requests by endpoint family, tenant, or
+        priority class.
+
+        Examples:
+            async with rate_limiter.limit(subject):
+                # performs the operation that is subject to rate limiting, after the
+                # gate is acquired.
+
+        Args:
+            subject: Domain input that may influence limiter behavior. Prefer a
+                stable, hashable value that represents the grouping intent.
+
+        Returns:
+            An async context manager that acquires limiter capacity.
+
+        Notes:
+            The contract does not require distinct limiter instances per call.
+            Returning a shared context manager object is valid.
+        """
+        ...
+
+
+class RateLimiterFactoryProtocol(Protocol):
+    """Protocol for callables that build shared rate-limiter instances.
+
+    This protocol is used to create configured rate limiters for use in
+    requesters. One produced limiter instance is typically reused by one
+    requester/task-group so concurrent work coordinates against shared budget.
+    """
+
+    def __call__(self) -> RateLimiterProtocol:
+        """Build and return a configured rate-limiter instance."""
+        ...

pfmsoft/api_request/request/__init__.py

@@ -0,0 +1,11 @@
+"""Request orchestration package.
+
+This package contains:
+        - Public request/response data models.
+        - Internal intermediate models used by the orchestration pipeline.
+        - The requester implementation and protocol contract.
+
+Most callers should import public request types from `api_request` package
+root exports (`Request`, `Response`, `ResponseMetadata`, `Source`) and use
+`ApiRequester` as an async context manager.
+"""