result-py

A functional programming library for Python.

Features

• Type-Safe Error Handling: Errors are values, not exceptions. Your type checker knows exactly what can go wrong.
• Railway-Oriented Programming: Chain operations elegantly with .pipe() and handle both success and failure paths.
• Rich Collection Operations: map, filter, reduce, flat_map, and more—all within the Either context.
• Modern Python: Built for Python 3.14+ with full type annotations and generics.
• Functional Composition: Build complex pipelines from simple, testable functions.

Installation

pip install fn-result-py

Or with Poetry:

poetry add fn-result-py

Quick Start

Basic Usage

from result_py import Either

# Create success and failure values
success = Either.right(42)       # Right = success
failure = Either.left("Error")   # Left = failure

# Chain operations - failures short-circuit automatically
result = (
    Either.right(10)
    .pipe(lambda x: x * 2)       # 20
    .pipe(lambda x: x + 5)       # 25
)
print(result)  # Either(_left=None, _right=25)

Error Handling Made Explicit

from result_py import Either

def divide(a: float, b: float) -> Either[str, float]:
    if b == 0:
        return Either.left("Division by zero!")
    return Either.right(a / b)

def sqrt(x: float) -> Either[str, float]:
    if x < 0:
        return Either.left("Cannot take sqrt of negative number!")
    return Either.right(x ** 0.5)

# Chain operations - first error stops the pipeline
result = (
    Either.right(16.0)
    .pipe(lambda x: divide(x, 2))   # Right(8.0)
    .pipe(sqrt)                      # Right(2.83...)
)

# Handle both cases with match
message = result.match(
    left=lambda err: f"Failed: {err}",
    right=lambda val: f"Result: {val:.2f}"
)
print(message)  # "Result: 2.83"

Working with Collections

from result_py import Either

# Transform collections within Either context
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()
)
print(result)  # Either(_left=None, _right=[20, 40])

# Filter and transform in one step
result = (
    Either.right([1, 2, 3, 4, 5])
    .filter_map(lambda x: x * 2 if x > 2 else None)
    .to_list()
)
print(result)  # Either(_left=None, _right=[6, 8, 10])

Wrapping External Code

Use wrap_external to safely wrap functions that might throw exceptions:

from result_py import wrap_external
import json

# Wrap a function that might raise exceptions
safe_json_loads = wrap_external(json.loads, json.JSONDecodeError)

result = safe_json_loads('{"valid": "json"}')
print(result)  # Either(_left=None, _right={'valid': 'json'})

result = safe_json_loads('not valid json')
print(result)  # Either(_left=JSONDecodeError(...), _right=None)

Using the @throws Decorator

Declare which exceptions your function might throw, and have them automatically converted to Either.left:

from result_py import Either, throws

@throws(ValueError, KeyError)
def risky_operation(data: dict, key: str) -> Either[ValueError | KeyError, int]:
    value = data[key]  # Might raise KeyError
    if value < 0:
        raise ValueError("Value must be positive")
    return Either.right(value * 2)

result = risky_operation({"x": 10}, "x")
print(result)  # Either(_left=None, _right=20)

result = risky_operation({}, "x")
print(result)  # Either(_left=KeyError('x'), _right=None)

API Reference

Creating Either Values

Transformations

Tuple Unpacking Variants

Aggregations

Combining & Matching

Properties

Utilities