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

class ResponseFactory: (source)

View In Hierarchy

Build every kind of HTTP response from a single entry-point.

Controllers use the module-level orionis.http.response instance so they do not need to import a different class for each response type:

return response.view("users.index", users=users)
return response.json({"ok": True})
return response.redirect("/login")
Method download Build a file response forced to be downloaded as an attachment.
Method eventStream Build a streaming response carrying UTF-8 server-sent events.
Method file Build a response streaming a file from disk.
Method html Build a response carrying raw HTML content.
Method json Build a response serialising the content as JSON.
Method make Build a bare response with full control over its content.
Method noContent Build an empty response, typically for 204 No Content.
Method redirect Build a response redirecting the client to another URL.
Method stream Build a response streaming byte chunks to the client.
Method text Build a response carrying plain text content.
Method view Render a template as an awaitable, chainable HTML response.
Class Variable __slots__ Declare that this class introduces no additional instance slots.
def download(self, path: str | Path, filename: str | None = None, headers: Mapping[str, str] | None = None, media_type: str | None = None, background: BackgroundTask | None = None) -> FileResponse: (source)

Build a file response forced to be downloaded as an attachment.

Parameters
path:str | pathlib.PathPath to the file to serve.
filename:str | None, optionalName advertised to the client; defaults to the file name.
headers:collections.abc.Mapping[str, str] | None, optionalExtra headers to include.
media_type:str | None, optionalMedia type of the file; guessed from the path when omitted.
background:orionis.background.BackgroundTask | None, optionalTask to run after the response is sent.
Returns
orionis.http.FileResponseThe configured attachment response.
def eventStream(self, content: AsyncIterable[ServerSentEvent | str] | Iterable[ServerSentEvent | str], status_code: HTTPStatus | int = 200, headers: Mapping[str, str] | None = None, background: BackgroundTask | None = None) -> EventStreamResponse: (source)

Build a streaming response carrying UTF-8 server-sent events.

Parameters
content:AsyncIterable[ServerSentEvent | str] | Iterable[ServerSentEvent | str]Typed events or text payloads, consumed lazily during delivery.
status_code:orionis.http.enums.HTTPStatus | int, optionalHTTP status code for the response.
headers:collections.abc.Mapping[str, str] | None, optionalExtra headers; Content-Length is discarded.
background:orionis.background.BackgroundTask | None, optionalTask to run after successful delivery and stream cleanup.
Returns
orionis.http.EventStreamResponseThe configured server-sent event response.
def file(self, path: str | Path, status_code: HTTPStatus | int = 200, headers: Mapping[str, str] | None = None, media_type: str | None = None, filename: str | None = None, chunk_size: int = 64 * 1024, background: BackgroundTask | None = None) -> FileResponse: (source)

Build a response streaming a file from disk.

Parameters
path:str | pathlib.PathPath to the file to serve.
status_code:orionis.http.enums.HTTPStatus | int, optionalThe HTTP status code for the response.
headers:collections.abc.Mapping[str, str] | None, optionalExtra headers to include.
media_type:str | None, optionalMedia type of the file; guessed from the path when omitted.
filename:str | None, optionalName advertised in the Content-Disposition header.
chunk_size:int, optionalSize of the chunks read from disk.
background:orionis.background.BackgroundTask | None, optionalTask to run after the response is sent.
Returns
orionis.http.FileResponseThe configured file response.
def html(self, content: str | bytes = '', status_code: HTTPStatus | int = 200, headers: Mapping[str, str] | None = None, background: BackgroundTask | None = None) -> HTMLResponse: (source)

Build a response carrying raw HTML content.

Parameters
content:str | bytes, optionalHTML content to send.
status_code:orionis.http.enums.HTTPStatus | int, optionalThe HTTP status code for the response.
headers:collections.abc.Mapping[str, str] | None, optionalExtra headers to include.
background:orionis.background.BackgroundTask | None, optionalTask to run after the response is sent.
Returns
orionis.http.HTMLResponseThe configured HTML response.
def json(self, content: Any, status_code: HTTPStatus | int = 200, headers: Mapping[str, str] | None = None, background: BackgroundTask | None = None, *, indent: int | None = None, ensure_ascii: bool = False, separators: tuple[str, str] | None = None, default: Any | None = None) -> JSONResponse: (source)

Build a response serialising the content as JSON.

