From e758fa9d9599af34fd7c9c325324edaa0ceda596 Mon Sep 17 00:00:00 2001
From: Roman Mogylatov <rmogilatov@gmail.com>
Date: Sat, 16 Jan 2021 08:47:55 -0500
Subject: [PATCH] Add docs

---
 docs/providers/configuration.rst              | 22 ++++++++++++++
 .../configuration/configuration_required.py   | 30 +++++++++++++++++++
 .../configuration/configuration_strict.py     | 30 +++++++++++++++++++
 3 files changed, 82 insertions(+)
 create mode 100644 examples/providers/configuration/configuration_required.py
 create mode 100644 examples/providers/configuration/configuration_strict.py

diff --git a/docs/providers/configuration.rst b/docs/providers/configuration.rst
index 496cb69d..40d7735a 100644
--- a/docs/providers/configuration.rst
+++ b/docs/providers/configuration.rst
@@ -143,6 +143,28 @@ With the ``.as_(callback, *args, **kwargs)`` you can specify a function that wil
 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.
 
+Strict mode and required options
+--------------------------------
+
+You can use configuration provider in strict mode. In strict mode configuration provider raises an error
+on access to any undefined option.
+
+.. literalinclude:: ../../examples/providers/configuration/configuration_strict.py
+   :language: python
+   :lines: 3-
+   :emphasize-lines: 12
+
+You can also use ``.required()`` option modifier when making an injection.
+
+.. literalinclude:: ../../examples/providers/configuration/configuration_required.py
+   :language: python
+   :lines: 11-20
+   :emphasize-lines: 8-9
+
+.. note::
+
+   Modifier ``.required()`` should be specified before type modifier ``.as_*()``.
+
 Injecting invariants
 --------------------
 
diff --git a/examples/providers/configuration/configuration_required.py b/examples/providers/configuration/configuration_required.py
new file mode 100644
index 00000000..77a8d65e
--- /dev/null
+++ b/examples/providers/configuration/configuration_required.py
@@ -0,0 +1,30 @@
+"""`Configuration` provider strict mode example."""
+
+from dependency_injector import containers, providers, errors
+
+
+class ApiClient:
+    def __init__(self, api_key: str, timeout: int):
+        self.api_key = api_key
+        self.timeout = timeout
+
+
+class Container(containers.DeclarativeContainer):
+
+    config = providers.Configuration()
+
+    api_client_factory = providers.Factory(
+        ApiClient,
+        api_key=config.api.key.required(),
+        timeout=config.api.timeout.required().as_int(),
+    )
+
+
+if __name__ == '__main__':
+    container = Container()
+
+    try:
+        api_client = container.api_client_factory()
+    except errors.Error:
+        # raises error: Undefined configuration option "config.api.key"
+        ...
diff --git a/examples/providers/configuration/configuration_strict.py b/examples/providers/configuration/configuration_strict.py
new file mode 100644
index 00000000..3922f450
--- /dev/null
+++ b/examples/providers/configuration/configuration_strict.py
@@ -0,0 +1,30 @@
+"""`Configuration` provider strict mode example."""
+
+from dependency_injector import containers, providers, errors
+
+
+class ApiClient:
+    def __init__(self, api_key: str, timeout: int):
+        self.api_key = api_key
+        self.timeout = timeout
+
+
+class Container(containers.DeclarativeContainer):
+
+    config = providers.Configuration(strict=True)
+
+    api_client_factory = providers.Factory(
+        ApiClient,
+        api_key=config.api.key,
+        timeout=config.api.timeout.as_int(),
+    )
+
+
+if __name__ == '__main__':
+    container = Container()
+
+    try:
+        api_client = container.api_client_factory()
+    except errors.Error:
+        # raises error: Undefined configuration option "config.api.key"
+        ...