Teach unstub how to do partial unstubbing

E.g. support:

```
        unstub(os.path.exists)
        unstub("os.path.exists")
        unstub(cat.meow)
```

Author: kaste

docs/walk-through.rst

@@ -52,7 +52,7 @@ When patching, you **MUST** **not** forget to :func:`unstub` of course! You can
 ::
 
     from mockito import unstub
-    unstub()  # restore os.path module
+    unstub()  # restore all patched/stubbed objects
 
 Usually you do this unconditionally in your `teardown` function. If you're using `pytest`, you could define a fixture instead
 

mockito/mock_registry.py

@@ -88,13 +88,14 @@ def mock_for(self, obj: object) -> Mock | None:
     def obj_for(self, mock: Mock) -> object | None:
         return self.mocks.lookup(mock)
 
-    def unstub(self, obj: object) -> None:
+    def unstub(self, obj: object) -> bool:
         try:
             mock = self.mocks.pop(obj)
         except KeyError:
-            pass
+            return False
         else:
             mock.unstub()
+            return True
 
     def unstub_mock(self, mock: Mock) -> None:
         self.mocks.pop_value(mock)

mockito/mocking.py

@@ -540,6 +540,24 @@ def forget_stubbed_invocation(
 
         mock_registry.unstub(self.mocked_obj)
 
+    def unstub_method(self, method_name: str) -> None:
+        invocations = [
+            invoc
+            for invoc in self.stubbed_invocations
+            if invoc.method_name == method_name
+        ]
+        if not invocations:
+            return
+
+        for invoc in invocations:
+            invoc.forget_self()
+
+        self.invocations = [
+            invocation
+            for invocation in self.invocations
+            if invocation.method_name != method_name
+        ]
+
     def unstub(self) -> None:
         while self._methods_to_unstub:
             _, patch = self._methods_to_unstub.popitem()

mockito/mockito.py

@@ -448,6 +448,15 @@ def unstub(*objs):
     If you don't pass in any argument, *all* registered mocks and
     patched modules, classes etc. will be unstubbed.
 
+    You can also unstub a single method/function target, e.g.::
+
+        unstub(os.path.exists)
+        unstub("os.path.exists")
+        unstub(cat.meow)
+
+    In these cases only that one attribute is restored, while other stubs on
+    the same object stay active.
+
     Note that additionally, the underlying registry will be cleaned.
     After an `unstub` you can't :func:`verify` anymore because all
     interactions will be forgotten.
@@ -457,13 +466,55 @@ def unstub(*objs):
         for obj in objs:
             if isinstance(obj, str):
                 obj = get_obj(obj)
-            mock_registry.unstub(obj)
-            patcher.unstub_matching(obj)
+
+            # mock_registry.unstub(obj)
+            # patcher.unstub_matching(obj)
+            if (
+                mock_registry.unstub(obj)
+                or patcher.unstub_matching(obj)
+            ):
+                return
+
+            resolved_target = _resolve_unstub_attr_target(obj)
+            if resolved_target is None:
+                continue
+
+            host, attr_name = resolved_target
+            host_mock = mock_registry.mock_for(host)
+            if host_mock is not None:
+                host_mock.unstub_method(attr_name)
     else:
         mock_registry.unstub_all()
         patcher.unstub_all()
 
 
+def _resolve_unstub_attr_target(target):
+    if not callable(target):
+        return None
+
+    host = getattr(target, "__self__", None)
+    attr_name = getattr(target, "__name__", None)
+    if host is not None and attr_name is not None:
+        return host, attr_name
+
+    target_function = _unwrap_unstub_target(target)
+    for theMock in mock_registry.get_registered_mocks():
+        for method_name, patch in theMock._methods_to_unstub.items():
+            replacement = getattr(patch, "replacement", None)
+            if _unwrap_unstub_target(replacement) is target_function:
+                return theMock.mocked_obj, method_name
+
+    return None
+
+
+
+def _unwrap_unstub_target(target):
+    if isinstance(target, (staticmethod, classmethod)):
+        return target.__func__
+
+    return getattr(target, "__func__", target)
+
+
 def forget_invocations(*objs):
     """Forget all invocations of given objs.
 

mockito/patching.py

@@ -68,14 +68,16 @@ def patch_dictionary(
         self._register_patch(dict_patch)
         return dict_patch
 
-    def unstub_matching(self, obj: object) -> None:
+    def unstub_matching(self, obj: object) -> bool:
         matching = [
             patch for patch in self._patches
             if patch.matches_unstub_target(obj)
         ]
         for patch in reversed(matching):
             patch.restore_and_unregister()
 
+        return bool(matching)
+
     def unstub_all(self) -> None:
         for patch in reversed(self._patches.copy()):
             patch.restore_and_unregister()

tests/modulefunctions_test.py

@@ -45,6 +45,24 @@ def testUnstubsByDottedPath(self):
 
         self.assertEqual(False, os.path.exists("test"))
 
+    def testCanUnstubSingleFunctionByFunctionTarget(self):
+        when(os.path).exists("test").thenReturn(True)
+        when(os.path).dirname(any(str)).thenReturn("mocked")
+
+        unstub(os.path.exists)
+
+        self.assertEqual(False, os.path.exists("test"))
+        self.assertEqual("mocked", os.path.dirname("/tmp/file.txt"))
+
+    def testCanUnstubSingleFunctionByDottedFunctionPath(self):
+        when(os.path).exists("test").thenReturn(True)
+        when(os.path).dirname(any(str)).thenReturn("mocked")
+
+        unstub("os.path.exists")
+
+        self.assertEqual(False, os.path.exists("test"))
+        self.assertEqual("mocked", os.path.dirname("/tmp/file.txt"))
+
     def testStubs(self):
         when(os.path).exists("test").thenReturn(True)
 

tests/staticmethods_test.py

@@ -50,6 +50,15 @@ def testUnstubs(self):
         unstub()
         self.assertEqual("woof", Dog.bark())
 
+    def testCanUnstubSingleStaticmethodByFunctionTarget(self):
+        when(Dog).bark().thenReturn("miau")
+        when(Dog).barkHardly(1, 2).thenReturn("arf")
+
+        unstub(Dog.bark)
+
+        self.assertEqual("woof", Dog.bark())
+        self.assertEqual("arf", Dog.barkHardly(1, 2))
+
     # TODO decent test case please :) without testing irrelevant implementation
     # details
     def testUnstubShouldPreserveMethodType(self):

tests/unstub_test.py

@@ -1,6 +1,14 @@
 import pytest
 
-from mockito import mock, when, unstub, verify, ArgumentError
+from mockito import (
+    ArgumentError,
+    ensureNoUnverifiedInteractions,
+    mock,
+    patch_attr,
+    unstub,
+    verify,
+    when,
+)
 
 
 class Dog(object):
@@ -11,6 +19,10 @@ def bark(self, sound='Wuff'):
         return sound
 
 
+class AttrHolder(object):
+    value = None
+
+
 class TestUntub:
     def testIndependentUnstubbing(self):
         rex = Dog()
@@ -38,6 +50,86 @@ def testUnconfigureMock(self):
         unstub(m)
         assert m.foo() is None
 
+    def testPartialUnstubByMethodReference(self):
+        cat = mock(strict=True)
+
+        when(cat).meow().thenReturn('Miau')
+        when(cat).runs().thenReturn('Yip')
+
+        unstub(cat.meow)
+
+        with pytest.raises(AttributeError):
+            cat.meow()
+
+        assert cat.runs() == 'Yip'
+
+    def testPartialUnstubByMethodReferenceKeepsDetachedChainAlive(self):
+        cat = mock(strict=True)
+
+        when(cat).meow().purr().sleep().thenReturn("ok")
+        child = cat.meow()
+        grand = child.purr()
+
+        unstub(cat.meow)
+
+        with pytest.raises(AttributeError):
+            cat.meow()
+
+        assert grand.sleep() == "ok"
+
+    def testPartialUnstubByMethodReferenceForgetsMethodInvocations(self):
+        cat = mock()
+
+        when(cat).meow().thenReturn("Miau")
+        when(cat).runs().thenReturn("Yip")
+
+        cat.meow()
+        cat.runs()
+        verify(cat).runs()
+
+        unstub(cat.meow)
+
+        ensureNoUnverifiedInteractions(cat)
+
+    def testPartialUnstubByMethodReferenceDoesNotRestoreMatchingPatchAttr(self):
+        cat = mock(strict=True)
+        holder = AttrHolder()
+
+        when(cat).meow().thenReturn("Miau")
+        replacement = cat.meow
+        patch_attr(holder, "value", replacement)
+
+        assert holder.value is replacement
+
+        unstub(cat.meow)
+
+        assert holder.value is replacement
+        with pytest.raises(AttributeError):
+            cat.meow()
+
+    @pytest.mark.xfail(
+        strict=False,
+        reason=(
+            "Characterization only: detached bound-method aliases currently "
+            "prefer patch_attr replacement matching before method-level unstub "
+            "resolution. This may change."
+        ),
+    )
+    def testCurrentBehaviorMethodAliasCanUnpatchWithoutUnstubbingMethod(self):
+        cat = mock(strict=True)
+        holder = AttrHolder()
+
+        when(cat).meow().thenReturn("Miau")
+        replacement = cat.meow
+        patch_attr(holder, "value", replacement)
+
+        assert holder.value is replacement
+
+        unstub(replacement)
+
+        assert holder.value is None
+        assert cat.meow() == "Miau"
+
 
 class TestContextManagerUnstubStrategy: