Merge branch 'release/3.37.0' into master

Author: rmk135

README.rst

@@ -52,7 +52,7 @@ What is ``Dependency Injector``?
 
 ``Dependency Injector`` is a dependency injection framework for Python.
 
-It helps you in implementing the dependency injection principle.
+It helps implementing the dependency injection principle.
 
 What is dependency injection?
 -----------------------------

docs/containers/index.rst

@@ -1,3 +1,5 @@
+.. _containers:
+
 Containers
 ==========
 

docs/images/internals.png

@@ -64,22 +64,49 @@ Dependency Injector --- Dependency injection framework for Python
 
 ``Dependency Injector`` is a dependency injection framework for Python.
 
-It stands on two principles:
+It helps implementing the dependency injection principle.
 
-- Explicit is better than implicit (PEP20).
-- Do no magic to your code.
+Key features of the ``Dependency Injector``:
 
-How does it different from the other frameworks?
+- **Providers**. Provides ``Factory``, ``Singleton``, ``Callable``, ``Coroutine``, ``Object``,
+ ``List``, ``Configuration``, ``Dependency`` and ``Selector`` providers that help assembling your
+ objects. See :ref:`providers`.
+- **Overriding**. Can override any provider by another provider on the fly. This helps in testing
+ and configuring dev / stage environment to replace API clients with stubs etc. See
+ :ref:`provider-overriding`.
+- **Configuration**. Read configuration from ``yaml`` & ``ini`` files, environment variables
+ and dictionaries. See :ref:`configuration-provider`.
+- **Containers**. Provides declarative and dynamic containers. See :ref:`containers`.
+- **Performance**. Fast. Written in ``Cython``.
+- **Maturity**. Mature and production-ready. Well-tested, documented and supported.
 
-- **No autowiring.** The framework does NOT do any autowiring / autoresolving of the dependencies. You need to specify everything explicitly. Because *"Explicit is better than implicit" (PEP20)*.
-- **Does not pollute your code.** Your application does NOT know and does NOT depend on the framework. No ``@inject`` decorators, annotations, patching or any other magic tricks.
+.. code-block:: python
 
-``Dependency Injector`` makes a simple contract with you:
+ from dependency_injector import containers, providers
 
-- You tell the framework how to assemble your objects
-- The framework does it for you
 
-The power of the ``Dependency Injector`` is in its simplicity and straightforwardness. It is a simple tool for the powerful concept.
+ class Container(containers.DeclarativeContainer):
+
+ config = providers.Configuration()
+
+ api_client = providers.Singleton(
+ ApiClient,
+ api_key=config.api_key,
+ timeout=config.timeout.as_int(),
+ )
+
+ service = providers.Factory(
+ Service,
+ api_client=api_client,
+ )
+
+
+ if __name__ == '__main__':
+ container = Container()
+ container.config.api_key.from_env('API_KEY')
+ container.config.timeout.from_env('TIMEOUT')
+
+ service = container.service()
 
 With the ``Dependency Injector`` you keep **application structure in one place**.
 This place is called **the container**. You use the container to manage all the components of the

docs/index.rst

@@ -17,4 +17,3 @@ dependency injection pattern, inversion of control principle and
  what_is_di
  di_in_python
  key_features
- structure

docs/introduction/index.rst

@@ -3,66 +3,33 @@ Key features
 
 .. meta::
  :keywords: Python,DI,Dependency injection,IoC,Inversion of Control
- :description: This article describes key features of "Dependency Injector" 
- framework. It also provides some cases and recommendations 
- about usage of "Dependency Injector" framework.
+ :description: This article describes key features of the Dependency Injector
+ framework.
 
+Key features of the ``Dependency Injector``:
 
