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

Define the contract for container implementations.

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.
def beginScope(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, 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, 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, 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) -> 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, 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, 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, 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, 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, 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, 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.