Client

The client module provides HTTP functionality with caching, rate limiting, and retry logic.

NumistaApiClient

class numistalib.client.NumistaApiClient(client: NumistaClientSync | NumistaClientAsync)

Bases: object

Unified client factory for both sync and async HTTP operations.

Wraps NumistaClientSync/Async and provides a convenient interface. Uses dependency injection pattern for services.

__init__(client: NumistaClientSync | NumistaClientAsync) → None

Initialize with a concrete client instance.

Parameters:

client (NumistaClientSync | NumistaClientAsync) – Pre-configured sync or async HTTP client

property is_async: bool

Check if this is an async client.

property raw_client: NumistaClientSync | NumistaClientAsync

Get the underlying raw client.

NumistaResponse

class numistalib.client.NumistaResponse(status_code: int, *, headers: Headers | Mapping[str, str] | Mapping[bytes, bytes] | Sequence[Tuple[str, str]] | Sequence[Tuple[bytes, bytes]] | None = None, content: str | bytes | Iterable[bytes] | AsyncIterable[bytes] | None = None, text: str | None = None, html: str | None = None, json: Any = None, stream: SyncByteStream | AsyncByteStream | None = None, request: Request | None = None, extensions: Mapping[str, Any] | None = None, history: list[Response] | None = None, default_encoding: str | Callable[[bytes], str] = 'utf-8')

Bases: Response

Custom HTTP response to expose caching info.

Response wrapper that exposes cache status.

data

The response payload (dict or list)

cached

Boolean indicating if response was served from cache

cached_indicator

String emoji: “💾” for cached, “🌐” for fresh

property cached: bool

Determine if response was served from cache.

property cached_indicator: str

Get cache indicator based on response.

Usage Example

Basic usage:

from numistalib.client import NumistaApiClient
from numistalib.config import Settings

settings = Settings()

with NumistaApiClient(settings) as client:
    response = client.get("/types/95420")
    print(f"Cached: {response.cached}")
    print(f"Data: {response.data}")

Async usage:

import asyncio
from numistalib.client import NumistaApiClient
from numistalib.config import Settings

async def main():
    settings = Settings()

    async with NumistaApiClient(settings) as client:
        response = await client.get_async("/types/95420")
        print(f"Data: {response.data}")

asyncio.run(main())