Skip to content

Commit

Permalink
feat: add .inspect() and .inspect_err() methods (#185)
Browse files Browse the repository at this point in the history
  • Loading branch information
@deliro
deliro authored Jun 2, 2024
1 parent 27b5aba commit 08a6030
Show file tree
Hide file tree
Showing 4 changed files with 137 additions and 31 deletions.
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ Possible log types:

## [Unreleased]

- `[added]` Add `inspect()` and `inspect_err()` methods (#185)

## [0.16.1] - 2024-02-29

- `[fixed]` PyPI not showing description (#176)
Expand Down
110 changes: 79 additions & 31 deletions docs/result.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L439"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L465"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

## <kbd>function</kbd> `as_result`

Expand All @@ -30,7 +30,7 @@ Regular return values are turned into ``Ok(return_value)``. Raised exceptions of

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L471"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L497"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

## <kbd>function</kbd> `as_async_result`

Expand All @@ -45,7 +45,7 @@ Make a decorator to turn an async function into one that returns a ``Result``. R

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L504"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L530"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

## <kbd>function</kbd> `is_ok`

Expand All @@ -68,7 +68,7 @@ elif is_err(r):

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L521"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L547"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

## <kbd>function</kbd> `is_err`

Expand All @@ -91,7 +91,7 @@ elif is_err(r):

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L538"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L564"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

## <kbd>function</kbd> `do`

Expand Down Expand Up @@ -128,7 +128,7 @@ NOTE: If you exclude the type annotation e.g. `Result[float, int]` your type che

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L583"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L609"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

## <kbd>function</kbd> `do_async`

Expand Down Expand Up @@ -278,6 +278,30 @@ Raise an UnwrapError since this type is `Ok`

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L205"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `inspect`

```python
inspect(op: 'Callable[[T], None]') → Result[T, E]
```

Calls a function with the contained value if `Ok`. Returns the original result.

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L212"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `inspect_err`

```python
inspect_err(op: 'Callable[[E], None]') → Result[T, E]
```

Calls a function with the contained value if `Err`. Returns the original result.

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L67"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `is_err`
Expand Down Expand Up @@ -451,12 +475,12 @@ Return the value.

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L206"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L219"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

## <kbd>class</kbd> `DoException`
This is used to signal to `do()` that the result is an `Err`, which short-circuits the generator and returns that Err. Using this exception for control flow in `do()` allows us to simulate `and_then()` in the Err case: namely, we don't call `op`, we just return `self` (the Err).

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L215"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L228"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `__init__`

Expand All @@ -474,12 +498,12 @@ __init__(err: 'Err[E]') → None

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L219"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L232"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

## <kbd>class</kbd> `Err`
A value that signifies failure and which stores arbitrary data for the error.

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L235"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L248"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `__init__`

Expand Down Expand Up @@ -510,7 +534,7 @@ Return the inner value.

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L378"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L391"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `and_then`

Expand All @@ -522,7 +546,7 @@ The contained result is `Err`, so return `Err` with the original value

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L384"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L397"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `and_then_async`

Expand All @@ -534,7 +558,7 @@ The contained result is `Err`, so return `Err` with the original value

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L262"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L275"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `err`

Expand All @@ -546,7 +570,7 @@ Return the error.

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L291"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L304"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `expect`

Expand All @@ -558,7 +582,7 @@ Raises an `UnwrapError`.

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L303"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L316"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `expect_err`

Expand All @@ -570,7 +594,31 @@ Return the inner value

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L253"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L410"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `inspect`

```python
inspect(op: 'Callable[[T], None]') → Result[T, E]
```

Calls a function with the contained value if `Ok`. Returns the original result.

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L416"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `inspect_err`

```python
inspect_err(op: 'Callable[[E], None]') → Result[T, E]
```

Calls a function with the contained value if `Err`. Returns the original result.

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L266"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `is_err`

Expand All @@ -584,7 +632,7 @@ is_err() → Literal[True]

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L250"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L263"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `is_ok`

Expand All @@ -598,7 +646,7 @@ is_ok() → Literal[False]

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L346"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L359"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `map`

Expand All @@ -610,7 +658,7 @@ Return `Err` with the same value

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L352"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L365"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `map_async`

Expand All @@ -622,7 +670,7 @@ The contained result is `Ok`, so return the result of `op` with the original val

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L371"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L384"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `map_err`

Expand All @@ -634,7 +682,7 @@ The contained result is `Err`, so return `Err` with original error mapped to a n

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L359"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L372"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `map_or`

Expand All @@ -646,7 +694,7 @@ Return the default value

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L365"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L378"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `map_or_else`

Expand All @@ -658,7 +706,7 @@ Return the result of the default operation

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L256"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L269"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `ok`

Expand All @@ -670,7 +718,7 @@ Return `None`.

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L390"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L403"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `or_else`

Expand All @@ -682,7 +730,7 @@ The contained result is `Err`, so return the result of `op` with the original va

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L309"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L322"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `unwrap`

Expand All @@ -694,7 +742,7 @@ Raises an `UnwrapError`.

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L321"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L334"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `unwrap_err`

Expand All @@ -706,7 +754,7 @@ Return the inner value

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L327"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L340"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `unwrap_or`

Expand All @@ -718,7 +766,7 @@ Return `default`.

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L333"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L346"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `unwrap_or_else`

Expand All @@ -730,7 +778,7 @@ The contained result is ``Err``, so return the result of applying ``op`` to the

---

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L340"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L353"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `unwrap_or_raise`

Expand All @@ -743,14 +791,14 @@ 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#L414"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L440"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

## <kbd>class</kbd> `UnwrapError`
Exception raised from ``.unwrap_<...>`` and ``.expect_<...>`` calls.

The original ``Result`` can be accessed via the ``.result`` attribute, but this is not intended for regular use, as type information is lost: ``UnwrapError`` doesn't know about both ``T`` and ``E``, since it's raised from ``Ok()`` or ``Err()`` which only knows about either ``T`` or ``E``, not both.

<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L427"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
<a href="https://github.com/rustedpy/result/blob/main/src/result/result.py#L453"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

### <kbd>method</kbd> `__init__`

Expand Down
26 changes: 26 additions & 0 deletions src/result/result.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -202,6 +202,19 @@ def or_else(self, op: object) -> Ok[T]:
"""
return self

def inspect(self, op: Callable[[T], Any]) -> Result[T, E]:
"""
Calls a function with the contained value if `Ok`. Returns the original result.
"""
op(self._value)
return self

def inspect_err(self, op: Callable[[E], Any]) -> Result[T, E]:
"""
Calls a function with the contained value if `Err`. Returns the original result.
"""
return self


class DoException(Exception):
"""
Expand Down Expand Up @@ -394,6 +407,19 @@ def or_else(self, op: Callable[[E], Result[T, F]]) -> Result[T, F]:
"""
return op(self._value)

def inspect(self, op: Callable[[T], Any]) -> Result[T, E]:
"""
Calls a function with the contained value if `Ok`. Returns the original result.
"""
return self

def inspect_err(self, op: Callable[[E], Any]) -> Result[T, E]:
"""
Calls a function with the contained value if `Err`. Returns the original result.
"""
op(self._value)
return self


# define Result as a generic type alias for use
# in type annotations
Expand Down
Loading

0 comments on commit 08a6030

Please sign in to comment.