common_http.contracts.urls

HTTP addressing: immutable query components, URLs, and path templates.

Values retain their supplied encoding. Inspection never rebuilds an address; only explicit transformations do. render() and model serialization expose actual content, while str() and repr() omit addresses and query values. This module performs no I/O and imports no HTTP transport or execution engine.

Classes

QueryParams

Bases: _AddressValue

A query component without its leading delimiter.

Stored text is preserved exactly. Decoded pairs retain order and repeated keys. A pair value of None represents a bare key (flag); "" is an explicitly empty value (flag=). This is wire representation, not the application’s policy for omitting missing parameters. Empty separators are preserved in encoded text but do not count as parameter entries.

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

encoded

encoded: str = Field(default='', repr=False)

pairs

Read-only property.

pairs: tuple[_QueryPair, ...]

Decoded UTF-8 entries; accessing these never rewrites stored text.

append

def append(pairs: Iterable[_QueryPair]) -> QueryParams

Append new entries, retaining the original query’s encoding.

from_pairs

@classmethod
def from_pairs(pairs: Iterable[_QueryPair]) -> QueryParams

Encode decoded UTF-8 entries; repeated names stay separate.

get_all

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

Return all values for a decoded, case-sensitive name.

render

def render() -> str

Return actual content, including any sensitive query values.

replace

def replace(name: str, values: Iterable[str | None]) -> QueryParams

Remove all entries for a name, then append its replacement values.

without

def without(*names: str) -> QueryParams

Remove named entries; retain other entries’ order and exact encoding.

URL

Bases: _AddressValue

A concrete HTTP(S) address or relative reference.

Construction validates without rebuilding the supplied address. Components expose the parsed meaning; render() preserves the original spelling. An empty relative reference is valid. Credentials and query values are available explicitly, but omitted from routine string representations.

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

fragment

Read-only property.

fragment: str

host

Read-only property.

host: str | None

is_absolute

Read-only property.

is_absolute: bool

path

Read-only property.

path: str

The encoded path, without query or fragment.

port

Read-only property.

port: int | None

The explicit port, or None; no default port is invented.

query

Read-only property.

query: QueryParams

scheme

Read-only property.

scheme: str | None

value

value: str = Field(repr=False)

parse

@classmethod
def parse(value: str) -> URL

Use the same validation as direct construction and model loading.

render

def render(*, include_fragment: bool = True) -> str

Return actual content; HTTP senders use include_fragment=False.

resolve

def resolve(base: URL | str) -> URL

Resolve against an absolute base using URI reference semantics.

/items replaces the base path; items resolves relative to its directory. An absolute reference retains its own origin. Explicit empty query/fragment delimiters survive resolution. This is address resolution, not an origin restriction or a client’s base-path append policy.

with_query

def with_query(query: QueryParams) -> URL

Replace the query; an empty QueryParams removes its delimiter.

URLTemplate

Bases: _AddressValue

An HTTP address with named path placeholders, such as /etf/{symbol}/.

Only simple {name} placeholders in the path are accepted. Binding takes decoded strings and returns a concrete URL. Query values use QueryParams; hosts, schemes, and fragments are not templated.

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

placeholders

Read-only property.

placeholders: tuple[str, ...]

template

template: str = Field(repr=False)

bind

def bind(**path_values: str) -> URL

Bind exact arguments; escape values so they cannot add URL delimiters.

Empty values and dot-segment values (’.’ and ’..’) are rejected: they would change the declared path structure during reference resolution.