-``Dependency Injector`` is a dependency injection framework for Python.
-It was designed to be a unified and developer-friendly tool that helps
-implement a dependency injection design pattern in a formal, pretty, and
-Pythonic way.
+- **Providers**. Provides ``Factory``, ``Singleton``, ``Callable``, ``Coroutine``, ``Object``,
+ ``List``, ``Configuration``, ``Dependency`` and ``Selector`` providers that help assembling your
+ objects. See :ref:`providers`.
+- **Overriding**. Can override any provider by another provider on the fly. This helps in testing
+ and configuring dev / stage environment to replace API clients with stubs etc. See
+ :ref:`provider-overriding`.
+- **Configuration**. Read configuration from ``yaml`` & ``ini`` files, environment variables
+ and dictionaries. See :ref:`configuration-provider`.
+- **Containers**. Provides declarative and dynamic containers. See :ref:`containers`.
+- **Performance**. Fast. Written in ``Cython``.
+- **Maturity**. Mature and production-ready. Well-tested, documented and supported.
 
-It stands on two principles:
+The framework stands on two principles:
 
-- Explicit is better than implicit (PEP20).
-- Do no magic to your code.
+- **Explicit is better than implicit (PEP20)**.
+- **Do not do any magic to your code**.
 
-How does it different from the other frameworks?
+How is that different from the other frameworks?
 
 - **No autowiring.** The framework does NOT do any autowiring / autoresolving of the dependencies. You need to specify everything explicitly. Because *"Explicit is better than implicit" (PEP20)*.
 - **Does not pollute your code.** Your application does NOT know and does NOT depend on the framework. No ``@inject`` decorators, annotations, patching or any other magic tricks.
 
-``Dependency Injector`` makes a simple contract with you:
-
-- You tell the framework how to build you code
-- The framework does it for you
-
-The power of the ``Dependency Injector`` is in its simplicity and straightforwardness. It is a simple tool for the powerful concept.
-
-The key features of the ``Dependency Injector`` framework are:
-
-+ Easy, smart, and Pythonic style.
-+ Does NOT pollute client code.
-+ Obvious and clear structure.
-+ Extensibility and flexibility.
-+ High performance.
-+ Memory efficiency.
-+ Thread safety.
-+ Documented.
-+ Semantically versioned.
-+ Distributed as pre-compiled wheels.
-
-``Dependency Injector`` containers and providers are implemented as C extension
-types using ``Cython``.
-
-``Dependency Injector`` framework can be used in the different application types:
-
-+ Web applications based on the ``Flask``, ``Django`` or any other web framework.
-+ Asynchronous applications ``asyncio``, ``aiohttp``, ``Tornado``, or ``Twisted``.
-+ Standalone frameworks and libraries.
-+ GUI applications.
-
-``Dependency Injector`` framework can be integrated on the different project
-stages:
-
-+ It can be used in the beginning of the development of a new application.
-+ It can be integrated into application that is on its active development stage.
-+ It can be used for refactoring of legacy application.
-
-Components of ``Dependency Injector`` framework could be used:
-
-+ In composition with each other.
-+ Independently from each other.
+The power of the framework is in a simplicity. ``Dependency Injector`` is a simple tool for the powerful concept.
 
 .. disqus::

docs/introduction/key_features.rst

@@ -7,6 +7,14 @@ that were made in every particular version.
 From version 0.7.6 *Dependency Injector* framework strictly 
 follows `Semantic versioning`_
 
+3.37.0
+------
+- Update index documentation page.
+- Make multiple improvements and fixes for the providers documentation.
+- Update "Key Features" documentation page.
+- Remove "Structure of Dependency Injector" documentation page.
+- Edit "Feedback" documentation page.
+
 3.36.0
 ------
 - Update providers overriding documentation and rework examples.

docs/introduction/structure.rst

@@ -1,12 +1,8 @@
 Feedback
 ========
 
-Feel free to post questions, bugs, feature requests, proposals etc. on
-*Dependency Injector* GitHub Issues:
-
- https://github.com/ets-labs/python-dependency-injector/issues
-
-Your feedback is quite important!
-
+To post a question, bug report, a feature proposal or get some help open a
+`Github Issue <https://github.com/ets-labs/python-dependency-injector/issues>`_ or leave a comment
+below.
 
 .. disqus::

