common_http.contracts.headers

HTTP fields shared by requests, responses, and client defaults.

Names retain their spelling; lookup and replacement are case-insensitive. Field lines retain their order and multiplicity. No implicit joining, splitting, or value trimming takes place. This is a field collection, not an HTTP wire parser.

Classes

Headers

Bases: BaseModel

Immutable, ordered HTTP field lines with case-insensitive name lookup.

Use from_mapping for ordinary dictionaries and from_pairs when names repeat. Direct pairs= construction and dictionary/JSON model loading use the same validation. Lists become tuples; strings are never coerced.

Values are parsed field contents: empty strings and internal spaces/tabs are valid; surrounding wire whitespace must already have been removed by the parser. U+0080..U+00FF represent opaque bytes reversibly through Latin-1. Transport adapters must preserve that mapping instead of guessing UTF-8.

Generic field syntax is checked here. Field-specific semantics, framing, and whether a sender may repeat a particular field belong to message preparation and the transport. get returns one line, never a comma-joined value.

str/repr omit content. Explicit pairs, lookup, and serialization expose actual values, including credentials when present.

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

pairs

pairs: tuple[_HeaderPair, ...] = Field(default=(), repr=False)

append

def append(pairs: Iterable[_HeaderPair]) -> Headers

Return a collection with new lines appended; retain existing lines.

from_mapping

@classmethod
def from_mapping(values: Mapping[str, str]) -> Headers

Copy a mapping’s items in iteration order; values must be strings.

from_pairs

@classmethod
def from_pairs(pairs: Iterable[_HeaderPair]) -> Headers

Copy an ordered iterable of pairs, including generators and repeats.

get

def get(name: str, default: str | None = None) -> str | None

Return the first matching line value, or default when absent.

Use get_all when multiplicity matters; this does not combine lines.

get_all

def get_all(name: str) -> tuple[str, ...]

Return every matching line value in its original order.

replace

def replace(name: str, values: Iterable[str]) -> Headers

Remove all matches, then append replacements with the supplied name.

An empty iterable removes the field. Other fields keep their order.

without

def without(*names: str) -> Headers

Remove all case-insensitive matches; retain remaining lines exactly.