orionis.Application

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

Explore modules View classes

class documentation

class Application(Container, IApplication): (source)

Constructor: Application(*args, **kwargs)

View In Hierarchy

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 the existing application without constructing or booting it.
Async Method	`__asgiLifespan`	Handle ASGI lifespan startup and shutdown events.
Method	`__assertConfigMutable`	Assert that configuration is mutable before modification.
Method	`__assertPythonVersion`	Assert that the current Python version meets the minimum requirement.
Method	`__bootCompiledState`	Initialize application compilation and configuration caching.
Async Method	`__bootEagerProviders`	Boot all pending eager service providers.
Async Method	`__call__`	Dispatch ASGI requests to the appropriate handler by scope type.
Method	`__commitConfig`	Lock configuration and mark application as initialized.
Method	`__defaultBootstrap`	Return the default bootstrap configuration.
Method	`__discoverProviders`	Discover and register service providers from the providers folder.
Method	`__ensureDefaultBootstrap`	Initialize the bootstrap configuration with default values.
Method	`__ensureDefaultPaths`	Ensure default application paths are set in the bootstrap configuration.
Method	`__ensureProvidersRegistryStructure`	Ensure the providers registry structure is properly initialized.
Method	`__getRuntimeConfigValue`	Retrieve a value from a nested dictionary using dot notation.
Async Method	`__handleHttpAsgi`	Handle an HTTP request using the configured disconnect policy.
Async Method	`__handleHttpRsgi`	Handle HTTP requests using the KernelHTTP in RSGI mode.
Method	`__init__`	Initialize the Application instance.
Async Method	`__initializeCliKernel`	Build and boot the CLI kernel once for concurrent commands.
Async Method	`__initializeHttpKernel`	Build and boot the HTTP kernel once for concurrent first requests.
Method	`__load`	Load and initialize application configuration and service providers.
Async Method	`__loadCLIKernel`	Load and return the configured CLI kernel instance.
Method	`__loadConfig`	Load and merge the final configuration from dataclasses and custom config.
Method	`__loadCoreProviders`	Load and register core framework service providers.
Method	`__loadCustomConfig`	Merge custom configuration and dataclass defaults into the base config.
Async Method	`__loadHTTPKernel`	Load and return the configured HTTP kernel instance.
Method	`__loadProviders`	Load and register all service providers.
Method	`__lockConfig`	Deeply freeze and lock the application configuration.
Async Method	`__onShutdown`	Execute shutdown callbacks for the application lifecycle.
Async Method	`__onStartup`	Execute startup callbacks for the application lifecycle.
Method	`__persistCompiledState`	Persist the compiled application state to cache.
Method	`__resolveAndValidateRoutingFiles`	Resolve and validate routing file paths.
Method	`__resolveEagerProvider`	Resolve and register all eager service providers.
Async Method	`__rsgi__`	Handle the RSGI protocol for incoming requests.
Method	`__rsgi_del__`	Execute the RSGI application shutdown lifecycle.
Method	`__rsgi_init__`	Initialize the RSGI application lifecycle and execute startup callbacks.
Method	`__setRuntimeConfigValue`	Set a value in a nested dictionary using dot notation.
Method	`__setTimezoneAndLocale`	Set system timezone and locale from application configuration.
Method	`__storeDeferredProviderClass`	Store a deferred service provider instance in the deferred registry.
Method	`__storeEagerProviderClass`	Store an eager service provider instance in the eager registry.
Method	`__storeProviderClass`	Store a service provider instance in the appropriate registry.
Method	`__validateAndReturnPath`	Validate and return a resolved Path object.
Method	`__validateProviderClass`	Validate that the provider class meets IServiceProvider requirements.
Async Method	`boot`	Create the application and await eager providers for headless use.
Method	`compile`	Compile the application with the specified caching and invalidation settings.
Method	`config`	Get or set an application configuration value.
Method	`create`	Bootstrap and initialize the application framework.
Async Method	`getExceptionHandler`	Retrieve the registered exception handler instance.
Method	`getMiddleware`	Retrieve the list of registered middleware classes.
Async Method	`getScheduler`	Retrieve the currently registered scheduler instance.
Async Method	`handleCommand`	Handle a CLI command using the configured KernelCLI.
Method	`isDebug`	Determine if the application is running in debug mode.
Method	`isProduction`	Determine if the application is running in a production environment.
Method	`on`	Register callbacks for a specific application lifespan event.
Method	`path`	Retrieve an application path by key or return all paths.
Method	`resetRuntimeConfig`	Reset the runtime configuration to a mutable copy of the bootstrap config.
Method	`routingPaths`	Retrieve routing file paths from configuration.
Method	`underMaintenance`	Determine if the application is currently in maintenance mode.
Method	`withConfigApp`	Configure application settings using keyword arguments.
Method	`withConfigAuth`	Configure authentication subsystem using keyword arguments.
Method	`withConfigCache`	Configure the cache subsystem using keyword arguments.
Method	`withConfigDatabase`	Configure the database subsystem using keyword arguments.
Method	`withConfigFilesystems`	Configure the filesystems subsystem using keyword arguments.
Method	`withConfigHttp`	Configure the HTTP subsystem using keyword arguments.
Method	`withConfigLogging`	Configure logging subsystem using keyword arguments.
Method	`withConfigMail`	Configure mail subsystem using keyword arguments.
Method	`withConfigMcp`	Configure validated MCP limits and the explicit Origin allowlist.
Method	`withConfigPaths`	Set and resolve application directory paths.
Method	`withConfigQueue`	Configure the queue subsystem using keyword arguments.
Method	`withConfigSession`	Configure session subsystem using keyword arguments.
Method	`withConfigTesting`	Configure the testing subsystem using keyword arguments.
Method	`withExceptionHandler`	Register a custom exception handler class for the application.
Method	`withMiddleware`	Register middleware for the application.
Method	`withProviders`	Register service providers for the application.
Method	`withRouting`	Configure separate routing files for each application protocol.
Method	`withScheduler`	Register a custom scheduler class for the application.
Instance Variable	`__basePath`	Undocumented
Instance Variable	`__booted`	Undocumented
Instance Variable	`__bootstrap`	Undocumented
Instance Variable	`__cache_resolved_providers`	Undocumented
Instance Variable	`__compiled`	Undocumented
Instance Variable	`__compiled_invalidation_paths_dirs`	Undocumented
Instance Variable	`__compiled_invalidation_paths_files`	Undocumented
Instance Variable	`__compiled_path`	Undocumented
Instance Variable	`__compiled_state_store`	Undocumented
Instance Variable	`__configured`	Undocumented
Instance Variable	`__entry_point`	Undocumented
Instance Variable	`__exception_handler_resolved`	Undocumented
Instance Variable	`__hook_events`	Undocumented
Instance Variable	`__http_disconnect_monitoring`	Undocumented
Instance Variable	`__http_disconnect_paths`	Undocumented
Instance Variable	`__is_compiled`	Undocumented
Instance Variable	`__is_debug_cache`	Undocumented
Instance Variable	`__is_production_cache`	Undocumented
Instance Variable	`__kernel_cli`	Undocumented
Instance Variable	`__kernel_cli_lock`	Undocumented
Instance Variable	`__kernel_http_asgi`	Undocumented
Instance Variable	`__kernel_http_lock`	Undocumented
Instance Variable	`__kernel_http_rsgi`	Undocumented
Instance Variable	`__maintenance_cache`	Undocumented
Instance Variable	`__maintenance_lock`	Undocumented
Instance Variable	`__maintenance_marker`	Undocumented
Instance Variable	`__pending_boot_providers`	Undocumented
Instance Variable	`__provider_boot_lock`	Undocumented
Instance Variable	`__providers_registry_initialized`	Undocumented
Instance Variable	`__runtime_config`	Undocumented
Instance Variable	`__runtime_config_initialized`	Undocumented
Instance Variable	`__scheduler_resolved`	Undocumented
Instance Variable	`__start_at`	Undocumented
Instance Variable	`_Application__initialized`	Undocumented
Instance Variable	`_deferred_providers`	Undocumented
Property	`areProvidersBooted`	Check whether every registered eager provider has finished startup.
Property	`basePath`	Return the base path of the application.
Property	`compiled`	Indicate whether the application is running in compiled mode.
Property	`compiledInvalidationPathsDirs`	Return the list of directory paths monitored for cache invalidation.
Property	`compiledInvalidationPathsFiles`	Return the list of file paths monitored for cache invalidation.
Property	`compiledPath`	Return the path where compiled cache files are stored.
Property	`entryPoint`	Return the entry point module path where the application was created.
Property	`isBooted`	Check whether configuration and provider registration have completed.
Property	`isCreated`	Check whether configuration and service registration are complete.
Property	`isHttpReady`	Check whether both HTTP protocol handlers have been published.
Property	`routeHealthCheck`	Return the health check route for the application.
Property	`startAt`	Return the application startup timestamp in nanoseconds.