Parameters
content:typing.AnyContent to serialise as JSON.
status_code:orionis.http.enums.HTTPStatus | int, optionalThe HTTP status code for the response.
headers:collections.abc.Mapping[str, str] | None, optionalExtra headers to include.
background:orionis.background.BackgroundTask | None, optionalTask to run after the response is sent.
indent:int | None, optionalIndentation level for pretty-printing JSON.
ensure_ascii:bool, optionalWhether to escape non-ASCII characters.
separators:tuple[str, str] | None, optionalItem and key separators for JSON output.
default:typing.Any | None, optionalCustom encoder for unsupported types.
Returns
orionis.http.JSONResponseThe configured JSON response.
def make(self, content: Any = None, status_code: HTTPStatus | int = 200, headers: Mapping[str, str] | None = None, media_type: str | None = None, background: BackgroundTask | None = None) -> Response: (source)

Build a bare response with full control over its content.

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, optionalExtra headers to include.
media_type:str | None, optionalMedia type advertised for the content.
background:orionis.background.BackgroundTask | None, optionalTask to run after the response is sent.
Returns
orionis.http.ResponseThe configured response.
def noContent(self, status_code: HTTPStatus | int = 204, headers: Mapping[str, str] | None = None, background: BackgroundTask | None = None) -> Response: (source)

Build an empty response, typically for 204 No Content.

Parameters
status_code:orionis.http.enums.HTTPStatus | int, optionalThe HTTP status code for the response.
headers:collections.abc.Mapping[str, str] | None, optionalExtra headers to include.
background:orionis.background.BackgroundTask | None, optionalTask to run after the response is sent.
Returns
orionis.http.ResponseThe configured empty response.
def redirect(self, url: str, status_code: HTTPStatus | int = 302, headers: Mapping[str, str] | None = None, background: BackgroundTask | None = None) -> RedirectResponse: (source)

Build a response redirecting the client to another URL.

Parameters
url:strTarget URL for the redirection.
status_code:orionis.http.enums.HTTPStatus | int, optionalRedirect status code (301, 302, 303, 307, 308).
headers:collections.abc.Mapping[str, str] | None, optionalExtra headers to include.
background:orionis.background.BackgroundTask | None, optionalTask to run after the response is sent.
Returns
orionis.http.RedirectResponseThe configured redirect response.
def stream(self, content: AsyncIterable[bytes] | Iterable[bytes], status_code: HTTPStatus | int = 200, headers: Mapping[str, str] | None = None, media_type: str | None = None, background: BackgroundTask | None = None) -> StreamingResponse: (source)

Build a response streaming byte chunks to the client.

Parameters
content:collections.abc.AsyncIterable[bytes] | collections.abc.Iterable[bytes]Streaming content source.
status_code:orionis.http.enums.HTTPStatus | int, optionalThe HTTP status code for the response.
headers:collections.abc.Mapping[str, str] | None, optionalExtra headers to include.
media_type:str | None, optionalMedia type advertised for the stream.
background:orionis.background.BackgroundTask | None, optionalTask to run after the response is sent.
Returns
orionis.http.StreamingResponseThe configured streaming response.
def text(self, content: str | bytes = '', status_code: HTTPStatus | int = 200, headers: Mapping[str, str] | None = None, background: BackgroundTask | None = None) -> PlainTextResponse: (source)

Build a response carrying plain text content.

Parameters
content:str | bytes, optionalPlain text content to send.
status_code:orionis.http.enums.HTTPStatus | int, optionalThe HTTP status code for the response.
headers:collections.abc.Mapping[str, str] | None, optionalExtra headers to include.
background:orionis.background.BackgroundTask | None, optionalTask to run after the response is sent.
Returns
orionis.http.PlainTextResponseThe configured plain text response.
def view(self, template: str, *, status_code: HTTPStatus | int = 200, headers: Mapping[str, str] | None = None, background: BackgroundTask | None = None, context: Mapping[str, Any] | None = None, **variables: Any) -> PendingView: (source)

Render a template as an awaitable, chainable HTML response.

Notes

Response options are validated when the pending view is awaited. Chained mutations are applied after the initial options, in call order.

Parameters
template:strTemplate name using dot notation (e.g. 'users.index') or a relative path (e.g. 'users/index.html').
status_code:orionis.http.enums.HTTPStatus | int, optionalHTTP status code for the rendered response.
headers:collections.abc.Mapping[str, str] | None, optionalResponse headers. The SSR marker is added when not supplied.
background:orionis.background.BackgroundTask | None, optionalTask to run after the response is sent.
context:collections.abc.Mapping[str, typing.Any] | None, optionalTemplate variables, including names reserved for response options.
**variables:typing.AnyAdditional template variables, overriding matching context entries.
Returns
orionis.view.pending.PendingViewAwaitable proxy that resolves to an orionis.http.HTMLResponse and accepts chained mutators such as withStatusCode() and withErrors().
Raises
TypeErrorIf context is neither a mapping nor None.
__slots__: tuple = (source)

Declare that this class introduces no additional instance slots.