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

pfmsoft/api_request/cli/request/request.py

@@ -0,0 +1,222 @@
+"""Command-line interface for making API requests."""
+
+import asyncio
+import logging
+from dataclasses import asdict
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.json import JSON
+
+from pfmsoft.api_request import ApiRequester, __app_name__, __version__
+from pfmsoft.api_request.cache import SqliteCacheFactory
+from pfmsoft.api_request.cli.helpers import (
+    get_api_request_settings_from_context,
+    get_stdin,
+)
+from pfmsoft.api_request.helpers.save_text_file import save_text_file
+from pfmsoft.api_request.logging_config import setup_logging
+from pfmsoft.api_request.rate_limit.aio_limiter import AiolimiterRateLimiterFactory
+from pfmsoft.api_request.request.models import (
+    Requests,
+    RequestsRoot,
+    Responses,
+    ResponsesRoot,
+)
+
+logger = logging.getLogger(__name__)
+
+app = typer.Typer(
+    no_args_is_help=True,
+    help="Commands for executing JSON-defined API request batches.",
+)
+
+
+@app.command(help="Make an API request.")
+def request(
+    ctx: Annotated[typer.Context, typer.Option(hidden=True)],
+    file_in: Annotated[
+        Path,
+        typer.Option(
+            "--from",
+            help="Input JSON file path. Use '-' (default) to read stdin.",
+            allow_dash=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+        ),
+    ] = Path("-"),
+    file_out: Annotated[
+        Path,
+        typer.Option(
+            "--to",
+            help="Output JSON file path. Use '-' (default) to write stdout.",
+            allow_dash=True,
+            file_okay=True,
+            dir_okay=False,
+            writable=True,
+        ),
+    ] = Path("-"),
+    app_dir: Annotated[
+        Path | None,
+        typer.Option(
+            "--app-dir",
+            help="Application directory override for cache/log/settings paths.",
+            file_okay=False,
+            dir_okay=True,
+            writable=True,
+        ),
+    ]
+    | None = None,
+    max_rate: Annotated[
+        float,
+        typer.Option(
+            "--max-rate",
+            help="Rate limiter max acquisitions per time window.",
+        ),
+    ] = 50.0,
+    time_period: Annotated[
+        float,
+        typer.Option(
+            "--time-period",
+            help="Rate limiter window length in seconds.",
+        ),
+    ] = 60.0,
+    forced_fail_status_codes: Annotated[
+        list[int] | None,
+        typer.Option(
+            "--code",
+            help="HTTP status codes that should be treated as batch request failures.",
+        ),
+    ] = None,
+    plain: Annotated[
+        bool,
+        typer.Option(
+            "--plain",
+            help="Write plain JSON to stdout instead of Rich formatted output.",
+        ),
+    ] = False,
+    overwrite: Annotated[
+        bool,
+        typer.Option(
+            "--overwrite",
+            help="Overwrite existing output file when --to is a file path.",
+        ),
+    ] = False,
+    indent: Annotated[
+        int | None,
+        typer.Option(
+            "--indent",
+            help="Indent width for output JSON (compact when omitted).",
+        ),
+    ] = None,
+    quiet: Annotated[
+        bool,
+        typer.Option(
+            "--quiet",
+            help="Suppress non-essential CLI messages.",
+        ),
+    ] = False,
+):
+    """Execute a batch of API requests from JSON input.
+
+    Input format:
+        A JSON object keyed by request UUID. Each value must match the
+        `Request` model shape.
+
+    Output format:
+        A JSON object matching the `Responses` model with `successful` and
+        `failed` maps keyed by the same request UUIDs.
+
+    Notes:
+        - `--from -` reads input JSON from stdin.
+        - `--to -` writes output to stdout.
+        - Use `--plain` for plain stdout JSON when writing to stdout.
+        - Use `--code` to treat specific HTTP status codes as batch request failures.
+          Any requests that have not made it to the network yet will fail if any of the
+          specified codes are present in a response.
+
+    UUID generation quick reference:
+        Request maps are keyed by UUID strings. Generate UUID values with one
+        of the commands below.
+
+        Shell:
+            ```bash
+            uuidgen
+            ```
+
+        Python:
+            ```bash
+            python -c "import uuid; print(uuid.uuid4())"
+            ```
+
+            ```bash
+            python3 -c "import uuid; print(uuid.uuid4())"
+            ```
+    """
+    if quiet:
+        messenger = Console(stderr=True, quiet=True)
+    else:
+        messenger = Console(stderr=True)
+    settings = get_api_request_settings_from_context(ctx)
+    if app_dir:
+        settings.application_directory = app_dir
+    setup_logging(log_dir=settings.logging_directory)
+    logger.info(
+        f"Starting {__app_name__} v{__version__} with settings: {asdict(settings)!r}"
+    )
+
+    input_data = get_stdin() if file_in == Path("-") else file_in.read_text()
+    requests = RequestsRoot.model_validate_json(input_data).root
+    if not requests:
+        messenger.print(
+            "[bold red]Error: No requests found in the input file.[/bold red]"
+        )
+        raise typer.Exit(code=1)
+    force_codes: set[int] = (
+        set(forced_fail_status_codes) if forced_fail_status_codes else set()
+    )
+
+    async def run_requests(
+        requests_to_run: Requests, force_fail_codes: set[int]
+    ) -> Responses:
+        cache_factory = SqliteCacheFactory(settings.web_cache_path)
+        rate_limiter_factory = AiolimiterRateLimiterFactory(
+            max_rate=max_rate, time_period=time_period
+        )
+
+        async with ApiRequester(
+            cache_factory=cache_factory,
+            rate_limiter_factory=rate_limiter_factory,
+            force_fail_on=force_fail_codes,
+        ) as requester:
+            responses = await requester.process_requests(requests_to_run)
+            return responses
+
+    responses = asyncio.run(run_requests(requests, force_codes))
+    if file_out == Path("-"):
+        if plain:
+            print(ResponsesRoot(root=responses).model_dump_json(indent=indent))
+        else:
+            messenger.print(
+                JSON(ResponsesRoot(root=responses).model_dump_json(indent=indent))
+            )
+    else:
+        output_path = save_text_file(
+            text=ResponsesRoot(root=responses).model_dump_json(indent=indent),
+            output_directory=file_out.parent,
+            file_name=file_out.name,
+            overwrite=overwrite,
+        )
+        messenger.print(f"[bold green]Responses saved to {output_path}[/bold green]")
+
+
+_example_request_status = {
+    "request_key": "293c20f6-7356-4787-9fb9-3833ed9a4956",
+    "method": "get",
+    "url": "https://esi.evetech.net/status/",
+    "cache_key": "af7c3da6-355b-4ece-abf3-b79ce625ea37",
+    "rate_key": "status",
+}

