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

Configure the container and serve requests within one worker event loop.

Notes

Concurrent tasks share kernel initialization and provider startup locks. Mutable application state is not synchronized across threads or event loops. Python and RSGI special methods retain their protocol-defined names.

Class Method current Return this class's existing singleton without initializing it.
Async Method __asgiLifespan Receive ASGI lifespan messages until shutdown or disconnect.
Method __assertConfigMutable Reject locked bootstrap changes and initialize mutable defaults.
Method __assertPythonVersion Reject Python runtimes below the framework's minimum version.
Method __bootCompiledState Configure bootstrap caching and restore a valid cached snapshot.
Async Method __bootEagerProviders Await pending eager providers under a shared startup lock.
Async Method __call__ Route ASGI HTTP, WebSocket, and lifespan scopes to their handlers.
Async Method __closeRuntimeLogger Close the bound logger under the final owner's lifecycle lock.
Async Method __closeRuntimeResources Drain runtime tasks and close the logging sink for its final owner.
Method __commitConfig Freeze bootstrap metadata and mark configuration initialized.
Method __defaultBootstrap Build a fresh bootstrap mapping from core framework metadata.
Method __discoverProviders Import concrete providers declared by the discovered modules.
Method __ensureDefaultBootstrap Populate an empty bootstrap mapping with core defaults.
Method __ensureDefaultPaths Populate missing bootstrap paths from the application defaults.
Method __ensureProvidersRegistryStructure Initialize eager and deferred provider registries once.
Method __getRuntimeConfigValue Read a runtime value through pre-parsed configuration components.
Async Method __handleHttpAsgi Dispatch ASGI connections under the configured disconnect policy.
Async Method __handleHttpRsgi Dispatch RSGI connections under the configured disconnect policy.
Async Method __handleLifespanEvent Process one ASGI lifespan event and report its outcome.
Method __init__ Initialize the application singleton and its lifecycle state once.
Async Method __initializeCliKernel Boot the CLI kernel and cache its handler under a shared lock.
Async Method __initializeHttpKernel Initialize both HTTP handlers under a shared startup lock.
Method __load Load bootstrap state and register providers without awaiting async boots.
Async Method __loadCLIKernel Build and validate the configured CLI kernel.
Method __loadConfig Load core defaults, custom sections, and discovered configuration data.
Method __loadCoreProviders Register the framework's core service provider classes.
Method __loadCustomConfig Merge custom sections and discovered dataclasses into the defaults.
Async Method __loadHTTPKernel Build and boot the configured HTTP kernel.
Method __loadProviders Discover application providers, then register core framework providers.
Method __lockConfig Recursively freeze the bootstrap configuration.
Async Method __onShutdown Run shutdown hooks before draining runtime resources.
Async Method __onStartup Boot eager providers and run runtime-specific startup hooks.
Method __persistCompiledState Save bootstrap metadata when compiled caching is active.
Method __resolveAndValidateRoutingFiles Resolve route files and verify their required imports.
Method __resolveEagerProvider Register eager providers and queue their asynchronous boot methods.
Async Method __rsgi__ Route RSGI HTTP and WebSocket connections to the HTTP kernel.
Method __rsgi_del__ Run RSGI shutdown on the server's event loop.
Method __rsgi_init__ Run RSGI startup on the server's event loop.
Async Method __runLifespanEvent Run lifespan callbacks and acknowledge successful completion.
Async Method __runShutdownCallbacks Attempt every shutdown callback and propagate its first failure.
Async Method __sendLifespanFailure Report a lifespan failure and send the ASGI failure response.
Method __setRuntimeConfigValue Write a runtime value, replacing non-dictionary parents as needed.
Method __setTimezoneAndLocale Apply configured timezone and locale settings to runtime services.
Async Method __startRsgi Complete RSGI startup before activating failure reporting.
Async Method __stopRsgi Run RSGI shutdown before releasing failure-reporting ownership.
Method __storeDeferredProviderClass Map each deferred service identifier to its provider metadata.
Method __storeEagerProviderClass Prepend validated provider metadata to the eager registry.
Method __storeProviderClass Validate and store a provider class in its matching registry.
Method __validateAndReturnPath Resolve a supported path to an absolute filesystem path.
Method __validateProviderClass Require a service provider class implementing IServiceProvider.
Async Method aclose Close the headless reporting lifetime acquired by boot.
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.
Instance Variable __basePath Validate and store the basePath as the application root.
Instance Variable __booted Initialize application state flags.
Instance Variable __bootstrap Initialize configuration dictionaries.
Instance Variable __cache_resolved_providers Initialize deferred providers cache.
Instance Variable __compiled Compilation and configuration caching logic.
Instance Variable __compiled_invalidation_paths_dirs Compiled invalidation paths dirs produced by set.
Instance Variable __compiled_invalidation_paths_files Compiled invalidation paths files produced by set.
Instance Variable __compiled_path Directory containing compiled application bootstrap metadata.
Instance Variable __compiled_state_store Cache driver for storing compiled configuration.
Instance Variable __configured Configured flag used by Application.
Instance Variable __entry_point Store the file path where the application was started.
Instance Variable __exception_handler_instance Shared handler constructed outside request and operation scopes.
Instance Variable __exception_handler_lock Serialize construction of the application exception handler.
Instance Variable __exception_handler_resolved Exception-handler instance cached after its first resolution.
Instance Variable __headless_close_lock Coordinate explicit headless startup and final resource closure.
Instance Variable __hook_events Lifecycle event callbacks for each runtime (HTTP/CLI/global). These are not cached and execute on each lifecycle event.
Instance Variable __http_disconnect_monitoring Http disconnect monitoring flag used by Application.
Instance Variable __http_disconnect_paths Http disconnect paths produced by kernel.disconnectPaths.
Instance Variable __is_compiled Flag to determine if working with previously compiled state.
Instance Variable __is_debug_cache Is debug cache flag used by Application.
Instance Variable __is_production_cache Is production cache flag used by Application.
Instance Variable __kernel_cli Kernel cli obtained from kernel.handle.
Instance Variable __kernel_cli_lock Synchronization primitive controlling access to kernel cli lock.
Instance Variable __kernel_http_asgi Kernel http asgi supplied through asgi_handler.
Instance Variable __kernel_http_lock Synchronization primitive controlling access to kernel http lock.
Instance Variable __kernel_http_rsgi Kernel http rsgi supplied through rsgi_handler.
Instance Variable __maintenance_cache Most recently observed maintenance-mode state.
Instance Variable __maintenance_lock Synchronization primitive controlling access to maintenance lock.
Instance Variable __maintenance_marker Store the shared maintenance marker and its last observed state.
Instance Variable __pending_boot_providers Pending boot providers produced by deque.
Instance Variable __provider_boot_lock Synchronization primitive controlling access to provider boot lock.
Instance Variable __providers_registry_initialized Initialize providers registry sentinel.
Instance Variable __runtime_config Mutable runtime view of the committed application configuration.
Instance Variable __runtime_config_initialized Runtime config initialized flag used by Application.
Instance Variable __scheduler_resolved Initialize references to resolved service classes.
Instance Variable __start_at Store the application startup timestamp in nanoseconds.
Instance Variable _Application__initialized Mark the Application as initialized to enforce singleton behavior.
Instance Variable _deferred_providers Initialize deferred providers storage for tracking.
Instance Variable _failure_runtime Prepared coordinator activated by successful runtime owners.
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 Container:

