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

class IApplication(IContainer, ABC): (source)

Known subclasses: orionis.Application

View In Hierarchy

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 getExceptionHandler Resolve and cache the configured exception handler instance.
Method getMiddleware Resolve registered middleware classes in application execution order.
Async Method getScheduler Resolve the scheduler class and build its instance.
Async Method handleCommand Run a CLI command within its startup and shutdown lifecycle.
Method isDebug Check the debug flag cached during application creation.
Method isProduction 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 resetRuntimeConfig Restore mutable runtime settings from the bootstrap configuration.
Method routingPaths Return mutable copies of configured routing paths.
Method underMaintenance Check effective maintenance mode using a short-lived worker cache.
Method withConfigApp Set application configuration overrides for bootstrap.
Method withConfigAuth Set authentication configuration overrides for bootstrap.
Method withConfigCache Set cache configuration overrides for bootstrap.
Method withConfigDatabase Set database configuration overrides for bootstrap.
Method withConfigFilesystems Set filesystem configuration overrides for bootstrap.
Method withConfigHttp Set HTTP configuration overrides for bootstrap.
Method withConfigLogging Set logging configuration overrides for bootstrap.
Method withConfigMail Set mail configuration overrides for bootstrap.
Method withConfigMcp Set MCP protocol limits and allowed origins for bootstrap.
Method withConfigPaths Configure resolved application directories with core path overrides.
Method withConfigQueue Set queue configuration overrides for bootstrap.
Method withConfigSession Set session configuration overrides for bootstrap.
Method withConfigTesting Set testing configuration overrides for bootstrap.
Method withExceptionHandler Set the exception handler class used for lazy singleton resolution.
Method withMiddleware Register unique middleware classes in application execution order.
Method withProviders Register eager or deferred service provider classes for bootstrap.
Method withRouting Configure route files and the health-check path for each protocol.
Method withScheduler Set the scheduler class built by getScheduler.
Class Variable __slots__ Declare that this class introduces no additional instance slots.
Property areProvidersBooted Check whether all eager providers have finished booting.
Property basePath Return the resolved application root directory.
Property compiled Check whether compiled bootstrap caching is enabled.
Property compiledInvalidationPathsDirs Return configured directories used for bootstrap cache invalidation.
Property compiledInvalidationPathsFiles Return configured files used for bootstrap cache invalidation.
Property compiledPath Return the configured bootstrap cache directory.
Property entryPoint Return the creation entry point as a module path with an app suffix.
Property isBooted Report whether configuration and eager registration are complete.
Property isCreated Report the configuration-stage state exposed by isBooted.
Property isHttpReady Check whether eager providers and both HTTP handlers are ready.
Property routeHealthCheck Return the configured health-check URL path.
Property startAt Return the instance initialization timestamp in Unix nanoseconds.

Inherited from IContainer:

Method beginScope 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 getCurrentScope 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.
async def aclose(self: Self): (source)
overridden in orionis.Application

Close 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
NoneRelease owned resources in overrides; do nothing in the default method.
@abstractmethod
async def boot(self: Self) -> Self: (source)
overridden in orionis.Application

Create 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.SelfThis application after all eager providers finish booting.
Raises
ExceptionIf creation, provider boot, or reporting startup fails. Unfinished providers remain pending for a later retry.
@abstractmethod
def compile(self: Self, path: str | None = None, invalidation_paths: list[str] | None = None): (source)
overridden in orionis.Application

Configure 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, optionalCache directory, defaulting to the application's framework cache path.
invalidation_paths:list[str] | None, optionalExisting files or directories monitored relative to the application root, or None for no additional invalidation paths.
Returns
NoneConfigure the cache and commit a valid restored snapshot, if present.
@abstractmethod
def config(self: Self, key: str | None = None, value: object = _SENTINEL) -> object: (source)
overridden in orionis.Application

Read or update the mutable runtime configuration.

Parameters
key:str or None, optionalDot-separated key, or None with no value to return all settings.
value:object, optionalReplacement value; omit to read the key. Explicit None is stored.
Returns
objectRequested value, assigned value, or the full mutable mapping. Missing keys and non-dictionary parents return None on reads.
Raises
RuntimeErrorIf the application configuration is not initialized.
TypeErrorIf a keyed read or write uses a non-string key.
@abstractmethod
def create(self: Self) -> Self: (source)
overridden in orionis.Application

Create 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.SelfThis application after configuration and registration complete.
Raises
TypeErrorIf http.monitor_disconnects is neither a boolean nor None.
@abstractmethod
async def getExceptionHandler(self: Self) -> IBaseExceptionHandler: (source)
overridden in orionis.Application

Resolve and cache the configured exception handler instance.

Construct shared dependencies outside request and operation scopes.