Inherited from Container:

Static Method	`__isBeingResolved`	Determine whether a concrete type is already resolving in this task.
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	`__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	`__resolveOrBuild`	Resolve a binding for an abstract service or build it when unbound.
Async Method	`__resolveSchemaArgument`	Resolve an argument that is a subclass of msgspec.Struct.
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 object instance as a singleton in the container.
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`	Undocumented
Class Variable	`_lock`	Undocumented
Instance Variable	`__aliases`	Undocumented
Instance Variable	`__bindings`	Undocumented
Instance Variable	`__cache_resolve_deferred_providers`	Undocumented
Instance Variable	`__creation_locks`	Undocumented
Instance Variable	`__pending_deferred`	Undocumented
Instance Variable	`__registered_deferred`	Undocumented
Instance Variable	`__singleton_cache`	Undocumented
Instance Variable	`_Container__initialized`	Undocumented

Inherited from IApplication (via Container):

Class Variable __slots__ Undocumented

@classmethod

def current(cls) -> Self | None: (source) ¶

Return the existing application without constructing or booting it.

Returns
`Self or None`	Application singleton for this class, if already instantiated. Its configuration may still be uninitialized before `create()`.

async def __asgiLifespan(self, receive: Callable[[], Awaitable[dict]], send: Callable[[dict], Awaitable[None]]): (source) ¶

