Prevent an Outcome to be unwrapped twice.

Author: smurfix

docs/source/api.rst

@@ -21,3 +21,5 @@ API Reference
 .. autoclass:: Error
    :members:
    :inherited-members:
+
+.. autoclass:: AlreadyUsedError

docs/source/tutorial.rst

@@ -25,4 +25,7 @@ which, like before, is the same as::
 
     x = await f(*args, **kwargs)
 
+An Outcome object may not be unwrapped twice. Attempting to do so will
+raise an :class:`AlreadyUsedError`.
+
 See the :ref:`api-reference` for the types involved.

newsfragments/7.feature.rst

@@ -0,0 +1,3 @@
+An Outcome may only be unwrapped or sent once.
+
+Attempting to do so a second time will raise an :class:`AlreadyUsedError`.

src/outcome/__init__.py

@@ -8,12 +8,12 @@
 
 if sys.version_info >= (3, 5):
     from ._async import Error, Outcome, Value, acapture, capture
-    __all__ = ('Error', 'Outcome', 'Value', 'acapture', 'capture')
+    __all__ = ('Error', 'Outcome', 'Value', 'acapture', 'capture', 'AlreadyUsedError')
 else:
     from ._sync import Error, Outcome, Value, capture
-    __all__ = ('Error', 'Outcome', 'Value', 'capture')
+    __all__ = ('Error', 'Outcome', 'Value', 'capture', 'AlreadyUsedError')
 
 
-from ._util import fixup_module_metadata
+from ._util import fixup_module_metadata, AlreadyUsedError
 fixup_module_metadata(__name__, globals())
 del fixup_module_metadata

src/outcome/_async.py

@@ -4,6 +4,7 @@
     Error as ErrorBase, Outcome as OutcomeBase, Value as ValueBase
 )
 
+from ._util import AlreadyUsedError
 __all__ = ['Error', 'Outcome', 'Value', 'acapture', 'capture']
 
 
@@ -49,11 +50,13 @@ async def asend(self, agen):
 
 class Value(ValueBase):
     async def asend(self, agen):
+        self._set_unwrapped()
         return await agen.asend(self.value)
 
 
 class Error(ErrorBase):
     async def asend(self, agen):
+        self._set_unwrapped()
         return await agen.athrow(self.error)
 
 

src/outcome/_sync.py

@@ -4,7 +4,7 @@
 import abc
 import attr
 
-from ._util import ABC
+from ._util import ABC, AlreadyUsedError
 
 __all__ = ['Error', 'Outcome', 'Value', 'capture']
 
@@ -21,7 +21,7 @@ def capture(sync_fn, *args, **kwargs):
     except BaseException as exc:
         return Error(exc)
 
-
+@attr.s(repr=False, init=False, slots=True)
 class Outcome(ABC):
     """An abstract class representing the result of a Python computation.
 
@@ -37,7 +37,13 @@ class Outcome(ABC):
     hashable.
 
     """
-    __slots__ = ()
+    _unwrapped = attr.ib(default=False, cmp=False, init=False)
+
+    def _set_unwrapped(self):
+        if self._unwrapped:
+            raise AlreadyUsedError
+        object.__setattr__(self, '_unwrapped', True)
+
 
     @abc.abstractmethod
     def unwrap(self):
@@ -62,7 +68,7 @@ def send(self, gen):
         """
 
 
-@attr.s(frozen=True, repr=False)
+@attr.s(frozen=True, repr=False, slots=True)
 class Value(Outcome):
     """Concrete :class:`Outcome` subclass representing a regular value.
 
@@ -75,13 +81,15 @@ def __repr__(self):
         return 'Value({!r})'.format(self.value)
 
     def unwrap(self):
+        self._set_unwrapped()
         return self.value
 
     def send(self, gen):
+        self._set_unwrapped()
         return gen.send(self.value)
 
 
-@attr.s(frozen=True, repr=False)
+@attr.s(frozen=True, repr=False, slots=True)
 class Error(Outcome):
     """Concrete :class:`Outcome` subclass representing a raised exception.
 
@@ -94,7 +102,10 @@ def __repr__(self):
         return 'Error({!r})'.format(self.error)
 
     def unwrap(self):
+        self._set_unwrapped()
         raise self.error
 
     def send(self, it):
+        self._set_unwrapped()
         return it.throw(self.error)
+

src/outcome/_util.py

@@ -6,6 +6,11 @@
 import sys
 
 
+class AlreadyUsedError(RuntimeError):
+    """An Outcome may not be unwrapped twice."""
+    pass
+
+
 def fixup_module_metadata(module_name, namespace):
     def fix_one(obj):
         mod = getattr(obj, "__module__", None)

tests/test_async.py

@@ -5,7 +5,7 @@
 from async_generator import async_generator, yield_
 
 import outcome
-from outcome import Error, Value
+from outcome import Error, Value, AlreadyUsedError
 
 pytestmark = pytest.mark.trio
 
@@ -38,8 +38,15 @@ async def my_agen_func():
     my_agen = my_agen_func().__aiter__()
     if sys.version_info < (3, 5, 2):
         my_agen = await my_agen
+    v = Value("value")
+    e = Error(KeyError())
     assert (await my_agen.asend(None)) == 1
-    assert (await Value("value").asend(my_agen)) == 2
-    assert (await Error(KeyError()).asend(my_agen)) == 3
+    assert (await v.asend(my_agen)) == 2
+    with pytest.raises(AlreadyUsedError):
+        await v.asend(my_agen)
+
+    assert (await e.asend(my_agen)) == 3
+    with pytest.raises(AlreadyUsedError):
+        await e.asend(my_agen)
     with pytest.raises(StopAsyncIteration):
         await my_agen.asend(None)

tests/test_sync.py

@@ -5,7 +5,7 @@
 import pytest
 
 import outcome
-from outcome import Error, Value
+from outcome import Error, Value, AlreadyUsedError
 
 
 def test_Outcome():
@@ -14,13 +14,21 @@ def test_Outcome():
     assert v.unwrap() == 1
     assert repr(v) == "Value(1)"
 
+    with pytest.raises(AlreadyUsedError):
+        v.unwrap()
+
+    v = Value(1)
+
     exc = RuntimeError("oops")
     e = Error(exc)
     assert e.error is exc
     with pytest.raises(RuntimeError):
         e.unwrap()
+    with pytest.raises(AlreadyUsedError):
+        e.unwrap()
     assert repr(e) == "Error({!r})".format(exc)
 
+    e = Error(exc)
     with pytest.raises(TypeError):
         Error("hello")
     with pytest.raises(TypeError):
@@ -33,6 +41,8 @@ def expect_1():
     it = iter(expect_1())
     next(it)
     assert v.send(it) == "ok"
+    with pytest.raises(AlreadyUsedError):
+        v.send(it)
 
     def expect_RuntimeError():
         with pytest.raises(RuntimeError):
@@ -42,6 +52,8 @@ def expect_RuntimeError():
     it = iter(expect_RuntimeError())
     next(it)
     assert e.send(it) == "ok"
+    with pytest.raises(AlreadyUsedError):
+        e.send(it)
 
 
 def test_Outcome_eq_hash():