Returns
orionis.failure.contracts.handler.IBaseExceptionHandlerShared handler instance, using the core default when not overridden.
Raises
RuntimeErrorIf application creation has not completed.
@abstractmethod
def getMiddleware(self: Self) -> list[type[IBaseMiddleware]]: (source)
overridden in orionis.Application

Resolve 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.
@abstractmethod
async def getScheduler(self: Self) -> IBaseScheduler: (source)
overridden in orionis.Application

Resolve the scheduler class and build its instance.

Returns
orionis.console.base.contracts.scheduler.IBaseSchedulerInstance built from the cached configured scheduler class.
Raises
RuntimeErrorIf application creation has not completed.
@abstractmethod
async def handleCommand(self: Self, args: list[str] | None = None) -> int: (source)
overridden in orionis.Application

Run a CLI command within its startup and shutdown lifecycle.

Parameters
args:list of str or None, optionalCommand arguments, or None to pass an empty argument list.
Returns
intExit code returned by the CLI kernel.
Raises
RuntimeErrorIf no CLI kernel is configured.
TypeErrorIf the configured kernel does not implement the CLI interface.
@abstractmethod
def isDebug(self: Self) -> bool: (source)
overridden in orionis.Application

Check the debug flag cached during application creation.

Returns
boolTrue only when the creation-time app.debug value is True.
Raises
RuntimeErrorIf application creation has not completed.
@abstractmethod
def isProduction(self: Self) -> bool: (source)
overridden in orionis.Application

Check the production flag cached during application creation.

Returns
boolTrue when the creation-time app.env string contains "prod".
Raises
RuntimeErrorIf application creation has not completed.
@abstractmethod
def on(self: Self, lifespan: Lifespan, *callbacks: Callable[..., Any] | Callable[..., Awaitable[Any]], runtime: Runtime | None = None) -> Self: (source)
overridden in orionis.Application

Register 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.LifespanLifecycle event that triggers the callbacks.
*callbacks:collections.abc.CallableSynchronous or asynchronous callbacks invoked through the container.
runtime:orionis.foundation.enums.runtimes.Runtime or None, optionalTarget runtime, or None for callbacks shared by HTTP and CLI.
Returns
typing.SelfThis application for method chaining.
Raises
TypeErrorIf the event/runtime type is invalid or a callback is not callable.
ValueErrorIf no callbacks are provided or the runtime selector is unknown.
@abstractmethod
def path(self: Self, key: str | None = None) -> Path | Mapping[str, Path] | None: (source)
overridden in orionis.Application

Return one configured application path or the read-only path mapping.

Parameters
key:str | None, optionalCore path name, or None to return the complete path mapping.
Returns
pathlib.Path | collections.abc.Mapping[str, pathlib.Path] | NoneResolved path, read-only mapping when omitted, or None for an unknown key.
Raises
RuntimeErrorIf the application configuration is not initialized.
TypeErrorIf a supplied key is not a string.
@abstractmethod
def resetRuntimeConfig(self: Self) -> bool: (source)
overridden in orionis.Application

Restore mutable runtime settings from the bootstrap configuration.

Replace runtime containers with an isolated copy without changing creation or readiness flags.

Returns
boolTrue after the runtime mapping has been replaced.
@abstractmethod
def routingPaths(self: Self, key: str | None = None) -> list[Path] | dict | None: (source)
overridden in orionis.Application

Return mutable copies of configured routing paths.

Parameters
key:str | None, optionalRouting type: api, web, console, ai, or websocket. Use None to return the complete routing dictionary.
Returns
list[pathlib.Path] | dict | NoneCopied 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
RuntimeErrorIf the application configuration is not initialized.
TypeErrorIf a supplied key is neither a string nor None.
@abstractmethod
def underMaintenance(self: Self) -> bool: (source)
overridden in orionis.Application

Check 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
boolTrue when maintenance is enabled. Marker values "down" and "up" override app.maintenance.
Raises
RuntimeErrorIf application creation has not completed.
@abstractmethod
def withConfigApp(self: Self, **app_config: object) -> Self: (source)
overridden in orionis.Application

Set application configuration overrides for bootstrap.

Parameters
**app_config:objectField values for the app configuration section.
Returns
typing.SelfThis application for method chaining.
Raises
RuntimeErrorIf bootstrap configuration is locked.
@abstractmethod
def withConfigAuth(self: Self, **auth_config: object) -> Self: (source)
overridden in orionis.Application

Set authentication configuration overrides for bootstrap.

Parameters
**auth_config:objectField values for the auth configuration section.
Returns
typing.SelfThis application for method chaining.
Raises
RuntimeErrorIf bootstrap configuration is locked.
@abstractmethod
def withConfigCache(self: Self, **cache_config: object) -> Self: (source)
overridden in orionis.Application

