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.
Define application configuration, lifecycle and runtime entry points.
| Async Method | aclose |
Close a headless lifetime when the implementation owns one. |
| Async Method | boot |
Create the application and start eager providers for headless use. |
| Method | compile |
Configure bootstrap caching and restore any valid compiled state. |
| Method | config |
Read or update the mutable runtime configuration. |
| Method | create |
Create application configuration and register eager services once. |
| Async Method | get |
Resolve and cache the configured exception handler instance. |
| Method | get |
Resolve registered middleware classes in application execution order. |
| Async Method | get |
Resolve the scheduler class and build its instance. |
| Async Method | handle |
Run a CLI command within its startup and shutdown lifecycle. |
| Method | is |
Check the debug flag cached during application creation. |
| Method | is |
Check the production flag cached during application creation. |
| Method | on |
Register unique callbacks for a runtime's startup or shutdown event. |
| Method | path |
Return one configured application path or the read-only path mapping. |
| Method | reset |
Restore mutable runtime settings from the bootstrap configuration. |
| Method | routing |
Return mutable copies of configured routing paths. |
| Method | under |
Check effective maintenance mode using a short-lived worker cache. |
| Method | with |
Set application configuration overrides for bootstrap. |
| Method | with |
Set authentication configuration overrides for bootstrap. |
| Method | with |
Set cache configuration overrides for bootstrap. |
| Method | with |
Set database configuration overrides for bootstrap. |
| Method | with |
Set filesystem configuration overrides for bootstrap. |
| Method | with |
Set HTTP configuration overrides for bootstrap. |
| Method | with |
Set logging configuration overrides for bootstrap. |
| Method | with |
Set mail configuration overrides for bootstrap. |
| Method | with |
Set MCP protocol limits and allowed origins for bootstrap. |
| Method | with |
Configure resolved application directories with core path overrides. |
| Method | with |
Set queue configuration overrides for bootstrap. |
| Method | with |
Set session configuration overrides for bootstrap. |
| Method | with |
Set testing configuration overrides for bootstrap. |
| Method | with |
Set the exception handler class used for lazy singleton resolution. |
| Method | with |
Register unique middleware classes in application execution order. |
| Method | with |
Register eager or deferred service provider classes for bootstrap. |
| Method | with |
Configure route files and the health-check path for each protocol. |
| Method | with |
Set the scheduler class built by getScheduler. |
| Class Variable | __slots__ |
Declare that this class introduces no additional instance slots. |
| Property | are |
Check whether all eager providers have finished booting. |
| Property | base |
Return the resolved application root directory. |
| Property | compiled |
Check whether compiled bootstrap caching is enabled. |
| Property | compiled |
Return configured directories used for bootstrap cache invalidation. |
| Property | compiled |
Return configured files used for bootstrap cache invalidation. |
| Property | compiled |
Return the configured bootstrap cache directory. |
| Property | entry |
Return the creation entry point as a module path with an app suffix. |
| Property | is |
Report whether configuration and eager registration are complete. |
| Property | is |
Report the configuration-stage state exposed by isBooted. |
| Property | is |
Check whether eager providers and both HTTP handlers are ready. |
| Property | route |
Return the configured health-check URL path. |
| Property | start |
Return the instance initialization timestamp in Unix nanoseconds. |
Inherited from IContainer:
| Method | begin |
Begin a new scope context manager for scoped services. |
| Method | bound |
Determine if a key is bound in the container or current scope. |
| Async Method | build |
Build and return an instance of the specified type. |
| Async Method | call |
Invoke a method on an object instance with automatic dependency injection. |
| Method | get |
Get the current active scope context for scoped services. |
| Method | instance |
Register an existing object globally or in the active scope. |
| Async Method | invoke |
Invoke a callable with automatic dependency injection. |
| Async Method | make |
Resolve and return a service instance by key. |
| Method | scoped |
Register a scoped service binding. |
| Method | singleton |
Register a singleton service binding. |
| Method | transient |
Register a transient service binding. |
orionis.ApplicationClose a headless lifetime when the implementation owns one.
Keep the default implementation as a no-op for custom applications that do not manage headless reporting ownership.
| Returns | |
None | Release owned resources in overrides; do nothing in the default method. |
orionis.ApplicationCreate the application and start eager providers for headless use.
Coordinate repeated calls and acquire headless reporting ownership. Leave HTTP and CLI kernels and lifecycle callbacks to their runtimes.
| Returns | |
typing.Self | This application after all eager providers finish booting. |
| Raises | |
Exception | If creation, provider boot, or reporting startup fails. Unfinished providers remain pending for a later retry. |
Self, path: str | None = None, invalidation_paths: list[ str] | None = None):
(source)
¶
orionis.ApplicationConfigure bootstrap caching and restore any valid compiled state.
Notes
Core application path definitions are always monitored so framework updates invalidate outdated snapshots. Configuration setters leave restored snapshots unchanged.
| Parameters | |
path:str | None, optional | Cache directory, defaulting to the application's framework cache path. |
invalidationlist[str] | None, optional | Existing files or directories monitored relative to the application root, or None for no additional invalidation paths. |
| Returns | |
None | Configure the cache and commit a valid restored snapshot, if present. |
Self, key: str | None = None, value: object = _SENTINEL) -> object:
(source)
¶
orionis.ApplicationRead or update the mutable runtime configuration.
| Parameters | |
key:str or None, optional | Dot-separated key, or None with no value to return all settings. |
value:object, optional | Replacement value; omit to read the key. Explicit None is stored. |
| Returns | |
object | Requested value, assigned value, or the full mutable mapping. Missing keys and non-dictionary parents return None on reads. |
| Raises | |
RuntimeError | If the application configuration is not initialized. |
TypeError | If a keyed read or write uses a non-string key. |
orionis.ApplicationCreate application configuration and register eager services once.
Apply locale settings and cache runtime flags without awaiting asynchronous provider boots or preparing HTTP handlers.
| Returns | |
typing.Self | This application after configuration and registration complete. |
| Raises | |
TypeError | If http.monitor_disconnects is neither a boolean nor None. |
orionis.ApplicationResolve and cache the configured exception handler instance.
Construct shared dependencies outside request and operation scopes.
| Returns | |
orionis.failure.contracts.handler.IBaseExceptionHandler | Shared handler instance, using the core default when not overridden. |
| Raises | |
RuntimeError | If application creation has not completed. |
orionis.ApplicationResolve registered middleware classes in application execution order.
| Returns | |
list[type[orionis.http.layer.contracts.middleware.IBaseMiddleware]] | Registered classes in order, or an empty list when none are stored. |
orionis.ApplicationResolve the scheduler class and build its instance.
| Returns | |
orionis.console.base.contracts.scheduler.IBaseScheduler | Instance built from the cached configured scheduler class. |
| Raises | |
RuntimeError | If application creation has not completed. |
Self, args: list[ str] | None = None) -> int:
(source)
¶
orionis.ApplicationRun a CLI command within its startup and shutdown lifecycle.
| Parameters | |
args:list of str or None, optional | Command arguments, or None to pass an empty argument list. |
| Returns | |
int | Exit code returned by the CLI kernel. |
| Raises | |
RuntimeError | If no CLI kernel is configured. |
TypeError | If the configured kernel does not implement the CLI interface. |
orionis.ApplicationCheck the debug flag cached during application creation.
| Returns | |
bool | True only when the creation-time app.debug value is True. |
| Raises | |
RuntimeError | If application creation has not completed. |
orionis.ApplicationCheck the production flag cached during application creation.
| Returns | |
bool | True when the creation-time app.env string contains "prod". |
| Raises | |
RuntimeError | If application creation has not completed. |
Self, lifespan: Lifespan, *callbacks: Callable[ ..., Any] | Callable[ ..., Awaitable[ Any]], runtime: Runtime | None = None) -> Self:
(source)
¶
orionis.ApplicationRegister unique callbacks for a runtime's startup or shutdown event.
Notes
Callbacks are deduplicated in sets; execution order is unspecified.
| Parameters | |
lifespan:orionis.foundation.enums.lifespan.Lifespan | Lifecycle event that triggers the callbacks. |
*callbacks:collections.abc.Callable | Synchronous or asynchronous callbacks invoked through the container. |
runtime:orionis.foundation.enums.runtimes.Runtime or None, optional | Target runtime, or None for callbacks shared by HTTP and CLI. |
| Returns | |
typing.Self | This application for method chaining. |
| Raises | |
TypeError | If the event/runtime type is invalid or a callback is not callable. |
ValueError | If no callbacks are provided or the runtime selector is unknown. |
Self, key: str | None = None) -> Path | Mapping[ str, Path] | None:
(source)
¶
orionis.ApplicationReturn one configured application path or the read-only path mapping.
| Parameters | |
key:str | None, optional | Core path name, or None to return the complete path mapping. |
| Returns | |
pathlib.Path | collections.abc.Mapping[str, pathlib.Path] | None | Resolved path, read-only mapping when omitted, or None for an unknown key. |
| Raises | |
RuntimeError | If the application configuration is not initialized. |
TypeError | If a supplied key is not a string. |
orionis.ApplicationRestore mutable runtime settings from the bootstrap configuration.
Replace runtime containers with an isolated copy without changing creation or readiness flags.
| Returns | |
bool | True after the runtime mapping has been replaced. |
Self, key: str | None = None) -> list[ Path] | dict | None:
(source)
¶
orionis.ApplicationReturn mutable copies of configured routing paths.
| Parameters | |
key:str | None, optional | Routing type: api, web, console, ai, or websocket. Use None to return the complete routing dictionary. |
| Returns | |
list[pathlib.Path] | dict | None | Copied route list, full mutable routing dictionary, or None for an unsupported or unconfigured type. The full dictionary may also contain the health-check setting. |
| Raises | |
RuntimeError | If the application configuration is not initialized. |
TypeError | If a supplied key is neither a string nor None. |
orionis.ApplicationCheck effective maintenance mode using a short-lived worker cache.
Refresh the shared marker at most every 100 ms. Treat unreadable markers as maintenance mode; use configuration for missing or unrecognized values.
| Returns | |
bool | True when maintenance is enabled. Marker values "down" and "up" override app.maintenance. |
| Raises | |
RuntimeError | If application creation has not completed. |
orionis.ApplicationSet application configuration overrides for bootstrap.
| Parameters | |
**appobject | Field values for the app configuration section. |
| Returns | |
typing.Self | This application for method chaining. |
| Raises | |
RuntimeError | If bootstrap configuration is locked. |
orionis.ApplicationSet authentication configuration overrides for bootstrap.
| Parameters | |
**authobject | Field values for the auth configuration section. |
| Returns | |
typing.Self | This application for method chaining. |
| Raises | |
RuntimeError | If bootstrap configuration is locked. |
orionis.ApplicationSet cache configuration overrides for bootstrap.
| Parameters | |
**cacheobject | Field values for the cache configuration section. |
| Returns | |
typing.Self | This application for method chaining. |
| Raises | |
RuntimeError | If bootstrap configuration is locked. |
orionis.ApplicationSet database configuration overrides for bootstrap.
| Parameters | |
**databaseobject | Field values for the database configuration section. |
| Returns | |
typing.Self | This application for method chaining. |
| Raises | |
RuntimeError | If bootstrap configuration is locked. |
Self, **filesystems_config: object) -> Self:
(source)
¶
orionis.ApplicationSet filesystem configuration overrides for bootstrap.
| Parameters | |
**filesystemsobject | Field values for the filesystems configuration section. |
| Returns | |
typing.Self | This application for method chaining. |
| Raises | |
RuntimeError | If bootstrap configuration is locked. |
orionis.ApplicationSet HTTP configuration overrides for bootstrap.
| Parameters | |
**httpobject | Field values for the http configuration section. |
| Returns | |
typing.Self | This application for method chaining. |
| Raises | |
RuntimeError | If bootstrap configuration is locked. |
orionis.ApplicationSet logging configuration overrides for bootstrap.
| Parameters | |
**loggingobject | Field values for the logging configuration section. |
| Returns | |
typing.Self | This application for method chaining. |
| Raises | |
RuntimeError | If bootstrap configuration is locked. |
orionis.ApplicationSet mail configuration overrides for bootstrap.
| Parameters | |
**mailobject | Field values for the mail configuration section. |
| Returns | |
typing.Self | This application for method chaining. |
| Raises | |
RuntimeError | If bootstrap configuration is locked. |
orionis.ApplicationSet MCP protocol limits and allowed origins for bootstrap.
| Parameters | |
**mcpobject | MCP configuration fields, including limits and the Origin allowlist. |
| Returns | |
typing.Self | This application for method chaining. |
| Raises | |
RuntimeError | If bootstrap configuration is locked. |
orionis.ApplicationConfigure resolved application directories with core path overrides.
| Parameters | |
**paths:str | pathlib.Path | None | Overrides keyed by core path names such as app_providers, config, and storage_framework. Relative strings use the root; path objects use the working directory. None uses defaults. Unknown keys are ignored, and root remains basePath. |
| Returns | |
typing.Self | This application for method chaining. |
| Raises | |
RuntimeError | If bootstrap configuration is locked. |
TypeError | If a known directory override is not a string, path, or None. |
orionis.ApplicationSet queue configuration overrides for bootstrap.
| Parameters | |
**queueobject | Field values for the queue configuration section. |
| Returns | |
typing.Self | This application for method chaining. |
| Raises | |
RuntimeError | If bootstrap configuration is locked. |
orionis.ApplicationSet session configuration overrides for bootstrap.
| Parameters | |
**sessionobject | Field values for the session configuration section. |
| Returns | |
typing.Self | This application for method chaining. |
| Raises | |
RuntimeError | If bootstrap configuration is locked. |
orionis.ApplicationSet testing configuration overrides for bootstrap.
| Parameters | |
**testingobject | Field values for the testing configuration section. |
| Returns | |
typing.Self | This application for method chaining. |
| Raises | |
RuntimeError | If bootstrap configuration is locked. |
Self, handler: type[ IBaseExceptionHandler]) -> Self:
(source)
¶
orionis.ApplicationSet the exception handler class used for lazy singleton resolution.
| Parameters | |
handler:type[orionis.failure.contracts.handler.IBaseExceptionHandler] | Handler class implementing IBaseExceptionHandler. |
| Returns | |
typing.Self | This application for method chaining. |
| Raises | |
TypeError | If handler is not a class implementing the handler contract. |
RuntimeError | If bootstrap configuration is locked. |
Self, *middleware: type[ IBaseMiddleware]) -> Self:
(source)
¶
orionis.ApplicationRegister unique middleware classes in application execution order.
| Parameters | |
*middleware:type[IBaseMiddleware] | Middleware classes implementing IBaseMiddleware. |
| Returns | |
typing.Self | This application for method chaining. |
| Raises | |
TypeError | If an argument is not a middleware class. |
RuntimeError | If bootstrap configuration is locked. |
Self, *providers: type[ IServiceProvider]) -> Self:
(source)
¶
orionis.ApplicationRegister eager or deferred service provider classes for bootstrap.
| Parameters | |
*providers:type[IServiceProvider] | Provider classes implementing IServiceProvider. |
| Returns | |
typing.Self | This application for method chaining. |
| Raises | |
TypeError | If a provider class or deferred service identifier is invalid. |
RuntimeError | If bootstrap configuration is locked. |
Self, api: str | list[ str] | None = None, web: str | list[ str] | None = None, console: str | list[ str] | None = None, health: str | None = None, ai: str | list[ str] | None = None, *, websocket: str | list[ str] | None = None) -> Self:
(source)
¶
orionis.ApplicationConfigure route files and the health-check path for each protocol.
| Parameters | |
api:str | list[str] | None, optional | API route files relative to the application root, or None. |
web:str | list[str] | None, optional | Web route files relative to the application root, or None. |
console:str | list[str] | None, optional | CLI route files relative to the application root, or None. |
health:str | None, optional | Health-check URL path, or None to use "/up". |
ai:str | list[str] | None, optional | MCP registration files loaded before HTTP or CLI startup. |
websocket:str | list[str] | None, optional | WebSocket and Hub route files using the web middleware profile. |
| Returns | |
typing.Self | This application for method chaining. |
| Raises | |
TypeError | If an argument has an invalid type or a route file lacks valid imports. |
FileNotFoundError | If a route file is missing outside an active recovery context. |
RuntimeError | If bootstrap configuration is locked. |
orionis.ApplicationSet the scheduler class built by getScheduler.
| Parameters | |
scheduler:type[orionis.console.base.contracts.scheduler.IBaseScheduler] | Scheduler class implementing IBaseScheduler. |
| Returns | |
typing.Self | This application for method chaining. |
| Raises | |
RuntimeError | If bootstrap configuration is locked. |
TypeError | If scheduler is not a class implementing IBaseScheduler. |
orionis.ApplicationCheck whether all eager providers have finished booting.
| Returns | |
bool | True after creation and eager startup. Deferred providers still boot on first resolution. |
orionis.ApplicationReturn the resolved application root directory.
| Returns | |
pathlib.Path | Absolute root selected when this singleton was first initialized. |
orionis.ApplicationCheck whether compiled bootstrap caching is enabled.
| Returns | |
bool | True when compiled caching is enabled, even before a cache hit. |
orionis.ApplicationReturn configured directories used for bootstrap cache invalidation.
| Returns | |
list of pathlib.Path | Configured directory invalidation paths as a new list. |
orionis.ApplicationReturn configured files used for bootstrap cache invalidation.
| Returns | |
list of pathlib.Path | Configured file invalidation paths as a new list. |
orionis.ApplicationReturn the configured bootstrap cache directory.
| Returns | |
pathlib.Path or None | Resolved cache directory, or None before caching is configured. |
orionis.ApplicationReturn the creation entry point as a module path with an app suffix.
| Returns | |
str | None | Inferred module:app path, or None before creation records the caller's filename. |
orionis.ApplicationReport whether configuration and eager registration are complete.
| Returns | |
bool | True after create() completes, independently of asynchronous provider startup and HTTP kernel readiness. |
orionis.ApplicationReport the configuration-stage state exposed by isBooted.
| Returns | |
bool | Legacy creation flag, identical to isBooted. |
orionis.ApplicationCheck whether eager providers and both HTTP handlers are ready.
| Returns | |
bool | True after eager startup and handler publication; this does not indicate listening sockets or deployment health. |
orionis.ApplicationReturn the configured health-check URL path.
| Returns | |
str | Health-check path, or "/up" when no nonempty path is configured. |