diff --git a/docs/api/catalogs.rst b/docs/api/catalogs.rst deleted file mode 100644 index 08cdfef9..00000000 --- a/docs/api/catalogs.rst +++ /dev/null @@ -1,6 +0,0 @@ -``dependency_injector.catalogs`` --------------------------------- - -.. automodule:: dependency_injector.catalogs - :members: - :special-members: diff --git a/docs/api/containers.rst b/docs/api/containers.rst new file mode 100644 index 00000000..79678008 --- /dev/null +++ b/docs/api/containers.rst @@ -0,0 +1,6 @@ +``dependency_injector.containers`` +-------------------------------- + +.. automodule:: dependency_injector.containers + :members: + :special-members: diff --git a/docs/api/index.rst b/docs/api/index.rst index 6d767939..1f1df940 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -6,7 +6,6 @@ API Documentation top_level providers - injections - catalogs + containers utils errors diff --git a/docs/api/injections.rst b/docs/api/injections.rst deleted file mode 100644 index 71884fe7..00000000 --- a/docs/api/injections.rst +++ /dev/null @@ -1,6 +0,0 @@ -``dependency_injector.injections`` ----------------------------------- - -.. automodule:: dependency_injector.injections - :members: - :inherited-members: diff --git a/docs/catalogs/declarative.rst b/docs/catalogs/declarative.rst deleted file mode 100644 index fbe241ea..00000000 --- a/docs/catalogs/declarative.rst +++ /dev/null @@ -1,64 +0,0 @@ -Declarative catalogs --------------------- - -.. currentmodule:: dependency_injector.catalogs - -:py:class:`DeclarativeCatalog` is a catalog of providers that could be -defined in declarative manner. It should cover most of the cases when list -of providers that would be included in catalog is deterministic (catalog -will not change its structure in runtime). - -Declarative catalogs have to extend base declarative catalog class - -:py:class:`dependency_injector.catalogs.DeclarativeCatalog`. - -Declarative catalog's providers have to be defined like catalog's class -attributes. Every provider in catalog has name. This name should follow -``some_provider`` convention, that is standard naming convention for -attribute names in Python. - -.. note:: - - Declarative catalogs have several features that could be useful - for some kind of operations on catalog's providers, please visit API - documentation for getting full list of features - - :py:class:`dependency_injector.catalogs.DeclarativeCatalog`. - -.. note:: - - It might be useful to add such - ``""":type: dependency_injector.providers.Provider -> Object1"""`` - docstrings just on the next line after provider's definition. It will - help code analyzing tools and IDE's to understand that variable above - contains some callable object, that returns particular instance as a - result of its call. - -Here is an simple example of defining declarative catalog with several -factories: - -.. image:: /images/catalogs/declarative.png - :width: 85% - :align: center - -.. literalinclude:: ../../examples/catalogs/declarative.py - :language: python - :linenos: - -Example of declarative catalogs inheritance: - -.. image:: /images/catalogs/declarative_inheritance.png - :width: 100% - :align: center - -.. literalinclude:: ../../examples/catalogs/declarative_inheritance.py - :language: python - :linenos: - -Example of declarative catalog's provider injections: - -.. image:: /images/catalogs/declarative_injections.png - :width: 100% - :align: center - -.. literalinclude:: ../../examples/catalogs/declarative_injections.py - :language: python - :linenos: diff --git a/docs/catalogs/index.rst b/docs/catalogs/index.rst deleted file mode 100644 index fa4e4ca8..00000000 --- a/docs/catalogs/index.rst +++ /dev/null @@ -1,27 +0,0 @@ -Catalogs -======== - -Catalogs are collections of providers. Main purpose of catalogs is to group -providers. - -There are, actually, several popular cases of catalogs usage: - -- Grouping of providers from the same architectural layer (for example, - ``Services``, ``Models`` and ``Forms`` catalogs). -- Grouping of providers from the same functional groups (for example, - catalog ``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. - -Catalogs module API docs - :py:mod:`dependency_injector.catalogs`. - -.. toctree:: - :maxdepth: 2 - - declarative - dynamic - specialization - overriding diff --git a/docs/containers/declarative.rst b/docs/containers/declarative.rst new file mode 100644 index 00000000..e290251e --- /dev/null +++ b/docs/containers/declarative.rst @@ -0,0 +1,55 @@ +Declarative containers +-------------------- + +.. currentmodule:: dependency_injector.containers + +:py:class:`DeclarativeContainer` is a container of providers 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). + +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 + +.. literalinclude:: ../../examples/containers/declarative.py + :language: python + :linenos: + +Example of declarative containers inheritance: + +.. image:: /images/containers/declarative_inheritance.png + :width: 100% + :align: center + +.. literalinclude:: ../../examples/containers/declarative_inheritance.py + :language: python + :linenos: + +Example of declarative containers's provider injections: + +.. image:: /images/containers/declarative_injections.png + :width: 100% + :align: center + +.. literalinclude:: ../../examples/containers/declarative_injections.py + :language: python + :linenos: diff --git a/docs/catalogs/dynamic.rst b/docs/containers/dynamic.rst similarity index 95% rename from docs/catalogs/dynamic.rst rename to docs/containers/dynamic.rst index 8489b60f..773dd20b 100644 --- a/docs/catalogs/dynamic.rst +++ b/docs/containers/dynamic.rst @@ -1,7 +1,7 @@ Dynamic catalogs ---------------- -.. currentmodule:: dependency_injector.catalogs +.. currentmodule:: dependency_injector.containers :py:class:`DynamicCatalog` is a catalog of providers that could be created in application's runtime. It should cover most of the cases when list of diff --git a/docs/containers/index.rst b/docs/containers/index.rst new file mode 100644 index 00000000..0cd66a08 --- /dev/null +++ b/docs/containers/index.rst @@ -0,0 +1,28 @@ +Containers +========== + +Containers are collections of providers. Main purpose of containers is to group +providers. + +There are, actually, several popular cases of containers usage: + ++ Keeping all providers in a single container. ++ Grouping of 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. + +Containers module API docs - :py:mod:`dependency_injector.containers`. + +.. toctree:: + :maxdepth: 2 + + declarative + dynamic + specialization + overriding diff --git a/docs/catalogs/overriding.rst b/docs/containers/overriding.rst similarity index 97% rename from docs/catalogs/overriding.rst rename to docs/containers/overriding.rst index b94ffa7e..676810c2 100644 --- a/docs/catalogs/overriding.rst +++ b/docs/containers/overriding.rst @@ -1,7 +1,7 @@ Overriding of catalogs ---------------------- -.. currentmodule:: dependency_injector.catalogs +.. currentmodule:: dependency_injector.containers Catalogs can be overridden by other catalogs. This, actually, means that all of the providers from overriding catalog will override providers with the diff --git a/docs/catalogs/specialization.rst b/docs/containers/specialization.rst similarity index 96% rename from docs/catalogs/specialization.rst rename to docs/containers/specialization.rst index 0bd622e3..1647180a 100644 --- a/docs/catalogs/specialization.rst +++ b/docs/containers/specialization.rst @@ -1,7 +1,7 @@ Specialization of catalogs -------------------------- -.. currentmodule:: dependency_injector.catalogs +.. currentmodule:: dependency_injector.containers :py:class:`DeclarativeCatalog` and :py:class:`DynamicCatalog` could be specialized for any kind of needs via declaring its subclasses. diff --git a/docs/images/internals.png b/docs/images/internals.png index bd91b3f5..35b99dcb 100644 Binary files a/docs/images/internals.png and b/docs/images/internals.png differ diff --git a/docs/index.rst b/docs/index.rst index 267aa8a8..7eefdb52 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -58,7 +58,7 @@ Contents introduction/index main/installation providers/index - catalogs/index + containers/index advanced_usage/index examples/index api/index diff --git a/docs/introduction/di_in_python.rst b/docs/introduction/di_in_python.rst index 378c9ccf..8411403f 100644 --- a/docs/introduction/di_in_python.rst +++ b/docs/introduction/di_in_python.rst @@ -119,9 +119,9 @@ Let's automate ``Engine`` into ``Car`` injections using *Dependency Injector*: .. note:: - ``Components`` from previous example is an inversion of control container. + ``Container`` from previous example is an inversion of control container. It contains a collection of component providers that could be injected into each other. - Assuming this, ``Components`` could be one and the only place, where + Assuming this, ``Container`` could be one and the only place, where application's structure is being managed on the high level. diff --git a/docs/introduction/structure.rst b/docs/introduction/structure.rst index b2a5391a..54f8d4d9 100644 --- a/docs/introduction/structure.rst +++ b/docs/introduction/structure.rst @@ -5,8 +5,8 @@ Structure of Dependency Injector :keywords: Python,DI,Dependency injection,IoC,Inversion of Control :description: This article describes "Dependency Injector" framework components and their interaction between each other. - Catalogs, providers and injections are the former - components of the framework. + Providers and containers are the former components of + the framework. Current section describes *Dependency Injector* main entities and their interaction between each other. @@ -15,11 +15,7 @@ interaction between each other. :width: 100% :align: center -There are 3 main entities: providers, injections and catalogs. - -+ All of the entities could be used in composition with each other or - separatelly. -+ Each of the entities could be extended via specialization. +There are 3 main entities: providers, containers. Providers ~~~~~~~~~ @@ -33,19 +29,21 @@ injected into each other. Providers could be overridden by another providers. Base class is - :py:class:`dependency_injector.providers.Provider`. -Injections +Providers could be: + ++ Injected into each other. ++ Overridden by each other. ++ Extended. + +Containers ~~~~~~~~~~ -Injections are instructions for making dependency injections -(there are several ways how they could be done). Injections are used -mostly by :py:class:`dependency_injector.providers.Factory` and -:py:class:`dependency_injector.providers.Singleton` providers, but -these are not only cases. Base class is - -:py:class:`dependency_injector.injections.Injection`. - -Catalogs -~~~~~~~~~ - -Catalogs are collections of providers. They are used for grouping +Containers are collections of providers. They are used for grouping of providers by some principles. Base class is - -:py:class:`dependency_injector.catalogs.DeclarativeCatalog`. +:py:class:`dependency_injector.containers.DeclarativeContainer`. + +Containers could be: + ++ Overridden by each other. ++ Copied from each other. ++ Extended. diff --git a/docs/main/changelog.rst b/docs/main/changelog.rst index 2ace8601..1a81bb25 100644 --- a/docs/main/changelog.rst +++ b/docs/main/changelog.rst @@ -23,8 +23,7 @@ Development version - ``Class`` - ``Config`` - Drop method injections. -- Drop catalog bundles. -- Drop catalog's ``name`` attribute. +- Replace catalogs with containers. - Drop backward compatibilities of 1.x. 1.17.0 diff --git a/docs/main/installation.rst b/docs/main/installation.rst index 1422383b..1a3e0cd1 100644 --- a/docs/main/installation.rst +++ b/docs/main/installation.rst @@ -12,13 +12,13 @@ framework can be installed from PyPi_: pip install dependency_injector # Installing particular version: - pip install dependency_injector==0.11.0 + pip install dependency_injector==2.0.0 Sources can be cloned from GitHub_: .. code-block:: bash - git clone https://github.com/ets-labs/dependency_injector.git + git clone https://github.com/ets-labs/python-dependency-injector.git Also all *Dependency Injector* releases can be downloaded from `GitHub releases page`_. @@ -30,7 +30,7 @@ Verification of currently installed version could be done using >>> from dependency_injector import VERSION >>> VERSION - '0.11.0' + '2.0.0' .. _PyPi: https://pypi.python.org/pypi/dependency_injector .. _GitHub: https://github.com/ets-labs/python-dependency-injector