peyk.transport

Transport layer: session, errors, retry.

Public re-exports so callers can do from peyk.transport import Session, ... instead of reaching into submodules.

class peyk.transport.Session(*, limit: int = DEFAULT_LIMIT, limit_per_host: int = DEFAULT_LIMIT_PER_HOST, keepalive_timeout: float = DEFAULT_KEEPALIVE_TIMEOUT, ttl_dns_cache: int = DEFAULT_TTL_DNS_CACHE, logger: TransportLogger | None = None)

Bases: object

Wraps one reused aiohttp.ClientSession backed by a tuned connector.

async close() → None

Performs the close operation for the transport client.

property connector: BaseConnector

The underlying connector, exposed so reuse can be asserted in tests.

Returns:

The operation result (aiohttp.BaseConnector).

async request(method: str, url: str, *, params: Mapping[str, object] | None = None, json_body: object | None = None, data: object | None = None, files: Mapping[str, FilePayload] | None = None, timeout: float | None = None) → TransportResponse

Performs the request operation for the transport client.

Parameters:

• method – Value used by this operation.

• url – Target URL.

• params – Value used by this operation.

• json_body – Value used by this operation.

• data – Value used by this operation.

• files – Value used by this operation.

• timeout – Maximum time to wait for the operation.

Returns:

Result produced by the transport operation.

class peyk.transport.TransportResponse(status: int, json: object | None, body: bytes, headers: Mapping[str, str])

Bases: object

The result of a successful (2xx) transport-level request.

Variables:

• status (int) – HTTP status code.

• json (object | None) – Parsed body via orjson, if the response’s Content-Type indicated JSON and the body parsed successfully. None otherwise.

• body (bytes) – Raw response body bytes, always populated.

• headers (Mapping[str, str]) – Response headers as a plain mapping.

status: int

json: object | None

body: bytes

headers: Mapping[str, str]

exception peyk.transport.TransportError

Bases: Exception

Base class for all errors raised by the transport layer.

exception peyk.transport.NetworkError

Bases: TransportError

Raised when the underlying connection fails.

Covers DNS failure, connection refused, connection reset, and other transport-level connectivity problems that are not an HTTP response.

exception peyk.transport.TimeoutError_

Bases: TransportError

Raised when a request does not complete within its configured timeout.

Named with a trailing underscore to avoid shadowing the builtin TimeoutError.

exception peyk.transport.RateLimitedError(message: str, *, retry_after_seconds: float | None = None)

Bases: TransportError

Raised when the server responds with HTTP 429 (Too Many Requests).

Variables:

retry_after_seconds – The value of the response’s Retry-After header, parsed to seconds, if present and parseable. None if the header was absent or not parseable as a plain number of seconds.

exception peyk.transport.HTTPStatusError(message: str, *, status_code: int, body: bytes)

Bases: TransportError

Raised for any non-2xx HTTP response other than 429.

Variables:

• status_code – The HTTP status code returned by the server.

• body – The raw response body bytes (may be empty).

class peyk.transport.RetryPolicy(max_attempts: int = 3, base_backoff_seconds: float = 0.5)

Bases: object

Configuration for run_with_retry.

Variables:

• max_attempts (int) – Total number of attempts (including the first), not the number of retries.

• base_backoff_seconds (float) – Base delay for exponential backoff between attempts, used when the raised error doesn’t carry its own hint (e.g. RateLimitedError.retry_after_seconds).

base_backoff_seconds: float = 0.5

max_attempts: int = 3

async peyk.transport.run_with_retry(operation: Callable[[], Awaitable[T]], policy: RetryPolicy, retryable: Tuple[Type[TransportError], ...] = DEFAULT_RETRYABLE, logger: TransportLogger | None = None) → T

Performs the run with retry operation for the transport client.

Parameters:

• operation – Value used by this operation.

• policy – Value used by this operation.

• retryable – Value used by this operation.

• logger – Value used by this operation.

Returns:

Result produced by the transport operation.

class peyk.transport.FilePayload(content: bytes | IO[bytes], filename: str, content_type: str = 'application/octet-stream')

Bases: object

A single file part for a multipart request.

Variables:

• content (bytes | IO[bytes]) – Raw bytes, or a file-like/stream object opened in binary mode. Streams are not read here — they’re passed through to aiohttp’s multipart writer, which reads them in chunks while sending.

• filename (str) – Filename reported in the part’s Content-Disposition.

• content_type (str) – The part’s Content-Type. Defaults to application/octet-stream.

content_type: str = 'application/octet-stream'

content: bytes | IO[bytes]

filename: str

peyk.transport.build_multipart_body(fields: Mapping[str, str] | None = None, files: Mapping[str, FilePayload] | None = None) → FormData

Performs the build multipart body operation for the transport client.

Parameters:

• fields – Value used by this operation.

• files – Value used by this operation.

Returns:

Result produced by the transport operation.

class peyk.transport.TransportLogger(*args, **kwargs)

Bases: Protocol

Logging hook used by the transport layer.

The protocol separates request, event, retry, and final-failure logging.

log_event(event: object) → None

Performs the log event operation for the transport client.

Parameters:

event – Value used by this operation.

log_failure(exception: Exception) → None

Performs the log failure operation for the transport client.

Parameters:

exception – Value used by this operation.

log_request(method: str, url: str) → None

Performs the log request operation for the transport client.

Parameters:

• method – Value used by this operation.

• url – Target URL.

log_retry(attempt: int, exception: Exception) → None

Performs the log retry operation for the transport client.

Parameters:

• attempt – Value used by this operation.

• exception – Value used by this operation.

class peyk.transport.StdlibTransportLogger(logger: Logger | None = None)

Bases: object

Default TransportLogger, backed by logging.getLogger(“peyk.transport”).

Requests log at DEBUG (high-volume, opt-in visibility), retries at WARNING (worth noticing but expected/handled), failures at ERROR (nothing left to retry — the caller now has to deal with it).

log_event(event: object) → None

Performs the log event operation for the transport client.

Parameters:

event – Value used by this operation.

log_failure(exception: Exception) → None

Performs the log failure operation for the transport client.

Parameters:

exception – Value used by this operation.

log_request(method: str, url: str) → None

Performs the log request operation for the transport client.

Parameters:

• method – Value used by this operation.

• url – Target URL.

log_retry(attempt: int, exception: Exception) → None

Performs the log retry operation for the transport client.

Parameters:

• attempt – Value used by this operation.

• exception – Value used by this operation.

peyk.transport.get_default_logger() → TransportLogger

A shared, lazily-created StdlibTransportLogger instance.

Used by Session and run_with_retry when no TransportLogger is passed explicitly, so A1’s existing call sites (which never pass a logger) keep working unmodified.

Returns:

The operation result (TransportLogger).

Modules

errors	Transport-level exceptions.
logging_hook	Minimal transport logging hook.
multipart	Helpers for building multipart/form-data bodies.
retry	Generic retry wrapper for transport operations.
session	A single, reused aiohttp.ClientSession behind a generic request() call.