ets-labs/python-dependency-injector
1
1
Fork 0
mirror of https://github.com/ets-labs/python-dependency-injector.git synced 2025-11-04 09:57:37 +03:00
Code Issues Packages Projects Releases Wiki Activity

Edit configuration provider docs

Browse Source
This commit is contained in:
Roman Mogylatov 2020-09-01 17:30:17 -04:00
parent a5e5b4b193
commit 5e5092c49f
2 changed files with 52 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/main/changelog.rst
View File

@ -10,7 +10,7 @@ follows `Semantic versioning`_
Development version Development version
------------------- -------------------
- Update documentation and rework examples for: ``Singleton``, ``Callable``, ``Coroutine``, - Update documentation and rework examples for: ``Singleton``, ``Callable``, ``Coroutine``,
``Object``, ``List`` providers. ``Object``, ``List``, ``Configuration`` providers.
3.34.0 3.34.0
------ ------

87
docs/providers/configuration.rst
View File

@ -1,5 +1,12 @@
Configuration providers Configuration provider
----------------------- ----------------------
.. meta::
:keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Configuration,Injection,
Option,Ini,Json,Yaml,Dict,Environment Variable,Load,Read,Get
:description: Configuration provides configuration options to the other providers. This page
demonstrates how to use Configuration provider to inject the dependencies, load
a configuration from an ini or yaml file, dictionary or an environment variable.
.. currentmodule:: dependency_injector.providers .. currentmodule:: dependency_injector.providers
@ -10,13 +17,13 @@ Configuration providers
:emphasize-lines: 4,9-10 :emphasize-lines: 4,9-10
:lines: 4-14 :lines: 4-14
It implements "use first, define later" principle. It implements the principle "use first, define later".
Loading from ``ini`` file Loading from an INI file
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
:py:class:`Configuration` provider can load configuration from ``ini`` file using ``Configuration`` provider can load configuration from an ``ini`` file using the
:py:meth:`Configuration.from_ini`: :py:meth:`Configuration.from_ini` method:
.. literalinclude:: ../../examples/providers/configuration/configuration_ini.py .. literalinclude:: ../../examples/providers/configuration/configuration_ini.py
:language: python :language: python
@ -28,15 +35,15 @@ where ``examples/providers/configuration/config.ini`` is:
.. literalinclude:: ../../examples/providers/configuration/config.ini .. literalinclude:: ../../examples/providers/configuration/config.ini
:language: ini :language: ini
:py:meth:`Configuration.from_ini` supports environment variables interpolation. Use :py:meth:`Configuration.from_ini` method supports environment variables interpolation. Use
``${ENV_NAME}`` format in the configuration file to substitute value of environment ``${ENV_NAME}`` format in the configuration file to substitute value of the environment
variable ``ENV_NAME``. variable ``ENV_NAME``.
Loading from ``yaml`` file Loading from a YAML file
~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
:py:class:`Configuration` provider can load configuration from ``yaml`` file using ``Configuration`` provider can load configuration from a ``yaml`` file using the
:py:meth:`Configuration.from_yaml`: :py:meth:`Configuration.from_yaml` method:
.. literalinclude:: ../../examples/providers/configuration/configuration_yaml.py .. literalinclude:: ../../examples/providers/configuration/configuration_yaml.py
:language: python :language: python
@ -48,43 +55,51 @@ where ``examples/providers/configuration/config.yml`` is:
.. literalinclude:: ../../examples/providers/configuration/config.yml .. literalinclude:: ../../examples/providers/configuration/config.yml
:language: ini :language: ini
:py:meth:`Configuration.from_yaml` supports environment variables interpolation. Use :py:meth:`Configuration.from_yaml` method supports environment variables interpolation. Use
``${ENV_NAME}`` format in the configuration file to substitute value of environment ``${ENV_NAME}`` format in the configuration file to substitute value of the environment
variable ``ENV_NAME``. variable ``ENV_NAME``.
.. note:: .. note::
Loading configuration from yaml requires ``PyYAML`` package. You can install Loading of a yaml configuration requires ``PyYAML`` package.
`Dependency Injector` with extras ``pip install dependency-injector[yaml]`` or install
``PyYAML`` separately ``pip install pyyaml``.
Loading from ``dict`` You can install the ``Dependency Injector`` with an extra dependency::
~~~~~~~~~~~~~~~~~~~~~
:py:class:`Configuration` provider can load configuration from Python ``dict`` using pip install dependency-injector[yaml]
:py:meth:`Configuration.from_dict`:
or install ``PyYAML`` directly::
pip install pyyaml
*Don't forget to mirror the changes in the requirements file.*
Loading from a dictionary
~~~~~~~~~~~~~~~~~~~~~~~~~
``Configuration`` provider can load configuration from a Python ``dict`` using the
:py:meth:`Configuration.from_dict` method:
.. literalinclude:: ../../examples/providers/configuration/configuration_dict.py .. literalinclude:: ../../examples/providers/configuration/configuration_dict.py
:language: python :language: python
:lines: 3-5,6- :lines: 3-5,6-
:emphasize-lines: 6-13 :emphasize-lines: 6-13
Loading from environment variable Loading from an environment variable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:py:class:`Configuration` provider can load configuration from environment variable using ``Configuration`` provider can load configuration from an environment variable using the
:py:meth:`Configuration.from_env`: :py:meth:`Configuration.from_env` method:
.. literalinclude:: ../../examples/providers/configuration/configuration_env.py .. literalinclude:: ../../examples/providers/configuration/configuration_env.py
:language: python :language: python
:lines: 5-7,13-21 :lines: 5-7,13-21
:emphasize-lines: 6-8 :emphasize-lines: 6-8
Loading from multiple sources Loading from the multiple sources
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:py:class:`Configuration` provider can load configuration from multiple sources. Loaded ``Configuration`` provider can load configuration from the multiple sources. Loaded
configuration is merged recursively over existing configuration. configuration is merged recursively over the existing configuration.
.. literalinclude:: ../../examples/providers/configuration/configuration_multiple.py .. literalinclude:: ../../examples/providers/configuration/configuration_multiple.py
:language: python :language: python
@ -96,12 +111,12 @@ where ``examples/providers/configuration/config.local.yml`` is:
.. literalinclude:: ../../examples/providers/configuration/config.local.yml .. literalinclude:: ../../examples/providers/configuration/config.local.yml
:language: ini :language: ini
Specifying value type Specifying the value type
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
You can specify the type of the injected configuration value explicitly. You can specify the type of the injected configuration value explicitly.
This helps when you read the value from the ini file or the environment variable and need to This helps when you read the value from an ini file or an environment variable and need to
convert it into an ``int`` or a ``float``. convert it into an ``int`` or a ``float``.
.. literalinclude:: ../../examples/providers/configuration/configuration_type.py .. literalinclude:: ../../examples/providers/configuration/configuration_type.py
@ -109,20 +124,20 @@ convert it into an ``int`` or a ``float``.
:lines: 3- :lines: 3-
:emphasize-lines: 17 :emphasize-lines: 17
:py:class:`Configuration` provider has next helper methods: ``Configuration`` provider has next helper methods:
- ``.as_int()`` - ``.as_int()``
- ``.as_float()`` - ``.as_float()``
- ``.as_(callback, *args, **kwargs)`` - ``.as_(callback, *args, **kwargs)``
The last method ``.as_(callback, *args, **kwargs)`` helps to implement a other conversions. The last method ``.as_(callback, *args, **kwargs)`` helps to implement other conversions.
.. literalinclude:: ../../examples/providers/configuration/configuration_type_custom.py .. literalinclude:: ../../examples/providers/configuration/configuration_type_custom.py
:language: python :language: python
:lines: 3- :lines: 3-
:emphasize-lines: 16 :emphasize-lines: 16
With the ``.as_(callback, *args, **kwargs)`` you can specify the function that will be called 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 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. value will be injected. Parameters ``*args`` and ``**kwargs`` are handled as any other injections.