Module

http.request

Immutable HTTP request.

Frozen metadata with async body access. The request is honest about what it is: received data that doesn't change.

5Classes

Classes

RequestUrlScope 3 ▼
Request-local public URL prefix. Middleware can attach this to a copied ``Request`` when the app r…

Request-local public URL prefix.

Middleware can attach this to a copiedRequestwhen the app routes a local path through a tenant or base-path public URL. It applies only to app-root paths, leaving external URLs, anchors, and relative paths alone.

Attributes

Name Type Description
prefix str —

Methods

apply 1 str ▼
Return ``path`` under this request scope when it is app-rooted.
def apply(self, path: str) -> str
Parameters
Name Type Description
path —
Returns
str
Internal Methods 1 ▼
__post_init__ 0 ▼
def __post_init__(self) -> None
HtmxDetails 16 ▼
Parsed htmx request headers with caching. Attached to ``request.htmx``. Truthy when ``HX-Request``…

Parsed htmx request headers with caching.

Attached torequest.htmx. Truthy when HX-Requestis present, providing typed access to all htmx request headers. Values are computed once and cached for the lifetime of the request.

Attributes

Name Type Description
_headers Headers —
_server tuple[str, int] | None —
_cache dict[str, str | None] —

Methods

boosted 0 bool ▼
True if this request came from an hx-boost enhanced element.
property
def boosted(self) -> bool
Returns
bool
history_restore 0 bool ▼
True if htmx is restoring from history (cache miss on back/forward).
property
def history_restore(self) -> bool
Returns
bool
target 0 str | None ▼
The target element ID from HX-Target header.
property
def target(self) -> str | None
Returns
str | None
target_id 0 str | None ▼
HX-Target normalized to a bare DOM id (no leading ``#``). Canonical form for r…
property
def target_id(self) -> str | None

HX-Target normalized to a bare DOM id (no leading#).

Canonical form for registry lookups and layout-chain matching. ReturnsNonewhen HX-Target is absent or reduces to empty after stripping (e.g. a bare#).

Returns
str | None
trigger 0 str | None ▼
The trigger element ID from HX-Trigger header.
property
def trigger(self) -> str | None
Returns
str | None
trigger_name 0 str | None ▼
The name attribute of the trigger element (HX-Trigger-Name header).
property
def trigger_name(self) -> str | None
Returns
str | None
current_url 0 str | None ▼
The browser's current URL from HX-Current-URL header.
property
def current_url(self) -> str | None
Returns
str | None
current_url_abs_path 0 str | None ▼
The path portion of the browser's current URL. Strips scheme and host when the…
property
def current_url_abs_path(self) -> str | None

The path portion of the browser's current URL.

Strips scheme and host when the origin matches this request's server, returning just the path (+ query + fragment). Returns the full URL unchanged when the origin differs or server info is unavailable.

Returns
str | None
prompt 0 str | None ▼
The user response to hx-prompt (HX-Prompt header).
property
def prompt(self) -> str | None
Returns
str | None
partial 0 str | None ▼
The partial element name from HX-Partial header (htmx 4.0+). Set when the requ…
property
def partial(self) -> str | None

The partial element name from HX-Partial header (htmx 4.0+).

Set when the request originates from an<htmx-partial>element.

Returns
str | None
Internal Methods 3 ▼
__init__ 2 ▼
def __init__(self, headers: Headers, server: tuple[str, int] | None) -> None
Parameters
Name Type Description
headers —
server —
__bool__ 0 bool ▼
True if this is an htmx request (HX-Request header is present).
def __bool__(self) -> bool
Returns
bool
_get 1 str | None ▼
Read an htmx header with URI-AutoEncoded decoding and caching.
def _get(self, name: str) -> str | None
Parameters
Name Type Description
name —
Returns
str | None
_LazyQueryParams 11 ▼
QueryParams that parses on first access.

QueryParams that parses on first access.

Methods

get 2 str | None ▼
def get(self, key: str, default: None = None) -> str | None
Parameters
Name Type Description
key —
default — Default:None
Returns
str | None
get 2 str | T ▼
def get(self, key: str, default: T) -> str | T
Parameters
Name Type Description
key —
default —
Returns
str | T
get 2 object ▼
def get(self, key: str, default: object = None) -> object
Parameters
Name Type Description
key —
default — Default:None
Returns
object
get_list 1 list[str] ▼
def get_list(self, key: str) -> list[str]
Parameters
Name Type Description
key —
Returns
list[str]
get_int 2 int | None ▼
def get_int(self, key: str, default: int | None = None) -> int | None
Parameters
Name Type Description
key —
default — Default:None
Returns
int | None
get_bool 2 bool | None ▼
def get_bool(self, key: str, default: bool | None = None) -> bool | None
Parameters
Name Type Description
key —
default — Default:None
Returns
bool | None
Internal Methods 5 ▼
__init__ 1 ▼
def __init__(self, raw: bytes) -> None
Parameters
Name Type Description
raw —
__getitem__ 1 str ▼
def __getitem__(self, key: str) -> str
Parameters
Name Type Description
key —
Returns
str
__contains__ 1 bool ▼
def __contains__(self, key: object) -> bool
Parameters
Name Type Description
key —
Returns
bool
__iter__ 0 Iterator[str] ▼
def __iter__(self) -> Iterator[str]
Returns
Iterator[str]
__len__ 0 int ▼
def __len__(self) -> int
Returns
int
_LazyCookies 8 ▼
Cookies that parse on first access.

Cookies that parse on first access.

Methods

get 2 str | None ▼
def get(self, key: str, default: None = None) -> str | None
Parameters
Name Type Description
key —
default — Default:None
Returns
str | None
get 2 str | T ▼
def get(self, key: str, default: T) -> str | T
Parameters
Name Type Description
key —
default —
Returns
str | T
get 2 object ▼
def get(self, key: str, default: object = None) -> object
Parameters
Name Type Description
key —
default — Default:None
Returns
object
Internal Methods 5 ▼
__init__ 1 ▼
def __init__(self, cookie_header: str) -> None
Parameters
Name Type Description
cookie_header —
__getitem__ 1 str ▼
def __getitem__(self, key: str) -> str
Parameters
Name Type Description
key —
Returns
str
__contains__ 1 bool ▼
def __contains__(self, key: object) -> bool
Parameters
Name Type Description
key —
Returns
bool
__iter__ 0 Iterator[str] ▼
def __iter__(self) -> Iterator[str]
Returns
Iterator[str]
__len__ 0 int ▼
def __len__(self) -> int
Returns
int
Request 39 ▼
An immutable HTTP request. Metadata (method, path, headers, etc.) is frozen at creation. Body is a…

An immutable HTTP request.

Metadata (method, path, headers, etc.) is frozen at creation. Body is accessed asynchronously via.body(), .json(), .form().

Query params and cookies are parsed lazily on first access (not at creation).

Attributes

Name Type Description
method str —
path str —
headers Headers —
query QueryParams | _LazyQueryParams —
path_params dict[str, str] —
http_version str —
server tuple[str, int] | None —
client tuple[str, int] | None —
cookies Mapping[str, str] | _LazyCookies —
request_id str —
_receive Receive —
url_scope RequestUrlScope | None —
_url_for Callable[..., str] | None —
_cache dict[str, Any] —

Methods

htmx 0 HtmxDetails ▼
Typed, cached htmx request details. Truthy when ``HX-Request`` is present:: …
property
def htmx(self) -> HtmxDetails

Typed, cached htmx request details.

Truthy whenHX-Requestis present::

if request.htmx:
    target = request.htmx.target
Returns
HtmxDetails
is_htmx 0 bool ▼
True if this is any htmx request (HX-Request header present).
property
def is_htmx(self) -> bool
Returns
bool
is_narrow_fragment 0 bool ▼
True if this htmx request targets a narrow fragment swap. False for boosted na…
property
def is_narrow_fragment(self) -> bool

True if this htmx request targets a narrow fragment swap.

False for boosted navigations and history restores, which need full page content despite using htmx transport.

Returns
bool
is_fragment 0 bool ▼
True if this is an htmx request (HX-Request header). .. deprecated:: Use `…
property
def is_fragment(self) -> bool

True if this is an htmx request (HX-Request header).

.. deprecated:: Useis_htmx (any htmx request) or is_narrow_fragment (narrow fragment swap, excludes boosted and history restore).

Returns
bool
is_history_restore 0 bool ▼
True if htmx is restoring from history (cache miss on back/forward).
property
def is_history_restore(self) -> bool
Returns
bool
is_boosted 0 bool ▼
True if this request came from an hx-boost enhanced element.
property
def is_boosted(self) -> bool
Returns
bool
htmx_target 0 str | None ▼
The target element ID from HX-Target header.
property
def htmx_target(self) -> str | None
Returns
str | None
htmx_target_id 0 str | None ▼
HX-Target normalized to a bare DOM id (no leading ``#``). Canonical form used …
property
def htmx_target_id(self) -> str | None

HX-Target normalized to a bare DOM id (no leading#).

Canonical form used throughout the framework's request → registry pipeline. Callers should prefer this overhtmx_targetunless they specifically need the raw header value.

Returns
str | None
htmx_trigger 0 str | None ▼
The trigger element ID from HX-Trigger header.
property
def htmx_trigger(self) -> str | None
Returns
str | None
htmx_trigger_name 0 str | None ▼
The name attribute of the trigger element (HX-Trigger-Name header).
property
def htmx_trigger_name(self) -> str | None
Returns
str | None
htmx_current_url 0 str | None ▼
The browser's current URL from HX-Current-URL header.
property
def htmx_current_url(self) -> str | None
Returns
str | None
htmx_current_url_abs_path 0 str | None ▼
The path portion of the browser's current URL.
property
def htmx_current_url_abs_path(self) -> str | None
Returns
str | None
htmx_partial 0 str | None ▼
The partial element name from HX-Partial header (htmx 4.0+).
property
def htmx_partial(self) -> str | None
Returns
str | None
content_type 0 str | None ▼
The Content-Type header value.
property
def content_type(self) -> str | None
Returns
str | None
content_length 0 int | None ▼
The Content-Length header as int.
property
def content_length(self) -> int | None
Returns
int | None
url 0 str ▼
Full request URL (path + query string).
property
def url(self) -> str
Returns
str
with_url_scope 1 Request ▼
Return a copy of this request with a public URL scope attached.
def with_url_scope(self, scope: RequestUrlScope | str | None) -> Request
Parameters
Name Type Description
scope —
Returns
Request
scoped_url 1 str ▼
Apply the request URL scope to an app-root path.
def scoped_url(self, path: str) -> str
Parameters
Name Type Description
path —
Returns
str
url_for 2 str ▼
Reverse a named route and apply this request's URL scope.
def url_for(self, name: str, /, **params: Any) -> str
Parameters
Name Type Description
name —
**params —
Returns
str
body 0 bytes ▼
Read the full request body. Result is cached — the ASGI receive is consumed on…
async
async def body(self) -> bytes

Read the full request body.

Result is cached — the ASGI receive is consumed once, then the same bytes are returned on subsequent calls.

Returns
bytes
stream 0 AsyncGenerator[bytes] ▼
Stream the request body in chunks.
async
async def stream(self) -> AsyncGenerator[bytes]
Returns
AsyncGenerator[bytes]
json 0 Any ▼
Parse the body as JSON.
async
async def json(self) -> Any
Returns
Any
text 0 str ▼
Read the body as text (UTF-8).
async
async def text(self) -> str
Returns
str
form 0 FormData ▼
Parse the body as form data (URL-encoded or multipart). Result is cached — the…
async
async def form(self) -> FormData

Parse the body as form data (URL-encoded or multipart).

Result is cached — the body is read and parsed once, then the sameFormDatais returned on subsequent calls.

Supportsapplication/x-www-form-urlencoded(stdlib) and multipart/form-data (requires pip install chirp[forms]).

Returns
FormData Parsed ``FormData`` implementing ``MultiValueMapping``.
from_asgi 4 Request ▼
Create a Request from an ASGI scope and receive callable. Reuses request_id fr…
classmethod
def from_asgi(cls, scope: Scope, receive: Receive, path_params: dict[str, str] | None = None, *, url_for: Callable[..., str] | None = None) -> Request

Create a Request from an ASGI scope and receive callable.

Reuses request_id from scope["extensions"]["request_id"] when Pounce (or another ASGI server) has already set it, avoiding redundant UUID generation.

Parameters
Name Type Description
scope —
receive —
path_params — Default:None
url_for — Default:None
Returns
Request