Method __aliasService Validate and normalize a service alias string.
Async Method __autoResolveCallable Resolve and invoke a callable, injecting dependencies.
Async Method __autoResolveClass Automatically instantiate a class with injected dependencies.
Async Method __awaitPendingProvider Wait for a provider that has registered services but is still booting.
Method __bind Bind a concrete implementation to an abstract contract with a given lifetime.
Async Method __bootDeferredProvider Register a deferred provider once and complete its boot hook.
Async Method __createScoped Build and store the instance backing a scoped binding.
Async Method __createSingleton Build and cache the single instance backing a singleton binding.
Method __creationLock Return the creation lock for a key, bound to the running loop.
Method __ensureCanOverrideGlobal Ensure that a service or alias can be overridden globally.
Method __ensureCanOverrideScope Ensure that a service can be overridden in the current scope.
Method __ensureConcreteImplements Ensure that a concrete class implements the specified abstract class.
Method __ensureInstanceImplements Ensure that an instance implements the specified abstract class.
Method __isBeingResolved Determine whether a concrete type is already resolving in this task.
Method __new__ Create and return a singleton instance for each class in the hierarchy.
Async Method __resolve Resolve an instance from a binding according to its lifetime.
Async Method __resolveArgument Resolve a single argument for dependency injection.
Async Method __resolveDeferredProvider Resolve and register a deferred service provider for a given service.
Async Method __resolveKey Resolve a service key to its abstract type.
Async Method __resolveMissingParameter Resolve a parameter whose value was omitted from a keyword call.
Async Method __resolveOrBuild Resolve a binding for an abstract service or build it when unbound.
Async Method __resolvePositionalArguments Resolve a positional call using the current bindings and scope.
Async Method __resolveSchemaArgument Validate a schema argument using the active HTTP request payload.
Async Method __resolveSignature Resolve arguments for a callable signature using dependency injection.
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.
Class Variable _instances Dictionary to hold singleton instances for each class This allows proper inheritance of the singleton pattern.
Class Variable _lock Lock for thread-safe singleton instantiation and access This lock ensures that only one thread can create or access instances at a time.
Instance Variable __aliases Aliases mapping for service resolution.
Instance Variable __bindings Registered bindings for services.
Instance Variable __cache_resolve_deferred_providers Tracks resolved deferred providers.
Instance Variable __creation_locks Per-key locks serialising one-shot construction, paired with the loop they were created on so a second loop never awaits a foreign lock.
Instance Variable __pending_deferred Deferred providers with boot work that is still pending.
Instance Variable __registered_deferred Deferred providers whose bindings have already been registered.
Instance Variable __singleton_cache Cache for singleton instances.
Instance Variable _Container__initialized Mark as initialized to prevent re-initialization.

