From 39c2ffbc136f0ec6d5824c1de286ab1b63b0e485 Mon Sep 17 00:00:00 2001
From: Roman Mogylatov <rmogilatov@gmail.com>
Date: Mon, 1 Feb 2021 09:29:26 -0500
Subject: [PATCH] Add docs and examples

---
 docs/containers/index.rst       |  1 +
 docs/containers/traversal.rst   | 33 +++++++++++++++++++++++
 docs/main/changelog.rst         |  1 +
 examples/containers/traverse.py | 48 +++++++++++++++++++++++++++++++++
 4 files changed, 83 insertions(+)
 create mode 100644 docs/containers/traversal.rst
 create mode 100644 examples/containers/traverse.py

diff --git a/docs/containers/index.rst b/docs/containers/index.rst
index c1abec16..ba28f0a8 100644
--- a/docs/containers/index.rst
+++ b/docs/containers/index.rst
@@ -23,3 +23,4 @@ Containers module API docs - :py:mod:`dependency_injector.containers`.
     dynamic
     specialization
     overriding
+    traversal
diff --git a/docs/containers/traversal.rst b/docs/containers/traversal.rst
new file mode 100644
index 00000000..ca80eb5e
--- /dev/null
+++ b/docs/containers/traversal.rst
@@ -0,0 +1,33 @@
+Container providers traversal
+-----------------------------
+
+To traverse container providers use method ``.traverse()``.
+
+.. literalinclude:: ../../examples/containers/traverse.py
+   :language: python
+   :lines: 3-
+   :emphasize-lines: 38
+
+Method ``.traverse()`` returns a generator. Traversal generator visits all container providers.
+This includes nested providers even if they are not present on the root level of the container.
+
+Traversal generator guarantees that each container provider will be visited only once.
+It can traverse cyclic provider graphs.
+
+Traversal generator does not guarantee traversal order.
+
+You can use ``types=[...]`` argument to filter providers. Traversal generator will only return
+providers matching specified types.
+
+.. code-block:: python
+   :emphasize-lines: 3
+
+   container = Container()
+
+   for provider in container.traverse(types=[providers.Resource]):
+       print(provider)
+
+    # <dependency_injector.providers.Resource(<function init_database at 0x10bd2cb80>) at 0x10d346b40>
+    # <dependency_injector.providers.Resource(<function init_cache at 0x10be373a0>) at 0x10d346bc0>
+
+.. disqus::
diff --git a/docs/main/changelog.rst b/docs/main/changelog.rst
index ed5df71a..3dee1fda 100644
--- a/docs/main/changelog.rst
+++ b/docs/main/changelog.rst
@@ -9,6 +9,7 @@ follows `Semantic versioning`_
 
 Development version
 -------------------
+- Add container providers traversal.
 - Add ``.provides`` attribute to ``Singleton`` and its subclasses.
   It's a consistency change to make ``Singleton`` match ``Callable``
   and ``Factory`` interfaces.
diff --git a/examples/containers/traverse.py b/examples/containers/traverse.py
new file mode 100644
index 00000000..3801aa0b
--- /dev/null
+++ b/examples/containers/traverse.py
@@ -0,0 +1,48 @@
+"""Container traversal example."""
+
+from dependency_injector import containers, providers
+
+
+def init_database():
+    return ...
+
+
+def init_cache():
+    return ...
+
+
+class Service:
+    def __init__(self, database, cache):
+        self.database = database
+        self.cache = cache
+
+
+class Container(containers.DeclarativeContainer):
+
+    config = providers.Configuration()
+
+    service = providers.Factory(
+        Service,
+        database=providers.Resource(
+            init_database,
+            url=config.database_url,
+        ),
+        cache=providers.Resource(
+            init_cache,
+            hosts=config.cache_hosts,
+        ),
+    )
+
+
+if __name__ == '__main__':
+    container = Container()
+
+    for provider in container.traverse():
+        print(provider)
+
+    # <dependency_injector.providers.Configuration('config') at 0x10d37d200>
+    # <dependency_injector.providers.Factory(<class '__main__.Service'>) at 0x10d3a2820>
+    # <dependency_injector.providers.Resource(<function init_database at 0x10bd2cb80>) at 0x10d346b40>
+    # <dependency_injector.providers.ConfigurationOption('config.cache_hosts') at 0x10d37d350>
+    # <dependency_injector.providers.Resource(<function init_cache at 0x10be373a0>) at 0x10d346bc0>
+    # <dependency_injector.providers.ConfigurationOption('config.database_url') at 0x10d37d2e0>