orionis.http.default.responses.DefaultResponses

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.

Explore modules View classes

class documentation

class DefaultResponses(IDefaultResponses): (source)

Constructor: DefaultResponses(app, directory, engine)

View In Hierarchy

Undocumented

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	`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`	Undocumented
Constant	`_ASSET_HEADERS`	Undocumented
Constant	`_ASSETS_DIR`	Undocumented
Constant	`_FAVICON_CACHE_CONTROL_AGE`	Undocumented
Constant	`_FAVICON_CANDIDATES`	Undocumented
Constant	`_FAVICON_NAME`	Undocumented
Constant	`_FONT_CONTENT_TYPE`	Undocumented
Constant	`_GENERAL_CACHE_CONTROL`	Undocumented
Constant	`_HEALTH_STATES`	Undocumented
Constant	`_NO_CACHE_HEADERS`	Undocumented
Constant	`_ROBOTS_CANDIDATES`	Undocumented
Constant	`_SITEMAP_CANDIDATES`	Undocumented
Constant	`_TEMPLATES`	Undocumented
Constant	`ASSET_PREFIX`	Undocumented
Class Variable	`__slots__`	Undocumented
Instance Variable	`__app`	Undocumented
Instance Variable	`__app_locale`	Undocumented
Instance Variable	`__app_name`	Undocumented
Instance Variable	`__asset_paths`	Undocumented
Instance Variable	`__directory`	Undocumented
Instance Variable	`__engine`	Undocumented
Instance Variable	`__memory_cache`	Undocumented

@staticmethod

def __fileResponse(path: Path, headers: dict[str, str]) -> FileResponse | None: (source) ¶

Build an independent response for an available regular file.

Parameters
path:`Path`	Candidate file whose current metadata is read by FileResponse.
headers:`dict[str, str]`	Fixed file headers including its content type.

Returns
`FileResponse \| None`	New 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:`str`	The key to check for existence in the cache.

Returns
`bool`	True 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:`str`	The key to remove from the cache.

Returns
`None`	This method does not return a value.

def __getitem__(self, key: str) -> object | None: (source) ¶

Retrieve a cached value by key.

Parameters
key:`str`	The key to look up in the cache.

Returns
`object or None`	The 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:`IApplication`	The application instance providing configuration and services.
directory:`IDirectory`	The directory service for accessing storage paths.
engine:`IViewEngine`	Official asynchronous template rendering engine.

Returns
`None`	This 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:`str`	Cache entry for the selected path and headers.
candidates:`tuple[tuple[str, dict[str, str]], ...]`	Public filenames and headers in order of preference.
missing_message:`str`	Description displayed when no candidate is available.
fallback:`tuple[str, dict[str, str]] \| None, optional`	Package filename and headers used when no public file exists.

Returns
`FileResponse \| HTMLResponse`	Independent file stream or an HTML error response.

def __refreshContext(self): (source) ¶

Refresh application labels and expire health bodies when they change.

Returns
`None`	Update 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:`str`	Internal template name, selected by this response service.
context:`dict[str, object]`	Owned request context, filled with common template values.

Returns
`str`	Rendered HTML document.

def __setitem__(self, key: str, value: object): (source) ¶

Store a value in the cache with the specified key.

Parameters
key:`str`	The key under which to store the value.
value:`object`	The value to store in the cache.

Returns
`None`	This method does not return a value.

def asset(self, path: str) -> FileResponse | Response: (source) ¶

overrides orionis.http.default.contracts.responses.IDefaultResponses.asset

Serve a whitelisted package asset without exposing arbitrary files.

Parameters
path:`str`	Exact asset name relative to the reserved asset URL prefix.

Returns
`FileResponse \| Response`	Local asset with its fixed MIME type, or an empty 404 response.

async def error(self, status_code: int | HTTPStatus, content: str | dict, *, expects_json: bool, headers: dict[str, str] | None = None) -> HTMLResponse | JSONResponse: (source) ¶

overrides orionis.http.default.contracts.responses.IDefaultResponses.error

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

