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 ResponseFactory: (source)
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 | event |
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 | no |
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. |
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.Path | Path to the file to serve. |
filename:str | None, optional | Name advertised to the client; defaults to the file name. |
headers:collections.abc.Mapping[str, str] | None, optional | Extra headers to include. |
mediastr | None, optional | Media type of the file; guessed from the path when omitted. |
background:orionis.background.BackgroundTask | None, optional | Task to run after the response is sent. |
| Returns | |
orionis.http.FileResponse | The configured attachment response. |
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[ | Typed events or text payloads, consumed lazily during delivery. |
statusorionis.http.enums.HTTPStatus | int, optional | HTTP status code for the response. |
headers:collections.abc.Mapping[str, str] | None, optional | Extra headers; Content-Length is discarded. |
background:orionis.background.BackgroundTask | None, optional | Task to run after successful delivery and stream cleanup. |
| Returns | |
orionis.http.EventStreamResponse | The configured server-sent event response. |
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.Path | Path to the file to serve. |
statusorionis.http.enums.HTTPStatus | int, optional | The HTTP status code for the response. |
headers:collections.abc.Mapping[str, str] | None, optional | Extra headers to include. |
mediastr | None, optional | Media type of the file; guessed from the path when omitted. |
filename:str | None, optional | Name advertised in the Content-Disposition header. |
chunkint, optional | Size of the chunks read from disk. |
background:orionis.background.BackgroundTask | None, optional | Task to run after the response is sent. |
| Returns | |
orionis.http.FileResponse | The configured file response. |
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, optional | HTML content to send. |
statusorionis.http.enums.HTTPStatus | int, optional | The HTTP status code for the response. |
headers:collections.abc.Mapping[str, str] | None, optional | Extra headers to include. |
background:orionis.background.BackgroundTask | None, optional | Task to run after the response is sent. |
| Returns | |
orionis.http.HTMLResponse | The configured HTML response. |
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.Any | Content to serialise as JSON. |
statusorionis.http.enums.HTTPStatus | int, optional | The HTTP status code for the response. |
headers:collections.abc.Mapping[str, str] | None, optional | Extra headers to include. |
background:orionis.background.BackgroundTask | None, optional | Task to run after the response is sent. |
indent:int | None, optional | Indentation level for pretty-printing JSON. |
ensurebool, optional | Whether to escape non-ASCII characters. |
separators:tuple[str, str] | None, optional | Item and key separators for JSON output. |
default:typing.Any | None, optional | Custom encoder for unsupported types. |
| Returns | |
orionis.http.JSONResponse | The configured JSON response. |
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, optional | The response content or stream. |
statusorionis.http.enums.HTTPStatus | int, optional | The HTTP status code for the response. |
headers:collections.abc.Mapping[str, str] | None, optional | Extra headers to include. |
mediastr | None, optional | Media type advertised for the content. |
background:orionis.background.BackgroundTask | None, optional | Task to run after the response is sent. |
| Returns | |
orionis.http.Response | The configured response. |
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 | |
statusorionis.http.enums.HTTPStatus | int, optional | The HTTP status code for the response. |
headers:collections.abc.Mapping[str, str] | None, optional | Extra headers to include. |
background:orionis.background.BackgroundTask | None, optional | Task to run after the response is sent. |
| Returns | |
orionis.http.Response | The configured empty response. |
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:str | Target URL for the redirection. |
statusorionis.http.enums.HTTPStatus | int, optional | Redirect status code (301, 302, 303, 307, 308). |
headers:collections.abc.Mapping[str, str] | None, optional | Extra headers to include. |
background:orionis.background.BackgroundTask | None, optional | Task to run after the response is sent. |
| Returns | |
orionis.http.RedirectResponse | The configured redirect response. |
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. |
statusorionis.http.enums.HTTPStatus | int, optional | The HTTP status code for the response. |
headers:collections.abc.Mapping[str, str] | None, optional | Extra headers to include. |
mediastr | None, optional | Media type advertised for the stream. |
background:orionis.background.BackgroundTask | None, optional | Task to run after the response is sent. |
| Returns | |
orionis.http.StreamingResponse | The configured streaming response. |
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, optional | Plain text content to send. |
statusorionis.http.enums.HTTPStatus | int, optional | The HTTP status code for the response. |
headers:collections.abc.Mapping[str, str] | None, optional | Extra headers to include. |
background:orionis.background.BackgroundTask | None, optional | Task to run after the response is sent. |
| Returns | |
orionis.http.PlainTextResponse | The configured plain text response. |
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:str | Template name using dot notation (e.g. 'users.index') or a relative path (e.g. 'users/index.html'). |
statusorionis.http.enums.HTTPStatus | int, optional | HTTP status code for the rendered response. |
headers:collections.abc.Mapping[str, str] | None, optional | Response headers. The SSR marker is added when not supplied. |
background:orionis.background.BackgroundTask | None, optional | Task to run after the response is sent. |
context:collections.abc.Mapping[str, typing.Any] | None, optional | Template variables, including names reserved for response options. |
**variables:typing.Any | Additional template variables, overriding matching context entries. |
| Returns | |
orionis.view.pending.PendingView | Awaitable proxy that resolves to an orionis.http.HTMLResponse and
accepts chained mutators such as withStatusCode() and
withErrors(). |
| Raises | |
TypeError | If context is neither a mapping nor None. |