feat: add unwrap_or_raise_itself() if a value of Err is a BaseException

CHANGELOG.md

@@ -16,6 +16,8 @@ Possible log types:
 - `[changed]` Improve type narrowing for `is_ok` and `is_err` type guards by
   replacing `typing.TypeGuard` with `typing.TypeIs` (#193)
 
+- `[added]` Add `unwrap_or_raise_itself()` for `Ok` and `Err` (#199)
+
 ## [0.17.0] - 2024-06-02
 
 - `[added]` Add `inspect()` and `inspect_err()` methods (#185)

docs/result.md

@@ -473,6 +473,19 @@ unwrap_or_raise(e: 'object') → T
 Return the value. 
 
 
+---
+
+<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L143"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+### <kbd>method</kbd> `unwrap_or_raise_itself`
+
+```python
+unwrap_or_raise_itself() → T
+```
+
+Return the value. 
+
+
 ---
 
 <a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L221"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
@@ -789,6 +802,21 @@ unwrap_or_raise(e: 'Type[TBE]') → NoReturn
 The contained result is ``Err``, so raise the exception with the value. 
 
 
+---
+
+<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L355"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+### <kbd>method</kbd> `unwrap_or_raise_itself`
+
+```python
+unwrap_or_raise_itself() → NoReturn
+```
+
+The contained result is ``Err``, so raise the error itself. 
+
+If the error is not an exception, this will raise an `UnwrapError`. 
+
+
 ---
 
 <a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L442"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

src/result/result.py

@@ -146,6 +146,12 @@ def unwrap_or_raise(self, e: object) -> T:
         """
         return self._value
 
+    def unwrap_or_raise_itself(self) -> T:
+        """
+        Return the value.
+        """
+        return self._value
+
     def map(self, op: Callable[[T], U]) -> Ok[U]:
         """
         The contained result is `Ok`, so return `Ok` with original value mapped to
@@ -358,6 +364,20 @@ def unwrap_or_raise(self, e: Type[TBE]) -> NoReturn:
         """
         raise e(self._value)
 
+    def unwrap_or_raise_itself(self) -> NoReturn:
+        """
+        The contained result is ``Err``, so raise the error itself.
+
+        If the error is not an exception, this will raise an `UnwrapError`.
+        """
+        if isinstance(self._value, BaseException):
+            raise self._value
+
+        raise UnwrapError(
+            self,
+            f"Called `Result.unwrap_or_raise_itself()` on non-exception value: {self._value}",
+        )
+
     def map(self, op: object) -> Err[E]:
         """
         Return `Err` with the same value

tests/test_result.py

@@ -158,6 +158,18 @@ def test_unwrap_or_raise() -> None:
     assert exc_info.value.args == ('nay',)
 
 
+def test_unwrap_or_raise_itself() -> None:
+    o = Ok('yay')
+    n = Err(RuntimeError('nay'))
+    assert o.unwrap_or_raise_itself() == 'yay'
+    with pytest.raises(RuntimeError) as exc_info:
+        n.unwrap_or_raise_itself()
+    assert exc_info.value.args == ('nay',)
+    ne = Err('nay')
+    with pytest.raises(UnwrapError):
+        ne.unwrap_or_raise_itself()
+
+
 def test_map() -> None:
     o = Ok('yay')
     n = Err('nay')