Inherited from IApplication (via Container):

Class Variable __slots__ Declare that this class introduces no additional instance slots.
def current(cls: type[Self]) -> Self | None: (source)

Return this class's existing singleton without initializing it.

Returns
typing.Self or NoneExisting instance, or None before construction. Configuration may remain uninitialized until create() completes.
async def __asgiLifespan(self: Self, receive: Callable[[], Awaitable[dict]], send: Callable[[dict], Awaitable[None]]): (source)

Receive ASGI lifespan messages until shutdown or disconnect.

Parameters
receive:collections.abc.CallableAsynchronous callable receiving lifespan messages.
send:collections.abc.CallableAsynchronous callable sending lifespan acknowledgements.
Returns
NoneFinish after shutdown, disconnect, or a reported lifecycle failure.
def __assertConfigMutable(self: Self): (source)

Reject locked bootstrap changes and initialize mutable defaults.

Returns
NonePrepare a mutable bootstrap mapping for configuration updates.
Raises
RuntimeErrorIf creation has already locked the bootstrap configuration.
def __assertPythonVersion(self: Self): (source)

Reject Python runtimes below the framework's minimum version.

Returns
NoneLeave application state unchanged when the runtime is supported.
Raises
RuntimeErrorIf the interpreter version is below PYTHON_REQUIRES.
def __bootCompiledState(self: Self, compiled_path: str | None = None, compiled_invalidation_paths: list[str] | None = None): (source)

Configure bootstrap caching and restore a valid cached snapshot.

Notes

Always monitor core path definitions. Skip snapshot loading during Reactor bootstrap recovery.

Parameters
compiled_path:str | None, optionalCache directory, or None to use the framework cache path.
compiled_invalidation_paths:list[str] | None, optionalExisting files and directories whose changes invalidate the snapshot.
Returns
NoneInitialize cache metadata and commit any valid restored configuration.
async def __bootEagerProviders(self: Self): (source)

Await pending eager providers under a shared startup lock.

Process providers in registration order. Keep an unfinished provider queued so a subsequent startup can retry it.

Returns
NoneRemove each provider only after its boot method completes.
async def __call__(self: Self, scope: dict, receive: Callable[[], Awaitable[dict[str, Any]]], send: Callable[[dict[str, Any]], Awaitable[None]]) -> Any | None: (source)

Route ASGI HTTP, WebSocket, and lifespan scopes to their handlers.

Parameters
scope:dictConnection metadata, including the ASGI scope type.
receive:collections.abc.CallableAsynchronous callable receiving connection messages.
send:collections.abc.CallableAsynchronous callable sending connection messages.
Returns
typing.Any | NoneHandler result, or None for an unsupported scope type.
async def __closeRuntimeLogger(self: Self, failure_runtime: FailureRuntime | None): (source)

Close the bound logger under the final owner's lifecycle lock.

Parameters
failure_runtime:orionis.failure.runtime.FailureRuntime or NoneRuntime whose automatic reporting must stop before logger cleanup.
Returns
NoneDisable failure reporting and close the logger when configured.
async def __closeRuntimeResources(self: Self, owner: object | None = None, *, owner_task: asyncio.Task | None = None, parent_event_id: str | None = None): (source)

Drain runtime tasks and close the logging sink for its final owner.

