Returns: Meaningful, Typed, and Safe Function Returns

0.26.0 · active · verified Sun Apr 12

The `returns` library (version 0.26.0) is a functional programming toolkit for Python, enhancing type-safety and explicit error handling. It allows developers to make functions return meaningful, typed, and safe values like `Result`, `Maybe`, and `IO` monads, promoting composable and testable code. The project is actively maintained with frequent releases, often every few months, introducing new features and compatibility updates.

Warnings

breaking `returns` has specific Python version requirements that have changed over time. Python 3.7 support was dropped in `0.22.0`, and Python 3.9 support was dropped in `0.24.0`. Current versions require Python `>=3.10`.
Fix: Ensure your Python environment is at version `3.10` or higher to use recent `returns` releases.
breaking The `success_type` and `failure_type` fields were removed from `IOResult`, `Maybe`, and `Result` types. Code that directly accessed these attributes will break.
Fix: Refactor code to not rely on these specific type attributes. Type hints should now be inferred correctly without needing to inspect these fields directly.
gotcha The `Maybe` type now implements a `__bool__` method where only `Nothing` evaluates to `False`. `Some` values, regardless of their content, evaluate to `True`.
Fix: Be explicit when checking `Maybe` values. Use `is_some()`, `is_nothing()`, or `match` statements instead of direct boolean evaluation to avoid unintended behavior, especially when dealing with `Some(False)` or `Some(0)`.
gotcha `returns` is highly reliant on specific `mypy` versions for correct type inference and to prevent `mypy` errors. The compatible `mypy` version often changes with `returns` releases.
Fix: Always check the `returns` changelog or documentation for the currently supported `mypy` version range. Install `returns` with the `[compatible-mypy]` extra, e.g., `pip install returns[compatible-mypy]` to ensure `mypy` is installed correctly.
gotcha Attempting to unwrap a `Failure` or `Nothing` value (e.g., using `.unwrap()`, `.value_or()`, or accessing `.value` directly on `Failure`) without handling the error path will raise an `UnwrapFailedError`.
Fix: Always handle the error case before unwrapping. Use methods like `.alt()`, `.bind_failure()`, `.lash()`, `.fix()`, `.map_failure()`, or `match` statements to safely process both `Success`/`Some` and `Failure`/`Nothing` paths.

Install

pip install returns Install core library
pip install returns[compatible-mypy] Install with compatible MyPy version

Imports

Result, Success, Failure

from returns.result import Result, Success, Failure

Maybe, Some, Nothing

from returns.maybe import Maybe, Some, Nothing

IO, IOResult
```
from returns.io import IO, IOResult
```
do
```
from returns.do_notation import do
```
safe
```
from returns.result import safe
```
maybe
```
from returns.maybe import maybe
```

Quickstart

This quickstart demonstrates the `do` notation for composing operations with `Result` types. Functions `divide` and `multiply` return `Result` objects, encapsulating either a `Success` value or a `Failure` message. The `calculate_compound` function uses `yield` within the `@do(Result)` decorator to sequentially process these results, automatically propagating any `Failure`.

from returns.result import Result, Success, Failure
from returns.do_notation import do

def divide(numerator: int, denominator: int) -> Result[float, str]:
    if denominator == 0:
        return Failure('Cannot divide by zero')
    return Success(numerator / denominator)

def multiply(value: float, multiplier: int) -> Result[float, str]:
    if multiplier < 0:
        return Failure('Multiplier cannot be negative')
    return Success(value * multiplier)

@do(Result)
def calculate_compound(num: int, den: int, mult: int) -> Result[float, str]:
    divided_val = yield divide(num, den)
    final_val = yield multiply(divided_val, mult)
    return final_val

# Example usage:
assert calculate_compound(10, 2, 5) == Success(25.0)
assert calculate_compound(10, 0, 5) == Failure('Cannot divide by zero')
assert calculate_compound(10, 2, -1) == Failure('Multiplier cannot be negative')

print(calculate_compound(10, 2, 5))

view raw JSON →