Handle ASGI lifespan startup and shutdown events.

Parameters
receive:`Callable[[], Awaitable[dict]]`	ASGI receive callable for lifespan message retrieval.
send:`Callable[[dict], Awaitable[None]]`	ASGI send callable for lifespan response transmission.

Returns
`None`	Returns after shutdown completes or a fatal error occurs.

def __assertConfigMutable(self): (source) ¶

Assert that configuration is mutable before modification.

Returns
`None`	This method does not return a value. Raises if configuration is locked.

Raises
`RuntimeError`	If attempting to modify configuration after application boot.

def __assertPythonVersion(self): (source) ¶

Assert that the current Python version meets the minimum requirement.

Returns
`None`	This method does not return a value. It raises if the version is insufficient.

Raises
`RuntimeError`	If the current Python version is lower than the required version.

def __bootCompiledState(self, compiled_path: str | None = None, compiled_invalidation_paths: list[str] | None = None): (source) ¶

Initialize application compilation and configuration caching.

Notes

This method sets up the cache driver and loads cached configuration if available. It also tracks directories and files for cache invalidation.

Parameters
compiled_path:`str \| None, optional`	Path to the cache directory, or None.
compiled_invalidation_paths:`list[str] \| None, optional`	List of paths to monitor for cache invalidation, or None.

Returns
`None`	Configure the cache and load any valid stored bootstrap state.

async def __bootEagerProviders(self): (source) ¶

Boot all pending eager service providers.

Await providers in registration order and retain unfinished providers so a later startup can retry them.

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

async def __call__(self, scope: dict, receive: Callable[[], Awaitable[dict[str, Any]]], send: Callable[[dict[str, Any]], Awaitable[None]]) -> Any | None: (source) ¶

Dispatch ASGI requests to the appropriate handler by scope type.

Parameters
scope:`dict`	ASGI connection scope containing request metadata and type.
receive:`Callable[[], Awaitable[dict[str, Any]]]`	ASGI receive callable for message retrieval.
send:`Callable[[dict[str, Any]], Awaitable[None]]`	ASGI send callable for response transmission.

Returns
`Any \| None`	Result from the lifespan or HTTP handler, or `None` for unsupported scope types.

def __commitConfig(self): (source) ¶

Lock configuration and mark application as initialized.

Freeze the bootstrap configuration to prevent further modifications and set the configured flag to indicate the application is ready for use.

Returns
`None`	This method does not return a value. It modifies internal state to lock configuration.

def __defaultBootstrap(self) -> dict[str, Any]: (source) ¶

Return the default bootstrap configuration.

Returns
`dict[str, Any]`	Default bootstrap configuration dictionary with all core sections initialized for application startup.

def __discoverProviders(self, modules: set[str]): (source) ¶

Discover and register service providers from the providers folder.

Imports each discovered module, identifies classes that are subclasses of ServiceProvider, and registers them in the appropriate registry based on whether they are deferred or immediate providers.

Parameters
modules:`set[str]`	Dotted module names containing service provider classes.

Returns
`None`	Modifies the internal providers registry in-place.

def __ensureDefaultBootstrap(self): (source) ¶

Initialize the bootstrap configuration with default values.

Initialize the internal bootstrap configuration dictionary with the default bootstrap configuration if it is currently empty. This ensures the application has a valid configuration structure before any customization.

Returns
`None`	This method does not return a value. It modifies the internal bootstrap configuration state in place.

def __ensureDefaultPaths(self): (source) ¶

Ensure default application paths are set in the bootstrap configuration.

Initialize the 'paths' key in the bootstrap dictionary using default configuration paths if it is missing or empty.

Returns
`None`	This method does not return a value. It modifies the internal bootstrap state to ensure paths are set.

def __ensureProvidersRegistryStructure(self): (source) ¶

Ensure the providers registry structure is properly initialized.

Initialize the eager and deferred provider registries in the bootstrap configuration if they do not already exist. This method creates the necessary dictionary structure for storing service provider information and prevents duplicate initialization through a sentinel attribute.

Returns
`None`	This method does not return a value. It modifies internal state.

def __getRuntimeConfigValue(self, key_parts: tuple[str, ...]) -> object: (source) ¶

Retrieve a value from a nested dictionary using dot notation.

Parameters
key_parts:`tuple[str, ...]`	Keys representing the path in the nested dictionary.

Returns
`object`	The value found at the nested key path, or None if not found.

async def __handleHttpAsgi(self, scope: dict, receive: Callable[[], Awaitable[dict[str, Any]]], send: Callable[[dict[str, Any]], Awaitable[None]]) -> Any | None: (source) ¶