Parameters
owner:object | None, optionalOwnership token to retire, or None to check shared ownership without releasing a token.
owner_task:asyncio.Task or None, optionalLifecycle task to exclude from the shutdown it is awaiting.
parent_event_id:str or None, optionalPrimary execution incident linked to resource cleanup failures.
Returns
NoneFinish shared work and retain the sink while another owner needs it.
def __commitConfig(self: Self): (source)

Freeze bootstrap metadata and mark configuration initialized.

Returns
NoneLock bootstrap containers and enable runtime configuration access.
def __defaultBootstrap(self: Self) -> dict[str, Any]: (source)

Build a fresh bootstrap mapping from core framework metadata.

Returns
dict[str, typing.Any]Mutable configuration, path, provider, routing, and kernel sections.
def __discoverProviders(self: Self, modules: set[str]): (source)

Import concrete providers declared by the discovered modules.

Parameters
modules:set[str]Dotted module names searched in sorted order.
Returns
NoneRegister nonabstract provider classes defined by each module.
def __ensureDefaultBootstrap(self: Self): (source)

Populate an empty bootstrap mapping with core defaults.

Returns
NoneInitialize defaults only when the bootstrap mapping is empty.
def __ensureDefaultPaths(self: Self): (source)

Populate missing bootstrap paths from the application defaults.

Returns
NoneResolve default paths only when no path mapping is configured.
def __ensureProvidersRegistryStructure(self: Self): (source)

Initialize eager and deferred provider registries once.

Returns
NoneCreate missing registry mappings and mark their structure initialized.
def __getRuntimeConfigValue(self: Self, key_parts: tuple[str, ...]) -> object: (source)

Read a runtime value through pre-parsed configuration components.

Parameters
key_parts:tuple of strConfiguration path components, including any empty-string keys.
Returns
objectResolved value, or None for a missing key or non-dictionary parent.
async def __handleHttpAsgi(self: Self, scope: dict, receive: Callable[[], Awaitable[dict[str, Any]]], send: Callable[[dict[str, Any]], Awaitable[None]]) -> Any | None: (source)

Dispatch ASGI connections under the configured disconnect policy.

Monitor HTTP disconnects when enabled globally or by an endpoint. Buffer at most nine body messages: eight queued and one pending. Pause receive calls while the queue is full. Dispatch WebSockets directly in the server task without a disconnect monitor.

Parameters
scope:dictASGI HTTP or WebSocket connection metadata.
receive:collections.abc.CallableAsynchronous callable receiving connection messages.
send:collections.abc.CallableAsynchronous callable transmitting response messages.
Returns
typing.Any | NoneKernel result, or None after disconnect-driven cancellation.
async def __handleHttpRsgi(self: Self, scope: Scope, protocol: HTTPProtocol) -> object: (source)

Dispatch RSGI connections under the configured disconnect policy.

Monitor HTTP disconnects when enabled globally or by an endpoint, and finish the watcher before returning. Dispatch WebSockets directly.

Parameters
scope:granian.rsgi.ScopeRSGI connection metadata.
protocol:granian.rsgi.HTTPProtocolConnection protocol exposing a client_disconnect awaitable when HTTP disconnect monitoring is enabled.
Returns
objectKernel result, or None after disconnect-driven cancellation.
Raises
TypeErrorIf the configured kernel does not implement the HTTP interface.
async def __handleLifespanEvent(self: Self, event: Lifespan, send: Callable[[dict], Awaitable[None]], *, started: bool) -> bool: (source)

Process one ASGI lifespan event and report its outcome.

Parameters
event:orionis.foundation.enums.lifespan.LifespanStartup or shutdown event to process.
send:collections.abc.CallableAsynchronous callable sending the event acknowledgement.
started:boolWhether an earlier startup event completed successfully.
Returns
boolTrue after successful startup; False after shutdown or failure.
def __init__(self: Self, base_path: Path = _CWD): (source)

Initialize the application singleton and its lifecycle state once.

Parameters
base_path:pathlib.Path, optionalApplication root, defaulting to the working directory at import time.
Returns
NoneInitialize container, configuration, and lifecycle state in place.
Raises
RuntimeErrorIf the Python runtime is below the framework's minimum version.
TypeErrorIf the root is neither a path object nor a string.
async def __initializeCliKernel(self: Self): (source)

Boot the CLI kernel and cache its handler under a shared lock.

Returns
NonePublish the command handler only after kernel boot completes.
async def __initializeHttpKernel(self: Self, interface: str, *, start_runtime: bool = False): (source)

Initialize both HTTP handlers under a shared startup lock.

Parameters
interface:strTransport identifier recorded as app.interface.
start_runtime:bool, optionalStart HTTP failure reporting for requests without lifespan startup.
Returns
NonePublish handlers after kernel boot and failure-runtime preparation.
def __load(self: Self): (source)

