diff --git a/docs/containers/declarative.rst b/docs/containers/declarative.rst index 045e9c6e..d193b83e 100644 --- a/docs/containers/declarative.rst +++ b/docs/containers/declarative.rst @@ -3,53 +3,42 @@ Declarative containers .. currentmodule:: dependency_injector.containers -:py:class:`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). +:py:class:`DeclarativeContainer` is a collection of the providers defined in the declarative +manner. It covers the use cases when your application structure does not change in the runtime. -Declarative containers have to extend base declarative container class - -:py: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. - -.. note:: - - 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 - - :py:class:`dependency_injector.containers.DeclarativeContainer`. - -Here is an simple example of defining declarative container with several -factories: - -.. image:: /images/containers/declarative.png - :width: 85% - :align: center +Container has the ``.providers`` attribute. It is a dictionary of the container providers. .. literalinclude:: ../../examples/containers/declarative.py :language: python + :lines: 3- -Example of declarative containers inheritance: +Your declarative container has to extend base declarative container class - +:py:class:`dependency_injector.containers.DeclarativeContainer`. -.. image:: /images/containers/declarative_inheritance.png - :width: 100% - :align: center +Declarative container classes can not have any methods or any other attributes then providers. + +The declarative container providers should only be used after the container is initialized. + +The container class provides next attributes: + +- ``providers`` - the dictionary of all the container providers +- ``cls_providers`` - the dictionary of the container providers of the current container +- ``inherited_providers`` - the dictionary of all the inherited container providers .. literalinclude:: ../../examples/containers/declarative_inheritance.py :language: python + :lines: 3- -Example of declarative containers's provider injections: - -.. image:: /images/containers/declarative_injections.png - :width: 100% - :align: center +Injections in the declarative container are done the usual way: .. literalinclude:: ../../examples/containers/declarative_injections.py :language: python + :lines: 3- +You can override the container providers when you create the container instance: + +.. literalinclude:: ../../examples/containers/declarative_override_providers.py + :language: python + :lines: 3- .. disqus:: diff --git a/docs/containers/index.rst b/docs/containers/index.rst index 93bee78a..510d4d02 100644 --- a/docs/containers/index.rst +++ b/docs/containers/index.rst @@ -1,21 +1,16 @@ -IoC Containers -============== +Containers +========== -Containers are collections of providers. Main purpose of containers is to group -providers. +Containers are collections of the providers. -There are, actually, several popular cases of containers usage: +There are several use cases how you can use containers: -+ Keeping all providers in a single container. -+ Grouping of providers from the same architectural layer (for example, ++ Keeping all the providers in a single container (most common). ++ Grouping of the providers from the same architectural layer (for example, ``Services``, ``Models`` and ``Forms`` containers). + Grouping of providers from the same functional groups (for example, - container ``Users``, that contains all functional parts of ``Users`` - component). - -Also, for both of these and some other cases, it might be useful to attach -some init / shutdown functionality or something else, that deals with group -of providers. + container ``Users``, that contains all functional parts of the ``users`` + package). Containers package API docs - :py:mod:`dependency_injector.containers`. diff --git a/docs/images/containers/declarative.png b/docs/images/containers/declarative.png deleted file mode 100644 index 11b0297d..00000000 Binary files a/docs/images/containers/declarative.png and /dev/null differ diff --git a/docs/images/containers/declarative_inheritance.png b/docs/images/containers/declarative_inheritance.png deleted file mode 100644 index 1e0eb1f4..00000000 Binary files a/docs/images/containers/declarative_inheritance.png and /dev/null differ diff --git a/docs/images/containers/declarative_injections.png b/docs/images/containers/declarative_injections.png deleted file mode 100644 index 36454e5b..00000000 Binary files a/docs/images/containers/declarative_injections.png and /dev/null differ diff --git a/examples/containers/declarative.py b/examples/containers/declarative.py index f095d5e9..1654e8fe 100644 --- a/examples/containers/declarative.py +++ b/examples/containers/declarative.py @@ -1,23 +1,22 @@ -"""Declarative IoC container simple example.""" +"""Declarative container example.""" -import dependency_injector.containers as containers -import dependency_injector.providers as providers +from dependency_injector import containers, 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() +container = Container() -# Making some asserts: -assert object1 is not object2 -assert isinstance(object1, object) -assert isinstance(object2, object) +object1 = container.factory1() +object2 = container.factory2() + +print(container.providers) +# { +# 'factory1':