diff --git a/docs/main/changelog.rst b/docs/main/changelog.rst index 4c851ae8..78f867c6 100644 --- a/docs/main/changelog.rst +++ b/docs/main/changelog.rst @@ -10,7 +10,7 @@ follows `Semantic versioning`_ Development version ------------------- - Update documentation and rework examples for: ``Singleton``, ``Callable``, ``Coroutine``, - ``Object``, ``List`` providers. + ``Object``, ``List``, ``Configuration`` providers. 3.34.0 ------ diff --git a/docs/providers/configuration.rst b/docs/providers/configuration.rst index dfa20539..43fd3ee3 100644 --- a/docs/providers/configuration.rst +++ b/docs/providers/configuration.rst @@ -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 @@ -10,13 +17,13 @@ Configuration providers :emphasize-lines: 4,9-10 :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 -:py:meth:`Configuration.from_ini`: +``Configuration`` provider can load configuration from an ``ini`` file using the +:py:meth:`Configuration.from_ini` method: .. literalinclude:: ../../examples/providers/configuration/configuration_ini.py :language: python @@ -28,15 +35,15 @@ where ``examples/providers/configuration/config.ini`` is: .. literalinclude:: ../../examples/providers/configuration/config.ini :language: ini -:py:meth:`Configuration.from_ini` supports environment variables interpolation. Use -``${ENV_NAME}`` format in the configuration file to substitute value of environment +:py:meth:`Configuration.from_ini` method supports environment variables interpolation. Use +``${ENV_NAME}`` format in the configuration file to substitute value of the environment variable ``ENV_NAME``. -Loading from ``yaml`` file -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Loading from a YAML file +~~~~~~~~~~~~~~~~~~~~~~~~ -:py:class:`Configuration` provider can load configuration from ``yaml`` file using -:py:meth:`Configuration.from_yaml`: +``Configuration`` provider can load configuration from a ``yaml`` file using the +:py:meth:`Configuration.from_yaml` method: .. literalinclude:: ../../examples/providers/configuration/configuration_yaml.py :language: python @@ -48,43 +55,51 @@ where ``examples/providers/configuration/config.yml`` is: .. literalinclude:: ../../examples/providers/configuration/config.yml :language: ini -:py:meth:`Configuration.from_yaml` supports environment variables interpolation. Use -``${ENV_NAME}`` format in the configuration file to substitute value of environment +:py:meth:`Configuration.from_yaml` method supports environment variables interpolation. Use +``${ENV_NAME}`` format in the configuration file to substitute value of the environment variable ``ENV_NAME``. .. note:: - Loading configuration from yaml requires ``PyYAML`` package. You can install - `Dependency Injector` with extras ``pip install dependency-injector[yaml]`` or install - ``PyYAML`` separately ``pip install pyyaml``. + Loading of a yaml configuration requires ``PyYAML`` package. -Loading from ``dict`` -~~~~~~~~~~~~~~~~~~~~~ + You can install the ``Dependency Injector`` with an extra dependency:: -:py:class:`Configuration` provider can load configuration from Python ``dict`` using -:py:meth:`Configuration.from_dict`: + pip install dependency-injector[yaml] + + 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 :language: python :lines: 3-5,6- :emphasize-lines: 6-13 -Loading from environment variable -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Loading from an environment variable +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:py:class:`Configuration` provider can load configuration from environment variable using -:py:meth:`Configuration.from_env`: +``Configuration`` provider can load configuration from an environment variable using the +:py:meth:`Configuration.from_env` method: .. literalinclude:: ../../examples/providers/configuration/configuration_env.py :language: python :lines: 5-7,13-21 :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 is merged recursively over existing configuration. +``Configuration`` provider can load configuration from the multiple sources. Loaded +configuration is merged recursively over the existing configuration. .. literalinclude:: ../../examples/providers/configuration/configuration_multiple.py :language: python @@ -96,12 +111,12 @@ where ``examples/providers/configuration/config.local.yml`` is: .. literalinclude:: ../../examples/providers/configuration/config.local.yml :language: ini -Specifying value type -~~~~~~~~~~~~~~~~~~~~~ +Specifying the value type +~~~~~~~~~~~~~~~~~~~~~~~~~ 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``. .. literalinclude:: ../../examples/providers/configuration/configuration_type.py @@ -109,20 +124,20 @@ convert it into an ``int`` or a ``float``. :lines: 3- :emphasize-lines: 17 -:py:class:`Configuration` provider has next helper methods: +``Configuration`` provider has next helper methods: - ``.as_int()`` - ``.as_float()`` - ``.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 :language: python :lines: 3- :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 value will be injected. Parameters ``*args`` and ``**kwargs`` are handled as any other injections.