Handle an HTTP request using the configured disconnect policy.

Direct dispatch uses the server task and receive callable. When http.monitor_disconnects or a compiled endpoint policy enables monitoring, a receive dispatcher cancels the kernel on disconnect and buffers incoming body messages. At most nine body messages are retained outside the kernel: eight in the queue and one waiting to enter it. Disconnect detection pauses while the queue is full.

Parameters
scope:`dict`	ASGI connection scope containing request metadata.
receive:`Callable[[], Awaitable[dict[str, Any]]]`	ASGI receive callable provided by the server.
send:`Callable[[dict[str, Any]], Awaitable[None]]`	ASGI send callable for transmitting the response.

Returns
`Any \| None`	Result of the kernel handler, or `None` if the client disconnected before the response was sent.

async def __handleHttpRsgi(self, scope: Scope, protocol: HTTPProtocol) -> object: (source) ¶

Handle HTTP requests using the KernelHTTP in RSGI mode.

Direct dispatch executes in the server task. When http.monitor_disconnects or a compiled endpoint policy enables monitoring, a watcher requests cancellation when the client disconnects. The watcher is joined before returning.

Parameters
scope:`Scope`	The connection scope information for the RSGI protocol.
protocol:`HTTPProtocol`	The RSGI protocol instance; must expose a `client_disconnect` coroutine that resolves when the client closes the connection.

Returns
`object`	The result returned by the HTTP kernel's handleRSGI method, or `None` when execution is cancelled due to client disconnect.

Raises
`RuntimeError`	If KernelHTTP is not configured in the application.
`TypeError`	If the HTTP kernel does not have a handleRSGI method.

def __init__(self, base_path: Path = _CWD): (source) ¶

overrides orionis.container.container.Container.__init__

Initialize the Application instance.

Parameters
base_path:`Path`	The base directory path of the application.

Returns
`None`	This method initializes the Application instance in place.

async def __initializeCliKernel(self): (source) ¶

Build and boot the CLI kernel once for concurrent commands.

Returns
`None`	The command handler is published after the kernel boots.

async def __initializeHttpKernel(self, interface: str): (source) ¶

Build and boot the HTTP kernel once for concurrent first requests.

Parameters
interface:`str`	Server interface recorded before the kernel is built.

Returns
`None`	Both protocol handlers are published after a successful boot.

def __load(self): (source) ¶

Load and initialize application configuration and service providers.

Ensures the bootstrap configuration is initialized, sets up default paths, loads the final application configuration, loads service providers, saves the configuration to cache, and locks the configuration. Registers and boots all service providers.

Returns
`None`	This method modifies internal state and does not return a value.

async def __loadCLIKernel(self) -> IKernelCLI: (source) ¶

Load and return the configured CLI kernel instance.

Returns
`IKernelCLI`	An instance of the configured CLI kernel.

Raises
`RuntimeError`	If KernelCLI is not configured in the application.
`TypeError`	If the loaded kernel does not implement IKernelCLI.

def __loadConfig(self): (source) ¶

Load and merge the final configuration from dataclasses and custom config.

Discovers configuration modules and dataclasses, loads default configuration values, merges them with custom configuration, and updates the application's bootstrap dictionary with the final configuration and discovered providers.

Returns
`None`	This method updates the internal bootstrap configuration in place.

def __loadCoreProviders(self): (source) ¶

Load and register core framework service providers.

Import and register essential service providers required for framework operation. Ensures core services are available before user-defined providers.

Parameters
self:`Application`	The current Application instance.

Returns
`None`	This method modifies the internal providers registry in place.