pfmsoft/api_request/cli/request/validate.py

@@ -0,0 +1,11 @@
+"""Validate an api request."""
+
+import typer
+
+app = typer.Typer(no_args_is_help=True)
+
+
+@app.command()
+def validate(ctx: typer.Context) -> None:
+    """Validate an api request."""
+    typer.echo("Validation Placeholder...")

pfmsoft/api_request/helpers/http_session_factory.py

@@ -0,0 +1,80 @@
+"""Create preconfigured sync and async HTTP clients for Eve Auth Manager."""
+
+from collections.abc import AsyncIterator, Iterator
+from contextlib import asynccontextmanager, contextmanager
+
+from httpx2 import AsyncClient, Client
+
+from pfmsoft.api_request.settings import USER_AGENT
+
+
+def config_http_client(user_agent: str = USER_AGENT) -> Client:
+    """Create an HTTP client configured with the project User-Agent header.
+
+    Args:
+        user_agent: User-Agent header value to send with requests. Defaults to
+            the project setting.
+
+    Returns:
+        Configured synchronous HTTP client.
+
+    Note:
+        The caller owns the returned client and must close it when finished.
+    """
+    return Client(headers={"User-Agent": user_agent})
+
+
+async def config_async_http_client(user_agent: str = USER_AGENT) -> AsyncClient:
+    """Create an async HTTP client configured with the project User-Agent header.
+
+    Args:
+        user_agent: User-Agent header value to send with requests. Defaults to
+            the project setting.
+
+    Returns:
+        Configured asynchronous HTTP client.
+
+    Note:
+        The caller owns the returned client and must close it when finished.
+    """
+    return AsyncClient(headers={"User-Agent": user_agent})
+
+
+@contextmanager
+def client_manager(user_agent: str = USER_AGENT) -> Iterator[Client]:
+    """Yield a configured HTTP client and close it automatically on exit.
+
+    Args:
+        user_agent: User-Agent header value to send with requests.
+
+    Yields:
+        Configured synchronous HTTP client.
+    """
+    client: Client | None = None
+    try:
+        client = config_http_client(user_agent)
+        yield client
+    finally:
+        if client is not None:
+            client.close()
+
+
+@asynccontextmanager
+async def async_client_manager(
+    user_agent: str = USER_AGENT,
+) -> AsyncIterator[AsyncClient]:
+    """Yield a configured async HTTP client and close it automatically on exit.
+
+    Args:
+        user_agent: User-Agent header value to send with requests.
+
+    Yields:
+        Configured asynchronous HTTP client.
+    """
+    client: AsyncClient | None = None
+    try:
+        client = await config_async_http_client(user_agent)
+        yield client
+    finally:
+        if client is not None:
+            await client.aclose()

