From a0a3da8f726e054b2ec5ddcb32de45d76dc24fd5 Mon Sep 17 00:00:00 2001
From: Roman Mogylatov <rmogilatov@gmail.com>
Date: Mon, 29 Jun 2020 16:32:48 -0400
Subject: [PATCH] Improve List and Configuration provider docs

---
 docs/providers/configuration.rst              | 32 +++++++++++++------
 docs/providers/list.rst                       |  6 ++--
 .../configuration/configuration_dict.py       | 20 ++++++++++++
 3 files changed, 46 insertions(+), 12 deletions(-)
 create mode 100644 examples/providers/configuration/configuration_dict.py

diff --git a/docs/providers/configuration.rst b/docs/providers/configuration.rst
index 91e9d1de..045a0e22 100644
--- a/docs/providers/configuration.rst
+++ b/docs/providers/configuration.rst
@@ -7,7 +7,8 @@ Configuration providers
 
 .. literalinclude:: ../../examples/providers/configuration/configuration.py
    :language: python
-   :emphasize-lines: 7,12-13,18-25
+   :emphasize-lines: 4,9-10
+   :lines: 4-14
    :linenos:
 
 It implements "use first, define later" principle.
@@ -20,8 +21,8 @@ Loading from ``ini`` file
 
 .. literalinclude:: ../../examples/providers/configuration/configuration_ini.py
    :language: python
-   :lines: 6-
-   :emphasize-lines: 3
+   :lines: 3-5,6-
+   :emphasize-lines: 6
    :linenos:
 
 where ``examples/providers/configuration/config.ini`` is:
@@ -42,8 +43,8 @@ Loading from ``yaml`` file
 
 .. literalinclude:: ../../examples/providers/configuration/configuration_yaml.py
    :language: python
-   :lines: 6-
-   :emphasize-lines: 3
+   :lines: 3-5,6-
+   :emphasize-lines: 6
    :linenos:
 
 where ``examples/providers/configuration/config.yml`` is:
@@ -62,6 +63,18 @@ variable ``ENV_NAME``.
     `Dependency Injector` with extras ``pip install dependency-injector[yaml]`` or install
     ``PyYAML`` separately  ``pip install pyyaml``.
 
+Loading from ``dict``
+~~~~~~~~~~~~~~~~~~~~~
+
+:py:class:`Configuration` provider can load configuration from Python ``dict`` using
+:py:meth:`Configuration.from_dict`:
+
+.. literalinclude:: ../../examples/providers/configuration/configuration_dict.py
+   :language: python
+   :lines: 3-5,6-
+   :emphasize-lines: 6-13
+   :linenos:
+
 Loading from environment variable
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -70,11 +83,10 @@ Loading from environment variable
 
 .. literalinclude:: ../../examples/providers/configuration/configuration_env.py
    :language: python
-   :lines: 13-21
-   :emphasize-lines: 3-5
+   :lines: 5-7,13-21
+   :emphasize-lines: 6-8
    :linenos:
 
-
 Loading from multiple sources
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -83,8 +95,8 @@ configuration is merged recursively over existing configuration.
 
 .. literalinclude:: ../../examples/providers/configuration/configuration_multiple.py
    :language: python
-   :lines: 6-14
-   :emphasize-lines: 3-4
+   :lines: 3-5,6-14
+   :emphasize-lines: 6-7
    :linenos:
 
 where ``examples/providers/configuration/config.local.yml`` is:
diff --git a/docs/providers/list.rst b/docs/providers/list.rst
index 0c319622..58f89f44 100644
--- a/docs/providers/list.rst
+++ b/docs/providers/list.rst
@@ -7,7 +7,8 @@ List providers
 
 .. literalinclude:: ../../examples/providers/list.py
    :language: python
-   :lines: 23-29
+   :emphasize-lines: 6-9
+   :lines: 6-8, 23-29
    :linenos:
 
 :py:class:`List` provider is needed for injecting a list of dependencies. It handles
@@ -24,7 +25,8 @@ Full example:
 
 .. literalinclude:: ../../examples/providers/list.py
    :language: python
-   :emphasize-lines: 23-29
+   :emphasize-lines: 23-26
+   :lines: 3-
    :linenos:
 
 .. note::
diff --git a/examples/providers/configuration/configuration_dict.py b/examples/providers/configuration/configuration_dict.py
new file mode 100644
index 00000000..275c2b12
--- /dev/null
+++ b/examples/providers/configuration/configuration_dict.py
@@ -0,0 +1,20 @@
+"""`Configuration` provider values loading example."""
+
+from dependency_injector import providers
+
+
+config = providers.Configuration()
+
+config.from_dict(
+    {
+        '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', 'secret_access_key': 'SECRET'}
+assert config.aws.access_key_id() == 'KEY'
+assert config.aws.secret_access_key() == 'SECRET'