add .peek()

Author: graingert

src/outcome/_impl.py

@@ -122,10 +122,23 @@ class Outcome(abc.ABC, Generic[ValueT]):
     hashable.
 
     """
+    @abc.abstractmethod
+    def peek(self) -> ValueT:
+        """Return or raise the contained value or exception, without
+        invalidating the outcome.
+
+        These two lines of code are equivalent::
+
+           x = fn(*args)
+           x = outcome.capture(fn, *args).peek()
+
+        """
+
 
     @abc.abstractmethod
     def unwrap(self) -> ValueT:
-        """Return or raise the contained value or exception.
+        """Return or raise the contained value or exception, and invalidate
+        the outcome.
 
         These two lines of code are equivalent::
 
@@ -173,6 +186,9 @@ def __repr__(self) -> str:
         except AttributeError:
             return 'Value(<AlreadyUsed>)'
 
+    def peek(self) -> ValueT:
+        return self.value
+
     def unwrap(self) -> ValueT:
         try:
             v = self._value
@@ -226,6 +242,27 @@ def _unwrap_error(self) -> BaseException:
             return v
         raise AlreadyUsedError
 
+    def peek(self) -> NoReturn:
+        # Tracebacks show the 'raise' line below out of context, so let's give
+        # this variable a name that makes sense out of context.
+        captured_error = self.error
+        try:
+            raise captured_error
+        finally:
+            # We want to avoid creating a reference cycle here. Python does
+            # collect cycles just fine, so it wouldn't be the end of the world
+            # if we did create a cycle, but the cyclic garbage collector adds
+            # latency to Python programs, and the more cycles you create, the
+            # more often it runs, so it's nicer to avoid creating them in the
+            # first place. For more details see:
+            #
+            #    https://github.com/python-trio/trio/issues/1770
+            #
+            # In particuar, by deleting this local variables from the 'unwrap'
+            # methods frame, we avoid the 'captured_error' object's
+            # __traceback__ from indirectly referencing 'captured_error'.
+            del captured_error, self
+
     def unwrap(self) -> NoReturn:
         # Tracebacks show the 'raise' line below out of context, so let's give
         # this variable a name that makes sense out of context.

tests/test_async.py

@@ -16,6 +16,7 @@ async def add(x, y):
 
     v = await outcome.acapture(add, 3, y=4)
     assert v == Value(7)
+    assert v.peek() == 7
 
     async def raise_ValueError(x):
         await asyncio.sleep(0)
@@ -24,6 +25,10 @@ async def raise_ValueError(x):
     e = await outcome.acapture(raise_ValueError, 9)
     assert type(e.error) is ValueError
     assert e.error.args == (9,)
+    with pytest.raises(ValueError):
+        e.peek()
+    with pytest.raises(ValueError):
+        e.unwrap()
 
 
 async def test_asend():

tests/test_sync.py

@@ -11,6 +11,7 @@ def test_Outcome():
     v = Value(1)
     assert v.value == 1
     assert repr(v) == "Value(1)"
+    assert v.peek() == 1
     assert v.unwrap() == 1
     assert repr(v) == "Value(<AlreadyUsed>)"
 
@@ -23,6 +24,8 @@ def test_Outcome():
     e = Error(exc)
     assert e.error is exc
     assert repr(e) == f"Error({exc!r})"
+    with pytest.raises(RuntimeError):
+        e.peek()
     with pytest.raises(RuntimeError):
         e.unwrap()
     with pytest.raises(AlreadyUsedError):
@@ -94,6 +97,7 @@ def add(x, y):
 
     v = outcome.capture(add, 2, y=3)
     assert type(v) == Value
+    assert v.peek() == 5
     assert v.unwrap() == 5
 
     def raise_ValueError(x):
@@ -103,6 +107,10 @@ def raise_ValueError(x):
     assert type(e) == Error
     assert type(e.error) is ValueError
     assert e.error.args == ("two",)
+    with pytest.raises(ValueError):
+        e.peek()
+    with pytest.raises(ValueError):
+        e.unwrap()
 
 
 def test_inheritance():