pfmsoft/api_request/helpers/json_io.py

@@ -0,0 +1,256 @@
+"""Helpers for loading, dumping, and streaming JSON and JSONL data with pydantic_core."""
+
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any, TextIO
+
+from pydantic_core import from_json, to_json
+
+
+def json_load_path(filepath: Path) -> Any:
+    """Load a JSON file into a Python object.
+
+    Args:
+        filepath: Path to a UTF-8 encoded JSON file.
+
+    Returns:
+        Parsed Python object produced by pydantic_core.from_json().
+    """
+    return from_json(filepath.read_text(encoding="utf-8"))
+
+
+def json_loads(json_string: str | bytes) -> Any:
+    """Parse a JSON text or byte payload into a Python object.
+
+    Args:
+        json_string: JSON document encoded as text or bytes.
+
+    Returns:
+        Parsed Python object produced by pydantic_core.from_json().
+    """
+    return from_json(json_string)
+
+
+def json_dumps(
+    obj: Any, indent: int | None = None, encoding: str = "utf-8", **kwargs: Any
+) -> str:
+    """Serialize a Python object to JSON text.
+
+    Args:
+        obj: Python object to serialize.
+        indent: Optional indentation level passed to pydantic_core.to_json().
+        encoding: Text encoding used to decode the serialized JSON bytes.
+        **kwargs: Additional keyword arguments forwarded to
+            pydantic_core.to_json().
+
+    Returns:
+        JSON document as a string.
+    """
+    return to_json(obj, indent=indent, **kwargs).decode(encoding)
+
+
+def json_dump_bytes(obj: Any, indent: int | None = None, **kwargs: Any) -> bytes:
+    """Serialize a Python object to JSON bytes.
+
+    Args:
+        obj: Python object to serialize.
+        indent: Optional indentation level passed to pydantic_core.to_json().
+        **kwargs: Additional keyword arguments forwarded to
+            pydantic_core.to_json().
+
+    Returns:
+        JSON document as bytes.
+    """
+    return to_json(obj, indent=indent, **kwargs)
+
+
+def json_dumps_path(
+    obj: Any,
+    *,
+    filepath: Path,
+    overwrite: bool = False,
+    encoding: str = "utf-8",
+    indent: int | None = None,
+    **kwargs: Any,
+) -> int:
+    """Dump a Python object to a JSON file.
+
+    Uses pydantic_core.to_json() to serialize the object and writes a trailing
+    newline after the JSON document.
+
+    Args:
+        obj: The Python object to dump.
+        filepath: The path to the JSON file.
+        overwrite: Whether to overwrite the file if it exists.
+        encoding: The encoding to use when writing the file.
+        indent: The indentation level for the JSON file.
+        **kwargs: Additional keyword arguments passed to `json_dumps`.
+
+    Returns:
+        The number of characters written to the file, including the trailing
+        newline.
+
+    Raises:
+        FileExistsError: If the file already exists and `overwrite` is False.
+    """
+    filepath.parent.mkdir(parents=True, exist_ok=True)
+    if overwrite:
+        mode = "w"
+    else:
+        mode = "x"
+    with filepath.open(mode, encoding=encoding) as f:
+        counter = 0
+        counter += f.write(json_dumps(obj, indent=indent, **kwargs))
+        counter += f.write("\n")
+        return counter
+
+
+def jsonl_loads(jsonl_string: str) -> Iterator[Any]:
+    """Yield Python objects parsed lazily from non-empty JSONL text lines."""
+    for line in jsonl_string.splitlines():
+        if line.strip():
+            yield from_json(line)
+
+
+def jsonl_loads_indexed(jsonl_string: str) -> Iterator[tuple[int, Any]]:
+    """Yield line-number and object pairs from non-empty JSONL text lines.
+
+    Line numbers correspond to the original input line positions, including
+    blank lines.
+    """
+    for line_number, line in enumerate(jsonl_string.splitlines(), start=1):
+        if line.strip():
+            yield line_number, from_json(line)
+
+
+def jsonl_load_bytes(jsonl_bytes: bytes) -> Iterator[Any]:
+    """Yield Python objects parsed lazily from non-empty JSONL byte lines."""
+    for line in jsonl_bytes.splitlines():
+        if line.strip():
+            yield from_json(line)
+
+
+def jsonl_load_bytes_indexed(jsonl_bytes: bytes) -> Iterator[tuple[int, Any]]:
+    """Yield line-number and object pairs from non-empty JSONL byte lines.
+
+    Line numbers correspond to the original input line positions, including
+    blank lines.
+    """
+    for line_number, line in enumerate(jsonl_bytes.splitlines(), start=1):
+        if line.strip():
+            yield line_number, from_json(line)
+
+
+def jsonl_load_path(filepath: Path) -> Iterator[Any]:
+    """Yield Python objects parsed lazily from non-empty lines in a JSONL file."""
+    with filepath.open("r", encoding="utf-8") as f:
+        for line in f:
+            if line.strip():
+                yield from_json(line)
+
+
+def jsonl_load_path_indexed(filepath: Path) -> Iterator[tuple[int, Any]]:
+    """Yield line-number and object pairs parsed from a JSONL file.
+
+    Line numbers correspond to the original file line positions, including
+    blank lines.
+    """
+    with filepath.open("r", encoding="utf-8") as f:
+        for line_number, line in enumerate(f, start=1):
+            if line.strip():
+                yield line_number, from_json(line)
+
+
+def jsonl_dump_path(
+    objs: Iterator[Any],
+    *,
+    filepath: Path,
+    encoding: str = "utf-8",
+    overwrite: bool = False,
+    append: bool = False,
+    **kwargs: Any,
+) -> int:
+    """Write JSONL output from an iterator of Python objects.
+
+    Serializes one object per line without materializing the full output in
+    memory.
+
+    Args:
+        objs: Iterator of Python objects to serialize as JSONL.
+        filepath: The path to the JSONL file.
+        encoding: The encoding to use when writing the file.
+        overwrite: Whether to overwrite the file if it exists.
+        append: Whether to append to the file if it exists.
+        **kwargs: Additional keyword arguments passed to `json_dumps`.
+
+    Returns:
+        Number of characters written to the file, including newline
+        separators.
+
+    Raises:
+        ValueError: If `indent` is provided or if `overwrite` and `append` are
+            both True.
+        FileExistsError: If the file already exists and neither overwrite nor
+            append permits writing.
+    """
+    if "indent" in kwargs:
+        raise ValueError("indent is not supported for JSONL files.")
+    filepath.parent.mkdir(parents=True, exist_ok=True)
+    if overwrite and append:
+        raise ValueError("overwrite and append are mutually exclusive.")
+    if append:
+        mode = "a"
+    elif overwrite:
+        mode = "w"
+    else:
+        mode = "x"
+
+    def write_objs(f: TextIO) -> int:
+        counter = 0
+        for obj in objs:
+            counter += f.write(json_dumps(obj, **kwargs))
+            counter += f.write("\n")
+        return counter
+
+    with filepath.open(mode, encoding=encoding) as f:
+        return write_objs(f)
+
+
+def jsonl_dumps(objs: Iterator[Any], encoding: str = "utf-8", **kwargs: Any) -> str:
+    """Serialize an iterator of objects to a JSONL string.
+
+    Args:
+        objs: Iterator of Python objects to serialize as JSONL.
+        encoding: Text encoding used when converting each JSON document.
+        **kwargs: Additional keyword arguments forwarded to json_dumps().
+
+    Returns:
+        JSONL document with one serialized object per line.
+
+    Raises:
+        ValueError: If `indent` is provided, because JSONL output must remain
+            one JSON value per line.
+    """
+    if "indent" in kwargs:
+        raise ValueError("indent is not supported for JSONL files.")
+    return "\n".join(json_dumps(obj, encoding=encoding, **kwargs) for obj in objs)
+
+
+def jsonl_dump_bytes(objs: Iterator[Any], **kwargs: Any) -> bytes:
+    """Serialize an iterator of objects to JSONL bytes.
+
+    Args:
+        objs: Iterator of Python objects to serialize as JSONL.
+        **kwargs: Additional keyword arguments forwarded to json_dump_bytes().
+
+    Returns:
+        JSONL document as bytes with one serialized object per line.
+
+    Raises:
+        ValueError: If `indent` is provided, because JSONL output must remain
+            one JSON value per line.
+    """
+    if "indent" in kwargs:
+        raise ValueError("indent is not supported for JSONL files.")
+    jsonl_bytes = b"\n".join(json_dump_bytes(obj, **kwargs) for obj in objs)
+    return jsonl_bytes

