orionis.http.contracts.request.IRequest

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

Explore modules View classes

class documentation

class IRequest(ABC): (source)

Known subclasses: orionis.http.Request

View In Hierarchy

Undocumented

Method	`accepts`	Check if the client accepts a specific MIME type.
Async Method	`body`	Return the full request body as bytes.
Method	`close`	Close request-owned uploaded file handles after response delivery.
Method	`csrfToken`	Return the CSRF token for the current request.
Async Method	`data`	Return a flat, validatable dictionary built from the request body.
Async Method	`form`	Parse and return multipart form data.
Async Method	`formUrlEncoded`	Parse the request body as URL-encoded form data.
Method	`isAjax`	Determine if the request was made via AJAX.
Async Method	`json`	Parse the request body as JSON.
Async Method	`msgpack`	Decode the request body as MessagePack.
Async Method	`payload`	Parse and return structured request data based on Content-Type.
Async Method	`raw`	Return the request body as raw bytes.
Method	`routeParam`	Return a specific path parameter by key.
Method	`routeParams`	Return all path parameters as a dictionary.
Async Method	`stream`	Yield chunks of the request body as they arrive.
Async Method	`text`	Decode the request body as UTF-8 text.
Method	`wantsHtml`	Determine if the client expects an HTML response based on the Accept header.
Method	`wantsJson`	Determine if the client prefers a JSON response based on the Accept header.
Method	`wantsXml`	Determine if the client prefers an XML response based on the Accept header.
Async Method	`xml`	Parse the request body as XML and return the root element.
Class Variable	`__slots__`	Undocumented
Class Variable	`csrf_token`	Undocumented
Property	`accept`	Return the value of the Accept header.
Property	`apiKey`	Return the API key from the request headers if present.
Property	`authorization`	Return the Authorization header value if present.
Property	`baseUrl`	Return the base URL for the request.
Property	`bearerToken`	Return the bearer token from the Authorization header if present.
Property	`cookies`	Return parsed cookies from the request.
Property	`forwarded`	Return the forwarded information from the request scope.
Property	`headers`	Return the request headers as a Headers object.
Property	`httpVersion`	Return the HTTP version of the request.
Property	`interface`	Return the interface type of the request (ASGI or RSGI).
Property	`ip`	Return the client's IP address from the request scope.
Property	`method`	Return the HTTP request method.
Property	`path`	Return the request path.
Property	`port`	Return the client's port number from the request scope.
Property	`queryParams`	Return parsed query parameters from the request.
Property	`scheme`	Return the URL scheme (e.g., 'http' or 'https') of the request.
Property	`scope`	Return the raw ASGI / RSGI connection scope.
Property	`state`	Return the mutable per-request state namespace.
Property	`url`	Return the full request URL.
Property	`userAgent`	Return the User-Agent string from the request headers.

@abstractmethod

def accepts(self, mime: str) -> bool: (source) ¶

overridden in orionis.http.Request

Check if the client accepts a specific MIME type.

Parameters
mime:`str`	The MIME type to check.

Returns
`bool`	True if the MIME type is present in the Accept header.

@abstractmethod

async def body(self) -> bytes: (source) ¶

overridden in orionis.http.Request

Return the full request body as bytes.

Buffers the stream on first call and caches the result. Subsequent calls are O(1) — they return the cached buffer.

Returns
`bytes`	The complete request body as bytes.

@abstractmethod

def close(self): (source) ¶

overridden in orionis.http.Request

Close request-owned uploaded file handles after response delivery.

Returns
`None`	Release parsed multipart resources; repeated calls must be safe.

@abstractmethod

def csrfToken(self) -> str | None: (source) ¶

overridden in orionis.http.Request

Return the CSRF token for the current request.

The token is set by CSRFTokenMiddleware on every web request before the route handler is invoked. Returns None on API routes where the middleware is not active.

Returns
`str \| None`	The CSRF token string, or `None` when not available.

@abstractmethod

async def data(self) -> dict[str, Any]: (source) ¶

overridden in orionis.http.Request

Return a flat, validatable dictionary built from the request body.

Dispatches by Content-Type:

application/json → parsed JSON object (must be a mapping)
application/msgpack → decoded MessagePack object (must be a mapping)
application/x-www-form-urlencoded → form fields; a key that appears once yields a scalar string, repeated keys yield a list
multipart/form-data → text fields and uploaded files with the same scalar-or-list collapsing

Returns
`dict[str, Any]`	Flat dictionary suitable for downstream validation (FormRequest).

