Quickstart

Creating Either Values

Either has two sides: Right for success, Left for failure.

from result_py import Either

success = Either.right(42)
failure = Either.left("something went wrong")

# Aliases
success = Either.success(42)
failure = Either.failure("something went wrong")

Chaining with pipe

.pipe() applies a function to the Right value. If the Either is Left, the chain short-circuits and the error propagates untouched.

result = (
    Either.right(5)
    .pipe(lambda x: x + 1)   # 6
    .pipe(lambda x: x * 2)   # 12
    .pipe(lambda x: x - 3)   # 9
)
# Either(_left=None, _right=9)

If any step returns an Either.left, everything after it is skipped:

def safe_div(x: float) -> Either[str, float]:
    if x == 0:
        return Either.left("cannot divide by zero")
    return Either.right(100 / x)

result = (
    Either.right(0)
    .pipe(safe_div)           # Left("cannot divide by zero")
    .pipe(lambda x: x + 1)   # skipped
)

Extracting Values

match lets you handle both cases:

message = result.match(
    left=lambda err: f"Failed: {err}",
    right=lambda val: f"Got: {val}",
)

unwrap_or gives you the Right value or a default:

value = Either.right(42).unwrap_or(0)   # 42
value = Either.left("err").unwrap_or(0) # 0

Working with Collections

When an Either wraps an iterable, you get collection operations:

result = (
    Either.right([1, 2, 3, 4, 5])
    .filter(lambda x: x % 2 == 0)      # [2, 4]
    .map(lambda x: x * 10)             # [20, 40]
    .to_list()
)
# Either(_left=None, _right=[20, 40])