common_http.contracts.bodies

Immutable HTTP payloads and multipart parts, independent of a transport.

Content stays in its declared representation. Request preparation owns wire encoding, multipart boundaries, and HTTPX arguments. Files and live streams are runtime resources; these contracts carry values and never open or read a file.

Classes

Body

Bases: _BodyValue

A payload value plus its representation, with one construction path.

JSON objects become read-only mappings and arrays become tuples recursively. JSON scalars, including None, are valid. Form mappings become ordered string pairs; pass pairs to retain repeated names. Multipart takes ordered BodyPart objects or their configuration dictionaries. Mutable binary buffers are copied.

Body.json(None) means JSON null; the future Request’s body=None means absence. Empty binary/text/form values remain explicit bodies. Multipart needs at least one part. Its Content-Type is left unset until boundary generation.

Serialization returns independent plain containers; binary content uses {‘base64’: ’…’} in JSON configuration only. This does not encode HTTP bytes. Routine representations omit payloads, filenames, names, and media types.

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

content

content: _BodyContent = Field(repr=False)

content_type

content_type: str | None = Field(default=None, repr=False)

kind

kind: BodyKind = Field(strict=False)

binary

@classmethod
def binary(content: bytes, *, content_type: str | None = None) -> Body

form

@classmethod
def form(content: Mapping[str, str] | Iterable[_FormPair]) -> Body

json

@classmethod
def json(content: JsonValue, *, content_type: str | None = None) -> Body

Snapshot a JSON value; serialize the contract with model_dump_json.

multipart

@classmethod
def multipart(content: Iterable[BodyPart | Mapping[str, Any]]) -> Body

text

@classmethod
def text(content: str, *, content_type: str | None = None) -> Body

BodyKind

Bases: StrEnum

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

BINARY

BINARY = 'binary'

FORM

FORM = 'form'

JSON

JSON = 'json'

MULTIPART

MULTIPART = 'multipart'

TEXT

TEXT = 'text'

default_content_type

Read-only property.

default_content_type: str | None

Default media type; multipart needs the encoder’s boundary first.

BodyPart

Bases: _BodyValue

One named multipart field or file; repeated names remain separate parts.

Text remains text; bytes remain bytes. Binary content uses a tagged base64 object in JSON configuration so loading cannot confuse file bytes with text. headers accepts Headers, an ordinary mapping, or model-shaped configuration. Content-Disposition and Content-Type are derived from the explicit fields; additional headers cannot override them or introduce competing framing.

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

content

content: str | bytes = Field(repr=False)

content_type

content_type: str | None = None

filename

filename: str | None = Field(default=None, repr=False)

headers

headers: Headers = Field(default_factory=Headers, repr=False)

name

name: str = Field(min_length=1, repr=False)