Load bootstrap state and register providers without awaiting async boots.

Reuse restored compiled metadata; otherwise load configuration, discover providers, persist the snapshot, and freeze bootstrap state.

Returns
NonePublish deferred bindings and register eager providers for startup.
async def __loadCLIKernel(self: Self) -> IKernelCLI: (source)

Build and validate the configured CLI kernel.

Returns
orionis.console.contracts.kernel.IKernelCLIValidated kernel awaiting command-handler initialization.
Raises
RuntimeErrorIf no CLI kernel metadata is configured.
TypeErrorIf the configured kernel does not implement IKernelCLI.
def __loadConfig(self: Self): (source)

Load core defaults, custom sections, and discovered configuration data.

Apply programmatic overrides before discovered dataclass values.

Returns
NoneReplace bootstrap configuration with the merged section mapping.
def __loadCoreProviders(self: Self): (source)

Register the framework's core service provider classes.

Returns
NoneAdd core provider metadata to the bootstrap registries.
def __loadCustomConfig(self: Self, default_config: dict[str, Any], custom_config: dict[str, Any], dataclasses: set[tuple[str, str, str, type[Any]]] | None = None) -> dict[str, Any]: (source)

Merge custom sections and discovered dataclasses into the defaults.

Parameters
default_config:dict[str, typing.Any]Mutable defaults updated in place.
custom_config:dict[str, typing.Any]Section dictionaries merged before discovered dataclass values.
dataclasses:set[tuple[str, str, str, type[typing.Any]]] | None, optionalEntries containing section name, module, class name, and dataclass type, or None to skip discovered configuration.
Returns
dict[str, typing.Any]Input defaults mapping after both merge stages.
Raises
RuntimeErrorIf a configuration dataclass cannot be instantiated or serialized.
async def __loadHTTPKernel(self: Self) -> IKernelHTTP: (source)

Build and boot the configured HTTP kernel.

Returns
orionis.http.contracts.kernel.IKernelHTTPValidated kernel after its boot method completes.
Raises
TypeErrorIf the configured kernel does not implement IKernelHTTP.
def __loadProviders(self: Self): (source)

Discover application providers, then register core framework providers.

Returns
NonePopulate registries from application and core provider classes.
def __lockConfig(self: Self): (source)

Recursively freeze the bootstrap configuration.

Returns
NoneReplace mutable containers without changing the creation flag.
async def __onShutdown(self: Self, runtime: Runtime, *, failure_owner: object | None = None, owner_task: asyncio.Task | None = None, parent_event_id: str | None = None): (source)

Run shutdown hooks before draining runtime resources.

Parameters
runtime:orionis.foundation.enums.runtimes.RuntimeHTTP or CLI runtime whose shutdown hooks should run.
failure_owner:object | None, optionalReporting ownership token; HTTP uses its shared owner when omitted.
owner_task:asyncio.Task or None, optionalLifecycle owner awaiting protected cleanup from another task.
parent_event_id:str or None, optionalPrimary incident from the lifecycle owner before cleanup started.
Returns
NoneFinish resource cleanup even when a shutdown hook fails.
async def __onStartup(self: Self, runtime: Runtime, http_interface: str = 'asgi'): (source)

Boot eager providers and run runtime-specific startup hooks.

Parameters
runtime:orionis.foundation.enums.runtimes.RuntimeHTTP or CLI runtime whose startup hooks should run.
http_interface:str, optionalTransport recorded when HTTP startup initializes the kernel.
Returns
NoneComplete hooks and, for HTTP, publish both kernel handlers.
def __persistCompiledState(self: Self): (source)

Save bootstrap metadata when compiled caching is active.

Skip writes during Reactor bootstrap recovery.

Returns
NonePersist state only when a cache driver is available.
def __resolveAndValidateRoutingFiles(self: Self, paths: str | list[str] | None, required_imports: set[str], *, context: str = '') -> list[Path]: (source)

Resolve route files and verify their required imports.

Parameters
paths:str | list[str] | NoneRoute files relative to the application root, or None.
required_imports:set[str]Module names accepted as routing imports.
context:str, optionalRouting context whose missing files Reactor may explicitly recover.
Returns
list[pathlib.Path]Resolved route files in input order, including recoverable missing files when recovery is active for this context.
Raises
TypeErrorIf path input is invalid or a nonempty file lacks required imports.
FileNotFoundErrorIf a file is missing outside an active recovery context.
def __resolveEagerProvider(self: Self): (source)

