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 Application(Container, IApplication): (source)
Constructor: Application(*args, **kwargs)
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 | __asgi |
Receive ASGI lifespan messages until shutdown or disconnect. |
| Method | __assert |
Reject locked bootstrap changes and initialize mutable defaults. |
| Method | __assert |
Reject Python runtimes below the framework's minimum version. |
| Method | __boot |
Configure bootstrap caching and restore a valid cached snapshot. |
| Async Method | __boot |
Await pending eager providers under a shared startup lock. |
| Async Method | __call__ |
Route ASGI HTTP, WebSocket, and lifespan scopes to their handlers. |
| Async Method | __close |
Close the bound logger under the final owner's lifecycle lock. |
| Async Method | __close |
Drain runtime tasks and close the logging sink for its final owner. |
| Method | __commit |
Freeze bootstrap metadata and mark configuration initialized. |
| Method | __default |
Build a fresh bootstrap mapping from core framework metadata. |
| Method | __discover |
Import concrete providers declared by the discovered modules. |
| Method | __ensure |
Populate an empty bootstrap mapping with core defaults. |
| Method | __ensure |
Populate missing bootstrap paths from the application defaults. |
| Method | __ensure |
Initialize eager and deferred provider registries once. |
| Method | __get |
Read a runtime value through pre-parsed configuration components. |
| Async Method | __handle |
Dispatch ASGI connections under the configured disconnect policy. |
| Async Method | __handle |
Dispatch RSGI connections under the configured disconnect policy. |
| Async Method | __handle |
Process one ASGI lifespan event and report its outcome. |
| Method | __init__ |
Initialize the application singleton and its lifecycle state once. |
| Async Method | __initialize |
Boot the CLI kernel and cache its handler under a shared lock. |
| Async Method | __initialize |
Initialize both HTTP handlers under a shared startup lock. |
| Method | __load |
Load bootstrap state and register providers without awaiting async boots. |
| Async Method | __load |
Build and validate the configured CLI kernel. |
| Method | __load |
Load core defaults, custom sections, and discovered configuration data. |
| Method | __load |
Register the framework's core service provider classes. |
| Method | __load |
Merge custom sections and discovered dataclasses into the defaults. |
| Async Method | __load |
Build and boot the configured HTTP kernel. |
| Method | __load |
Discover application providers, then register core framework providers. |
| Method | __lock |
Recursively freeze the bootstrap configuration. |
| Async Method | __on |
Run shutdown hooks before draining runtime resources. |
| Async Method | __on |
Boot eager providers and run runtime-specific startup hooks. |
| Method | __persist |
Save bootstrap metadata when compiled caching is active. |
| Method | __resolve |
Resolve route files and verify their required imports. |
| Method | __resolve |
Register eager providers and queue their asynchronous boot methods. |
| Async Method | __rsgi__ |
Route RSGI HTTP and WebSocket connections to the HTTP kernel. |
| Method | __rsgi |
Run RSGI shutdown on the server's event loop. |
| Method | __rsgi |
Run RSGI startup on the server's event loop. |
| Async Method | __run |
Run lifespan callbacks and acknowledge successful completion. |
| Async Method | __run |
Attempt every shutdown callback and propagate its first failure. |
| Async Method | __send |
Report a lifespan failure and send the ASGI failure response. |
| Method | __set |
Write a runtime value, replacing non-dictionary parents as needed. |
| Method | __set |
Apply configured timezone and locale settings to runtime services. |
| Async Method | __start |
Complete RSGI startup before activating failure reporting. |
| Async Method | __stop |
Run RSGI shutdown before releasing failure-reporting ownership. |
| Method | __store |
Map each deferred service identifier to its provider metadata. |
| Method | __store |
Prepend validated provider metadata to the eager registry. |
| Method | __store |
Validate and store a provider class in its matching registry. |
| Method | __validate |
Resolve a supported path to an absolute filesystem path. |
| Method | __validate |
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 | 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. |
| Instance Variable | __base |
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 |
Initialize deferred providers cache. |
| Instance Variable | __compiled |
Compilation and configuration caching logic. |
| Instance Variable | __compiled |
Compiled invalidation paths dirs produced by set. |
| Instance Variable | __compiled |
Compiled invalidation paths files produced by set. |
| Instance Variable | __compiled |
Directory containing compiled application bootstrap metadata. |
| Instance Variable | __compiled |
Cache driver for storing compiled configuration. |
| Instance Variable | __configured |
Configured flag used by Application. |
| Instance Variable | __entry |
Store the file path where the application was started. |
| Instance Variable | __exception |
Shared handler constructed outside request and operation scopes. |
| Instance Variable | __exception |
Serialize construction of the application exception handler. |
| Instance Variable | __exception |
Exception-handler instance cached after its first resolution. |
| Instance Variable | __headless |
Coordinate explicit headless startup and final resource closure. |
| Instance Variable | __hook |
Lifecycle event callbacks for each runtime (HTTP/CLI/global). These are not cached and execute on each lifecycle event. |
| Instance Variable | __http |
Http disconnect monitoring flag used by Application. |
| Instance Variable | __http |
Http disconnect paths produced by kernel.disconnectPaths. |
| Instance Variable | __is |
Flag to determine if working with previously compiled state. |
| Instance Variable | __is |
Is debug cache flag used by Application. |
| Instance Variable | __is |
Is production cache flag used by Application. |
| Instance Variable | __kernel |
Kernel cli obtained from kernel.handle. |
| Instance Variable | __kernel |
Synchronization primitive controlling access to kernel cli lock. |
| Instance Variable | __kernel |
Kernel http asgi supplied through asgi_handler. |
| Instance Variable | __kernel |
Synchronization primitive controlling access to kernel http lock. |
| Instance Variable | __kernel |
Kernel http rsgi supplied through rsgi_handler. |
| Instance Variable | __maintenance |
Most recently observed maintenance-mode state. |
| Instance Variable | __maintenance |
Synchronization primitive controlling access to maintenance lock. |
| Instance Variable | __maintenance |
Store the shared maintenance marker and its last observed state. |
| Instance Variable | __pending |
Pending boot providers produced by deque. |
| Instance Variable | __provider |
Synchronization primitive controlling access to provider boot lock. |
| Instance Variable | __providers |
Initialize providers registry sentinel. |
| Instance Variable | __runtime |
Mutable runtime view of the committed application configuration. |
| Instance Variable | __runtime |
Runtime config initialized flag used by Application. |
| Instance Variable | __scheduler |
Initialize references to resolved service classes. |
| Instance Variable | __start |
Store the application startup timestamp in nanoseconds. |
| Instance Variable | _ |
Mark the Application as initialized to enforce singleton behavior. |
| Instance Variable | _deferred |
Initialize deferred providers storage for tracking. |
| Instance Variable | _failure |
Prepared coordinator activated by successful runtime owners. |
| 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 Container:
| Method | __alias |
Validate and normalize a service alias string. |
| Async Method | __auto |
Resolve and invoke a callable, injecting dependencies. |
| Async Method | __auto |
Automatically instantiate a class with injected dependencies. |
| Async Method | __await |
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 | __boot |
Register a deferred provider once and complete its boot hook. |
| Async Method | __create |
Build and store the instance backing a scoped binding. |
| Async Method | __create |
Build and cache the single instance backing a singleton binding. |
| Method | __creation |
Return the creation lock for a key, bound to the running loop. |
| Method | __ensure |
Ensure that a service or alias can be overridden globally. |
| Method | __ensure |
Ensure that a service can be overridden in the current scope. |
| Method | __ensure |
Ensure that a concrete class implements the specified abstract class. |
| Method | __ensure |
Ensure that an instance implements the specified abstract class. |
| Method | __is |
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 | __resolve |
Resolve a single argument for dependency injection. |
| Async Method | __resolve |
Resolve and register a deferred service provider for a given service. |
| Async Method | __resolve |
Resolve a service key to its abstract type. |
| Async Method | __resolve |
Resolve a parameter whose value was omitted from a keyword call. |
| Async Method | __resolve |
Resolve a binding for an abstract service or build it when unbound. |
| Async Method | __resolve |
Resolve a positional call using the current bindings and scope. |
| Async Method | __resolve |
Validate a schema argument using the active HTTP request payload. |
| Async Method | __resolve |
Resolve arguments for a callable signature using dependency injection. |
| 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. |
| 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 |
Tracks resolved deferred providers. |
| Instance Variable | __creation |
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 providers with boot work that is still pending. |
| Instance Variable | __registered |
Deferred providers whose bindings have already been registered. |
| Instance Variable | __singleton |
Cache for singleton instances. |
| Instance Variable | _ |
Mark as initialized to prevent re-initialization. |
Inherited from IApplication (via Container):
| Class Variable | __slots__ |
Declare that this class introduces no additional instance slots. |
Return this class's existing singleton without initializing it.
| Returns | |
typing.Self or None | Existing instance, or None before construction. Configuration may remain uninitialized until create() completes. |
Self, receive: Callable[ [], Awaitable[ dict]], send: Callable[ [ dict], Awaitable[ None]]):
(source)
¶
Receive ASGI lifespan messages until shutdown or disconnect.
| Parameters | |
receive:collections.abc.Callable | Asynchronous callable receiving lifespan messages. |
send:collections.abc.Callable | Asynchronous callable sending lifespan acknowledgements. |
| Returns | |
None | Finish after shutdown, disconnect, or a reported lifecycle failure. |
Reject locked bootstrap changes and initialize mutable defaults.
| Returns | |
None | Prepare a mutable bootstrap mapping for configuration updates. |
| Raises | |
RuntimeError | If creation has already locked the bootstrap configuration. |
Reject Python runtimes below the framework's minimum version.
| Returns | |
None | Leave application state unchanged when the runtime is supported. |
| Raises | |
RuntimeError | If the interpreter version is below PYTHON_REQUIRES. |
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 | |
compiledstr | None, optional | Cache directory, or None to use the framework cache path. |
compiledlist[str] | None, optional | Existing files and directories whose changes invalidate the snapshot. |
| Returns | |
None | Initialize cache metadata and commit any valid restored configuration. |
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 | |
None | Remove each provider only after its boot method completes. |
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:dict | Connection metadata, including the ASGI scope type. |
receive:collections.abc.Callable | Asynchronous callable receiving connection messages. |
send:collections.abc.Callable | Asynchronous callable sending connection messages. |
| Returns | |
typing.Any | None | Handler result, or None for an unsupported scope type. |
Close the bound logger under the final owner's lifecycle lock.
| Parameters | |
failureorionis.failure.runtime.FailureRuntime or None | Runtime whose automatic reporting must stop before logger cleanup. |
| Returns | |
None | Disable failure reporting and close the logger when configured. |
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, optional | Ownership token to retire, or None to check shared ownership without releasing a token. |
ownerasyncio.Task or None, optional | Lifecycle task to exclude from the shutdown it is awaiting. |
parentstr or None, optional | Primary execution incident linked to resource cleanup failures. |
| Returns | |
None | Finish shared work and retain the sink while another owner needs it. |
Freeze bootstrap metadata and mark configuration initialized.
| Returns | |
None | Lock bootstrap containers and enable runtime configuration access. |
Build a fresh bootstrap mapping from core framework metadata.
| Returns | |
dict[str, typing.Any] | Mutable configuration, path, provider, routing, and kernel sections. |
Populate an empty bootstrap mapping with core defaults.
| Returns | |
None | Initialize defaults only when the bootstrap mapping is empty. |
Populate missing bootstrap paths from the application defaults.
| Returns | |
None | Resolve default paths only when no path mapping is configured. |
Initialize eager and deferred provider registries once.
| Returns | |
None | Create missing registry mappings and mark their structure initialized. |
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:dict | ASGI HTTP or WebSocket connection metadata. |
receive:collections.abc.Callable | Asynchronous callable receiving connection messages. |
send:collections.abc.Callable | Asynchronous callable transmitting response messages. |
| Returns | |
typing.Any | None | Kernel result, or None after disconnect-driven cancellation. |
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.Scope | RSGI connection metadata. |
protocol:granian.rsgi.HTTPProtocol | Connection protocol exposing a client_disconnect awaitable when HTTP disconnect monitoring is enabled. |
| Returns | |
object | Kernel result, or None after disconnect-driven cancellation. |
| Raises | |
TypeError | If the configured kernel does not implement the HTTP interface. |
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.Lifespan | Startup or shutdown event to process. |
send:collections.abc.Callable | Asynchronous callable sending the event acknowledgement. |
started:bool | Whether an earlier startup event completed successfully. |
| Returns | |
bool | True after successful startup; False after shutdown or failure. |
Initialize the application singleton and its lifecycle state once.
| Parameters | |
basepathlib.Path, optional | Application root, defaulting to the working directory at import time. |
| Returns | |
None | Initialize container, configuration, and lifecycle state in place. |
| Raises | |
RuntimeError | If the Python runtime is below the framework's minimum version. |
TypeError | If the root is neither a path object nor a string. |
Boot the CLI kernel and cache its handler under a shared lock.
| Returns | |
None | Publish the command handler only after kernel boot completes. |
Self, interface: str, *, start_runtime: bool = False):
(source)
¶
Initialize both HTTP handlers under a shared startup lock.
| Parameters | |
interface:str | Transport identifier recorded as app.interface. |
startbool, optional | Start HTTP failure reporting for requests without lifespan startup. |
| Returns | |
None | Publish handlers after kernel boot and failure-runtime preparation. |
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 | |
None | Publish deferred bindings and register eager providers for startup. |
Build and validate the configured CLI kernel.
| Returns | |
orionis.console.contracts.kernel.IKernelCLI | Validated kernel awaiting command-handler initialization. |
| Raises | |
RuntimeError | If no CLI kernel metadata is configured. |
TypeError | If the configured kernel does not implement IKernelCLI. |
Load core defaults, custom sections, and discovered configuration data.
Apply programmatic overrides before discovered dataclass values.
| Returns | |
None | Replace bootstrap configuration with the merged section mapping. |
Register the framework's core service provider classes.
| Returns | |
None | Add core provider metadata to the bootstrap registries. |
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 | |
defaultdict[str, typing.Any] | Mutable defaults updated in place. |
customdict[str, typing.Any] | Section dictionaries merged before discovered dataclass values. |
dataclasses:set[tuple[str, str, str, type[typing.Any]]] | None, optional | Entries 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 | |
RuntimeError | If a configuration dataclass cannot be instantiated or serialized. |
Build and boot the configured HTTP kernel.
| Returns | |
orionis.http.contracts.kernel.IKernelHTTP | Validated kernel after its boot method completes. |
| Raises | |
TypeError | If the configured kernel does not implement IKernelHTTP. |
Discover application providers, then register core framework providers.
| Returns | |
None | Populate registries from application and core provider classes. |
Recursively freeze the bootstrap configuration.
| Returns | |
None | Replace mutable containers without changing the creation flag. |
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.Runtime | HTTP or CLI runtime whose shutdown hooks should run. |
failureobject | None, optional | Reporting ownership token; HTTP uses its shared owner when omitted. |
ownerasyncio.Task or None, optional | Lifecycle owner awaiting protected cleanup from another task. |
parentstr or None, optional | Primary incident from the lifecycle owner before cleanup started. |
| Returns | |
None | Finish resource cleanup even when a shutdown hook fails. |
Boot eager providers and run runtime-specific startup hooks.
| Parameters | |
runtime:orionis.foundation.enums.runtimes.Runtime | HTTP or CLI runtime whose startup hooks should run. |
httpstr, optional | Transport recorded when HTTP startup initializes the kernel. |
| Returns | |
None | Complete hooks and, for HTTP, publish both kernel handlers. |
Save bootstrap metadata when compiled caching is active.
Skip writes during Reactor bootstrap recovery.
| Returns | |
None | Persist state only when a cache driver is available. |
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] | None | Route files relative to the application root, or None. |
requiredset[str] | Module names accepted as routing imports. |
context:str, optional | Routing 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 | |
TypeError | If path input is invalid or a nonempty file lacks required imports. |
FileNotFoundError | If a file is missing outside an active recovery context. |
Register eager providers and queue their asynchronous boot methods.
Run synchronous boot methods immediately and skip resolved providers.
| Returns | |
None | Record resolved providers and retain asynchronous boots for startup. |
Run RSGI shutdown on the server's event loop.
| Parameters | |
loop:asyncio.AbstractEventLoop | Server event loop used to complete shutdown synchronously. |
| Returns | |
None | Complete shutdown hooks and release HTTP reporting ownership. |
Run RSGI startup on the server's event loop.
| Parameters | |
loop:asyncio.AbstractEventLoop | Server event loop used to complete startup synchronously. |
| Returns | |
None | Complete provider, kernel, and startup-hook initialization. |
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.Lifespan | Startup or shutdown event whose callbacks should run. |
send:collections.abc.Callable | Asynchronous callable sending the completion message. |
| Returns | |
None | Complete the event callbacks and send their acknowledgement. |
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.Callable | Independent resource cleanup hooks in unspecified execution order. |
parentstr or None | Primary execution incident linked to subsequent cleanup failures. |
| Returns | |
None | Complete every callback, observing each operational failure once. |
| Raises | |
Exception | The first callback failure, after attempting the remaining hooks. |
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.Lifespan | Lifecycle event that failed. |
send:collections.abc.Callable | Asynchronous callable sending the failure response. |
error:Exception | Original lifecycle exception to report. |
| Returns | |
bool | Whether the failure response was sent. A failed send is observed separately so the caller can propagate the original lifecycle error. |
Apply configured timezone and locale settings to runtime services.
| Returns | |
None | Configure date handling, environment values, and supported system timezone and locale settings. |
Complete RSGI startup before activating failure reporting.
| Returns | |
None | Acquire HTTP reporting ownership after successful initialization. |
Run RSGI shutdown before releasing failure-reporting ownership.
| Returns | |
None | Release HTTP ownership even if shutdown raises an exception. |
Map each deferred service identifier to its provider metadata.
| Parameters | |
provider:type[IDeferrableProvider] | Validated deferred provider class declaring its provided services. |
| Returns | |
None | Replace deferred bindings for the provider's declared services. |
| Raises | |
TypeError | If a provided service is neither a string identifier nor a class. |
Prepend validated provider metadata to the eager registry.
| Parameters | |
provider:type[IServiceProvider] | Validated eager provider class. |
| Returns | |
None | Store module and class names with highest registration priority. |
Validate and store a provider class in its matching registry.
| Parameters | |
provider:type[IServiceProvider] | Eager or deferred provider class to register. |
| Returns | |
None | Record eager metadata or deferred service bindings. |
| Raises | |
TypeError | If the provider class or a deferred service identifier is invalid. |
Resolve a supported path to an absolute filesystem path.
| Parameters | |
path:pathlib.Path or str | Path 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.Path | Resolved absolute path. |
| Raises | |
TypeError | If path is neither a path object nor a string. |
Require a service provider class implementing IServiceProvider.
| Parameters | |
providertype[IServiceProvider] | Provider class to validate before storing its metadata. |
| Returns | |
None | Accept a class that satisfies the provider contract. |
| Raises | |
TypeError | If the value is not a class implementing IServiceProvider. |
orionis.IApplication.acloseClose 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 | |
None | Drain final resources and release headless ownership when present. |
orionis.IApplication.bootCreate 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.IApplication.compileConfigure 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. |
orionis.IApplication.configRead 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.IApplication.createCreate 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.IApplication.getExceptionHandlerResolve 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.IApplication.getMiddlewareResolve 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.IApplication.getSchedulerResolve 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. |
orionis.IApplication.handleCommandRun 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.IApplication.isDebugCheck 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.IApplication.isProductionCheck 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.IApplication.onRegister 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. |
orionis.IApplication.pathReturn 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.IApplication.resetRuntimeConfigRestore 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. |
orionis.IApplication.routingPathsReturn 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.IApplication.underMaintenanceCheck 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.IApplication.withConfigAppSet 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.IApplication.withConfigAuthSet 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.IApplication.withConfigCacheSet 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.IApplication.withConfigDatabaseSet 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. |
Set 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.IApplication.withConfigHttpSet 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.IApplication.withConfigLoggingSet 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.IApplication.withConfigMailSet 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.IApplication.withConfigMcpSet 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.IApplication.withConfigPathsConfigure 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.IApplication.withConfigQueueSet 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.IApplication.withConfigSessionSet 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.IApplication.withConfigTestingSet 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. |
Set 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. |
orionis.IApplication.withMiddlewareRegister 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. |
orionis.IApplication.withProvidersRegister 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.IApplication.withRoutingConfigure 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.IApplication.withSchedulerSet 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. |
Lifecycle event callbacks for each runtime (HTTP/CLI/global). These are not cached and execute on each lifecycle event.
orionis.IApplication.areProvidersBootedCheck whether all eager providers have finished booting.
| Returns | |
bool | True after creation and eager startup. Deferred providers still boot on first resolution. |
orionis.IApplication.basePathReturn the resolved application root directory.
| Returns | |
pathlib.Path | Absolute root selected when this singleton was first initialized. |
orionis.IApplication.compiledCheck whether compiled bootstrap caching is enabled.
| Returns | |
bool | True when compiled caching is enabled, even before a cache hit. |
Return configured directories used for bootstrap cache invalidation.
| Returns | |
list of pathlib.Path | Configured directory invalidation paths as a new list. |
Return configured files used for bootstrap cache invalidation.
| Returns | |
list of pathlib.Path | Configured file invalidation paths as a new list. |
orionis.IApplication.compiledPathReturn the configured bootstrap cache directory.
| Returns | |
pathlib.Path or None | Resolved cache directory, or None before caching is configured. |
orionis.IApplication.entryPointReturn 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.IApplication.isBootedReport whether configuration and eager registration are complete.
| Returns | |
bool | True after create() completes, independently of asynchronous provider startup and HTTP kernel readiness. |
orionis.IApplication.isCreatedReport the configuration-stage state exposed by isBooted.
| Returns | |
bool | Legacy creation flag, identical to isBooted. |
orionis.IApplication.isHttpReadyCheck 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.IApplication.routeHealthCheckReturn the configured health-check URL path.
| Returns | |
str | Health-check path, or "/up" when no nonempty path is configured. |