Set cache configuration overrides for bootstrap.

Parameters
**cache_config:objectField values for the cache configuration section.
Returns
typing.SelfThis application for method chaining.
Raises
RuntimeErrorIf bootstrap configuration is locked.
@abstractmethod
def withConfigDatabase(self: Self, **database_config: object) -> Self: (source)
overridden in orionis.Application

Set database configuration overrides for bootstrap.

Parameters
**database_config:objectField values for the database configuration section.
Returns
typing.SelfThis application for method chaining.
Raises
RuntimeErrorIf bootstrap configuration is locked.
@abstractmethod
def withConfigFilesystems(self: Self, **filesystems_config: object) -> Self: (source)
overridden in orionis.Application

Set filesystem configuration overrides for bootstrap.

Parameters
**filesystems_config:objectField values for the filesystems configuration section.
Returns
typing.SelfThis application for method chaining.
Raises
RuntimeErrorIf bootstrap configuration is locked.
@abstractmethod
def withConfigHttp(self: Self, **http_config: object) -> Self: (source)
overridden in orionis.Application

Set HTTP configuration overrides for bootstrap.

Parameters
**http_config:objectField values for the http configuration section.
Returns
typing.SelfThis application for method chaining.
Raises
RuntimeErrorIf bootstrap configuration is locked.
@abstractmethod
def withConfigLogging(self: Self, **logging_config: object) -> Self: (source)
overridden in orionis.Application

Set logging configuration overrides for bootstrap.

Parameters
**logging_config:objectField values for the logging configuration section.
Returns
typing.SelfThis application for method chaining.
Raises
RuntimeErrorIf bootstrap configuration is locked.
@abstractmethod
def withConfigMail(self: Self, **mail_config: object) -> Self: (source)
overridden in orionis.Application

Set mail configuration overrides for bootstrap.

Parameters
**mail_config:objectField values for the mail configuration section.
Returns
typing.SelfThis application for method chaining.
Raises
RuntimeErrorIf bootstrap configuration is locked.
@abstractmethod
def withConfigMcp(self: Self, **mcp_config: object) -> Self: (source)
overridden in orionis.Application

Set MCP protocol limits and allowed origins for bootstrap.

Parameters
**mcp_config:objectMCP configuration fields, including limits and the Origin allowlist.
Returns
typing.SelfThis application for method chaining.
Raises
RuntimeErrorIf bootstrap configuration is locked.
@abstractmethod
def withConfigPaths(self: Self, **paths: str | Path | None) -> Self: (source)
overridden in orionis.Application

Configure resolved application directories with core path overrides.

Parameters
**paths:str | pathlib.Path | NoneOverrides 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.SelfThis application for method chaining.
Raises
RuntimeErrorIf bootstrap configuration is locked.
TypeErrorIf a known directory override is not a string, path, or None.
@abstractmethod
def withConfigQueue(self: Self, **queue_config: object) -> Self: (source)
overridden in orionis.Application

Set queue configuration overrides for bootstrap.

Parameters
**queue_config:objectField values for the queue configuration section.
Returns
typing.SelfThis application for method chaining.
Raises
RuntimeErrorIf bootstrap configuration is locked.
@abstractmethod
def withConfigSession(self: Self, **session_config: object) -> Self: (source)
overridden in orionis.Application

Set session configuration overrides for bootstrap.

Parameters
**session_config:objectField values for the session configuration section.
Returns
typing.SelfThis application for method chaining.
Raises
RuntimeErrorIf bootstrap configuration is locked.
@abstractmethod
def withConfigTesting(self: Self, **testing_config: object) -> Self: (source)
overridden in orionis.Application

Set testing configuration overrides for bootstrap.

Parameters
**testing_config:objectField values for the testing configuration section.
Returns
typing.SelfThis application for method chaining.
Raises
RuntimeErrorIf bootstrap configuration is locked.
@abstractmethod
def withExceptionHandler(self: Self, handler: type[IBaseExceptionHandler]) -> Self: (source)
overridden in orionis.Application

Set the exception handler class used for lazy singleton resolution.

Parameters
handler:type[orionis.failure.contracts.handler.IBaseExceptionHandler]Handler class implementing IBaseExceptionHandler.
Returns
typing.SelfThis application for method chaining.
Raises
TypeErrorIf handler is not a class implementing the handler contract.
RuntimeErrorIf bootstrap configuration is locked.
@abstractmethod
def withMiddleware(self: Self, *middleware: type[IBaseMiddleware]) -> Self: (source)
overridden in orionis.Application

Register unique middleware classes in application execution order.