pfmsoft/api_request/helpers/save_text_file.py

@@ -0,0 +1,43 @@
+"""Write text files while creating parent directories and enforcing overwrite policy."""
+
+from pathlib import Path
+
+
+def save_text_file(
+    *,
+    text: str,
+    output_directory: Path,
+    file_name: str,
+    overwrite: bool = False,
+    encoding: str = "utf-8",
+) -> Path:
+    """Write text to a file in the target output directory.
+
+    Args:
+        text: Text content to write.
+        output_directory: Directory that should contain the output file.
+        file_name: Name of the output file to create.
+        overwrite: If true, replace an existing file. If false, raise an error
+            when the target file already exists.
+        encoding: Text encoding to use when writing the file.
+
+    Returns:
+        Path object for the written file.
+
+    Raises:
+        FileExistsError: If the target file exists and overwrite is false.
+        OSError: If the parent directory cannot be created or the file cannot
+            be written.
+
+    Notes:
+        Parent directories are created automatically when missing.
+    """
+    output_file = output_directory / file_name
+    output_file.parent.mkdir(parents=True, exist_ok=True)
+    if overwrite:
+        mode = "w"
+    else:
+        mode = "x"
+    with output_file.open(mode, encoding=encoding) as f:
+        f.write(text)
+    return output_file

