Instruction file imported from orionis-framework/framework (.github/instructions/di-container-providers.instructions.md). Copyright stays with the author.

Container, Providers and Facades

Read the module docs first

orionis/foundation/ has no docs/ yet: for the application lifecycle and config entities, read the code. Everything below is rules and gotchas, not an API reference.

Application lifecycle

1. Application(...) in bootstrap/app.py — singleton, extends Container.
2. withRouting / withScheduler / withExceptionHandler / withProviders / withMiddleware — declarative config, frozen with FreezeThaw.freeze() on boot.
3. app.create() — asserts Python version, loads CORE_CONFIG + config/*.py, sets timezone/locale via DateTime._loadConfig, self-registers IApplication, runs register() of every provider, stores deferred ones in _deferred_providers.
4. Application.__onStartup() — runs boot() of eager providers. Only fires under the HTTP or CLI runtime, never from a bare import bootstrap.app.
5. Runtime: handleASGI / handleRSGI (HTTP) or handleCommand (CLI).

Container

• Singleton per subclass (_instances dict + threading.RLock double-check in __new__).
• Lifetimes: TRANSIENT = 1, SINGLETON = 2, SCOPED = 3.
• Registration: bind, singleton, scoped, transient, instance(contract, obj, alias=None). Aliases are strings and are global only.
• Resolution is async: make, build, invoke, call. make() uses the singleton cache; build() always creates a new instance.
• async with app.beginScope(): for SCOPED; resolving scoped without a scope raises RuntimeError.
• Cycles are detected via a ContextVar frozenset stack → CircularDependencyException.
• Creation of singletons, scoped services and deferred providers is guarded by __creationLock(key) (one asyncio.Lock per key, bound to the running loop) with double-checked locking and an anti-deadlock guard on the resolution stack.
• A parameter annotated with a subclass of orionis.schemas.schema.Schema makes the container validate the request body automatically.

Hard DI rules

Private methods that are not reflected by the container may annotate with TYPE_CHECKING-only imports (PEP 649 makes annotations lazy).

Service providers

from orionis.container.providers import ServiceProvider

class AppServiceProvider(ServiceProvider):

    def register(self) -> None:
        """Register application services."""
        self.app.singleton(IMyService, MyService)

    async def boot(self) -> None:
        """Bootstrap application services."""
        await MyFacade.pin()

• register() is sync and only declares bindings; boot() is async and does the wiring.
• DeferrableProvider.provides() only declares keys; the real deferred registry is built by Application.create().
• The 15 core providers live in orionis/foundation/core_providers.py: CacheProvider, CatchProvider, ConnectionManagerProvider, EncrypterProvider, HashProvider, LocalizationProvider, LoggerProvider, QueryBuilderProvider, ReactorProvider, RouterProvider, ScheduleProvider, SchemaProvider, StorageProvider, TestingProvider, ViewServiceProvider.
• If a facade is consumed without await from synchronous framework code, its provider must NOT be deferrable — it has to be eager so the facade is pinned at startup (this is why HashProvider and EncrypterProvider are eager).

Facades

orionis/support/facades/ — each facade only overrides getFacadeAccessor(); the parallel .pyi exists solely for editor autocompletion and is never executed.

16 facades: Application, Cache, Catch, Crypt, DB, Hash, Lang, Log, Reactor, Route, Schedule, Schema, Session, Storage, Test, View — plus DateTime, which is not a facade but a classmethod-only wrapper over pendulum and the single source of truth for timezone/locale.

# Unpinned: every attribute access returns a _FacadeDispatch
repo = Cache.store("redis")          # _FacadeDispatch, NOT the repository
repo = await Cache.store("redis")    # correct without pin (and pins as a side effect)

# Pinned (after await Facade.pin() or the provider boot): direct passthrough
Hash.make("secret")                  # synchronous, no await

• _FacadeDispatch implements __await__, __aenter__ and __aexit__, so async with Schema.create(...) requires a pin but await Schema.create(...) does not.
• A real classmethod defined on the facade subclass (e.g. DB.table()) bypasses FacadeMeta.__getattr__ entirely — that hook is only an attribute-not-found fallback. Do not delete such an override without grepping for callers that rely on the unpinned path.
• _pinned_instance is a class attribute shared process-wide. Session is pinned and unpinned per request inside StartSessionMiddleware; concurrent code must read request.state.session instead.

Configuration

• Config entities: orionis/foundation/config/<section>/entities/*.py, dataclasses frozen=True, kw_only=True extending BaseEntity, validated in __post_init__, reading env via default_factory=lambda: Env.get("VAR", default).
• CORE_CONFIG has 14 sections: app, auth, cache, database, filesystems, hashing, http, logging, mail, queue, scheduler, session, testing, view.
• The application overrides them in config/*.py with Bootstrap* classes.
• app.config("path.to.key") returns None for unknown keys — always provide a fallback in the consumer.

Adding or removing a provider, a core command or a config entity field invalidates nothing automatically: delete storage/framework/bootstrap (or run reactor optimize:clear) or the app keeps booting with stale compiled metadata.