Parameters
*middleware:type[IBaseMiddleware]Middleware classes implementing IBaseMiddleware.
Returns
typing.SelfThis application for method chaining.
Raises
TypeErrorIf an argument is not a middleware class.
RuntimeErrorIf bootstrap configuration is locked.
@abstractmethod
def withProviders(self: Self, *providers: type[IServiceProvider]) -> Self: (source)
overridden in orionis.Application

Register eager or deferred service provider classes for bootstrap.

Parameters
*providers:type[IServiceProvider]Provider classes implementing IServiceProvider.
Returns
typing.SelfThis application for method chaining.
Raises
TypeErrorIf a provider class or deferred service identifier is invalid.
RuntimeErrorIf bootstrap configuration is locked.
@abstractmethod
def withRouting(self: 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)
overridden in orionis.Application

Configure route files and the health-check path for each protocol.

Parameters
api:str | list[str] | None, optionalAPI route files relative to the application root, or None.
web:str | list[str] | None, optionalWeb route files relative to the application root, or None.
console:str | list[str] | None, optionalCLI route files relative to the application root, or None.
health:str | None, optionalHealth-check URL path, or None to use "/up".
ai:str | list[str] | None, optionalMCP registration files loaded before HTTP or CLI startup.
websocket:str | list[str] | None, optionalWebSocket and Hub route files using the web middleware profile.
Returns
typing.SelfThis application for method chaining.
Raises
TypeErrorIf an argument has an invalid type or a route file lacks valid imports.
FileNotFoundErrorIf a route file is missing outside an active recovery context.
RuntimeErrorIf bootstrap configuration is locked.
@abstractmethod
def withScheduler(self: Self, scheduler: type[IBaseScheduler]) -> Self: (source)
overridden in orionis.Application

Set the scheduler class built by getScheduler.

Parameters
scheduler:type[orionis.console.base.contracts.scheduler.IBaseScheduler]Scheduler class implementing IBaseScheduler.
Returns
typing.SelfThis application for method chaining.
Raises
RuntimeErrorIf bootstrap configuration is locked.
TypeErrorIf scheduler is not a class implementing IBaseScheduler.
__slots__: tuple = (source)

Declare that this class introduces no additional instance slots.

@property
@abstractmethod
areProvidersBooted: bool = (source)
overridden in orionis.Application

Check whether all eager providers have finished booting.

Returns
boolTrue after creation and eager startup. Deferred providers still boot on first resolution.
@property
@abstractmethod
basePath: Path = (source)
overridden in orionis.Application

Return the resolved application root directory.

Returns
pathlib.PathAbsolute root selected when this singleton was first initialized.
@property
@abstractmethod
compiled: bool = (source)
overridden in orionis.Application

Check whether compiled bootstrap caching is enabled.

Returns
boolTrue when compiled caching is enabled, even before a cache hit.
@property
@abstractmethod
compiledInvalidationPathsDirs: list[Path] = (source)
overridden in orionis.Application

Return configured directories used for bootstrap cache invalidation.

Returns
list of pathlib.PathConfigured directory invalidation paths as a new list.
@property
@abstractmethod
compiledInvalidationPathsFiles: list[Path] = (source)
overridden in orionis.Application

Return configured files used for bootstrap cache invalidation.

Returns
list of pathlib.PathConfigured file invalidation paths as a new list.
@property
@abstractmethod
compiledPath: Path | None = (source)
overridden in orionis.Application

Return the configured bootstrap cache directory.

Returns
pathlib.Path or NoneResolved cache directory, or None before caching is configured.
@property
@abstractmethod
entryPoint: str | None = (source)
overridden in orionis.Application

Return the creation entry point as a module path with an app suffix.

Returns
str | NoneInferred module:app path, or None before creation records the caller's filename.
@property
@abstractmethod
isBooted: bool = (source)
overridden in orionis.Application

Report whether configuration and eager registration are complete.

Returns
boolTrue after create() completes, independently of asynchronous provider startup and HTTP kernel readiness.
@property
@abstractmethod
isCreated: bool = (source)
overridden in orionis.Application

Report the configuration-stage state exposed by isBooted.

Returns
boolLegacy creation flag, identical to isBooted.
@property
@abstractmethod
isHttpReady: bool = (source)
overridden in orionis.Application

Check whether eager providers and both HTTP handlers are ready.

Returns
boolTrue after eager startup and handler publication; this does not indicate listening sockets or deployment health.
@property
@abstractmethod
routeHealthCheck: str = (source)
overridden in orionis.Application

Return the configured health-check URL path.

Returns
strHealth-check path, or "/up" when no nonempty path is configured.
@property
@abstractmethod
startAt: int = (source)
overridden in orionis.Application

Return the instance initialization timestamp in Unix nanoseconds.

Returns
intTime recorded when this singleton was first initialized.