Declarative containers

DeclarativeContainer is inversion of control container that could be defined in declarative manner. It should cover most of the cases when list of providers that would be included in container is deterministic (container will not change its structure in runtime).

Declarative containers have to extend base declarative container class - dependency_injector.containers.DeclarativeContainer.

Declarative container’s providers have to be defined like container’s class attributes. Every provider in container has name. This name should follow some_provider convention, that is standard naming convention for attribute names in Python.


Declarative containers have several features that could be useful for some kind of operations on container’s providers, please visit API documentation for getting full list of features - dependency_injector.containers.DeclarativeContainer.

Here is an simple example of defining declarative container with several factories:

"""Declarative IoC container simple example."""

import dependency_injector.containers as containers
import dependency_injector.providers as providers

# Defining declarative IoC container:
class Container(containers.DeclarativeContainer):
    """Example IoC container."""

    factory1 = providers.Factory(object)

    factory2 = providers.Factory(object)

# Creating some objects:
object1 = Container.factory1()
object2 = Container.factory2()

# Making some asserts:
assert object1 is not object2
assert isinstance(object1, object)
assert isinstance(object2, object)

Example of declarative containers inheritance:

"""Declarative IoC containers inheritance example."""

import dependency_injector.containers as containers
import dependency_injector.providers as providers

class ContainerA(containers.DeclarativeContainer):
    """Example IoC container A."""

    provider1 = providers.Factory(object)

class ContainerB(ContainerA):
    """Example IoC container B."""

    provider2 = providers.Singleton(object)

# Making some asserts for `providers` attribute:
assert ContainerA.providers == dict(provider1=ContainerA.provider1)
assert ContainerB.providers == dict(provider1=ContainerA.provider1,

# Making some asserts for `cls_providers` attribute:
assert ContainerA.cls_providers == dict(provider1=ContainerA.provider1)
assert ContainerB.cls_providers == dict(provider2=ContainerB.provider2)

# Making some asserts for `inherited_providers` attribute:
assert ContainerA.inherited_providers == dict()
assert ContainerB.inherited_providers == dict(provider1=ContainerB.provider1)

Example of declarative containers’s provider injections:

"""Declarative IoC container's provider injections example."""

import sqlite3
import collections

import dependency_injector.containers as containers
import dependency_injector.providers as providers

UsersService = collections.namedtuple('UsersService', ['db'])
AuthService = collections.namedtuple('AuthService', ['db', 'users_service'])

class Services(containers.DeclarativeContainer):
    """IoC container of service providers."""

    database = providers.Singleton(sqlite3.connect, ':memory:')

    users = providers.Factory(UsersService,

    auth = providers.Factory(AuthService,

# Retrieving service providers from container:
users_service = Services.users()
auth_service = Services.auth()

# Making some asserts:
assert users_service.db is auth_service.db is Services.database()
assert isinstance(auth_service.users_service, UsersService)
assert users_service is not Services.users()
assert auth_service is not Services.auth()