ORIONIS API REFERENCE

THE ORIONIS API

Build with clarity.

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

class documentation

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 __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 __init__ Initialize the internal state of the container.
Method __isBeingResolved Determine whether a concrete type is already resolving in this task.
Method __new__ Create and return a singleton instance for each class in the hierarchy.
Async Method __resolve Resolve an instance from a binding according to its lifetime.
Async Method __resolveArgument Resolve a single argument for dependency injection.
Async Method __resolveDeferredProvider Resolve and register a deferred service provider for a given service.
Async Method __resolveKey Resolve a service key to its abstract type.
Async Method __resolveMissingParameter Resolve a parameter whose value was omitted from a keyword call.
Async Method __resolveOrBuild Resolve a binding for an abstract service or build it when unbound.
Async Method __resolvePositionalArguments Resolve a positional call using the current bindings and scope.
Async Method __resolveSchemaArgument Validate a schema argument using the active HTTP request payload.
Async Method __resolveSignature Resolve arguments for a callable signature using dependency injection.
Method beginScope Begin a new scope context manager for scoped services.
Method bound Determine if a key is bound in the container or current scope.
Async Method build Build and return an instance of the specified type.
Async Method call Invoke a method on an object instance with automatic dependency injection.
Method getCurrentScope Get the current active scope context for scoped services.
Method instance Register an existing object globally or in the active scope.
Async Method invoke Invoke a callable with automatic dependency injection.
Async Method make Resolve and return a service instance by key.
Method scoped Register a scoped service binding.
Method singleton Register a singleton service binding.
Method transient Register a transient service binding.
Class Variable _instances Dictionary to hold singleton instances for each class This allows proper inheritance of the singleton pattern.
Class Variable _lock Lock for thread-safe singleton instantiation and access This lock ensures that only one thread can create or access instances at a time.
Instance Variable __aliases Aliases mapping for service resolution.
Instance Variable __bindings Registered bindings for services.
Instance Variable __cache_resolve_deferred_providers Tracks resolved deferred providers.
Instance Variable __creation_locks Per-key locks serialising one-shot construction, paired with the loop they were created on so a second loop never awaits a foreign lock.
Instance Variable __pending_deferred Deferred providers with boot work that is still pending.
Instance Variable __registered_deferred Deferred providers whose bindings have already been registered.
Instance Variable __singleton_cache Cache for singleton instances.
Instance Variable _Container__initialized Mark as initialized to prevent re-initialization.
Instance Variable _deferred_providers Deferred providers for lazy loading.
def __aliasService(self: Self, alias: str | None) -> str | None: (source)

Validate and normalize a service alias string.

