Add docs and example

docs/providers/singleton.rst

@@ -54,6 +54,14 @@ provider.
    Resetting of the memorized object clears the reference to it. Further object's lifecycle is
    managed by the garbage collector.
 
+Method ``.reset()`` resets only current provider. To reset all dependent singleton providers
+call ``.full_reset()`` method.
+
+.. literalinclude:: ../../examples/providers/singleton_full_resetting.py
+   :language: python
+   :lines: 3-
+   :emphasize-lines: 25
+
 Using singleton with multiple threads
 -------------------------------------
 

examples/providers/singleton_full_resetting.py

@@ -0,0 +1,31 @@
+"""`Singleton` provider full resetting example."""
+
+from dependency_injector import containers, providers
+
+
+class Database:
+    ...
+
+
+class UserService:
+    def __init__(self, db: Database):
+        self.db = db
+
+
+class Container(containers.DeclarativeContainer):
+
+    database = providers.Singleton(Database)
+
+    user_service = providers.Singleton(UserService, db=database)
+
+
+if __name__ == '__main__':
+    container = Container()
+
+    user_service1 = container.user_service()
+
+    container.user_service.full_reset()
+
+    user_service2 = container.user_service()
+    assert user_service2 is not user_service1
+    assert user_service2.db is not user_service1.db

examples/providers/singleton_resetting.py

@@ -9,15 +9,15 @@ class UserService:
 
 class Container(containers.DeclarativeContainer):
 
-    user_service_provider = providers.Singleton(UserService)
+    user_service = providers.Singleton(UserService)
 
 
 if __name__ == '__main__':
     container = Container()
 
-    user_service1 = container.user_service_provider()
+    user_service1 = container.user_service()
 
-    container.user_service_provider.reset()
+    container.user_service.reset()
 
-    user_service2 = container.user_service_provider()
+    user_service2 = container.user_service()
     assert user_service2 is not user_service1