ORIONIS API REFERENCE

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.

class documentation

Represent an HTTP response with status, headers, cookies and body.

Method __init__ Initialize the BaseResponse object.
Method addHeader Add a header to the response.
Method deleteCookie Delete a cookie by setting its expiration to the past.
Method getBody Return the response body as bytes.
Method getFlashData Return the data queued by withFlash() for the session flash bag.
Method getHeader Get the values for a header.
Method getMediaType Return the media type of the response.
Method getRawHeaders Return the headers as a list of (key, value) byte tuples.
Method getStatusCode Return the HTTP status code of the response.
Method getStream Return the response stream if present.
Method getStringHeaders Return the headers as a list of (key, value) string tuples.
Method hasHeader Check if a header is present.
Method hasStream Check if the response has a stream.
Method removeHeader Remove a header from the response.
Method render Render the content to bytes.
Async Method runBackground Run the background task if it exists.
Method setCookie Set a cookie header in the response.
Method setHeader Set a header, replacing any existing values.
Method withBackground Set the background task and return the response.
Method withCookie Attach a cookie and return the response for chaining.
Method withCookies Attach several cookies at once and return the response.
Method withHeaders Merge response headers and return the response.
Method withoutCookie Expire a cookie and return the response for chaining.
Method withStatusCode Set the HTTP status code and return the response.
Class Variable __slots__ Declare the instance attribute slots reserved by this class.
Class Variable charset Encode text responses using UTF-8.
Instance Variable _body HTTP response body or encoded payload returned to the client.
Instance Variable _flash Initialize flash data when it is first queued.
Instance Variable _headers The headers to include in the response.
Instance Variable _raw_headers Protocol-ready header pairs emitted with the response.
Instance Variable _stream Iterator supplying response body chunks.
Instance Variable background The background task to run after response.
Instance Variable media_type The media type of the response.
Instance Variable status_code The HTTP status code for the response.

Inherited from _FlashData:

Method withErrors Flash validation errors for the next request.
Method withFlash Queue a status message for the owning response or pending view.
Method withInput Flash the submitted payload so the next request can repopulate it.
def __init__(self: Self, content: Any | None = None, status_code: HTTPStatus | int = 200, headers: Mapping[str, str] | None = None, media_type: str | None = None, background: BackgroundTask | None = None): (source)

Initialize the BaseResponse object.

Parameters
content:typing.Any, optionalThe response content or stream.
status_code:orionis.http.enums.HTTPStatus | int, optionalThe HTTP status code for the response.
headers:collections.abc.Mapping[str, str] | None, optionalThe headers to include in the response.
media_type:str | None, optionalThe media type of the response.
background:orionis.background.BackgroundTask | None, optionalThe background task to run after response.
Returns
NoneThis method does not return a value.
def addHeader(self: Self, key: str, value: str): (source)

Add a header to the response.

Parameters
key:strThe header name.
value:strThe header value.
Returns
NoneThis method does not return a value.
def deleteCookie(self: Self, key: str, *, path: str = '/', domain: str | None = None): (source)

Delete a cookie by setting its expiration to the past.

Parameters
key:strThe name of the cookie to delete.
path:str, default "/"The path for which the cookie is valid.
domain:str | None, optionalThe domain for which the cookie is valid.
Returns
NoneThis method does not return a value.
def getBody(self: Self) -> bytes | None: (source)

Return the response body as bytes.

Returns
bytes | NoneThe response body as bytes, or None if not set.
def getFlashData(self: Self) -> dict[str, Any] | None: (source)

Return the data queued by withFlash() for the session flash bag.

Returns
dict[str, typing.Any] | NoneThe queued key-value pairs, or None when nothing was queued.
def getHeader(self: Self, key: str) -> list[str] | None: (source)

Get the values for a header.

Parameters
key:strThe header name.
Returns
list[str] | NoneThe list of header values, or None if not present.
def getMediaType(self: Self) -> str | None: (source)

Return the media type of the response.

Returns
str | NoneThe media type, or None if not set.
def getRawHeaders(self: Self) -> list[tuple[bytes, bytes]]: (source)

Return the headers as a list of (key, value) byte tuples.

Returns
list of tuple of (bytes, bytes)The headers as (key, value) pairs encoded in latin-1.
def getStatusCode(self: Self) -> int: (source)

Return the HTTP status code of the response.

Returns
intThe HTTP status code.
def getStream(self: Self) -> AsyncIterable[bytes] | None: (source)

Return the response stream if present.

Returns
collections.abc.AsyncIterable[bytes] | NoneThe response stream, or None if not set.
def getStringHeaders(self: Self) -> list[tuple[str, str]]: (source)

Return the headers as a list of (key, value) string tuples.

Returns
list of tuple of strThe headers represented as (key, value) string pairs.
def hasHeader(self: Self, key: str) -> bool: (source)

Check if a header is present.

Parameters
key:strThe header name.
Returns
boolTrue if the header is present, False otherwise.
def hasStream(self: Self) -> bool: (source)

Check if the response has a stream.

Returns
boolTrue if a stream is present, False otherwise.
def removeHeader(self: Self, key: str): (source)

Remove a header from the response.