Register eager providers and queue their asynchronous boot methods.

Run synchronous boot methods immediately and skip resolved providers.

Returns
NoneRecord resolved providers and retain asynchronous boots for startup.
async def __rsgi__(self: Self, scope: Scope, protocol: HTTPProtocol | WebsocketProtocol | ProtocolError | ProtocolClosed) -> object: (source)

Route RSGI HTTP and WebSocket connections to the HTTP kernel.

Parameters
scope:granian.rsgi.ScopeConnection metadata, including the RSGI protocol type.
protocol:objectRSGI HTTP, WebSocket, error, or closed-connection protocol instance.
Returns
objectKernel result, or None for an unsupported protocol.
def __rsgi_del__(self: Self, loop: asyncio.AbstractEventLoop): (source)

Run RSGI shutdown on the server's event loop.

Parameters
loop:asyncio.AbstractEventLoopServer event loop used to complete shutdown synchronously.
Returns
NoneComplete shutdown hooks and release HTTP reporting ownership.
def __rsgi_init__(self: Self, loop: asyncio.AbstractEventLoop): (source)

Run RSGI startup on the server's event loop.

Parameters
loop:asyncio.AbstractEventLoopServer event loop used to complete startup synchronously.
Returns
NoneComplete provider, kernel, and startup-hook initialization.
async def __runLifespanEvent(self: Self, event: Lifespan, send: Callable[[dict], Awaitable[None]]): (source)

Run lifespan callbacks and acknowledge successful completion.

Activate HTTP failure reporting only after startup acknowledgement.

Parameters
event:orionis.foundation.enums.lifespan.LifespanStartup or shutdown event whose callbacks should run.
send:collections.abc.CallableAsynchronous callable sending the completion message.
Returns
NoneComplete the event callbacks and send their acknowledgement.
async def __runShutdownCallbacks(self: Self, callbacks: set[Callable], parent_event_id: str | None): (source)

Attempt every shutdown callback and propagate its first failure.

Parameters
callbacks:set of collections.abc.CallableIndependent resource cleanup hooks in unspecified execution order.
parent_event_id:str or NonePrimary execution incident linked to subsequent cleanup failures.
Returns
NoneComplete every callback, observing each operational failure once.
Raises
ExceptionThe first callback failure, after attempting the remaining hooks.
async def __sendLifespanFailure(self: Self, event: Lifespan, send: Callable[[dict], Awaitable[None]], error: Exception) -> bool: (source)

Report a lifespan failure and send the ASGI failure response.

Parameters
event:orionis.foundation.enums.lifespan.LifespanLifecycle event that failed.
send:collections.abc.CallableAsynchronous callable sending the failure response.
error:ExceptionOriginal lifecycle exception to report.
Returns
boolWhether the failure response was sent. A failed send is observed separately so the caller can propagate the original lifecycle error.
def __setRuntimeConfigValue(self: Self, key_parts: tuple[str, ...], value: object) -> object: (source)

Write a runtime value, replacing non-dictionary parents as needed.

Parameters
key_parts:tuple of strNonempty sequence of configuration path components.
value:objectValue stored at the final path component.
Returns
objectThe assigned value, unchanged.
def __setTimezoneAndLocale(self: Self): (source)

Apply configured timezone and locale settings to runtime services.

Returns
NoneConfigure date handling, environment values, and supported system timezone and locale settings.
async def __startRsgi(self: Self): (source)

Complete RSGI startup before activating failure reporting.

Returns
NoneAcquire HTTP reporting ownership after successful initialization.
async def __stopRsgi(self: Self): (source)

Run RSGI shutdown before releasing failure-reporting ownership.

Returns
NoneRelease HTTP ownership even if shutdown raises an exception.
def __storeDeferredProviderClass(self: Self, provider: type[IDeferrableProvider]): (source)

Map each deferred service identifier to its provider metadata.

Parameters
provider:type[IDeferrableProvider]Validated deferred provider class declaring its provided services.
Returns
NoneReplace deferred bindings for the provider's declared services.
Raises
TypeErrorIf a provided service is neither a string identifier nor a class.
def __storeEagerProviderClass(self: Self, provider: type[IServiceProvider]): (source)

Prepend validated provider metadata to the eager registry.

Parameters
provider:type[IServiceProvider]Validated eager provider class.
Returns
NoneStore module and class names with highest registration priority.
def __storeProviderClass(self: Self, provider: type[IServiceProvider]): (source)

Validate and store a provider class in its matching registry.

