ets-labs/python-dependency-injector
1
1
Fork 0
mirror of https://github.com/ets-labs/python-dependency-injector.git synced 2025-03-19 01:22:13 +03:00
Code Issues Packages Projects Releases Wiki Activity

Make huge updates for docs (not atomic commit)

Browse Source
This commit is contained in:
Roman Mogilatov 2016-06-03 00:48:06 +03:00
parent 5d7622428f
commit b86760e467
17 changed files with 118 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/api/catalogs.rst
View File

@ -1,6 +0,0 @@
``dependency_injector.catalogs``
--------------------------------
.. automodule:: dependency_injector.catalogs
:members:
:special-members:

6
docs/api/containers.rst Normal file
View File

@ -0,0 +1,6 @@
``dependency_injector.containers``
--------------------------------
.. automodule:: dependency_injector.containers
:members:
:special-members:

3
docs/api/index.rst
View File

@ -6,7 +6,6 @@ API Documentation
top_level
providers
injections
catalogs
containers
utils
errors

6
docs/api/injections.rst
View File

@ -1,6 +0,0 @@
``dependency_injector.injections``
----------------------------------
.. automodule:: dependency_injector.injections
:members:
:inherited-members:

64
docs/catalogs/declarative.rst
View File

@ -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:

27
docs/catalogs/index.rst
View File

@ -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
View 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:

2
docs/catalogs/dynamic.rst → docs/containers/dynamic.rst
View File

@ -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

28
docs/containers/index.rst Normal file
View 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

2
docs/catalogs/overriding.rst → docs/containers/overriding.rst
View File

@ -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

2
docs/catalogs/specialization.rst → docs/containers/specialization.rst
View File

@ -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.

BIN
docs/images/internals.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 29 KiB

After

Width:  |  Height:  |  Size: 8.2 KiB

2
docs/index.rst
View File

@ -58,7 +58,7 @@ Contents
introduction/index
main/installation
providers/index
catalogs/index
containers/index
advanced_usage/index
examples/index
api/index

4
docs/introduction/di_in_python.rst
View File

@ -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.

38
docs/introduction/structure.rst
View File

@ -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.

3
docs/main/changelog.rst
View File

@ -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

6
docs/main/installation.rst
View File

@ -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