Parameters
key:strThe header name.
Returns
NoneThis method does not return a value.
def render(self: Self, content: Any) -> bytes: (source)

Render the content to bytes.

Parameters
content:typing.AnyThe content to render.
Returns
bytesThe rendered content as bytes.
async def runBackground(self: Self): (source)

Run the background task if it exists.

Returns
NoneThis method does not return a value.
def setCookie(self: Self, key: str, value: str = '', *, max_age: int | None = None, expires: datetime | str | int | None = None, path: str | None = '/', domain: str | None = None, secure: bool = False, http_only: bool = False, same_site: Literal['lax', 'strict', 'none'] | None = 'lax', partitioned: bool = False): (source)

Set a cookie header in the response.

Parameters
key:strThe cookie name.
value:str, optionalThe cookie value. Defaults to an empty string.
max_age:int | None, optionalThe maximum age of the cookie in seconds.
expires:datetime.datetime | str | int | None, optionalThe expiration date of the cookie.
path:str | None, optionalThe path for which the cookie is valid.
domain:str | None, optionalThe domain for which the cookie is valid.
secure:bool, optionalWhether the cookie is secure.
http_only:bool, optionalWhether the cookie is HTTP only.
same_site:str | None, optionalThe SameSite policy for the cookie.
partitioned:bool, optionalWhether the cookie is partitioned.
Returns
NoneThis method does not return a value.
def setHeader(self: Self, key: str, value: str): (source)

Set a header, replacing any existing values.

Parameters
key:strThe header name.
value:strThe header value.
Returns
NoneThis method does not return a value.
def withBackground(self: Self, background: BackgroundTask | None) -> Self: (source)

Set the background task and return the response.

Parameters
background:orionis.background.BackgroundTask | NoneTask to run after the response is sent, or None to clear it.
Returns
typing.SelfThe same response, enabling fluent chaining.
Raises
TypeErrorIf background is neither a background task nor None.
def withCookie(self: Self, key: str, value: str = '', *, max_age: int | None = None, expires: datetime | str | int | None = None, path: str | None = '/', domain: str | None = None, secure: bool = False, http_only: bool = False, same_site: Literal['lax', 'strict', 'none'] | None = 'lax', partitioned: bool = False) -> Self: (source)

Attach a cookie and return the response for chaining.

Parameters
key:strThe cookie name.
value:str, optionalThe cookie value. Defaults to an empty string.
max_age:int | None, optionalThe maximum age of the cookie in seconds.
expires:datetime.datetime | str | int | None, optionalThe expiration date of the cookie.
path:str | None, optionalThe path for which the cookie is valid.
domain:str | None, optionalThe domain for which the cookie is valid.
secure:bool, optionalWhether the cookie is secure.
http_only:bool, optionalWhether the cookie is HTTP only.
same_site:str | None, optionalThe SameSite policy for the cookie.
partitioned:bool, optionalWhether the cookie is partitioned.
Returns
typing.SelfThe same response instance, allowing fluent chaining.
def withCookies(self: Self, cookies: Mapping[str, str | Mapping[str, Any]]) -> Self: (source)

Attach several cookies at once and return the response.

Parameters
cookies:typing.Mapping[str, str | typing.Mapping[str, typing.Any]]Mapping of cookie names to either a plain value or a mapping of keyword arguments accepted by orionis.http.Response.setCookie.
Returns
typing.SelfThe same response instance, allowing fluent chaining.
def withHeaders(self: Self, headers: Mapping[str, str]) -> Self: (source)

Merge response headers and return the response.

Replace existing values for each supplied name without changing unrelated headers. Header names are compared without regard to case.

Parameters
headers:collections.abc.Mapping[str, str]Header names and values to apply through setHeader().
Returns
typing.SelfThe same response, enabling fluent chaining.
Raises
TypeErrorIf headers is not a mapping.
def withoutCookie(self: Self, key: str, *, path: str = '/', domain: str | None = None) -> Self: (source)

Expire a cookie and return the response for chaining.

Parameters
key:strThe name of the cookie to delete.
path:str, default "/"The path for which the cookie is valid.
domain:str | None, optionalThe domain for which the cookie is valid.
Returns
typing.SelfThe same response instance, allowing fluent chaining.
def withStatusCode(self: Self, status_code: HTTPStatus | int) -> Self: (source)

Set the HTTP status code and return the response.

Parameters
status_code:orionis.http.enums.HTTPStatus | intHTTP status code between 100 and 599.
Returns
typing.SelfThe same response, enabling fluent chaining.
Raises
TypeErrorIf status_code is not an integer.
ValueErrorIf status_code is outside the accepted HTTP range.
charset: ClassVar[str] = (source)

Encode text responses using UTF-8.

HTTP response body or encoded payload returned to the client.

_flash: dict[str, Any] | None = (source)

Initialize flash data when it is first queued.

_headers: dict[str, str | list[str]] = (source)

The headers to include in the response.

_raw_headers: tuple[tuple[bytes, bytes], ...] | None = (source)

Protocol-ready header pairs emitted with the response.

_stream: AsyncIterable[bytes] | None = (source)

Iterator supplying response body chunks.

background = (source)

The background task to run after response.

media_type = (source)

The media type of the response.

status_code = (source)

The HTTP status code for the response.