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

Render the framework default HTTP error and status responses.

Static Method __fileResponse Build an independent response for an available regular file.
Method __contains__ Check if the cache contains the specified key.
Method __delitem__ Remove an item from the memory cache by key.
Method __getitem__ Retrieve a cached value by key.
Method __init__ Initialize instance with application and directory dependencies.
Async Method __publicFile Select a public file and recover when a previously selected file vanishes.
Method __refreshContext Refresh application labels and expire health bodies when they change.
Async Method __render Render a built-in template through the application's official engine.
Method __setitem__ Store a value in the cache with the specified key.
Method asset Serve a whitelisted package asset without exposing arbitrary files.
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.
Constant _ASSET_BASE Asset base used by DefaultResponses.
Constant _ASSET_HEADERS Asset headers used by DefaultResponses.
Constant _ASSETS_DIR Assets dir used by DefaultResponses.
Constant _FAVICON_CACHE_CONTROL_AGE public, max-age=31536000, immutable.
Constant _FAVICON_CANDIDATES Favicon candidates in order of preference.
Constant _FAVICON_NAME favicon.ico.
Constant _FONT_CONTENT_TYPE font/ttf.
Constant _GENERAL_CACHE_CONTROL no-cache, no-store, must-revalidate.
Constant _HEALTH_STATES Map the maintenance flag to the health response metadata.
Constant _NO_CACHE_HEADERS No cache headers definitions used by DefaultResponses.
Constant _ROBOTS_CANDIDATES Robots candidates definitions used by DefaultResponses.
Constant _SITEMAP_CANDIDATES Sitemap candidates definitions used by DefaultResponses.
Constant _TEMPLATES Templates definitions used by DefaultResponses.
Constant _WEB_FONT_CONTENT_TYPE font/woff2.
Constant ASSET_PREFIX Only these package-owned files can be served through the reserved URL.
Class Variable __slots__ Declare the instance attribute slots reserved by this class.
Instance Variable __app The application instance providing configuration and services.
Instance Variable __app_locale App locale produced by self.__app.config.
Instance Variable __app_name Store the application name and locale.
Instance Variable __asset_paths Resolved paths of assets used by the default response templates.
Instance Variable __directory The directory service for accessing storage paths.
Instance Variable __engine Official asynchronous template rendering engine.
Instance Variable __memory_cache Initialize storage for asset paths and rendered page bodies.
def __fileResponse(path: Path, headers: dict[str, str]) -> FileResponse | None: (source)

Build an independent response for an available regular file.

Parameters
path:pathlib.PathCandidate file whose current metadata is read by FileResponse.
headers:dict[str, str]Fixed file headers including its content type.
Returns
orionis.http.FileResponse | NoneNew response, or None when the file is unavailable or not regular.
def __contains__(self, key: str) -> bool: (source)

Check if the cache contains the specified key.

Parameters
key:strThe key to check for existence in the cache.
Returns
boolTrue if the key exists in the cache, False otherwise.
def __delitem__(self, key: str): (source)

Remove an item from the memory cache by key.

Parameters
key:strThe key to remove from the cache.
Returns
NoneThis method does not return a value.
def __getitem__(self, key: str) -> object | None: (source)

Retrieve a cached value by key.

Parameters
key:strThe key to look up in the cache.
Returns
object or NoneThe cached value if found, otherwise None.
def __init__(self, app: IApplication, directory: Directory, engine: IViewEngine): (source)

Initialize instance with application and directory dependencies.

Parameters
app:orionis.IApplicationThe application instance providing configuration and services.
directory:orionis.foundation.contracts.directory.IDirectoryThe directory service for accessing storage paths.
engine:orionis.view.contracts.engine.IViewEngineOfficial asynchronous template rendering engine.
Returns
NoneThis constructor does not return a value.
async def __publicFile(self, key: str, candidates: tuple[tuple[str, dict[str, str]], ...], missing_message: str, *, fallback: tuple[str, dict[str, str]] | None = None) -> FileResponse | HTMLResponse: (source)

Select a public file and recover when a previously selected file vanishes.

Parameters
key:strCache entry for the selected path and headers.
candidates:tuple[tuple[str, dict[str, str]], ...]Public filenames and headers in order of preference.
missing_message:strDescription displayed when no candidate is available.
fallback:tuple[str, dict[str, str]] | None, optionalPackage filename and headers used when no public file exists.
Returns
orionis.http.FileResponse | orionis.http.HTMLResponseIndependent file stream or an HTML error response.
def __refreshContext(self): (source)

Refresh application labels and expire health bodies when they change.

Returns
NoneUpdate the labels used by subsequent template renders.
async def __render(self, page: str, context: dict[str, object]) -> str: (source)

Render a built-in template through the application's official engine.

Parameters
page:strInternal template name, selected by this response service.
context:dict[str, object]Owned request context, filled with common template values.
Returns
strRendered HTML document.
def __setitem__(self, key: str, value: object): (source)

Store a value in the cache with the specified key.

