Add examples and docs

docs/containers/index.rst

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

docs/containers/reset_singletons.rst

@@ -0,0 +1,19 @@
+Reset container singletons
+--------------------------
+
+To reset all container singletons use method ``.reset_singletons()``.
+
+.. literalinclude:: ../../examples/containers/reset_singletons.py
+   :language: python
+   :lines: 3-
+   :emphasize-lines: 16
+
+Method ``.reset_singletons()`` also resets singletons in sub-containers: ``providers.Container`` and
+``providers.DependenciesContainer.``
+
+.. literalinclude:: ../../examples/containers/reset_singletons_subcontainers.py
+   :language: python
+   :lines: 3-
+   :emphasize-lines: 21
+
+.. disqus::

examples/containers/reset_singletons.py

@@ -0,0 +1,21 @@
+"""Container reset singletons example."""
+
+from dependency_injector import containers, providers
+
+
+class Container(containers.DeclarativeContainer):
+
+    service1 = providers.Singleton(object)
+    service2 = providers.Singleton(object)
+
+
+if __name__ == '__main__':
+    container = Container()
+
+    service1 = container.service1()
+    service2 = container.service2()
+
+    container.reset_singletons()
+
+    assert service1 is not container.service1()
+    assert service2 is not container.service2()

examples/containers/reset_singletons_subcontainers.py

@@ -0,0 +1,26 @@
+"""Container reset singletons in subcontainer example."""
+
+from dependency_injector import containers, providers
+
+
+class SubContainer(containers.DeclarativeContainer):
+
+    service = providers.Singleton(object)
+
+
+class Container(containers.DeclarativeContainer):
+
+    service = providers.Singleton(object)
+    sub = providers.Container(SubContainer)
+
+
+if __name__ == '__main__':
+    container = Container()
+
+    service1 = container.service()
+    service2 = container.sub().service()
+
+    container.reset_singletons()
+
+    assert service1 is not container.service()
+    assert service2 is not container.sub().service()