Update container overriding docs

docs/containers/overriding.rst

@@ -1,41 +1,24 @@
-Overriding of containers
+Overriding of the container
-------------------------
+---------------------------
 
 .. currentmodule:: dependency_injector.containers
 
-Containers can be overridden by other containers. This, actually, means that 
+The container can be overridden by the other container. All of the providers from the overriding
-all of the providers from overriding container will override providers with 
+container will override the providers with the same names in the overridden container.
-the same names in overridden container.
 
-There are two ways to override :py:class:`DeclarativeContainer` with another 
+.. literalinclude:: ../../examples/containers/override.py
-container:
-
-- Use :py:meth:`DeclarativeContainer.override` method.
-- Use :py:func:`override` class decorator.
-
-Example of overriding container using :py:meth:`DeclarativeContainer.override` 
-method:
-
-.. literalinclude:: ../../examples/containers/override_declarative.py
    :language: python
+   :lines: 3-
 
-Example of overriding container using :py:func:`override` decorator:
+It helps in a testing. Also you can use it for configuring project for the different
+environments: replace an API client with a stub on the dev or stage.
 
-.. literalinclude:: ../../examples/containers/override_declarative_decorator.py
+The container also has:
-   :language: python
 
-Also there are several useful :py:class:`DeclarativeContainer` methods and 
+- ``container.overridden`` - tuple of all overriding containers.
-properties that help to work with container overridings:
+- ``container.reset_last_overriding()`` - reset last overriding for each provider in the container.
-
+- ``container.reset_override()`` - reset all overriding in the container.
-- :py:attr:`DeclarativeContainer.overridden` - tuple of all overriding 
-  containers.
-- :py:meth:`DeclarativeContainer.reset_last_overriding()` - reset last 
-  overriding provider for each container providers.
-- :py:meth:`DeclarativeContainer.reset_override()` - reset all overridings 
-  for each container providers. 
-
-:py:class:`DynamicContainer` has exactly the same functionality, except of 
-:py:func:`override` decorator.
 
+:py:class:`DynamicContainer` has the same functionality.
 
 .. disqus::

examples/containers/override.py

@@ -0,0 +1,31 @@
+"""Container overriding example."""
+
+from dependency_injector import containers, providers
+
+
+class Service:
+    ...
+
+
+class ServiceStub:
+    ...
+
+
+class Container(containers.DeclarativeContainer):
+
+    service = providers.Factory(Service)
+
+
+class OverridingContainer(containers.DeclarativeContainer):
+
+    service = providers.Factory(ServiceStub)
+
+
+if __name__ == '__main__':
+    container = Container()
+    overriding_container = OverridingContainer()
+
+    container.override(overriding_container)
+
+    service = container.service()
+    assert isinstance(service, ServiceStub)

examples/containers/override_declarative.py

@@ -1,28 +0,0 @@
-"""Declarative IoC container overriding example."""
-
-import dependency_injector.containers as containers
-import dependency_injector.providers as providers
-
-
-class Container(containers.DeclarativeContainer):
-    """IoC container."""
-
-    sequence_factory = providers.Factory(list)
-
-
-class OverridingContainer(containers.DeclarativeContainer):
-    """Overriding IoC container."""
-
-    sequence_factory = providers.Factory(tuple)
-
-
-# Overriding `Container` with `OverridingContainer`:
-Container.override(OverridingContainer)
-
-# Creating some objects using overridden container:
-sequence_1 = Container.sequence_factory([1, 2, 3])
-sequence_2 = Container.sequence_factory([3, 2, 1])
-
-# Making some asserts:
-assert Container.overridden == (OverridingContainer,)
-assert sequence_1 == (1, 2, 3) and sequence_2 == (3, 2, 1)

examples/containers/override_declarative_decorator.py

@@ -1,27 +0,0 @@
-"""Declarative IoC container overriding using `@override()` decorator."""
-
-import dependency_injector.containers as containers
-import dependency_injector.providers as providers
-
-
-class Container(containers.DeclarativeContainer):
-    """IoC container."""
-
-    sequence_factory = providers.Factory(list)
-
-
-# Overriding `Container` with `OverridingContainer`:
-@containers.override(Container)
-class OverridingContainer(containers.DeclarativeContainer):
-    """Overriding IoC container."""
-
-    sequence_factory = providers.Factory(tuple)
-
-
-# Creating some objects using overridden container:
-sequence_1 = Container.sequence_factory([1, 2, 3])
-sequence_2 = Container.sequence_factory([3, 2, 1])
-
-# Making some asserts:
-assert Container.overridden == (OverridingContainer,)
-assert sequence_1 == (1, 2, 3) and sequence_2 == (3, 2, 1)