Add configuration provider docs

Author: rmk135

docs/main/changelog.rst

@@ -14,6 +14,7 @@ Development version
 - Add ``Configuration.from_dict()`` method to load configuration from the dictionary.
 - Add ``Configuration.from_env()`` method to load configuration from the environment variable.
 - Add default value for ``name`` argument of ``Configuration`` provider.
+- Add documentation for ``Configuration`` provider.
 - Remove undocumented positional parameter of ``DependenciesContainer`` provider.
 
 3.17.1

docs/providers/configuration.rst

@@ -0,0 +1,88 @@
+Configuration providers
+-----------------------
+
+.. currentmodule:: dependency_injector.providers
+
+:py:class:`Configuration` provider provides configuration options to the other providers.
+
+.. literalinclude:: ../../examples/providers/configuration/configuration.py
+ :language: python
+ :emphasize-lines: 7,12-13,18-25
+ :linenos:
+
+It implements "use first, define later" principle.
+
+Loading from ``ini`` file
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:py:class:`Configuration` provider can load configuration from ``ini`` file using
+:py:meth:`Configuration.from_ini`:
+
+.. literalinclude:: ../../examples/providers/configuration/configuration_ini.py
+ :language: python
+ :lines: 6-
+ :emphasize-lines: 3
+ :linenos:
+
+where ``examples/providers/configuration/config.ini`` is:
+
+.. literalinclude:: ../../examples/providers/configuration/config.ini
+ :language: ini
+ :linenos:
+
+Loading from ``yaml`` file
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:py:class:`Configuration` provider can load configuration from ``yaml`` file using
+:py:meth:`Configuration.from_yaml`:
+
+.. literalinclude:: ../../examples/providers/configuration/configuration_yaml.py
+ :language: python
+ :lines: 6-
+ :emphasize-lines: 3
+ :linenos:
+
+where ``examples/providers/configuration/config.yml`` is:
+
+.. literalinclude:: ../../examples/providers/configuration/config.yml
+ :language: ini
+ :linenos:
+
+.. 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 from environment variable
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:py:class:`Configuration` provider can load configuration from environment variable using
+:py:meth:`Configuration.from_env`:
+
+.. literalinclude:: ../../examples/providers/configuration/configuration_env.py
+ :language: python
+ :lines: 13-21
+ :emphasize-lines: 3-5
+ :linenos:
+
+
+Loading from multiple sources
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:py:class:`Configuration` provider can load configuration from multiple sources. Loaded
+configuration is merged recursively over existing configuration.
+
+.. literalinclude:: ../../examples/providers/configuration/configuration_multiple.py
+ :language: python
+ :lines: 6-14
+ :emphasize-lines: 3-4
+ :linenos:
+
+where ``examples/providers/configuration/config.local.yml`` is:
+
+.. literalinclude:: ../../examples/providers/configuration/config.local.yml
+ :language: ini
+ :linenos:
+
+.. disqus::

docs/providers/index.rst

@@ -23,6 +23,7 @@ Providers package API docs - :py:mod:`dependency_injector.providers`
  coroutine
  object
  list
+ configuration
  dependency
  overriding
  custom

examples/providers/configuration/config.ini

@@ -0,0 +1,3 @@
+[aws]
+access_key_id = KEY
+secret_access_key = SECRET

examples/providers/configuration/config.local.yml

@@ -0,0 +1,3 @@
+aws:
+ access_key_id: "LOCAL-KEY"
+ secret_access_key: "LOCAL-SECRET"

examples/providers/configuration/config.yml

@@ -0,0 +1,3 @@
+aws:
+ access_key_id: "KEY"
+ secret_access_key: "SECRET"

examples/providers/configuration/configuration.py

@@ -0,0 +1,26 @@
+"""`Configuration` provider example."""
+
+import boto3
+from dependency_injector import providers
+
+
+config = providers.Configuration()
+
+s3_client_factory = providers.Factory(
+ boto3.client,
+ 's3',
+ aws_access_key_id=config.aws.access_key_id,
+ aws_secret_access_key=config.aws.secret_access_key,
+)
+
+
+if __name__ == '__main__':
+ config.from_dict(
+ {
+ 'aws': {
+ 'access_key_id': 'KEY',
+ 'secret_access_key': 'SECRET',
+ },
+ },
+ )
+ s3_client = s3_client_factory()

examples/providers/configuration/configuration_env.py

@@ -0,0 +1,21 @@
+"""`Configuration` provider values loading example."""
+
+import os
+
+from dependency_injector import providers
+
+
+# Emulate environment variables
+os.environ['AWS_ACCESS_KEY_ID'] = 'KEY'
+os.environ['AWS_SECRET_ACCESS_KEY'] = 'SECRET'
+
+
+config = providers.Configuration()
+
+config.aws.access_key_id.from_env('AWS_ACCESS_KEY_ID')
+config.aws.secret_access_key.from_env('AWS_SECRET_ACCESS_KEY')
+config.optional.from_env('UNDEFINED', 'default_value')
+
+assert config.aws.access_key_id() == 'KEY'
+assert config.aws.secret_access_key() == 'SECRET'
+assert config.optional() == 'default_value'

examples/providers/configuration/configuration_ini.py

@@ -0,0 +1,13 @@
+"""`Configuration` provider values loading example."""
+
+from dependency_injector import providers
+
+
+config = providers.Configuration()
+
+config.from_ini('examples/providers/configuration/config.ini')
+
+assert config() == {'aws': {'access_key_id': 'KEY', 'secret_access_key': 'SECRET'}}
+assert config.aws() == {'access_key_id': 'KEY', 'secret_access_key': 'SECRET'}
+assert config.aws.access_key_id() == 'KEY'
+assert config.aws.secret_access_key() == 'SECRET'

examples/providers/configuration/configuration_multiple.py

@@ -0,0 +1,14 @@
+"""`Configuration` provider values loading example."""
+
+from dependency_injector import providers
+
+
+config = providers.Configuration()
+
+config.from_yaml('examples/providers/configuration/config.yml')
+config.from_yaml('examples/providers/configuration/config.local.yml')
+
+assert config() == {'aws': {'access_key_id': 'LOCAL-KEY', 'secret_access_key': 'LOCAL-SECRET'}}
+assert config.aws() == {'access_key_id': 'LOCAL-KEY', 'secret_access_key': 'LOCAL-SECRET'}
+assert config.aws.access_key_id() == 'LOCAL-KEY'
+assert config.aws.secret_access_key() == 'LOCAL-SECRET'