Add configuration provider docs

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'

examples/providers/configuration/configuration_yaml.py

@@ -0,0 +1,13 @@
+"""`Configuration` provider values loading example."""
+
+from dependency_injector import providers
+
+
+config = providers.Configuration()
+
+config.from_yaml('examples/providers/configuration/config.yml')
+
+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'

src/dependency_injector/providers.pyx

@@ -1002,10 +1002,7 @@ cdef class CoroutineDelegate(Delegate):
 
 
 cdef class Configuration(Object):
-    """Configuration provider.
-
-    Configuration provider helps with implementing late static binding of
-    configuration options - use first, define later.
+    """Configuration provider provides configuration options to the other providers.
 
     .. code-block:: python
 
@@ -1014,8 +1011,14 @@ cdef class Configuration(Object):
         print(config.section1.option1())  # None
         print(config.section1.option2())  # None
 
-        config.override({'section1': {'option1': 1,
-                                      'option2': 2}})
+        config.from_dict(
+            {
+                'section1': {
+                    'option1': 1,
+                    'option2': 2,
+                },
+            },
+        )
 
         print(config.section1.option1())  # 1
         print(config.section1.option2())  # 2
@@ -1168,7 +1171,7 @@ cdef class Configuration(Object):
     def from_ini(self, filepath):
         """Load configuration from the ini file.
 
-        Loaded configuration is merged recursively over current configuration.
+        Loaded configuration is merged recursively over existing configuration.
 
         :param filepath: Path to the configuration file.
         :type filepath: str
@@ -1190,7 +1193,7 @@ cdef class Configuration(Object):
     def from_yaml(self, filepath):
         """Load configuration from the yaml file.
 
-        Loaded configuration is merged recursively over current configuration.
+        Loaded configuration is merged recursively over existing configuration.
 
         :param filepath: Path to the configuration file.
         :type filepath: str
@@ -1215,7 +1218,7 @@ cdef class Configuration(Object):
     def from_dict(self, options):
         """Load configuration from the dictionary.
 
-        Loaded configuration is merged recursively over current configuration.
+        Loaded configuration is merged recursively over existing configuration.
 
         :param options: Configuration options.
         :type options: dict