Parameters
provider:type[IServiceProvider]Eager or deferred provider class to register.
Returns
NoneRecord eager metadata or deferred service bindings.
Raises
TypeErrorIf the provider class or a deferred service identifier is invalid.
def __validateAndReturnPath(self: Self, path: Path | str) -> Path: (source)

Resolve a supported path to an absolute filesystem path.

Parameters
path:pathlib.Path or strPath to resolve. Relative strings use the application root, or the import-time working directory before the root is initialized. Relative path objects use the current working directory.
Returns
pathlib.PathResolved absolute path.
Raises
TypeErrorIf path is neither a path object nor a string.
def __validateProviderClass(self: Self, provider_class: type[IServiceProvider]): (source)

Require a service provider class implementing IServiceProvider.

Parameters
provider_class:type[IServiceProvider]Provider class to validate before storing its metadata.
Returns
NoneAccept a class that satisfies the provider contract.
Raises
TypeErrorIf the value is not a class implementing IServiceProvider.
async def aclose(self: Self): (source)

Close the headless reporting lifetime acquired by boot.

Do not run HTTP or CLI hooks. Preserve shared tasks and the logging sink while another owner remains active.

Ignore reentrant calls from reporting hooks; the external lifecycle owner performs closure after those hooks finish.

Returns
NoneDrain final resources and release headless ownership when present.
async def boot(self: Self) -> Self: (source)

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.
def compile(self: Self, path: str | None = None, invalidation_paths: list[str] | None = None): (source)

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.
def config(self: Self, key: str | None = None, value: object = _SENTINEL) -> object: (source)

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.
def create(self: Self) -> Self: (source)

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.
async def getExceptionHandler(self: Self) -> IBaseExceptionHandler: (source)

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.
def getMiddleware(self: Self) -> list[type[IBaseMiddleware]]: (source)

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.
async def getScheduler(self: Self) -> IBaseScheduler: (source)

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.
async def handleCommand(self: Self, args: list[str] | None = None) -> int: (source)

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.
def isDebug(self: Self) -> bool: (source)

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.
def isProduction(self: Self) -> bool: (source)

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.
def on(self: Self, lifespan: Lifespan, *callbacks: Callable[..., Any] | Callable[..., Awaitable[Any]], runtime: Runtime | None = None) -> Self: (source)

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.
def path(self: Self, key: str | None = None) -> Path | Mapping[str, Path] | None: (source)

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.
def resetRuntimeConfig(self: Self) -> bool: (source)

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.
def routingPaths(self: Self, key: str | None = None) -> list[Path] | dict | None: (source)

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.
def underMaintenance(self: Self) -> bool: (source)

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.
def withConfigApp(self: Self, **app_config: object) -> Self: (source)

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.
def withConfigAuth(self: Self, **auth_config: object) -> Self: (source)

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.
def withConfigCache(self: Self, **cache_config: object) -> Self: (source)

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.
def withConfigDatabase(self: Self, **database_config: object) -> Self: (source)

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.
def withConfigFilesystems(self: Self, **filesystems_config: object) -> Self: (source)

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.
def withConfigHttp(self: Self, **http_config: object) -> Self: (source)

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.
def withConfigLogging(self: Self, **logging_config: object) -> Self: (source)

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.
def withConfigMail(self: Self, **mail_config: object) -> Self: (source)

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.
def withConfigMcp(self: Self, **mcp_config: object) -> Self: (source)

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.
def withConfigPaths(self: Self, **paths: str | Path | None) -> Self: (source)

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.
def withConfigQueue(self: Self, **queue_config: object) -> Self: (source)

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.
def withConfigSession(self: Self, **session_config: object) -> Self: (source)

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.
def withConfigTesting(self: Self, **testing_config: object) -> Self: (source)

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.
def withExceptionHandler(self: Self, handler: type[IBaseExceptionHandler]) -> Self: (source)

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.
def withMiddleware(self: Self, *middleware: type[IBaseMiddleware]) -> Self: (source)

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.
def withProviders(self: Self, *providers: type[IServiceProvider]) -> Self: (source)

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

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.
def withScheduler(self: Self, scheduler: type[IBaseScheduler]) -> Self: (source)

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.
__basePath = (source)

Validate and store the basePath as the application root.

__booted: bool = (source)

Initialize application state flags.

__bootstrap: dict[str, Any] = (source)

Initialize configuration dictionaries.

__cache_resolved_providers: set[str] = (source)

Initialize deferred providers cache.

__compiled: bool = (source)

Compilation and configuration caching logic.

__compiled_invalidation_paths_dirs: set[Path] = (source)

Compiled invalidation paths dirs produced by set.

