Add container examples

examples/containers/declarative.py

@@ -0,0 +1,22 @@
+"""Declarative IoC container simple example."""
+
+from dependency_injector import containers
+from dependency_injector import 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)

examples/containers/declarative_inheritance.py

@@ -0,0 +1,30 @@
+"""Declarative IoC containers inheritance example."""
+
+from dependency_injector import containers
+from dependency_injector import 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,
+                                    provider2=ContainerB.provider2)
+
+# 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)

examples/containers/declarative_injections.py

@@ -0,0 +1,47 @@
+"""Declarative IoC container's provider injections example."""
+
+import sqlite3
+
+from dependency_injector import containers
+from dependency_injector import providers
+
+
+class UsersService(object):
+    """Users service, that has dependency on database."""
+
+    def __init__(self, db):
+        """Initializer."""
+        self.db = db
+
+
+class AuthService(object):
+    """Auth service, that has dependencies on users service and database."""
+
+    def __init__(self, db, users_service):
+        """Initializer."""
+        self.db = db
+        self.users_service = users_service
+
+
+class Services(containers.DeclarativeContainer):
+    """IoC container of service providers."""
+
+    database = providers.Singleton(sqlite3.connect, ':memory:')
+
+    users = providers.Factory(UsersService,
+                              db=database)
+
+    auth = providers.Factory(AuthService,
+                             db=database,
+                             users_service=users)
+
+
+# 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()

examples/containers/declarative_provider_type/container.py

@@ -0,0 +1,17 @@
+"""Specialized declarative IoC container example."""
+
+import core
+import services
+
+
+class Services(core.ServicesContainer):
+    """IoC container of service providers."""
+
+    users = core.ServiceProvider(services.UsersService,
+                                 config={'option1': '111',
+                                         'option2': '222'})
+
+    auth = core.ServiceProvider(services.AuthService,
+                                config={'option3': '333',
+                                        'option4': '444'},
+                                users_service=users)

examples/containers/declarative_provider_type/core.py

@@ -0,0 +1,26 @@
+"""Base classes for services."""
+
+from dependency_injector import containers
+from dependency_injector import providers
+
+
+class BaseService(object):
+    """Base service class."""
+
+
+class ServiceProvider(providers.Factory):
+    """Service provider.
+
+    Can provide :py:class:`Base` only.
+    """
+
+    provided_type = BaseService
+
+
+class ServicesContainer(containers.DeclarativeContainer):
+    """Base IoC container of service providers.
+
+    Can include :py:class:`Provider`'s only.
+    """
+
+    provider_type = ServiceProvider

examples/containers/declarative_provider_type/main.py

@@ -0,0 +1,42 @@
+"""Main module."""
+
+import core
+import services
+import container
+
+from dependency_injector import providers
+from dependency_injector import errors
+
+
+if __name__ == '__main__':
+    # Creating users & auth services:
+    users_service = container.Services.users()
+    auth_service = container.Services.auth()
+
+    # Making some asserts:
+    assert users_service.config == {'option1': '111',
+                                    'option2': '222'}
+    assert auth_service.config == {'option3': '333',
+                                   'option4': '444'}
+    assert isinstance(auth_service.users_service, services.UsersService)
+
+    # Trying to declare services container with other provider type:
+    try:
+        class _Services1(core.ServicesContainer):
+
+            users = providers.Factory(services.UsersService)
+    except errors.Error as exception:
+        print exception
+        # <class '__main__._Services1'> can contain only
+        # <class 'core.ServiceProvider'> instances
+
+    # Trying to declare services container with correct provider by invalid
+    # provided type:
+    try:
+        class _Services2(core.ServicesContainer):
+
+            users = core.ServiceProvider(object)
+    except errors.Error as exception:
+        print exception
+        # <class 'core.ServiceProvider'> can provide only
+        # <class 'core.BaseService'> instances

examples/containers/declarative_provider_type/services.py

@@ -0,0 +1,22 @@
+"""Base classes for services."""
+
+import core
+
+
+class UsersService(core.BaseService):
+    """Users service."""
+
+    def __init__(self, config):
+        """Initializer."""
+        self.config = config
+        super(UsersService, self).__init__()
+
+
+class AuthService(core.BaseService):
+    """Auth service."""
+
+    def __init__(self, config, users_service):
+        """Initializer."""
+        self.config = config
+        self.users_service = users_service
+        super(AuthService, self).__init__()

examples/containers/override_declarative.py

@@ -0,0 +1,45 @@
+"""Declarative IoC container overriding example."""
+
+import collections
+
+from dependency_injector import containers
+from dependency_injector import providers
+
+
+# Creating some example classes:
+Object1 = collections.namedtuple('Object1', ['arg1', 'arg2'])
+Object2 = collections.namedtuple('Object2', ['object1'])
+ExtendedObject2 = collections.namedtuple('ExtendedObject2', [])
+
+
+class Container(containers.DeclarativeContainer):
+    """Example IoC container."""
+
+    object1_factory = providers.Factory(Object1,
+                                        arg1=1,
+                                        arg2=2)
+
+    object2_factory = providers.Factory(Object2,
+                                        object1=object1_factory)
+
+
+class OverridingContainer(containers.DeclarativeContainer):
+    """Overriding IoC container."""
+
+    object2_factory = providers.Factory(ExtendedObject2)
+
+
+# Overriding `Container` with `OverridingContainer`:
+Container.override(OverridingContainer)
+
+# Creating some objects using overridden container:
+object2_1 = Container.object2_factory()
+object2_2 = Container.object2_factory()
+
+# Making some asserts:
+assert Container.overridden_by == (OverridingContainer,)
+
+assert object2_1 is not object2_2
+
+assert isinstance(object2_1, ExtendedObject2)
+assert isinstance(object2_2, ExtendedObject2)

examples/containers/override_declarative_decorator.py

@@ -0,0 +1,41 @@
+"""Declarative IoC container overriding using `@override()` decorator."""
+
+import collections
+
+from dependency_injector import containers
+from dependency_injector import providers
+
+
+# Creating some example classes:
+Object1 = collections.namedtuple('Object1', ['arg1', 'arg2'])
+Object2 = collections.namedtuple('Object2', ['object1'])
+ExtendedObject2 = collections.namedtuple('ExtendedObject2', [])
+
+
+class Container(containers.DeclarativeContainer):
+    """Example IoC container."""
+
+    object1_factory = providers.Factory(Object1, arg1=1, arg2=2)
+
+    object2_factory = providers.Factory(Object2, object1=object1_factory)
+
+
+# Overriding `Container` with `OverridingContainer`:
+@containers.override(Container)
+class OverridingContainer(containers.DeclarativeContainer):
+    """Overriding IoC container."""
+
+    object2_factory = providers.Factory(ExtendedObject2)
+
+
+# Creating some objects using overridden container:
+object2_1 = Container.object2_factory()
+object2_2 = Container.object2_factory()
+
+# Making some asserts:
+assert Container.overridden_by == (OverridingContainer,)
+
+assert object2_1 is not object2_2
+
+assert isinstance(object2_1, ExtendedObject2)
+assert isinstance(object2_2, ExtendedObject2)