common_http.contracts.parameters

HTTP parameter declarations and native-value serialization.

Canonical strings such as type='str' and list_style='repeat' normalize to enums at construction. Values serialize to decoded strings: QueryParams owns query encoding, URLTemplate owns path encoding, and header/cookie values are handed to their respective message contracts. No defaults are silently applied while rendering; the request builder decides when a value is absent.

Classes

ListStyle

Bases: StrEnum

The wire representation of a collection of scalar parameter values.

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

COMMA

COMMA = 'comma'

PIPE

PIPE = 'pipe'

REPEAT

REPEAT = 'repeat'

SPACE

SPACE = 'space'

separator

Read-only property.

separator: str | None

ParamKind

Bases: StrEnum

Where a declared parameter is carried by a request.

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

COOKIE

COOKIE = 'cookie'

HEADER

HEADER = 'header'

PATH

PATH = 'path'

QUERY

QUERY = 'query'

in_url

Read-only property.

in_url: bool

ParamType

Bases: StrEnum

Scalar meaning, independent of whether a parameter is a collection.

String inputs for numeric, boolean, and temporal types are parsed explicitly; arbitrary objects are never converted with a permissive str(value). Datetimes must have an explicit UTC offset. Floating-point values must be finite. Booleans are not integers, and datetimes are not bare dates.

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

BOOL

BOOL = 'bool'

DATE

DATE = 'date'

DATETIME

DATETIME = 'datetime'

FLOAT

FLOAT = 'float'

INT

INT = 'int'

STR

STR = 'str'

normalize

def normalize(value: object) -> _Scalar

Normalize a native scalar or its explicit string representation.

render

def render(value: object, *, fmt: str | None = None) -> str

Return a decoded scalar string; never apply URL percent encoding.

validate_format

def validate_format(fmt: str | None) -> None

Allow ISO output, Unix seconds, or documented strftime directives.

Parameter

Bases: BaseModel

A parameter’s declared name, location, type, and accepted values.

list_style=None declares a scalar; any ListStyle declares a collection whose elements have type. Inputs accept ordered lists or tuples. Stored defaults/choices are normalized and immutable, including after JSON loading.

default=None means no default. required means the caller must supply a value, so required declarations cannot also carry a default. Path parameters are always required. render and pairs require an actual value; omission and default application belong to request construction.

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

alias

alias: str | None = Field(default=None, min_length=1)

choices

choices: tuple[_Scalar, ...] | None = Field(default=None, repr=False)

default

default: _Value | None = Field(default=None, repr=False)

fmt

fmt: str | None = None

kind

kind: ParamKind = Field(default=(ParamKind.QUERY), strict=False)

list_style

list_style: ListStyle | None = Field(default=None, strict=False)

maximum

maximum: int | float | None = None

maximum_items

maximum_items: int | None = Field(default=None, ge=0)

minimum

minimum: int | float | None = None

minimum_items

minimum_items: int | None = Field(default=None, ge=0)

name

name: str = Field(min_length=1)

required

required: bool = False

type

type: ParamType = Field(default=(ParamType.STR), strict=False)

wire_name

Read-only property.

wire_name: str

cookie

@classmethod
def cookie(name: str, **declaration: Any) -> Self

header

@classmethod
def header(name: str, **declaration: Any) -> Self

pairs

def pairs(value: object) -> tuple[tuple[str, str], ...]

Serialize decoded entries; an empty repeat collection emits no pairs.

path

@classmethod
def path(name: str, **declaration: Any) -> Self

query

@classmethod
def query(name: str, **declaration: Any) -> Self

render

def render(value: object) -> str

Serialize one scalar or joined collection to a decoded string.