diff --git a/docs/containers/overriding.rst b/docs/containers/overriding.rst index 729a8b1c..cf5627af 100644 --- a/docs/containers/overriding.rst +++ b/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 -all of the providers from overriding container will override providers with -the same names in overridden container. +The container can be overridden by the other container. All of the providers from the overriding +container will override the providers with the same names in the overridden container. -There are two ways to override :py:class:`DeclarativeContainer` with another -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 +.. literalinclude:: ../../examples/containers/override.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 - :language: python +The container also has: -Also there are several useful :py:class:`DeclarativeContainer` methods and -properties that help to work with container overridings: - -- :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. +- ``container.overridden`` - tuple of all overriding containers. +- ``container.reset_last_overriding()`` - reset last overriding for each provider in the container. +- ``container.reset_override()`` - reset all overriding in the container. +:py:class:`DynamicContainer` has the same functionality. .. disqus:: diff --git a/examples/containers/override.py b/examples/containers/override.py new file mode 100644 index 00000000..268cc4d0 --- /dev/null +++ b/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) diff --git a/examples/containers/override_declarative.py b/examples/containers/override_declarative.py deleted file mode 100644 index b11d1b2e..00000000 --- a/examples/containers/override_declarative.py +++ /dev/null @@ -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) diff --git a/examples/containers/override_declarative_decorator.py b/examples/containers/override_declarative_decorator.py deleted file mode 100644 index 74165383..00000000 --- a/examples/containers/override_declarative_decorator.py +++ /dev/null @@ -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)