Parameters
key:strThe key under which to store the value.
value:objectThe value to store in the cache.
Returns
NoneThis method does not return a value.
def asset(self, path: str) -> FileResponse | Response: (source)

Serve a whitelisted package asset without exposing arbitrary files.

Parameters
path:strExact asset name relative to the reserved asset URL prefix.
Returns
orionis.http.FileResponse | orionis.http.ResponseLocal asset with its fixed MIME type, or an empty 404 response.
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. HTML renders the description as 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.
_ASSET_BASE: str = (source)

Asset base used by DefaultResponses.

Value
ASSET_PREFIX.rstrip('/')
_ASSET_HEADERS: ClassVar[dict[str, dict[str, str]]] = (source)

Asset headers used by DefaultResponses.

Value
{name: {'content-type': content_type, 'cache-control': 'public, max-age=3600', '↵
x-content-type-options': 'nosniff'} for name, content_type in (('default.css', '↵
text/css; charset=utf-8'), ('default.js', 'text/javascript; charset=utf-8'), (_F↵
AVICON_NAME, 'image/x-icon'), ('fonts/orbitron.ttf', _FONT_CONTENT_TYPE), ('font↵
s/share-tech-mono.ttf', _FONT_CONTENT_TYPE), ('fonts/fira-code.ttf', _FONT_CONTE↵
NT_TYPE), ('fonts/titillium-web-400-latin.woff2', _WEB_FONT_CONTENT_TYPE), ('fon↵
ts/titillium-web-400-latin-ext.woff2', _WEB_FONT_CONTENT_TYPE), ('fonts/titilliu↵
...
_ASSETS_DIR: Path = (source)

Assets dir used by DefaultResponses.

Value
Path(__file__).parent / 'assets'
_FAVICON_CACHE_CONTROL_AGE: str = (source)

public, max-age=31536000, immutable.

Value
'public, max-age=31536000, immutable'
_FAVICON_CANDIDATES: ClassVar[tuple[tuple[str, dict[str, str]], ...]] = (source)

Favicon candidates in order of preference.

Value
((_FAVICON_NAME,
  {'content-type': 'image/x-icon', 'cache-control': _FAVICON_CACHE_CONTROL_AGE})↵
,
 ('favicon.png',
  {'content-type': 'image/png', 'cache-control': _FAVICON_CACHE_CONTROL_AGE}),
 ('favicon.svg',
  {'content-type': 'image/svg+xml', 'cache-control': _FAVICON_CACHE_CONTROL_AGE}↵
...
_FAVICON_NAME: str = (source)

favicon.ico.

Value
'favicon.ico'
_FONT_CONTENT_TYPE: str = (source)

font/ttf.

Value
'font/ttf'
_GENERAL_CACHE_CONTROL: str = (source)

no-cache, no-store, must-revalidate.

Value
'no-cache, no-store, must-revalidate'
_HEALTH_STATES: ClassVar[dict[bool, tuple[HTTPStatus, str, str, str]]] = (source)

Map the maintenance flag to the health response metadata.

Value
{False: (HTTPStatus.OK, 'Online Application', 'up', 'state_page_200:html'),
 True: (HTTPStatus.SERVICE_UNAVAILABLE,
        'Application in Maintenance',
        'down',
        'state_page_503:html')}
_NO_CACHE_HEADERS: ClassVar[dict[str, str]] = (source)

No cache headers definitions used by DefaultResponses.

Value
{'cache-control': _GENERAL_CACHE_CONTROL}
_ROBOTS_CANDIDATES: ClassVar[tuple[tuple[str, dict[str, str]], ...]] = (source)

Robots candidates definitions used by DefaultResponses.

Value
(('robots.txt',
  {'content-type': 'text/plain', 'cache-control': 'public, max-age=3600'}))
_SITEMAP_CANDIDATES: ClassVar[tuple[tuple[str, dict[str, str]], ...]] = (source)

Sitemap candidates definitions used by DefaultResponses.

Value
(('sitemap.xml',
  {'content-type': 'application/xml', 'cache-control': 'public, max-age=600'}))

Templates definitions used by DefaultResponses.

Value
{'up': '__orionis__/default/up.html',
 'down': '__orionis__/default/down.html',
 'error': '__orionis__/default/error.html',
 'exception': '__orionis__/default/exception.html',
 'dump': '__orionis__/default/dump.html'}
_WEB_FONT_CONTENT_TYPE: str = (source)

font/woff2.

Value
'font/woff2'
ASSET_PREFIX: str = (source)

Only these package-owned files can be served through the reserved URL.

Value
'/_orionis/assets/'
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

__app: IApplication = (source)

The application instance providing configuration and services.

__app_locale: str = (source)

App locale produced by self.__app.config.

__app_name: str = (source)

Store the application name and locale.

__asset_paths: dict[str, Path] = (source)

Resolved paths of assets used by the default response templates.

The directory service for accessing storage paths.

Official asynchronous template rendering engine.

__memory_cache: dict[str, object] = (source)

Initialize storage for asset paths and rendered page bodies.