docs/main/changelog.rst

@@ -1,3 +1,5 @@
+.. _configuration-provider:
+
 Configuration provider
 ======================
 
@@ -14,8 +16,8 @@ Configuration provider
 
 .. literalinclude:: ../../examples/providers/configuration/configuration.py
  :language: python
- :emphasize-lines: 4,9-10
- :lines: 4-14
+ :emphasize-lines: 7,12-13
+ :lines: 3-
 
 It implements the principle "use first, define later".
 
@@ -27,8 +29,8 @@ Loading from an INI file
 
 .. literalinclude:: ../../examples/providers/configuration/configuration_ini.py
  :language: python
- :lines: 3-5,6-
- :emphasize-lines: 6
+ :lines: 3-
+ :emphasize-lines: 12
 
 where ``examples/providers/configuration/config.ini`` is:
 
@@ -47,8 +49,8 @@ Loading from a YAML file
 
 .. literalinclude:: ../../examples/providers/configuration/configuration_yaml.py
  :language: python
- :lines: 3-5,6-
- :emphasize-lines: 6
+ :lines: 3-
+ :emphasize-lines: 12
 
 where ``examples/providers/configuration/config.yml`` is:
 
@@ -81,8 +83,8 @@ Loading from a dictionary
 
 .. literalinclude:: ../../examples/providers/configuration/configuration_dict.py
  :language: python
- :lines: 3-5,6-
- :emphasize-lines: 6-13
+ :lines: 3-
+ :emphasize-lines: 12-19
 
 Loading from an environment variable
 ------------------------------------
@@ -92,8 +94,8 @@ Loading from an environment variable
 
 .. literalinclude:: ../../examples/providers/configuration/configuration_env.py
  :language: python
- :lines: 5-7,13-21
- :emphasize-lines: 6-8
+ :lines: 3-
+ :emphasize-lines: 18-20
 
 Loading from the multiple sources
 ---------------------------------
@@ -103,8 +105,8 @@ configuration is merged recursively over the existing configuration.
 
 .. literalinclude:: ../../examples/providers/configuration/configuration_multiple.py
  :language: python
- :lines: 3-5,6-14
- :emphasize-lines: 6-7
+ :lines: 3-
+ :emphasize-lines: 12-13
 
 where ``examples/providers/configuration/config.local.yml`` is:
 
@@ -122,7 +124,7 @@ convert it into an ``int`` or a ``float``.
 .. literalinclude:: ../../examples/providers/configuration/configuration_type.py
  :language: python
  :lines: 3-
- :emphasize-lines: 17
+ :emphasize-lines: 19
 
 ``Configuration`` provider has next helper methods:
 
@@ -135,10 +137,27 @@ The last method ``.as_(callback, *args, **kwargs)`` helps to implement other con
 .. literalinclude:: ../../examples/providers/configuration/configuration_type_custom.py
  :language: python
  :lines: 3-
- :emphasize-lines: 16
+ :emphasize-lines: 18
 
 With the ``.as_(callback, *args, **kwargs)`` you can specify a function that will be called
 before the injection. The value from the config will be passed as a first argument. The returned
 value will be injected. Parameters ``*args`` and ``**kwargs`` are handled as any other injections.
 
+Injecting invariants
+--------------------
+
+You can inject invariant configuration options based on the value of the other configuration
+option.
+
+To use that you should provide the switch-value as an item of the configuration option that
+contains sections ``config.options[config.switch]``:
+
+- When the value of the ``config.switch`` is ``A``, the ``config.options.A`` is injected
+- When the value of the ``config.switch`` is ``B``, the ``config.options.B`` is injected
+
+.. literalinclude:: ../../examples/providers/configuration/configuration_itemselector.py
+ :language: python
+ :lines: 3-
+ :emphasize-lines: 15,30-31,38
+
 .. disqus::