mirror of
https://github.com/ets-labs/python-dependency-injector.git
synced 2025-05-03 23:43:44 +03:00
Make huge updates for docs (not atomic commit)
This commit is contained in:
parent
5d7622428f
commit
b86760e467
|
@ -1,6 +0,0 @@
|
||||||
``dependency_injector.catalogs``
|
|
||||||
--------------------------------
|
|
||||||
|
|
||||||
.. automodule:: dependency_injector.catalogs
|
|
||||||
:members:
|
|
||||||
:special-members:
|
|
6
docs/api/containers.rst
Normal file
6
docs/api/containers.rst
Normal file
|
@ -0,0 +1,6 @@
|
||||||
|
``dependency_injector.containers``
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
.. automodule:: dependency_injector.containers
|
||||||
|
:members:
|
||||||
|
:special-members:
|
|
@ -6,7 +6,6 @@ API Documentation
|
||||||
|
|
||||||
top_level
|
top_level
|
||||||
providers
|
providers
|
||||||
injections
|
containers
|
||||||
catalogs
|
|
||||||
utils
|
utils
|
||||||
errors
|
errors
|
||||||
|
|
|
@ -1,6 +0,0 @@
|
||||||
``dependency_injector.injections``
|
|
||||||
----------------------------------
|
|
||||||
|
|
||||||
.. automodule:: dependency_injector.injections
|
|
||||||
:members:
|
|
||||||
:inherited-members:
|
|
|
@ -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:
|
|
|
@ -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
|
|
55
docs/containers/declarative.rst
Normal file
55
docs/containers/declarative.rst
Normal file
|
@ -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:
|
|
@ -1,7 +1,7 @@
|
||||||
Dynamic catalogs
|
Dynamic catalogs
|
||||||
----------------
|
----------------
|
||||||
|
|
||||||
.. currentmodule:: dependency_injector.catalogs
|
.. currentmodule:: dependency_injector.containers
|
||||||
|
|
||||||
:py:class:`DynamicCatalog` is a catalog of providers that could be created in
|
: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
|
application's runtime. It should cover most of the cases when list of
|
28
docs/containers/index.rst
Normal file
28
docs/containers/index.rst
Normal file
|
@ -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
|
|
@ -1,7 +1,7 @@
|
||||||
Overriding of catalogs
|
Overriding of catalogs
|
||||||
----------------------
|
----------------------
|
||||||
|
|
||||||
.. currentmodule:: dependency_injector.catalogs
|
.. currentmodule:: dependency_injector.containers
|
||||||
|
|
||||||
Catalogs can be overridden by other catalogs. This, actually, means that
|
Catalogs can be overridden by other catalogs. This, actually, means that
|
||||||
all of the providers from overriding catalog will override providers with the
|
all of the providers from overriding catalog will override providers with the
|
|
@ -1,7 +1,7 @@
|
||||||
Specialization of catalogs
|
Specialization of catalogs
|
||||||
--------------------------
|
--------------------------
|
||||||
|
|
||||||
.. currentmodule:: dependency_injector.catalogs
|
.. currentmodule:: dependency_injector.containers
|
||||||
|
|
||||||
:py:class:`DeclarativeCatalog` and :py:class:`DynamicCatalog` could be
|
:py:class:`DeclarativeCatalog` and :py:class:`DynamicCatalog` could be
|
||||||
specialized for any kind of needs via declaring its subclasses.
|
specialized for any kind of needs via declaring its subclasses.
|
Binary file not shown.
Before Width: | Height: | Size: 29 KiB After Width: | Height: | Size: 8.2 KiB |
|
@ -58,7 +58,7 @@ Contents
|
||||||
introduction/index
|
introduction/index
|
||||||
main/installation
|
main/installation
|
||||||
providers/index
|
providers/index
|
||||||
catalogs/index
|
containers/index
|
||||||
advanced_usage/index
|
advanced_usage/index
|
||||||
examples/index
|
examples/index
|
||||||
api/index
|
api/index
|
||||||
|
|
|
@ -119,9 +119,9 @@ Let's automate ``Engine`` into ``Car`` injections using *Dependency Injector*:
|
||||||
|
|
||||||
.. note::
|
.. 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
|
It contains a collection of component providers that could be injected
|
||||||
into each other.
|
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.
|
application's structure is being managed on the high level.
|
||||||
|
|
|
@ -5,8 +5,8 @@ Structure of Dependency Injector
|
||||||
:keywords: Python,DI,Dependency injection,IoC,Inversion of Control
|
:keywords: Python,DI,Dependency injection,IoC,Inversion of Control
|
||||||
:description: This article describes "Dependency Injector" framework
|
:description: This article describes "Dependency Injector" framework
|
||||||
components and their interaction between each other.
|
components and their interaction between each other.
|
||||||
Catalogs, providers and injections are the former
|
Providers and containers are the former components of
|
||||||
components of the framework.
|
the framework.
|
||||||
|
|
||||||
Current section describes *Dependency Injector* main entities and their
|
Current section describes *Dependency Injector* main entities and their
|
||||||
interaction between each other.
|
interaction between each other.
|
||||||
|
@ -15,11 +15,7 @@ interaction between each other.
|
||||||
:width: 100%
|
:width: 100%
|
||||||
:align: center
|
:align: center
|
||||||
|
|
||||||
There are 3 main entities: providers, injections and catalogs.
|
There are 3 main entities: providers, containers.
|
||||||
|
|
||||||
+ All of the entities could be used in composition with each other or
|
|
||||||
separatelly.
|
|
||||||
+ Each of the entities could be extended via specialization.
|
|
||||||
|
|
||||||
Providers
|
Providers
|
||||||
~~~~~~~~~
|
~~~~~~~~~
|
||||||
|
@ -33,19 +29,21 @@ injected into each other. Providers could be overridden by another
|
||||||
providers. Base class is -
|
providers. Base class is -
|
||||||
:py:class:`dependency_injector.providers.Provider`.
|
: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
|
Containers are collections of providers. They are used for grouping
|
||||||
(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
|
|
||||||
of providers by some principles. Base class is -
|
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.
|
||||||
|
|
|
@ -23,8 +23,7 @@ Development version
|
||||||
- ``Class``
|
- ``Class``
|
||||||
- ``Config``
|
- ``Config``
|
||||||
- Drop method injections.
|
- Drop method injections.
|
||||||
- Drop catalog bundles.
|
- Replace catalogs with containers.
|
||||||
- Drop catalog's ``name`` attribute.
|
|
||||||
- Drop backward compatibilities of 1.x.
|
- Drop backward compatibilities of 1.x.
|
||||||
|
|
||||||
1.17.0
|
1.17.0
|
||||||
|
|
|
@ -12,13 +12,13 @@ framework can be installed from PyPi_:
|
||||||
pip install dependency_injector
|
pip install dependency_injector
|
||||||
|
|
||||||
# Installing particular version:
|
# Installing particular version:
|
||||||
pip install dependency_injector==0.11.0
|
pip install dependency_injector==2.0.0
|
||||||
|
|
||||||
Sources can be cloned from GitHub_:
|
Sources can be cloned from GitHub_:
|
||||||
|
|
||||||
.. code-block:: bash
|
.. 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
|
Also all *Dependency Injector* releases can be downloaded from
|
||||||
`GitHub releases page`_.
|
`GitHub releases page`_.
|
||||||
|
@ -30,7 +30,7 @@ Verification of currently installed version could be done using
|
||||||
|
|
||||||
>>> from dependency_injector import VERSION
|
>>> from dependency_injector import VERSION
|
||||||
>>> VERSION
|
>>> VERSION
|
||||||
'0.11.0'
|
'2.0.0'
|
||||||
|
|
||||||
.. _PyPi: https://pypi.python.org/pypi/dependency_injector
|
.. _PyPi: https://pypi.python.org/pypi/dependency_injector
|
||||||
.. _GitHub: https://github.com/ets-labs/python-dependency-injector
|
.. _GitHub: https://github.com/ets-labs/python-dependency-injector
|
||||||
|
|
Loading…
Reference in New Issue
Block a user