From 90748b4bb5255d20cc9cd0ee77a8c7e868ecb3cd Mon Sep 17 00:00:00 2001
From: Roman Mogylatov <rmogilatov@gmail.com>
Date: Wed, 3 Mar 2021 08:14:14 -0500
Subject: [PATCH] Add docs and example

---
 docs/providers/singleton.rst                  | 29 ++++++++++++++++---
 .../providers/singleton_resetting_with.py     | 27 +++++++++++++++++
 2 files changed, 52 insertions(+), 4 deletions(-)
 create mode 100644 examples/providers/singleton_resetting_with.py

diff --git a/docs/providers/singleton.rst b/docs/providers/singleton.rst
index ae5257f4..c0f2cc5d 100644
--- a/docs/providers/singleton.rst
+++ b/docs/providers/singleton.rst
@@ -20,13 +20,12 @@ returns it on the rest of the calls.
    :language: python
    :lines: 3-
 
-``Singleton`` provider handles an injection of the dependencies the same way like a
-:ref:`factory-provider`.
+``Singleton`` provider handles dependencies injection the same way like a :ref:`factory-provider`.
 
 .. note::
 
-   ``Singleton`` provider does dependencies injection only when creates the object. When the object
-   is created and memorized ``Singleton`` provider just returns it without applying the injections.
+   ``Singleton`` provider makes dependencies injection only when creates an object. When an object
+   is created and memorized ``Singleton`` provider just returns it without applying injections.
 
 Specialization of the provided type and abstract singletons work the same like like for the
 factories:
@@ -56,6 +55,21 @@ provider.
    Resetting of the memorized object clears the reference to it. Further object's lifecycle is
    managed by the garbage collector.
 
+You can use ``.reset()`` method with a context manager. Memorized instance will be reset on
+both entering and exiting a context.
+
+.. literalinclude:: ../../examples/providers/singleton_resetting_with.py
+   :language: python
+   :lines: 3-
+   :emphasize-lines: 18-19
+
+Context manager ``.reset()`` returns resetting singleton provider. You can use it for aliasing.
+
+.. code-block:: python
+
+   with container.user_service.reset() as user_service:
+       ...
+
 Method ``.reset()`` resets only current provider. To reset all dependent singleton providers
 call ``.full_reset()`` method.
 
@@ -64,6 +78,13 @@ call ``.full_reset()`` method.
    :lines: 3-
    :emphasize-lines: 25
 
+Method ``.full_reset()`` supports context manager interface like ``.reset()`` does.
+
+.. code-block:: python
+
+   with container.user_service.full_reset() as user_service:
+       ...
+
 See also: :ref:`reset-container-singletons`.
 
 Using singleton with multiple threads
diff --git a/examples/providers/singleton_resetting_with.py b/examples/providers/singleton_resetting_with.py
new file mode 100644
index 00000000..fe52996b
--- /dev/null
+++ b/examples/providers/singleton_resetting_with.py
@@ -0,0 +1,27 @@
+"""`Singleton` provider resetting context manager example."""
+
+from dependency_injector import containers, providers
+
+
+class UserService:
+    ...
+
+
+class Container(containers.DeclarativeContainer):
+
+    user_service = providers.Singleton(UserService)
+
+
+if __name__ == '__main__':
+    container = Container()
+
+    user_service1 = container.user_service()
+
+    with container.user_service.reset():
+        user_service2 = container.user_service()
+
+    user_service3 = container.user_service()
+
+    assert user_service1 is not user_service2
+    assert user_service2 is not user_service3
+    assert user_service3 is not user_service1