Raises
`UnsupportedMediaTypeException`	If the `Content-Type` cannot be converted to a dictionary.
`ValueError`	If a JSON or MessagePack body is empty or cannot be decoded, or if multipart parsing fails.
`TypeError`	If a decoded JSON or MessagePack body is not a mapping.

@abstractmethod

async def form(self) -> FormData: (source) ¶

overridden in orionis.http.Request

Parse and return multipart form data.

Returns
`FormData`	The parsed multipart form data.

Raises
`UnsupportedMediaTypeException`	If the Content-Type is not multipart/form-data.
`ValueError`	If the multipart boundary is missing.

@abstractmethod

async def formUrlEncoded(self) -> dict[str, Any]: (source) ¶

overridden in orionis.http.Request

Parse the request body as URL-encoded form data.

Returns
`dict[str, Any]`	The parsed form data as a dictionary.

@abstractmethod

def isAjax(self) -> bool: (source) ¶

overridden in orionis.http.Request

Determine if the request was made via AJAX.

Returns
`bool`	True if the X-Requested-With header is 'XMLHttpRequest'.

@abstractmethod

async def json(self) -> object: (source) ¶

overridden in orionis.http.Request

Parse the request body as JSON.

Validates Content-Type, buffers the body, and delegates decoding to msgspec. Result is cached; a JSON null literal is handled correctly via the __json_parsed sentinel.

Returns
`object`	The decoded JSON value: dict, list, str, int, float, bool, or None.

Raises
`UnsupportedMediaTypeException`	If the Content-Type is not `application/json` (or a `+json` subtype).
`ValueError`	If the body is empty or not valid JSON.

@abstractmethod

async def msgpack(self) -> object: (source) ¶

overridden in orionis.http.Request

Decode the request body as MessagePack.

Returns
`object`	The decoded MessagePack value, including maps, arrays, scalars, binary data, extension values, or None.

Raises
`msgspec.DecodeError`	If the payload is not valid MessagePack.

@abstractmethod

async def payload(self) -> Any: (source) ¶

overridden in orionis.http.Request

Parse and return structured request data based on Content-Type.

Returns
`Any`	Structured data parsed from the request body, or raw bytes if no parser is available.

@abstractmethod

async def raw(self) -> bytes: (source) ¶

overridden in orionis.http.Request

Return the request body as raw bytes.

Returns
`bytes`	The raw request body.

@abstractmethod

def routeParam(self, key: str) -> object: (source) ¶

overridden in orionis.http.Request

Return a specific path parameter by key.

Parameters
key:`str`	The specific path parameter key to retrieve.

Returns
`object`	Converted parameter value, or None when the key is absent.

@abstractmethod

def routeParams(self) -> dict[str, Any]: (source) ¶

overridden in orionis.http.Request

Return all path parameters as a dictionary.

Returns
`dict[str, Any]`	A dictionary of all path parameters.

@abstractmethod

async def stream(self) -> AsyncGenerator[bytes]: (source) ¶

overridden in orionis.http.Request

Yield chunks of the request body as they arrive.

Delegates to BodyStream, which handles RSGI and ASGI transports, enforces max_body_size, and replays from the internal buffer when the body has already been fully read by body() or a parser.

Returns
`AsyncGenerator[bytes]`	Yields chunks of the request body as bytes.

@abstractmethod

async def text(self) -> str: (source) ¶

overridden in orionis.http.Request

Decode the request body as UTF-8 text.

Returns
`str`	The decoded request body as a string.

@abstractmethod

def wantsHtml(self) -> bool: (source) ¶

overridden in orionis.http.Request

Determine if the client expects an HTML response based on the Accept header.

Returns
`bool`	True if the Accept header indicates HTML is expected.

@abstractmethod

def wantsJson(self) -> bool: (source) ¶

overridden in orionis.http.Request

Determine if the client prefers a JSON response based on the Accept header.

Returns
`bool`	True if the Accept header indicates JSON is preferred, otherwise False.

@abstractmethod

def wantsXml(self) -> bool: (source) ¶

overridden in orionis.http.Request

Determine if the client prefers an XML response based on the Accept header.

Returns
`bool`	True if the Accept header indicates XML is preferred.

@abstractmethod

async def xml(self) -> ET.Element: (source) ¶

overridden in orionis.http.Request

Parse the request body as XML and return the root element.

Entity declarations are rejected. DTDs without entity declarations are allowed; external resources are not resolved.

Returns
`ET.Element`	The root element parsed from the XML request body.

Raises
`xml.etree.ElementTree.ParseError`	If the XML body is malformed.
`defusedxml.common.EntitiesForbidden`	If the document declares an internal or external entity. This is a subclass of `defusedxml.common.DefusedXmlException`, not ParseError.

