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 Container(IContainer): (source)
Known subclasses: orionis.Application
Constructor: Container(*args, **kwargs)
Resolve services from contracts, aliases and constructor signatures.
Concurrency
Allocation and initialization of container registries use _lock so concurrent construction of the same subclass shares initialized state. Subclasses remain responsible for safely initializing their additional state.
Inside one event loop, the one-shot work behind Lifetime.SINGLETON, Lifetime.SCOPED and deferred providers is serialised per key, so concurrent tasks share a single construction instead of duplicating it.
No other guarantee is provided: registration methods mutate plain dictionaries without locks, and containers shared between distinct event loops fall back to per-loop serialisation only.
| 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 | __init__ |
Initialize the internal state of the container. |
| 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. |
| Instance Variable | _deferred |
Deferred providers for lazy loading. |
Validate and normalize a service alias string.
| Parameters | |
alias:str | None | The alias string to validate and normalize. |
| Returns | |
str | None | The validated and normalized alias string, or None if not provided. |
| Raises | |
TypeError | If the alias is not a string. |
ValueError | If the alias is empty after stripping. |
Self, type_: Callable[ ..., Any], *args: object, **kwargs: object) -> Any:
(source)
¶
Resolve and invoke a callable, injecting dependencies.
| Parameters | |
type_:collections.abc.Callable[..., typing.Any] | The callable to invoke. |
*args:object | Positional arguments for the callable. |
**kwargs:object | Keyword arguments for the callable. |
| Returns | |
typing.Any | The result of the callable invocation. |
| Raises | |
orionis.container.exceptions.CircularDependencyException | If a circular dependency is detected. |
Exception | If the callable cannot be auto-resolved. |
Self, type_: type[ Any], *args: object, **kwargs: object) -> Any:
(source)
¶
Automatically instantiate a class with injected dependencies.
| Parameters | |
type_:type[typing.Any] | The class to instantiate. |
*args:object | Positional arguments for the constructor. |
**kwargs:object | Keyword arguments for the constructor. |
| Returns | |
typing.Any | The instantiated object with dependencies resolved. |
| Raises | |
orionis.container.exceptions.CircularDependencyException | If a circular dependency is detected. |
Exception | If the type cannot be auto-resolved. |
Wait for a provider that has registered services but is still booting.
| Parameters | |
key:type[typing.Any] | str | Service type or alias requested by a resolver. |
| Returns | |
None | No return value. |
Self, lifetime: Lifetime, abstract: type[ Any] | None, concrete: type[ Any], *, alias: str | None, override: bool) -> bool:
(source)
¶
Bind a concrete implementation to an abstract contract with a given lifetime.
| Parameters | |
lifetime:orionis.container.enums.Lifetime | The lifetime of the binding (singleton, scoped, or transient). |
abstract:type[typing.Any] | None | The abstract contract class to associate with the concrete class, or None to use the concrete class as the contract. |
concrete:type[typing.Any] | The concrete class to register. |
alias:str | None | An optional alias for the registration. |
override:bool | If True, override any existing registration. |
| Returns | |
bool | True if the binding was registered successfully. |
| Raises | |
TypeError | If the concrete is not a class type or type validation fails. |
ValueError | If the alias is invalid or already registered, or if the contract is already registered and override is False. |
Self, binding: Binding, scope: ScopeManager, *args: object, **kwargs: object) -> Any:
(source)
¶
Build and store the instance backing a scoped binding.
| Parameters | |
binding:orionis.container.entities.Binding | The scoped binding to materialize. |
scope:orionis.container.context.manager.ScopeManager | The active scope that owns the resulting instance. |
*args:object | Positional arguments for the constructor. |
**kwargs:object | Keyword arguments for the constructor. |
| Returns | |
typing.Any | The scoped instance, built by this call or by the task that won the creation lock. |
Self, binding: Binding, *args: object, **kwargs: object) -> Any:
(source)
¶
Build and cache the single instance backing a singleton binding.
| Parameters | |
binding:orionis.container.entities.Binding | The singleton binding to materialize. |
*args:object | Positional arguments for the constructor. |
**kwargs:object | Keyword arguments for the constructor. |
| Returns | |
typing.Any | The cached instance, built by this call or by the task that won the creation lock. |
Return the creation lock for a key, bound to the running loop.
| Parameters | |
key:object | Contract or deferred provider key whose construction is guarded. |
| Returns | |
asyncio.Lock | Lock owned by the running loop for this key. A new lock replaces any entry created on a different loop. |
Self, abstract: type[ Any], alias: str | None, *, override: bool):
(source)
¶
Ensure that a service or alias can be overridden globally.
| Parameters | |
abstract:type[typing.Any] | The abstract contract type to check. |
alias:str | None | The alias to check for conflicts. |
override:bool | Whether to allow overriding existing registrations. |
| Returns | |
None | No return value. |
| Raises | |
ValueError | If the service or alias already exists globally and override is False. |
Self, abstract: type[ Any], scope: ScopeManager, *, override: bool):
(source)
¶
Ensure that a service can be overridden in the current scope.
| Parameters | |
abstract:type[typing.Any] | The abstract contract type to check. |
scope:orionis.container.context.manager.ScopeManager | The current scoped service registry. |
override:bool | Whether to allow overriding existing registrations. |
| Returns | |
None | No return value. |
| Raises | |
ValueError | If the service already exists in the current scope and override is False. |
Ensure that a concrete class implements the specified abstract class.
| Parameters | |
abstract:type[typing.Any] | The abstract class type to check against. |
concrete:type[typing.Any] | The concrete class type to validate. |
| Returns | |
None | No return value. |
| Raises | |
TypeError | If abstract or concrete is not a class type, or if concrete does not implement abstract. |
Ensure that an instance implements the specified abstract class.
| Parameters | |
abstract:type[typing.Any] | The abstract class type to check against. |
instance:object | The object instance to validate. |
| Returns | |
None | No return value. |
| Raises | |
TypeError | If abstract is not a class type or instance does not implement it. |
orionis.ApplicationInitialize the internal state of the container.
Sets up internal data structures for dependency injection and ensures single initialization per instance.
| Returns | |
None | No return value. |
Determine whether a concrete type is already resolving in this task.
| Parameters | |
concrete:type[typing.Any] | Concrete class about to be constructed. |
| Returns | |
bool | True when the type is already on the current resolution stack, which means the caller must skip the creation lock it already owns. |
Create and return a singleton instance for each class in the hierarchy.
Ensures thread-safe singleton instantiation for each subclass of Container. Acquire the allocation lock only when the subclass has no registered instance.
| Parameters | |
cls:type | Class or metaclass to allocate. |
*args:object | Value supplied for *args. |
**kwargs:object | Value supplied for **kwargs. |
| Returns | |
typing.Self | The singleton instance of the calling class. |
Self, binding: Binding, *args: object, **kwargs: object) -> Any:
(source)
¶
Resolve an instance from a binding according to its lifetime.
| Parameters | |
binding:orionis.container.entities.Binding | The binding to resolve. |
*args:object | Positional arguments for the constructor. |
**kwargs:object | Keyword arguments for the constructor. |
| Returns | |
typing.Any | The resolved instance according to the binding's lifetime. |
| Raises | |
RuntimeError | If there is no active scope for scoped services. |
Resolve a single argument for dependency injection.
| Parameters | |
argument:orionis.introspection.dependencies.entities.argument.Argument | The argument metadata to resolve. |
| Returns | |
typing.Any | The resolved value for the argument. |
| Raises | |
TypeError | If the argument cannot be resolved or is a built-in type. |
Resolve and register a deferred service provider for a given service.
Notes
Loads and registers a deferred provider for the specified service. Returns early if the provider is already resolved or is a built-in.
| Parameters | |
key:type[typing.Any] | str | The service type or fully qualified class name for which to find the deferred provider. |
| Returns | |
None | No return value. |
Resolve a service key to its abstract type.
| Parameters | |
key:type[typing.Any] | str | Service identifier as an abstract type or alias string. |
| Returns | |
type[typing.Any] | The resolved abstract service type. |
| Raises | |
ValueError | If a string alias is not registered after deferred resolution. |
Resolve a parameter whose value was omitted from a keyword call.
| Parameters | |
argument:orionis.introspection.dependencies.entities.argument.Argument | Parameter metadata requiring a service, schema, or default value. |
| Returns | |
typing.Any | Value selected from the current provider registrations and scope. |
Self, abstract: type[ Any], key: type[ Any] | str, *args: object, **kwargs: object) -> Any:
(source)
¶
Resolve a binding for an abstract service or build it when unbound.
| Parameters | |
abstract:type[typing.Any] | Abstract service type to resolve. |
key:type[typing.Any] | str | Original service key used for resolution and error messages. |
*args:object | Positional arguments passed to the resolver or builder. |
**kwargs:object | Keyword arguments passed to the resolver or builder. |
| Returns | |
typing.Any | Resolved service instance. |
| Raises | |
ValueError | If no binding exists and the service cannot be resolved. |
Self, arguments: tuple[ Argument, ...], args: tuple[ object, ...]) -> list[ Any] | tuple[ object, ...]:
(source)
¶
Resolve a positional call using the current bindings and scope.
| Parameters | |
arguments:tuple[Argument, ...] | Parameters from a plan with no keyword-only arguments. |
args:tuple[object, ...] | Explicit positional values, including any variadic tail. |
| Returns | |
list[typing.Any] | tuple[object, ...] | Explicit values followed by dependencies resolved at call time. |
Validate a schema argument using the active HTTP request payload.
| Parameters | |
argument:orionis.introspection.dependencies.entities.argument.Argument | Parameter metadata declaring the schema to construct. |
| Returns | |
msgspec.Struct | Schema instance populated from the request body. |
| Raises | |
Exception | If request resolution, body parsing or schema validation fails. |
Self, arguments: tuple[ Argument, ...], args: tuple[ object, ...], kwargs: dict[ str, object], *, positional_only: frozenset[ str]) -> tuple[ list[ Any], dict[ str, Any]]:
(source)
¶
Resolve arguments for a callable signature using dependency injection.
| Parameters | |
arguments:tuple[Argument, ...] | Parameter metadata in declaration order. |
args:tuple[object, ...] | Positional arguments to pass to the callable. |
kwargs:dict[str, object] | Invocation-owned keyword mapping, consumed during resolution. |
positionalfrozenset[str] | Parameter names whose values cannot be supplied by keyword. |
| Returns | |
tuple[list[typing.Any], dict[str, typing.Any]] | A tuple containing the resolved positional and keyword arguments. |
Begin a new scope context manager for scoped services.
| Parameters | |
self:orionis.container.container.Container | The container instance. |
| Returns | |
orionis.container.context.manager.ScopeManager | Context manager for managing the lifecycle of scoped services. |
Determine if a key is bound in the container or current scope.
| Parameters | |
key:type[typing.Any] | str | The abstract type or alias to check for binding. |
| Returns | |
bool | True if the key is bound in the current scope or container, otherwise False. |
Build and return an instance of the specified type.
Notes
Resolves deferred providers before attempting instantiation.
| Parameters | |
type_:type[typing.Any] | The class to instantiate. |
*args:object | Positional arguments for the constructor. |
**kwargs:object | Keyword arguments for the constructor. |
| Returns | |
typing.Any | Instantiated object of the specified type. |
| Raises | |
TypeError | If the type cannot be auto-resolved by the container. |
Self, instance: object, method_name: str, *args: object, **kwargs: object) -> Any:
(source)
¶
Invoke a method on an object instance with automatic dependency injection.
| Parameters | |
instance:object | The object instance containing the method. |
methodstr | The name of the method to invoke. |
*args:object | Positional arguments for the method. |
**kwargs:object | Keyword arguments for the method. |
| Returns | |
typing.Any | The result of the method invocation with dependencies resolved. |
| Raises | |
AttributeError | If the method is not found on the instance. |
TypeError | If the attribute is not callable. |
Get the current active scope context for scoped services.
Notes
Returns None if there is no active scope. Use beginScope() to create a new scope context before accessing scoped services.
| Parameters | |
self:orionis.container.container.Container | The container instance. |
| Returns | |
orionis.container.context.manager.ScopeManager | None | The current active scope context if available, otherwise None. The scope context is a dictionary-like object that contains instances of scoped services registered in the current scope. |
Self, abstract: type[ Any] | None, instance: object, *, alias: str | None = None, override: bool = False) -> bool:
(source)
¶
Register an existing object globally or in the active scope.
| Parameters | |
abstract:type[typing.Any] | None | The abstract contract class to associate with the instance, or None. |
instance:object | The initialized object to register. |
alias:str | None, optional | An optional alias for the registration. |
override:bool, optional | If True, override any existing registration. |
| Returns | |
bool | True if the instance was registered successfully. |
| Raises | |
TypeError | If the instance is a class, or if type validation fails. |
ValueError | If the alias is invalid or already registered, or if the contract is already registered and override is False. |
Self, fn: Callable[ ..., Any], *args: object, **kwargs: object) -> Any:
(source)
¶
Invoke a callable with automatic dependency injection.
| Parameters | |
fn:collections.abc.Callable[..., typing.Any] | The callable to invoke. Must not be a class or type. |
*args:object | Positional arguments for the callable. |
**kwargs:object | Keyword arguments for the callable. |
| Returns | |
typing.Any | The result of the callable execution with dependencies injected. |
| Raises | |
TypeError | If fn is not a callable or is a class/type. |
Self, key: type[ Any] | str, *args: object, **kwargs: object) -> Any:
(source)
¶
Resolve and return a service instance by key.
An explicitly registered scoped instance takes precedence over a cached global singleton. The global instance remains available after scope exit.
| Parameters | |
key:type[typing.Any] | str | The abstract type or alias to resolve. |
*args:object | Positional arguments for instantiation. |
**kwargs:object | Keyword arguments for instantiation. |
| Returns | |
typing.Any | The resolved service instance. |
| Raises | |
ValueError | If the service is not registered and cannot be auto-resolved. |
Self, abstract: type[ Any] | None, concrete: type[ Any], *, alias: str | None = None, override: bool = False) -> bool:
(source)
¶
Register a scoped service binding.
| Parameters | |
abstract:type[typing.Any] | None | The abstract contract type to bind, or None to use the concrete type. |
concrete:type[typing.Any] | The concrete implementation type to register. |
alias:str | None, optional | An optional alias for the service. |
override:bool, optional | Whether to override an existing registration. |
| Returns | |
bool | True if the binding was registered successfully. |
Self, abstract: type[ Any] | None, concrete: type[ Any], *, alias: str | None = None, override: bool = False) -> bool:
(source)
¶
Register a singleton service binding.
| Parameters | |
abstract:type[typing.Any] | None | The abstract contract type to bind, or None to use the concrete type. |
concrete:type[typing.Any] | The concrete implementation type to register. |
alias:str | None, optional | An optional alias for the service. |
override:bool, optional | Whether to override an existing registration. |
| Returns | |
bool | True if the binding was registered successfully. |
Self, abstract: type[ Any] | None, concrete: type[ Any], *, alias: str | None = None, override: bool = False) -> bool:
(source)
¶
Register a transient service binding.
| Parameters | |
abstract:type[typing.Any] | None | The abstract contract type to bind, or None to use the concrete type. |
concrete:type[typing.Any] | The concrete implementation type to register. |
alias:str | None, optional | An optional alias for the service. |
override:bool, optional | Whether to override an existing registration. |
| Returns | |
bool | True if the binding was registered successfully. |
Dictionary to hold singleton instances for each class This allows proper inheritance of the singleton pattern.
Lock for thread-safe singleton instantiation and access This lock ensures that only one thread can create or access instances at a time.
Per-key locks serialising one-shot construction, paired with the loop they were created on so a second loop never awaits a foreign lock.