Parameters
status_code:`int \| HTTPStatus`	Integer HTTP status between 100 and 599. Unlisted codes use an `HTTP <code>` label on the HTML page.
content:`str \| dict`	Content of the error to display. HTML renders the description as escaped text; JSON preserves the supplied values.
expects_json:`bool`	If True, returns a JSON response; otherwise, returns HTML.
headers:`dict[str, str] \| None, optional`	Additional headers to include in the response.

Returns
`HTMLResponse or JSONResponse`	HTMLResponse with rendered error page, or JSONResponse if expects_json is True.

Raises
`TypeError`	If status_code is not an integer.
`ValueError`	If 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) ¶

overrides orionis.http.default.contracts.responses.IDefaultResponses.exception

Render an exception page with request and traceback details.

Parameters
request_path:`str`	Path of the request that caused the exception.
request_method:`str`	HTTP method of the request that caused the exception.
exception:`BaseException`	Exception instance to be rendered.
status_code:`int \| HTTPStatus, optional`	HTTP status code for the response. Defaults to 500.

Returns
`HTMLResponse`	Rendered exception page as an HTMLResponse with the given status code.

async def favicon(self) -> FileResponse | Response: (source) ¶

overrides orionis.http.default.contracts.responses.IDefaultResponses.favicon

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
`FileResponse or Response`	A FileResponse containing the favicon if found, otherwise a Response with status 404.

async def health(self, request: Request) -> HTMLResponse | JSONResponse: (source) ¶

overrides orionis.http.default.contracts.responses.IDefaultResponses.health

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

Parameters
request:`Request`	The HTTP request object.

Returns
`HTMLResponse or JSONResponse`	HTMLResponse 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) ¶

overrides orionis.http.default.contracts.responses.IDefaultResponses.robotsTxt

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
`FileResponse or Response`	FileResponse with robots.txt if found, otherwise Response with 404.

async def sitemapXml(self) -> FileResponse | Response: (source) ¶

overrides orionis.http.default.contracts.responses.IDefaultResponses.sitemapXml

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
`FileResponse or Response`	FileResponse with sitemap.xml if found, otherwise Response with status 404.

_ASSET_BASE: str = (source) ¶

Undocumented

Value

ASSET_PREFIX.rstrip('/')

_ASSET_HEADERS: ClassVar[dict[str, dict[str, str]]] = (source) ¶

Undocumented

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))}

_ASSETS_DIR: Path = (source) ¶

Undocumented

Value

Path(__file__).parent / 'assets'

_FAVICON_CACHE_CONTROL_AGE: str = (source) ¶

Undocumented

Value

'public, max-age=31536000, immutable'

_FAVICON_CANDIDATES: ClassVar[tuple[tuple[str, dict[str, str]], ...]] = (source) ¶

Undocumented

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) ¶

Undocumented

Value

'favicon.ico'

_FONT_CONTENT_TYPE: str = (source) ¶

Undocumented

Value

'font/ttf'

_GENERAL_CACHE_CONTROL: str = (source) ¶

Undocumented

Value

'no-cache, no-store, must-revalidate'

_HEALTH_STATES: ClassVar[dict[bool, tuple[HTTPStatus, str, str, str]]] = (source) ¶

Undocumented

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) ¶

Undocumented

Value

{'cache-control': _GENERAL_CACHE_CONTROL}

_ROBOTS_CANDIDATES: ClassVar[tuple[tuple[str, dict[str, str]], ...]] = (source) ¶

Undocumented

Value

(('robots.txt',
  {'content-type': 'text/plain', 'cache-control': 'public, max-age=3600'}))

_SITEMAP_CANDIDATES: ClassVar[tuple[tuple[str, dict[str, str]], ...]] = (source) ¶

Undocumented

Value

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

_TEMPLATES: ClassVar[dict[str, str]] = (source) ¶

Undocumented

Value

{'up': '__orionis__/default/up.html',
 'down': '__orionis__/default/down.html',
 'error': '__orionis__/default/error.html',
 'exception': '__orionis__/default/exception.html'}