Singleton reset context (#417)

* Add implementation and typing stubs * Make some refactoring and add tests * Pin ubuntu version to 18.04 * Add docs and example * Add changelog * Add container docs

Author: rmk135

.github/workflows/tests-and-linters.yml

@@ -6,7 +6,7 @@ jobs:
 
  test-on-different-versions:
  name: Run tests
- runs-on: ubuntu-latest
+ runs-on: ubuntu-18.04
  strategy:
  matrix:
  python-version: [2.7, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, pypy2, pypy3]

docs/containers/reset_singletons.rst

@@ -18,6 +18,14 @@ Method ``.reset_singletons()`` also resets singletons in sub-containers: ``provi
  :lines: 3-
  :emphasize-lines: 21
 
+You can use ``.reset_singletons()`` method with a context manager. Singletons will be reset on
+both entering and exiting a context.
+
+.. literalinclude:: ../../examples/containers/reset_singletons_with.py
+ :language: python
+ :lines: 3-
+ :emphasize-lines: 14-15
+
 See also: :ref:`singleton-provider`.
 
 .. disqus::

docs/main/changelog.rst

@@ -7,6 +7,12 @@ that were made in every particular version.
 From version 0.7.6 *Dependency Injector* framework strictly 
 follows `Semantic versioning`_
 
+Development version
+-------------------
+- Implement context manager interface for resetting a singleton provider.
+ See issue: `#413 <https://github.com/ets-labs/python-dependency-injector/issues/413>`_.
+ Thanks to `@Arrowana <https://github.com/Arrowana>`_ for suggesting the improvement.
+
 4.28.1
 ------
 - Fix async mode mode exception handling issue in ``Dependency`` provider.

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

examples/containers/reset_singletons_with.py

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

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