__compiled_invalidation_paths_files: set[Path] = (source)

Compiled invalidation paths files produced by set.

__compiled_path: Path | None = (source)

Directory containing compiled application bootstrap metadata.

__compiled_state_store: IFileBasedCache | None = (source)

Cache driver for storing compiled configuration.

__configured: bool = (source)

Configured flag used by Application.

__entry_point: str | None = (source)

Store the file path where the application was started.

__exception_handler_instance: IBaseExceptionHandler | None = (source)

Shared handler constructed outside request and operation scopes.

__exception_handler_lock = (source)

Serialize construction of the application exception handler.

__exception_handler_resolved: type[IBaseExceptionHandler] | None = (source)

Exception-handler instance cached after its first resolution.

__headless_close_lock = (source)

Coordinate explicit headless startup and final resource closure.

__hook_events: dict = (source)

Lifecycle event callbacks for each runtime (HTTP/CLI/global). These are not cached and execute on each lifecycle event.

__http_disconnect_monitoring: bool = (source)

Http disconnect monitoring flag used by Application.

__http_disconnect_paths: frozenset[str] = (source)

Http disconnect paths produced by kernel.disconnectPaths.

__is_compiled: bool = (source)

Flag to determine if working with previously compiled state.

__is_debug_cache: bool = (source)

Is debug cache flag used by Application.

__is_production_cache: bool = (source)

Is production cache flag used by Application.

__kernel_cli: Callable | None = (source)

Kernel cli obtained from kernel.handle.

__kernel_cli_lock = (source)

Synchronization primitive controlling access to kernel cli lock.

__kernel_http_asgi: Callable | None = (source)

Kernel http asgi supplied through asgi_handler.

__kernel_http_lock = (source)

Synchronization primitive controlling access to kernel http lock.

__kernel_http_rsgi: Callable | None = (source)

Kernel http rsgi supplied through rsgi_handler.

__maintenance_cache: tuple[int, bool] = (source)

Most recently observed maintenance-mode state.

__maintenance_lock = (source)

Synchronization primitive controlling access to maintenance lock.

__maintenance_marker: Path | None = (source)

Store the shared maintenance marker and its last observed state.

__pending_boot_providers: deque[IServiceProvider] = (source)

Pending boot providers produced by deque.

__provider_boot_lock = (source)

Synchronization primitive controlling access to provider boot lock.

__providers_registry_initialized: bool = (source)

Initialize providers registry sentinel.

__runtime_config: dict[str, Any] = (source)

Mutable runtime view of the committed application configuration.

__runtime_config_initialized: bool = (source)

Runtime config initialized flag used by Application.

__scheduler_resolved: type[IBaseScheduler] | None = (source)

Initialize references to resolved service classes.

__start_at = (source)

Store the application startup timestamp in nanoseconds.

_Application__initialized: bool = (source)

Mark the Application as initialized to enforce singleton behavior.

_deferred_providers: dict = (source)

Initialize deferred providers storage for tracking.

_failure_runtime = (source)

Prepared coordinator activated by successful runtime owners.

areProvidersBooted: bool = (source)

Check whether all eager providers have finished booting.

Returns
boolTrue after creation and eager startup. Deferred providers still boot on first resolution.
basePath: Path = (source)

Return the resolved application root directory.

Returns
pathlib.PathAbsolute root selected when this singleton was first initialized.

Check whether compiled bootstrap caching is enabled.

Returns
boolTrue when compiled caching is enabled, even before a cache hit.
compiledInvalidationPathsDirs: list[Path] = (source)

Return configured directories used for bootstrap cache invalidation.

Returns
list of pathlib.PathConfigured directory invalidation paths as a new list.
compiledInvalidationPathsFiles: list[Path] = (source)

Return configured files used for bootstrap cache invalidation.

Returns
list of pathlib.PathConfigured file invalidation paths as a new list.
compiledPath: Path | None = (source)

Return the configured bootstrap cache directory.

Returns
pathlib.Path or NoneResolved cache directory, or None before caching is configured.

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.

Report whether configuration and eager registration are complete.

Returns
boolTrue after create() completes, independently of asynchronous provider startup and HTTP kernel readiness.

Report the configuration-stage state exposed by isBooted.

Returns
boolLegacy creation flag, identical to isBooted.

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.
routeHealthCheck: str = (source)

Return the configured health-check URL path.

Returns
strHealth-check path, or "/up" when no nonempty path is configured.

Return the instance initialization timestamp in Unix nanoseconds.

Returns
intTime recorded when this singleton was first initialized.