common_http.schemas.results

HTTP response evidence and operation reports, independent of a transport engine.

These frozen envelopes are built by operating code. Construction checks types and cross-field consistency without parsing bodies, copying decoded trees, or performing I/O. Payloads remain ordinary Python values owned by the caller.

Routine inspection never expands requests, headers, payloads, execution keys, or exception messages. Explicit attribute access (and dataclasses.asdict) is NOT a safe logging/export mechanism: actual response data can contain secrets.

Classes

`HttpBatchResult`

Input-aligned HTTP reports attached to the original batch execution.

Every results[i].execution must be execution.results[i] by identity. HTTP summaries use HttpResult.ok: an executed 404 is not an HTTP success. No batch key, retry count, or duration is re-declared here.

`init`

def __init__(*, results: tuple[HttpResult, ...], execution: BatchResult) -> None

Fields and properties declared here; inherited members belong to the bases above.

`all_ok`

Read-only property.

all_ok: bool

`execution`

execution: BatchResult = field(repr=False)

`ok_count`

Read-only property.

ok_count: int

`results`

results: tuple[HttpResult, ...] = field(repr=False)

`total`

Read-only property.

total: int

`describe`

def describe() -> str

`failures`

def failures() -> tuple[HttpResult, ...]

Failures in input order; use results for full index alignment.

`HttpResponse`

Bases: HttpResponseHead

Buffered evidence, possibly incomplete when receiving the body failed.

content is the retained body after HTTP content decoding, not compressed wire traffic. body_complete records end-of-body, NOT application coverage (a complete HTTP 206 still contains a range, not the entire resource).

decoded_as describes a successful payload interpretation. None means it did not finish; ‘empty’ means successfully handled absence of content. JSON null is payload=None with decoded_as=‘json’. Partial bodies never expose a successful decoded payload. Decoding itself belongs to runtime.

encoding records the effective text codec (required for text). elapsed is this exchange through completion/failure, not total execution duration. The envelope is frozen; decoded JSON is not recursively frozen or copied.

`init`

def __init__(*, request: Request, status: int, headers: Headers, http_version: str | None = None, content: bytes, body_complete: bool, decoded_as: Literal['json', 'text', 'bytes', 'empty'] | None, payload: JsonValue | bytes = None, encoding: str | None = None, elapsed: float | None = None) -> None

Fields and properties declared here; inherited members belong to the bases above.

`body_complete`

body_complete: bool

`content`

content: bytes = field(repr=False)

`decoded_as`

decoded_as: Literal['json', 'text', 'bytes', 'empty'] | None

`elapsed`

elapsed: float | None = None

`encoding`

encoding: str | None = field(default=None, repr=False)

`payload`

payload: JsonValue | bytes = field(default=None, repr=False)

`size_bytes`

Read-only property.

size_bytes: int

Retained decoded-body bytes, not Content-Length or network bytes.

`HttpResponseHead`

Metadata for a response actually received, including an unopened body.

request is the effective, resolved application message for this exchange; it is not a capture of backend-added framing or credential bytes. Header field order/multiplicity is retained by the existing Headers contract. http_version records the negotiated version when known.

`init`

def __init__(*, request: Request, status: int, headers: Headers, http_version: str | None = None) -> None

Fields and properties declared here; inherited members belong to the bases above.

`headers`

headers: Headers = field(repr=False)

`http_version`

http_version: str | None = None

`is_success`

Read-only property.

is_success: bool

`location`

Read-only property.

location: str | None

First Location field, without resolving or following it.

`request`

request: Request = field(repr=False)

`status`

status: int

`HttpResult`

One HTTP operation plus its existing execution report and evidence.

request is the caller’s requested message. response, when present, belongs to the TERMINAL exchange of the terminal attempt. history holds responses followed earlier in that attempt (redirects/auth replays); if a subsequent connection fails, response is None and history retains the earlier heads. Previous retry attempts remain execution.retries, not history.

completed means execution/body/decoding finished. ok additionally requires a 2xx status; it is not a business-success or pagination/completeness claim. Evidence may be present even when execution failed. Never infer that a failed operation was not sent, or is safe to retry, from these flags.

execution.value may point at the response; it is never copied. If it does, response must be that SAME object. Attempts retain the runner’s meaning; they are not a count of redirects or proof of actual network dispatches.

`init`

def __init__(*, request: Request, execution: ExecutionResult, response: HttpResponse | None = None, history: tuple[HttpResponseHead, ...] = ()) -> None

Fields and properties declared here; inherited members belong to the bases above.

`attempts`

Read-only property.

attempts: int

`completed`

Read-only property.

completed: bool

`elapsed`

Read-only property.

elapsed: float

`error`

Read-only property.

error: BaseException | None

`execution`

execution: ExecutionResult = field(repr=False)

`history`

history: tuple[HttpResponseHead, ...] = field(default=(), repr=False)

`ok`

Read-only property.

ok: bool

`request`

request: Request = field(repr=False)

`response`

response: HttpResponse | None = field(default=None, repr=False)

`status`

Read-only property.

status: int | None

`describe`

def describe() -> str

`unwrap`

def unwrap() -> HttpResponse

Require an ok response; preserve original exceptions on failure.

A non-exception rejection, bad HTTP status, or incomplete outcome raises HttpResultError with this result attached. It uses a safe summary instead of the foundation’s possibly sensitive error text. Re-raising an original exception intentionally retains its message.

`HttpResultError`

Bases: RuntimeError

unwrap() failure without an original exception; evidence stays attached.

This is the inspection helper’s fallback, not a transport error taxonomy. Catch RuntimeError or HttpResultError; inspect result.response/execution explicitly when needed. Its message contains only the safe result summary.

`init`

def __init__(result: HttpResult) -> None

Fields and properties declared here; inherited members belong to the bases above.

`result`

result = result

`HttpTransportInfo`

Engine capability/lifecycle snapshot, never remote-service health.

http_versions are locally enabled versions, not negotiated server truth; None means unknown. owns_engine controls lifecycle responsibility. An engine’s streaming capability does not claim a stream API is implemented.

`init`

def __init__(*, engine: str, state: Literal['new', 'open', 'closed'], owns_engine: bool, http_versions: tuple[str, ...] | None, supports_response_streaming: bool, supports_request_streaming: bool) -> None

Fields and properties declared here; inherited members belong to the bases above.

`engine`

engine: str

`http_versions`

http_versions: tuple[str, ...] | None

`owns_engine`

owns_engine: bool

`state`

state: Literal['new', 'open', 'closed']

`supports_request_streaming`

supports_request_streaming: bool

`supports_response_streaming`

supports_response_streaming: bool