def __loadCustomConfig(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 configuration and dataclass defaults into the base config.

Parameters
default_config:`dict[str, Any]`	The base configuration dictionary containing default values.
custom_config:`dict[str, Any]`	The custom configuration dictionary to merge into defaults.
dataclasses:`set[tuple[str, str, str, Type[Any]]] \| None, optional`	Set of tuples containing dataclass info to merge, or None.

Returns
`dict[str, Any]`	The merged configuration dictionary containing all sections.

async def __loadHTTPKernel(self) -> IKernelHTTP: (source) ¶

Load and return the configured HTTP kernel instance.

Returns
`IKernelHTTP`	An instance of the configured HTTP kernel.

Raises
`TypeError`	If the loaded kernel does not implement IKernelHTTP.

def __loadProviders(self): (source) ¶

Load and register all service providers.

Discovers provider modules, registers provider classes, and loads core framework providers. Ensures all service providers are available for dependency injection and application bootstrapping.

Parameters
self:`Application`	The current application instance.

Returns
`None`	This method updates the internal providers registry in place.

def __lockConfig(self): (source) ¶

Deeply freeze and lock the application configuration.

Freezes the internal bootstrap configuration in-place to prevent further modifications. The booted flag is set separately in create().

Returns
`None`	This method does not return a value. The configuration is locked in-place.

async def __onShutdown(self, runtime: Runtime): (source) ¶

Execute shutdown callbacks for the application lifecycle.

Parameters
runtime:`Runtime`	The runtime environment (HTTP or CLI) for which to execute shutdown callbacks.

Returns
`None`	This method executes shutdown callbacks and does not return a value.

async def __onStartup(self, runtime: Runtime, http_interface: str = 'asgi'): (source) ¶

Execute startup callbacks for the application lifecycle.

Parameters
runtime:`Runtime`	The runtime environment (HTTP or CLI) for which to execute startup callbacks.
http_interface:`str, optional`	HTTP transport recorded when the kernel is warmed during startup.

Returns
`None`	This method executes startup callbacks and does not return a value.

def __persistCompiledState(self): (source) ¶

Persist the compiled application state to cache.

Save the current bootstrap configuration to the cache if the application is running in compiled mode and the cache driver is initialized.

Returns
`None`	This method does not return a value. It persists the configuration state to cache if applicable.

def __resolveAndValidateRoutingFiles(self, paths: str | list[str] | None, required_imports: set[str]) -> list[Path]: (source) ¶

Resolve and validate routing file paths.

Parameters
paths:`str \| list[str] \| None`	Routing file path(s) to validate and resolve.
required_imports:`set[str]`	Set of required module imports for validation.

Returns
`list[Path]`	List of resolved Path objects for valid routing files.

Raises
`TypeError`	If `paths` is not a str, list[str], or None, or if a file does not contain valid routing definitions.
`FileNotFoundError`	If a specified routing file does not exist.

def __resolveEagerProvider(self): (source) ¶

Resolve and register all eager service providers.

Resolves all eager service providers defined in the application's bootstrap configuration. Registers each provider and schedules its boot method if asynchronous.

Returns
`None`	This method does not return a value. It registers and schedules eager providers for booting.

async def __rsgi__(self, scope: Scope, protocol: HTTPProtocol | WebsocketProtocol | ProtocolError | ProtocolClosed) -> object: (source) ¶

Handle the RSGI protocol for incoming requests.

Parameters
scope:`Scope`	The connection scope information.
protocol:`HTTPProtocol \| WebsocketProtocol \| ProtocolError \| ProtocolClosed`	The RSGI protocol instance representing the connection.

Returns
`object`	The result of handling the RSGI request.

def __rsgi_del__(self, loop: asyncio.AbstractEventLoop): (source) ¶

Execute the RSGI application shutdown lifecycle.

Parameters
loop:`asyncio.AbstractEventLoop`	The event loop for asynchronous execution.

Returns
`None`	This method executes shutdown callbacks and does not return a value.

def __rsgi_init__(self, loop: asyncio.AbstractEventLoop): (source) ¶

Initialize the RSGI application lifecycle and execute startup callbacks.

Parameters
loop:`asyncio.AbstractEventLoop`	The event loop for asynchronous execution.

Returns
`None`	This method executes startup callbacks and does not return a value.

def __setRuntimeConfigValue(self, key_parts: tuple[str, ...], value: object) -> object: (source) ¶

Set a value in a nested dictionary using dot notation.

Parameters
key_parts:`tuple[str, ...]`	Keys representing the path in the nested dictionary.
value:`object`	The value to set at the specified nested key path.

Returns
`object`	The value that was set.

def __setTimezoneAndLocale(self): (source) ¶

Set system timezone and locale from application configuration.

Uses the application's configuration to set the system timezone and locale. This method updates environment variables and system locale settings if the relevant configuration values are present.

Returns
`None`	This method updates environment variables and system locale settings in place. It does not return a value.

def __storeDeferredProviderClass(self, provider: type[IDeferrableProvider]): (source) ¶

Store a deferred service provider instance in the deferred registry.

Parameters
provider:`type[IDeferrableProvider]`	The service provider class to register.

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

Raises
`TypeError`	If the provider is not a class or not a subclass of IServiceProvider.

def __storeEagerProviderClass(self, provider: type[IServiceProvider]): (source) ¶

Store an eager service provider instance in the eager registry.

Parameters
provider:`type[IServiceProvider]`	The service provider class to register.

Returns
`None`	This method does not return a value. It modifies the internal eager providers registry in-place.

Raises
`TypeError`	If the provider is not a class or not a subclass of IServiceProvider.

def __storeProviderClass(self, provider: type[IServiceProvider]): (source) ¶

Store a service provider instance in the appropriate registry.

Register the provider class in either the eager or deferred registry based on its inheritance hierarchy. Validates provider type and ensures proper registry structure before storage.

Parameters
provider:`type[IServiceProvider]`	The service provider class to register.

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

Raises
`TypeError`	If the provider is not a class or not a subclass of IServiceProvider.

def __validateAndReturnPath(self, path: Path | str) -> Path: (source) ¶

Validate and return a resolved Path object.

Parameters
path:`Path or str`	The path to validate and resolve.

Returns
`Path`	The validated and resolved Path object.

Raises
`TypeError`	If `path` is not a Path or str.

def __validateProviderClass(self, provider_class: type[IServiceProvider]): (source) ¶

Validate that the provider class meets IServiceProvider requirements.

Parameters
provider_class:`type[IServiceProvider]`	The service provider class to validate.

Returns
`None`	This method does not return a value. Raises exceptions if validation fails.

Raises
`TypeError`	If the provider is not a class or not a subclass of IServiceProvider.

async def boot(self) -> Self: (source) ¶

overrides orionis.IApplication.boot

Create the application and await eager providers for headless use.

Repeated and concurrent calls share provider startup coordination. HTTP and Reactor continue to own their kernels and lifecycle callbacks.

Returns
`Self`	The application with all eager provider boot methods completed.

Raises
`Exception`	Propagate configuration or provider startup failures. An unfinished provider remains pending so another call can retry its startup.

def compile(self, path: str | None = None, invalidation_paths: list[str] | None = None): (source) ¶

overrides orionis.IApplication.compile

Compile the application with the specified caching and invalidation settings.

Parameters
path:`str \| None, optional`	The path where compiled files should be stored. Defaults to None.
invalidation_paths:`list[str] \| None, optional`	List of paths that trigger cache invalidation when modified. Defaults to None.

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

def config(self, key: str | None = None, value: object = _SENTINEL) -> object: (source) ¶

overrides orionis.IApplication.config

Get or set an application configuration value.

Parameters
key:`str or None, optional`	Dot-notated key specifying the configuration value to get or set. If None and value is not provided, returns the entire configuration.
value:`object, optional`	Value to set at the specified key. If not provided, retrieves the value.

Returns
`object`	The configuration value for the given key, or the entire configuration if no key is provided. If setting a value, returns the value set.

Raises
`RuntimeError`	If the application configuration is not initialized.
`TypeError`	If the configuration key is not a string.

def create(self) -> Self: (source) ¶

overrides orionis.IApplication.create

Bootstrap and initialize the application framework.

Returns
`Self`	The current Application instance for method chaining.

async def getExceptionHandler(self) -> IBaseExceptionHandler: (source) ¶

overrides orionis.IApplication.getExceptionHandler

Retrieve the registered exception handler instance.

Parameters
self:`Application`	The current application instance.

Returns
`IBaseExceptionHandler`	The registered exception handler instance. If none is set, returns the default BaseExceptionHandler instance.

Raises
`RuntimeError`	If called before the application is booted.

def getMiddleware(self) -> list[type[IBaseMiddleware]]: (source) ¶

overrides orionis.IApplication.getMiddleware

Retrieve the list of registered middleware classes.

Returns
`list[type[IBaseMiddleware]]`	A list of middleware classes registered in the application.

async def getScheduler(self) -> IBaseScheduler: (source) ¶

overrides orionis.IApplication.getScheduler

Retrieve the currently registered scheduler instance.

Returns
`IBaseScheduler`	The registered scheduler instance.

Raises
`RuntimeError`	If the application is not booted.

async def handleCommand(self, args: list[str] | None = None) -> int: (source) ¶

overrides orionis.IApplication.handleCommand

Handle a CLI command using the configured KernelCLI.

Parameters
args:`list[str] \| None, optional`	Arguments to pass to the kernel's handle method. Defaults to an empty list if not provided.

Returns
`int`	The exit code returned by the CLI kernel's handle method.

Raises
`RuntimeError`	If KernelCLI is not configured in the application.
`TypeError`	If the CLI kernel does not have a handle method.

def isDebug(self) -> bool: (source) ¶

overrides orionis.IApplication.isDebug

Determine if the application is running in debug mode.

Returns
`bool`	True if debug mode is enabled in the configuration, otherwise False.

Raises
`RuntimeError`	If the application configuration is not initialized.

def isProduction(self) -> bool: (source) ¶

overrides orionis.IApplication.isProduction

Determine if the application is running in a production environment.

Checks the 'app.env' configuration value to see if it contains 'prod'. This is useful for toggling production-specific features.

Returns
`bool`	True if the application environment contains 'prod', otherwise False.

Raises
`RuntimeError`	If the application configuration is not initialized.

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

overrides orionis.IApplication.on

Notes

Callbacks are stored as-is and executed during the specified lifespan event. Lambdas and dynamic callables are supported.

Parameters
lifespan:`Lifespan`	The application lifespan event to register callbacks for.
*callbacks:`Callable[..., Any] \| Callable[..., Awaitable[Any]]`	One or more callback functions to execute during the event.
runtime:`Runtime \| None, optional`	The runtime environment for which to register the callbacks. If None, callbacks are registered for all runtimes.

Returns
`Self`	The current Application instance for method chaining.

Raises
`TypeError`	If `lifespan` is not a Lifespan enum or any callback is not callable.
`ValueError`	If no callbacks are provided.

def path(self, key: str | None = None) -> Path | Mapping[str, Path] | None: (source) ¶

overrides orionis.IApplication.path

Retrieve an application path by key or return all paths.

Parameters
key:`str \| None, optional`	The key for the desired path. If None, returns all paths.

Returns
`Path \| Mapping[str, Path] \| None`	The resolved path for the given key, all paths as a read-only mapping, or None if the key does not exist.

Raises
`RuntimeError`	If the application configuration is not initialized.
`TypeError`	If the key is not a string.

def resetRuntimeConfig(self) -> bool: (source) ¶

overrides orionis.IApplication.resetRuntimeConfig

Reset the runtime configuration to a mutable copy of the bootstrap config.

Resets the application's runtime configuration to a mutable and isolated copy of the bootstrap configuration. The application remains booted and subsequent accesses use the restored runtime values.

Returns
`bool`	True if the configuration was reset successfully.

def routingPaths(self, key: str | None = None) -> list[Path] | dict | None: (source) ¶

overrides orionis.IApplication.routingPaths

Retrieve routing file paths from configuration.

The 'api', 'web', 'console', 'ai', and 'websocket' types are supported. The health-check route is exposed through the routeHealthCheck property and is not accessible via this method.

Parameters
key:`str \| None, optional`	Routing type: 'api', 'web', 'console', 'ai', or 'websocket'. If None, returns the complete routing configuration dictionary.

Returns
`list[Path] \| dict \| None`	List of Path objects for the specified routing type, the complete routing configuration dictionary if no key is provided, or None if the key is not one of the valid routing types.

Raises
`RuntimeError`	If the application configuration is not initialized.
`TypeError`	If the key is not a string or None.

def underMaintenance(self) -> bool: (source) ¶

overrides orionis.IApplication.underMaintenance

Determine if the application is currently in maintenance mode.

The shared marker is refreshed at most once every 100 ms per worker. Runtime changes from other processes become visible after that interval.

Returns
`bool`	True when the effective maintenance state is enabled. The runtime marker overrides the configured value when present.

Raises
`RuntimeError`	If the application configuration is not initialized.

def withConfigApp(self, **app_config: object) -> Self: (source) ¶

overrides orionis.IApplication.withConfigApp

Configure application settings using keyword arguments.

Parameters
**app_config:`object`	Configuration parameters for the application. Keys must match the field names and types expected by the App dataclass from orionis.foundation.config.app.entities.app.App.

Returns
`Self`	The current Application instance for method chaining.

def withConfigAuth(self, **auth_config: object) -> Self: (source) ¶

overrides orionis.IApplication.withConfigAuth

Configure authentication subsystem using keyword arguments.

Parameters
**auth_config:`object`	Keyword arguments for authentication configuration. Keys must match the fields of the `Auth` dataclass from `orionis.foundation.config.auth.entities.auth.Auth`.

Returns
`Self`	The current Application instance for method chaining.

def withConfigCache(self, **cache_config: object) -> Self: (source) ¶

overrides orionis.IApplication.withConfigCache

Configure the cache subsystem using keyword arguments.

Parameters
**cache_config:`object`	Keyword arguments representing cache configuration options. Keys must match the field names and types expected by the `Cache` dataclass from `orionis.foundation.config.cache.entities.cache.Cache`.

Returns
`Self`	The current Application instance to enable method chaining.

def withConfigDatabase(self, **database_config: object) -> Self: (source) ¶

overrides orionis.IApplication.withConfigDatabase

Configure the database subsystem using keyword arguments.

Parameters
**database_config:`object`	Keyword arguments for database configuration. Keys must match the fields of the `Database` dataclass from `orionis.foundation.config.database.entities.database.Database`.

Returns
`Self`	The current Application instance for method chaining.

def withConfigFilesystems(self, **filesystems_config: object) -> Self: (source) ¶

overrides orionis.IApplication.withConfigFilesystems

Configure the filesystems subsystem using keyword arguments.

Parameters
**filesystems_config:`object`	Keyword arguments for filesystems configuration. Keys must match the fields of the `Filesystems` dataclass from `orionis.foundation.config.filesystems.entitites.filesystems.Filesystems`.

Returns
`Self`	The current Application instance for method chaining.

def withConfigHttp(self, **http_config: object) -> Self: (source) ¶

overrides orionis.IApplication.withConfigHttp

Configure the HTTP subsystem using keyword arguments.

Parameters
**http_config:`object`	Keyword arguments for HTTP configuration. Keys must match the field names and types expected by the `HTTP` dataclass from `orionis.foundation.config.http.entitites.http.HTTP`.

Returns
`Self`	The current Application instance for method chaining.

def withConfigLogging(self, **logging_config: object) -> Self: (source) ¶

overrides orionis.IApplication.withConfigLogging

Configure logging subsystem using keyword arguments.

Parameters
**logging_config:`object`	Keyword arguments for logging configuration. Keys must match the fields of the `Logging` dataclass from `orionis.foundation.config.logging.entities.logging.Logging`.

Returns
`Self`	The current Application instance for method chaining.

def withConfigMail(self, **mail_config: object) -> Self: (source) ¶

overrides orionis.IApplication.withConfigMail

Configure mail subsystem using keyword arguments.

Parameters
**mail_config:`object`	Keyword arguments for mail configuration. Keys must match the fields of the `Mail` dataclass from `orionis.foundation.config.mail.entities.mail.Mail`.

Returns
`Self`	The current Application instance for method chaining.

def withConfigMcp(self, **mcp_config: object) -> Self: (source) ¶

overrides orionis.IApplication.withConfigMcp

Configure validated MCP limits and the explicit Origin allowlist.

Parameters
**mcp_config:`object`	Fields accepted by the native McpConfig entity.

Returns
`Self`	The application for further configuration.

def withConfigPaths(self, **paths: str | Path | None) -> Self: (source) ¶

overrides orionis.IApplication.withConfigPaths

Set and resolve application directory paths.

Parameters
**paths:`str \| Path \| None`	Optional directory path overrides. Valid keys are 'app', 'console', 'exceptions', 'http', 'models', 'providers', 'notifications', 'services', 'jobs', 'bootstrap', 'config', 'database', 'resources', 'routes', 'storage' and 'tests'. The root always comes from basePath.

Returns
`Self`	The current Application instance for method chaining.

def withConfigQueue(self, **queue_config: object) -> Self: (source) ¶

overrides orionis.IApplication.withConfigQueue

Configure the queue subsystem using keyword arguments.

Parameters
**queue_config:`object`	Keyword arguments representing queue configuration options. Keys must match the field names and types expected by the `Queue` dataclass from `orionis.foundation.config.queue.entities.queue.Queue`.

Returns
`Self`	The current Application instance for method chaining.

def withConfigSession(self, **session_config: object) -> Self: (source) ¶

overrides orionis.IApplication.withConfigSession

Configure session subsystem using keyword arguments.

Parameters
**session_config:`object`	Keyword arguments for session configuration. Keys must match the fields of the `Session` dataclass from `orionis.foundation.config.session.entities.session.Session`.

Returns
`Self`	The current Application instance for method chaining.

def withConfigTesting(self, **testing_config: object) -> Self: (source) ¶

overrides orionis.IApplication.withConfigTesting

Configure the testing subsystem using keyword arguments.

Parameters
**testing_config:`object`	Keyword arguments for testing configuration. Keys must match the fields of the `Testing` dataclass from `orionis.foundation.config.testing.entities.testing.Testing`.

Returns
`Self`	The current Application instance for method chaining.

def withExceptionHandler(self, handler: type[IBaseExceptionHandler]) -> Self: (source) ¶

overrides orionis.IApplication.withExceptionHandler

Notes

Stores the handler class for later instantiation. Any previously registered handler is silently replaced.

Parameters
handler:`type[IBaseExceptionHandler]`	Exception handler class to use. Must inherit from BaseExceptionHandler.

Returns
`Self`	The current Application instance for method chaining.

Raises
`TypeError`	If the handler is not a class or not a subclass of BaseExceptionHandler.
`RuntimeError`	If attempting to set handler after application has been booted.

def withMiddleware(self, *middleware: type[IBaseMiddleware]) -> Self: (source) ¶

overrides orionis.IApplication.withMiddleware

Parameters
*middleware:`tuple[type[IBaseMiddleware], ...]`	Middleware classes to register. Each must inherit from IBaseMiddleware.

Returns
`Self`	The current Application instance for method chaining.

def withProviders(self, *providers: type[IServiceProvider]) -> Self: (source) ¶

overrides orionis.IApplication.withProviders

Parameters
*providers:`tuple[type[IServiceProvider], ...]`	Service provider classes to register. Each must inherit from IServiceProvider.

Returns
`Self`	The current Application instance for method chaining.

Raises
`TypeError`	If any argument is not a class or does not inherit from IServiceProvider.

overrides orionis.IApplication.withRouting

Configure separate routing files for each application protocol.

Parameters
api:`str \| list[str] \| None`	Path or list of paths to API routing files.
web:`str \| list[str] \| None`	Path or list of paths to web routing files.
console:`str \| list[str] \| None`	Path or list of paths to console routing files.
health:`str \| None`	Path to the health check route.
ai:`str \| list[str] \| None`	MCP registration files loaded before HTTP or CLI startup.
websocket:`str \| list[str] \| None`	WebSocket and Hub route files using the web middleware profile.

Returns
`Self`	The current Application instance for method chaining.

Raises
`TypeError`	If routing arguments are of invalid types or do not contain valid routing definitions.
`FileNotFoundError`	If a specified routing file does not exist.

def withScheduler(self, scheduler: type[IBaseScheduler]) -> Self: (source) ¶

overrides orionis.IApplication.withScheduler

Notes

Stores the scheduler class metadata for later instantiation. Any previously registered scheduler is silently replaced.

Parameters
scheduler:`type[IBaseScheduler]`	The scheduler class to be used. Must inherit from IBaseScheduler.

Returns
`Self`	The current Application instance for method chaining.

Raises
`RuntimeError`	If attempting to set scheduler after application has been booted.
`TypeError`	If the provided scheduler is not a subclass of IBaseScheduler.