Add docs and examples

docs/containers/index.rst

@@ -23,3 +23,4 @@ Containers module API docs - :py:mod:`dependency_injector.containers`.
     dynamic
     specialization
     overriding
+    traversal

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::

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.

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>