Parameters
alias:str | NoneThe alias string to validate and normalize.
Returns
str | NoneThe validated and normalized alias string, or None if not provided.
Raises
TypeErrorIf the alias is not a string.
ValueErrorIf the alias is empty after stripping.
async def __autoResolveCallable(self: 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:objectPositional arguments for the callable.
**kwargs:objectKeyword arguments for the callable.
Returns
typing.AnyThe result of the callable invocation.
Raises
orionis.container.exceptions.CircularDependencyExceptionIf a circular dependency is detected.
ExceptionIf the callable cannot be auto-resolved.
async def __autoResolveClass(self: 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:objectPositional arguments for the constructor.
**kwargs:objectKeyword arguments for the constructor.
Returns
typing.AnyThe instantiated object with dependencies resolved.
Raises
orionis.container.exceptions.CircularDependencyExceptionIf a circular dependency is detected.
ExceptionIf the type cannot be auto-resolved.
async def __awaitPendingProvider(self: Self, key: type[Any] | str): (source)

Wait for a provider that has registered services but is still booting.

Parameters
key:type[typing.Any] | strService type or alias requested by a resolver.
Returns
NoneNo return value.
def __bind(self: 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.LifetimeThe lifetime of the binding (singleton, scoped, or transient).
abstract:type[typing.Any] | NoneThe 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 | NoneAn optional alias for the registration.
override:boolIf True, override any existing registration.
Returns
boolTrue if the binding was registered successfully.
Raises
TypeErrorIf the concrete is not a class type or type validation fails.
ValueErrorIf the alias is invalid or already registered, or if the contract is already registered and override is False.
async def __bootDeferredProvider(self: Self, provider_key: tuple[str, str]): (source)

Register a deferred provider once and complete its boot hook.

Parameters
provider_key:tuple[str, str]Module and class identifying a provider whose lock is held.
Returns
NoneNo return value.
async def __createScoped(self: 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.BindingThe scoped binding to materialize.
scope:orionis.container.context.manager.ScopeManagerThe active scope that owns the resulting instance.
*args:objectPositional arguments for the constructor.
**kwargs:objectKeyword arguments for the constructor.
Returns
typing.AnyThe scoped instance, built by this call or by the task that won the creation lock.
async def __createSingleton(self: Self, binding: Binding, *args: object, **kwargs: object) -> Any: (source)

Build and cache the single instance backing a singleton binding.

Parameters
binding:orionis.container.entities.BindingThe singleton binding to materialize.
*args:objectPositional arguments for the constructor.
**kwargs:objectKeyword arguments for the constructor.
Returns
typing.AnyThe cached instance, built by this call or by the task that won the creation lock.
def __creationLock(self: Self, key: object) -> asyncio.Lock: (source)

Return the creation lock for a key, bound to the running loop.

Parameters
key:objectContract or deferred provider key whose construction is guarded.
Returns
asyncio.LockLock owned by the running loop for this key. A new lock replaces any entry created on a different loop.
def __ensureCanOverrideGlobal(self: 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 | NoneThe alias to check for conflicts.
override:boolWhether to allow overriding existing registrations.
Returns
NoneNo return value.
Raises
ValueErrorIf the service or alias already exists globally and override is False.
def __ensureCanOverrideScope(self: 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.ScopeManagerThe current scoped service registry.
override:boolWhether to allow overriding existing registrations.
Returns
NoneNo return value.
Raises
ValueErrorIf the service already exists in the current scope and override is False.
def __ensureConcreteImplements(self: Self, abstract: type[Any], concrete: type[Any]): (source)

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
NoneNo return value.
Raises
TypeErrorIf abstract or concrete is not a class type, or if concrete does not implement abstract.
def __ensureInstanceImplements(self: Self, abstract: type[Any], instance: object): (source)

Ensure that an instance implements the specified abstract class.

Parameters
abstract:type[typing.Any]The abstract class type to check against.
instance:objectThe object instance to validate.
Returns
NoneNo return value.
Raises
TypeErrorIf abstract is not a class type or instance does not implement it.
def __init__(self: Self): (source)
overridden in orionis.Application

Initialize the internal state of the container.

Sets up internal data structures for dependency injection and ensures single initialization per instance.

Returns
NoneNo return value.
def __isBeingResolved(self, concrete: type[Any]) -> bool: (source)

Determine whether a concrete type is already resolving in this task.

Parameters
concrete:type[typing.Any]Concrete class about to be constructed.
Returns
boolTrue when the type is already on the current resolution stack, which means the caller must skip the creation lock it already owns.
def __new__(cls: type[Self], *args: object, **kwargs: object) -> Self: (source)

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:typeClass or metaclass to allocate.
*args:objectValue supplied for *args.
**kwargs:objectValue supplied for **kwargs.
Returns
typing.SelfThe singleton instance of the calling class.
async def __resolve(self: Self, binding: Binding, *args: object, **kwargs: object) -> Any: (source)

Resolve an instance from a binding according to its lifetime.

Parameters
binding:orionis.container.entities.BindingThe binding to resolve.
*args:objectPositional arguments for the constructor.
**kwargs:objectKeyword arguments for the constructor.
Returns
typing.AnyThe resolved instance according to the binding's lifetime.
Raises
RuntimeErrorIf there is no active scope for scoped services.
async def __resolveArgument(self: Self, argument: Argument) -> Any: (source)

Resolve a single argument for dependency injection.

Parameters
argument:orionis.introspection.dependencies.entities.argument.ArgumentThe argument metadata to resolve.
Returns
typing.AnyThe resolved value for the argument.
Raises
TypeErrorIf the argument cannot be resolved or is a built-in type.
async def __resolveDeferredProvider(self: Self, key: type[Any] | str): (source)

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] | strThe service type or fully qualified class name for which to find the deferred provider.
Returns
NoneNo return value.
async def __resolveKey(self: Self, key: type[Any] | str) -> type[Any]: (source)

Resolve a service key to its abstract type.

Parameters
key:type[typing.Any] | strService identifier as an abstract type or alias string.
Returns
type[typing.Any]The resolved abstract service type.
Raises
ValueErrorIf a string alias is not registered after deferred resolution.
async def __resolveMissingParameter(self, argument: Argument) -> Any: (source)

Resolve a parameter whose value was omitted from a keyword call.

Parameters
argument:orionis.introspection.dependencies.entities.argument.ArgumentParameter metadata requiring a service, schema, or default value.
Returns
typing.AnyValue selected from the current provider registrations and scope.
async def __resolveOrBuild(self: 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] | strOriginal service key used for resolution and error messages.
*args:objectPositional arguments passed to the resolver or builder.
**kwargs:objectKeyword arguments passed to the resolver or builder.
Returns
typing.AnyResolved service instance.
Raises
ValueErrorIf no binding exists and the service cannot be resolved.
async def __resolvePositionalArguments(self: 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.
async def __resolveSchemaArgument(self: Self, argument: Argument) -> msgspec.Struct: (source)

Validate a schema argument using the active HTTP request payload.

Parameters
argument:orionis.introspection.dependencies.entities.argument.ArgumentParameter metadata declaring the schema to construct.
Returns
msgspec.StructSchema instance populated from the request body.
Raises
ExceptionIf request resolution, body parsing or schema validation fails.
async def __resolveSignature(self: 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.
positional_only:frozenset[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.
def beginScope(self: Self) -> ScopeManager: (source)

Begin a new scope context manager for scoped services.

Parameters
self:orionis.container.container.ContainerThe container instance.
Returns
orionis.container.context.manager.ScopeManagerContext manager for managing the lifecycle of scoped services.
def bound(self: Self, key: type[Any] | str) -> bool: (source)

Determine if a key is bound in the container or current scope.

Parameters
key:type[typing.Any] | strThe abstract type or alias to check for binding.
Returns
boolTrue if the key is bound in the current scope or container, otherwise False.
async def build(self: Self, type_: type[Any], *args: object, **kwargs: object) -> Any: (source)

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:objectPositional arguments for the constructor.
**kwargs:objectKeyword arguments for the constructor.
Returns
typing.AnyInstantiated object of the specified type.
Raises
TypeErrorIf the type cannot be auto-resolved by the container.
async def call(self: 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:objectThe object instance containing the method.
method_name:strThe name of the method to invoke.
*args:objectPositional arguments for the method.
**kwargs:objectKeyword arguments for the method.
Returns
typing.AnyThe result of the method invocation with dependencies resolved.
Raises
AttributeErrorIf the method is not found on the instance.
TypeErrorIf the attribute is not callable.
def getCurrentScope(self: Self) -> ScopeManager | None: (source)

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.ContainerThe container instance.
Returns
orionis.container.context.manager.ScopeManager | NoneThe 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.
def instance(self: 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] | NoneThe abstract contract class to associate with the instance, or None.
instance:objectThe initialized object to register.
alias:str | None, optionalAn optional alias for the registration.
override:bool, optionalIf True, override any existing registration.
Returns
boolTrue if the instance was registered successfully.
Raises
TypeErrorIf the instance is a class, or if type validation fails.
ValueErrorIf the alias is invalid or already registered, or if the contract is already registered and override is False.
async def invoke(self: 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:objectPositional arguments for the callable.
**kwargs:objectKeyword arguments for the callable.
Returns
typing.AnyThe result of the callable execution with dependencies injected.
Raises
TypeErrorIf fn is not a callable or is a class/type.
async def make(self: 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] | strThe abstract type or alias to resolve.
*args:objectPositional arguments for instantiation.
**kwargs:objectKeyword arguments for instantiation.
Returns
typing.AnyThe resolved service instance.
Raises
ValueErrorIf the service is not registered and cannot be auto-resolved.
def scoped(self: 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] | NoneThe 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, optionalAn optional alias for the service.
override:bool, optionalWhether to override an existing registration.
Returns
boolTrue if the binding was registered successfully.
def singleton(self: 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] | NoneThe 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, optionalAn optional alias for the service.
override:bool, optionalWhether to override an existing registration.
Returns
boolTrue if the binding was registered successfully.
def transient(self: 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] | NoneThe 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, optionalAn optional alias for the service.
override:bool, optionalWhether to override an existing registration.
Returns
boolTrue 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.

__aliases: dict[str, type] = (source)

Aliases mapping for service resolution.

__bindings: dict[type[Any], Binding] = (source)

Registered bindings for services.

__cache_resolve_deferred_providers: set[tuple[str, str]] = (source)

Tracks resolved deferred providers.

Per-key locks serialising one-shot construction, paired with the loop they were created on so a second loop never awaits a foreign lock.

__pending_deferred: dict[str, tuple[str, str]] = (source)

Deferred providers with boot work that is still pending.

__registered_deferred: dict[tuple[str, str], IServiceProvider] = (source)

Deferred providers whose bindings have already been registered.

__singleton_cache: dict[type[Any], Any] = (source)

Cache for singleton instances.

_Container__initialized: bool = (source)

Mark as initialized to prevent re-initialization.

_deferred_providers: dict[str, dict[str, str]] = (source)
overridden in orionis.Application

Deferred providers for lazy loading.