Update container provider type specialization docs

docs/containers/specialization.rst

@@ -1,25 +1,25 @@
-Specialization of containers
+Specialization of the container provider type
-----------------------------
+---------------------------------------------
 
 .. currentmodule:: dependency_injector.containers
 
-:py:class:`DeclarativeContainer` could be specialized for any kind of needs 
+You can make a restriction of the :py:class:`DeclarativeContainer` provider type:
-via declaring its subclasses. 
-
-One of such `builtin` features is a limitation for providers type.
-
-Next example shows usage of this feature with :py:class:`DeclarativeContainer` 
-in couple with feature of :py:class:`dependency_injector.providers.Factory` 
-for limitation of its provided type:
 
 .. literalinclude:: ../../examples/containers/declarative_provider_type.py
    :language: python
+   :lines: 3-
+   :emphasize-lines: 29-31
 
-Limitation for providers type could be used with :py:class:`DynamicContainer` 
+The emphasized lines will cause an error because ``other_provider`` is not a subtype of the
-as well:
+``ServiceProvider``. This helps to control the content of the container.
+
+The same works for the :py:class:`DynamicContainer`:
 
 .. literalinclude:: ../../examples/containers/dynamic_provider_type.py
    :language: python
+   :lines: 3-
+   :emphasize-lines: 23
 
+The emphasized line will also cause an error.
 
 .. disqus::

examples/containers/declarative_provider_type.py

@@ -1,48 +1,33 @@
-"""Specializing declarative container and factory provider example."""
+"""Declarative container provider type restriction example."""
 
-import collections
+import abc
 
-import dependency_injector.containers as containers
+from dependency_injector import containers, providers
-import dependency_injector.providers as providers
-import dependency_injector.errors as errors
 
 
-class SequenceProvider(providers.Factory):
+class Service(metaclass=abc.ABCMeta):
-    """Sequence factory.
+    ...
-
-    Can provide only sequence objects.
-    """
-
-    provided_type = collections.Sequence
 
 
-class SequencesContainer(containers.DeclarativeContainer):
+class UserService(Service):
-    """IoC container.
+    ...
-
-    Can contain only sequence providers.
-    """
-
-    provider_type = SequenceProvider
 
 
-if __name__ == '__main__':
+class ServiceProvider(providers.Factory):
-    try:
-        class _SequenceContainer1(SequencesContainer):
-            object_provider = providers.Factory(object)
-    except errors.Error as exception:
-        print(exception)
-        # <class '__main__._SequenceContainer1'> can contain only
-        # <class '__main__.SequenceProvider'> instances
 
-    try:
+    provided_type = Service
-        class _SequenceContainer2(SequencesContainer):
-            object_provider = SequenceProvider(object)
-    except errors.Error as exception:
-        print(exception)
-        # <class '__main__.SequenceProvider'> can provide only
-        # <class '_abcoll.Sequence'> instances
 
-    class _SequenceContaier3(SequencesContainer):
-        list_provider = SequenceProvider(list)
 
-    assert _SequenceContaier3.list_provider() == list()
+class ServiceContainer(containers.DeclarativeContainer):
+
+    provider_type = ServiceProvider
+
+
+class MyServices(ServiceContainer):
+
+    user_service = ServiceProvider(UserService)
+
+
+class ImproperServices(ServiceContainer):
+
+    other_provider = providers.Factory(object)

examples/containers/dynamic_provider_type.py

@@ -1,41 +1,25 @@
-"""Specializing dynamic container and factory provider example."""
+"""Dynamic container provider type restriction example."""
 
-import collections
+import abc
 
-import dependency_injector.containers as containers
+from dependency_injector import containers, providers
-import dependency_injector.providers as providers
-import dependency_injector.errors as errors
 
 
-class SequenceProvider(providers.Factory):
+class Service(metaclass=abc.ABCMeta):
-    """Sequence factory.
+    ...
-
-    Can provide only sequence objects.
-    """
-
-    provided_type = collections.Sequence
 
 
-sequences_container = containers.DynamicContainer()
+class UserService(Service):
-sequences_container.provider_type = SequenceProvider
+    ...
 
 
-if __name__ == '__main__':
+class ServiceProvider(providers.Factory):
-    try:
-        sequences_container.object_provider = providers.Factory(object)
-    except errors.Error as exception:
-        print(exception)
-        # <dependency_injector.containers.DynamicContainer object at
-        # 0x107820ed0> can contain only <class '__main__.SequenceProvider'>
-        # instances
 
-    try:
+    provided_type = Service
-        sequences_container.object_provider = SequenceProvider(object)
-    except errors.Error as exception:
-        print(exception)
-        # <class '__main__.SequenceProvider'> can provide only
-        # <class '_abcoll.Sequence'> instances
 
-    sequences_container.list_provider = SequenceProvider(list)
 
-    assert sequences_container.list_provider() == list()
+services = containers.DynamicContainer()
+services.provider_type = ServiceProvider
+
+services.user_service = ServiceProvider(UserService)
+services.other_provider = providers.Factory(object)