common_http.contracts.requests

Endpoint declarations and concrete HTTP requests, without transport state.

Both construction paths compose the same address, parameter, header, and body contracts. Query inputs become part of the URL; cookies become a Cookie field. No execution, authentication, connection, or vendor vocabulary is introduced.

Classes

`Endpoint`

Bases: _RequestValue

A reusable declaration that binds caller values into a Request.

Undeclared path slots are required strings. Declare Parameter.path to add types/constraints or map an internal name to a template slot with alias. Unknown inputs fail unless allow_extra=True, which routes them to query. Each required_any group needs at least one value that produces a wire entry.

Missing inputs use parameter defaults; explicit None suppresses an optional value/default. Required inputs cannot be absent or empty repeated lists. Headers layer in this order: endpoint headers, parameter defaults, per-call headers, explicitly supplied parameters. Query values replace matching URL entries. Cookies conflict with an explicit Cookie header rather than silently discarding one source. A body’s kind, when declared, is an expectation, not a requirement to send a body; body=None suppresses a default payload.

Use values={…} for parameter names that collide with request() arguments. base_url uses URL.resolve URI semantics: “items” preserves a “/v1/” base directory; “/items” replaces it. Client base-path policies belong to clients.

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

`allow_extra`

allow_extra: bool = False

`body`

body: Body | None = Field(default=None, repr=False)

`body_kind`

body_kind: BodyKind | None = Field(default=None, strict=False)

`headers`

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

`method`

method: HttpMethod = Field(default=(HttpMethod.GET), strict=False)

`name`

name: str = Field(min_length=1)

`param_names`

Read-only property.

param_names: tuple[str, ...]

`params`

params: tuple[Parameter, ...] = ()

`required_any`

required_any: tuple[tuple[str, ...], ...] = ()

`url`

url: URLTemplate = Field(repr=False)

`get_param`

def get_param(name: str) -> Parameter

`request`

def request(*, values: Mapping[str, object] | None = None, base_url: URL | str | None = None, headers: Headers | Mapping[str, str] | list[tuple[str, str]] | None = None, cookies: Mapping[str, str] | None = None, body: object = _UNSET, **inputs: Any) -> Request

Bind once, using the same lower contracts as direct Request inputs.

body accepts a Body/configuration, or native content when body_kind is declared. Direct Request offers json/form/etc. shortcuts; endpoint keyword inputs are parameter values, including a parameter actually named json.

`HttpMethod`

Bases: StrEnum

Standard HTTP methods and their protocol semantics, not retry policy.

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

`CONNECT`

CONNECT = 'CONNECT'

`DELETE`

DELETE = 'DELETE'

`GET`

GET = 'GET'

`HEAD`

HEAD = 'HEAD'

`OPTIONS`

OPTIONS = 'OPTIONS'

`PATCH`

PATCH = 'PATCH'

`POST`

POST = 'POST'

`PUT`

PUT = 'PUT'

`TRACE`

TRACE = 'TRACE'

`is_idempotent`

Read-only property.

is_idempotent: bool

`is_safe`

Read-only property.

is_safe: bool

`Request`

Bases: _RequestValue

A concrete message, constructible independently of an Endpoint.

Strings/dictionaries and typed values share validation. params accepts native scalars, lists (repeated keys), ordered pairs, or QueryParams. Supplied names replace existing URL query entries; unrelated raw encoding survives. None/empty lists remove a name; use QueryParams for an explicit bare key.

cookies accepts string mappings and conflicts with an explicit Cookie header. It describes this message only, not a persistent scoped cookie jar. json=None is JSON null; body=None is no body. The five body shortcuts are exclusive with each other and with body. Raw body values need an explicit representation (Body, a body configuration, or a shortcut).

Relative URLs remain usable until the caller resolves a base. Wire framing, media headers, fragment removal, and method-specific send support belong to preparation/transport. Routine representations omit all request values.

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

`body`

body: Body | None = Field(default=None, repr=False)

`headers`

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

`method`

method: HttpMethod = Field(default=(HttpMethod.GET), strict=False)

`url`

url: URL = Field(repr=False)

`get`

@classmethod
def get(url: URL | str, **inputs: Any) -> Self

`post`

@classmethod
def post(url: URL | str, **inputs: Any) -> Self