__slots__: tuple = (source) ¶

overridden in orionis.http.Request

Undocumented

csrf_token = (source) ¶

overridden in orionis.http.Request

Undocumented

@property
@abstractmethod

accept: str | None = (source) ¶

overridden in orionis.http.Request

Return the value of the Accept header.

Returns
`str \| None`	The value of the 'Accept' header, or None if not present.

@property
@abstractmethod

apiKey: str | None = (source) ¶

overridden in orionis.http.Request

Return the API key from the request headers if present.

Returns
`str \| None`	The API key from the 'X-API-Key' header, or None if not present.

@property
@abstractmethod

authorization: str | None = (source) ¶

overridden in orionis.http.Request

Return the Authorization header value if present.

Returns
`str \| None`	The value of the 'Authorization' header, or None if not present.

@property
@abstractmethod

baseUrl: str = (source) ¶

overridden in orionis.http.Request

Return the base URL for the request.

Returns
`str`	The base URL composed of scheme and host.

@property
@abstractmethod

bearerToken: str | None = (source) ¶

overridden in orionis.http.Request

Return the bearer token from the Authorization header if present.

Returns
`str \| None`	The bearer token extracted from the 'Authorization' header, or None if not present or does not start with 'Bearer '.

@property
@abstractmethod

cookies: Cookies = (source) ¶

overridden in orionis.http.Request

Return parsed cookies from the request.

Returns
`Cookies`	The parsed cookies as a Cookies object.

@property
@abstractmethod

forwarded: dict[str, Any] = (source) ¶

overridden in orionis.http.Request

Return the forwarded information from the request scope.

Returns
`dict[str, Any]`	The forwarded information as a dictionary.

@property
@abstractmethod

headers: Headers = (source) ¶

overridden in orionis.http.Request

Return the request headers as a Headers object.

Returns
`Headers`	The headers associated with the request.

@property
@abstractmethod

httpVersion: str = (source) ¶

overridden in orionis.http.Request

Return the HTTP version of the request.

Returns
`str`	The HTTP version string, such as '1.1' or '2'.

@property
@abstractmethod

interface: Interface = (source) ¶

overridden in orionis.http.Request

Return the interface type of the request (ASGI or RSGI).

Returns
`Interface`	The interface type of the request.

@property
@abstractmethod

ip: str | None = (source) ¶

overridden in orionis.http.Request

Return the client's IP address from the request scope.

Returns
`str \| None`	The client's IP address if available, otherwise None.

@property
@abstractmethod

method: str = (source) ¶

overridden in orionis.http.Request

Return the HTTP request method.

Returns
`str`	The HTTP method of the request, such as 'GET' or 'POST'.

@property
@abstractmethod

path: str = (source) ¶

overridden in orionis.http.Request

Return the request path.

Returns
`str`	The path component of the request URL.

@property
@abstractmethod

port: int | None = (source) ¶

overridden in orionis.http.Request

Return the client's port number from the request scope.

Returns
`int \| None`	The client's port number if available, otherwise None.

@property
@abstractmethod

queryParams: QueryParams = (source) ¶

overridden in orionis.http.Request

Return parsed query parameters from the request.

Returns
`QueryParams`	The parsed query parameters as a QueryParams object.

@property
@abstractmethod

scheme: str = (source) ¶

overridden in orionis.http.Request

Return the URL scheme (e.g., 'http' or 'https') of the request.

Returns
`str`	The URL scheme of the request.

@property
@abstractmethod

scope: dict[str, Any] = (source) ¶

overridden in orionis.http.Request

Return the raw ASGI / RSGI connection scope.

Exposes the underlying scope dict so that ASGI-aware middleware, tracing libraries, and extensions can read or annotate transport-level data without requiring framework-specific adapters.

Returns
`dict[str, Any]`	The raw scope dictionary provided by the transport layer.

@property
@abstractmethod

state: SimpleNamespace = (source) ¶

overridden in orionis.http.Request

Return the mutable per-request state namespace.

Middleware and handlers can attach arbitrary attributes to this namespace without polluting the scope dict.

Returns
`types.SimpleNamespace`	The mutable state object for this request.

@property
@abstractmethod

url: str = (source) ¶

overridden in orionis.http.Request

Return the full request URL.

Returns
`str`	Absolute URL including scheme, host, path, and query string. Result is cached after the first call.

@property
@abstractmethod

userAgent: str | None = (source) ¶

overridden in orionis.http.Request

Return the User-Agent string from the request headers.

Returns
`str \| None`	The User-Agent string if present, otherwise None.