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

Define the contract for default responses implementations.

Method asset Return an allowlisted framework asset, or a 404 response.
Async Method dump Wrap an escaped variable dump in the framework's diagnostic layout.
Async Method error Return an error page or JSON response for the specified status code.
Async Method exception Render an exception page with request and traceback details.
Async Method favicon Return the favicon file response or a 404 response if not found.
Async Method health Render the application health state as an HTML or JSON response.
Async Method robotsTxt Return the robots.txt file or a 404 response if not found.
Async Method sitemapXml Return the public sitemap.xml file, or a 404 response when absent.
Class Variable __slots__ Declare that this class introduces no additional instance slots.
def asset(self, path: str) -> FileResponse | Response: (source)

Return an allowlisted framework asset, or a 404 response.

Parameters
path:strAsset path relative to the framework's public asset prefix.
Returns
orionis.http.FileResponse or orionis.http.ResponsePackaged static file when allowed and present, otherwise a 404.
async def dump(self, content: str) -> HTMLResponse: (source)

Wrap an escaped variable dump in the framework's diagnostic layout.

Parameters
content:strTrusted HTML fragment produced by VarDumper.toHtml(). Variable values and type labels must already be escaped.
Returns
orionis.http.HTMLResponseUncached debug page using the shared local styles and fonts.
async def error(self, status_code: int | HTTPStatus, content: str | dict, *, expects_json: bool, headers: dict[str, str] | None = None) -> HTMLResponse | JSONResponse: (source)

Return an error page or JSON response for the specified status code.

Parameters
status_code:int | orionis.http.enums.HTTPStatusInteger HTTP status between 100 and 599. Unlisted codes use an HTTP <code> label on the HTML page.
content:str | dictContent of the error to display. A str is used as the message; a dict is serialised directly into the JSON payload or extracted via its message key for HTML rendering. The HTML description is escaped text; JSON preserves the supplied values.
expects_json:boolIf True, returns a JSON response; otherwise, returns HTML.
headers:dict[str, str] | None, optionalAdditional headers to include in the response.
Returns
orionis.http.HTMLResponse or orionis.http.JSONResponseHTMLResponse with rendered error page, or JSONResponse if expects_json is True.
Raises
TypeErrorIf status_code is not an integer.
ValueErrorIf status_code is outside the range 100 to 599.
async def exception(self, request_path: str, request_method: str, exception: BaseException, status_code: int | HTTPStatus = HTTPStatus.INTERNAL_SERVER_ERROR) -> HTMLResponse: (source)

Render an exception page with request and traceback details.

Parameters
request_path:strPath of the request that caused the exception.
request_method:strHTTP method of the request that caused the exception.
exception:BaseExceptionException instance to be rendered.
status_code:int | orionis.http.enums.HTTPStatus, optionalHTTP status code for the response. Defaults to 500.
Returns
orionis.http.HTMLResponseRendered exception page as an HTMLResponse with the given status code.
async def favicon(self) -> FileResponse | Response: (source)

Return the favicon file response or a 404 response if not found.

Searches for a favicon in the public storage directory using common favicon file names and content types. If not found, attempts to use the framework's internal fallback favicon. Caches the result for subsequent calls.

Returns
orionis.http.FileResponse or orionis.http.ResponseA FileResponse containing the favicon if found, otherwise a Response with status 404.
async def health(self, request: Request) -> HTMLResponse | JSONResponse: (source)

Render the application health state as an HTML or JSON response.

Parameters
request:orionis.http.RequestThe HTTP request object.
Returns
orionis.http.HTMLResponse or orionis.http.JSONResponseHTMLResponse with the state page content or JSONResponse with the application status. Status is 200 if healthy, 503 if under maintenance.
async def robotsTxt(self) -> FileResponse | Response: (source)

Return the robots.txt file or a 404 response if not found.

Search for a robots.txt file in the public storage directory. If not found, check for a fallback file. Cache the result for future calls.

Returns
orionis.http.FileResponse or orionis.http.ResponseFileResponse with robots.txt if found, otherwise Response with 404.
async def sitemapXml(self) -> FileResponse | Response: (source)

Return the public sitemap.xml file, or a 404 response when absent.

Retain the selected path and read its current metadata for each response.

Returns
orionis.http.FileResponse or orionis.http.ResponseFileResponse with sitemap.xml if found, otherwise Response with status 404.
__slots__: tuple = (source)

Declare that this class introduces no additional instance slots.