pfmsoft/api_request/helpers/whenever/__init__.py

@@ -0,0 +1,4 @@
+"""Helper functions for working with the whenever library.
+
+https://github.com/ariebovenberg/whenever
+"""

pfmsoft/api_request/helpers/whenever/instant_helpers.py

@@ -0,0 +1,41 @@
+"""Convenience helpers for current-time and relative-time calculations with whenever.Instant."""
+
+from pfmsoft.api_request.helpers.whenever import Instant
+
+
+def timestamp() -> int:
+    """Return the current Unix timestamp in whole seconds."""
+    return Instant.now().timestamp()
+
+
+def timestamp_nanos() -> int:
+    """Return the current Unix timestamp in nanoseconds."""
+    return Instant.now().timestamp_nanos()
+
+
+def from_now(timestamp: int) -> int:
+    """Compute the signed number of seconds until a target Unix timestamp.
+
+    Args:
+        timestamp: Target Unix timestamp in whole seconds.
+
+    Returns:
+        Signed number of seconds between now and the target timestamp.
+        Negative values indicate the target time is already in the past.
+    """
+    now = Instant.now().timestamp()
+    return timestamp - now
+
+
+def from_now_nanos(timestamp_nanos: int) -> int:
+    """Compute the signed number of nanoseconds until a target Unix timestamp.
+
+    Args:
+        timestamp_nanos: Target Unix timestamp in nanoseconds.
+
+    Returns:
+        Signed number of nanoseconds between now and the target timestamp.
+        Negative values indicate the target time is already in the past.
+    """
+    now_nanos = Instant.now().timestamp_nanos()
+    return timestamp_nanos - now_nanos