philiprehberger-result 0.5.0

Rust-inspired Result type for Python with pattern matching and type-safe error handling

philiprehberger-result

Rust-inspired Result type for Python with pattern matching and type-safe error handling.

Installation

pip install philiprehberger-result

Usage

Basic Result

from philiprehberger_result import Ok, Err, Result

def divide(a: float, b: float) -> Result[float, str]:
    if b == 0:
        return Err("division by zero")
    return Ok(a / b)

result = divide(10, 2)
print(result.unwrap())  # 5.0

result = divide(10, 0)
print(result.unwrap_or(0.0))  # 0.0

Pattern Matching (Python 3.10+)

match divide(10, 3):
    case Ok(value):
        print(f"Result: {value}")
    case Err(error):
        print(f"Error: {error}")

Chaining

result = (
    Ok(10)
    .map(lambda x: x * 2)
    .flat_map(lambda x: Ok(x + 1) if x < 100 else Err("too large"))
)

Fallback with or_else

result = Err("not found").or_else(lambda e: Ok("default"))
# Ok("default")

Serialization

Ok(42).to_dict()    # {"ok": 42}
Err("x").to_dict()  # {"err": "x"}

Try/Catch Wrapping

from philiprehberger_result import try_catch

result = try_catch(lambda: int("not a number"))
# Err(ValueError("invalid literal..."))

Async Support

from philiprehberger_result import try_catch_async

result = await try_catch_async(fetch_data)

Collecting Results

from philiprehberger_result import all_ok

results = [Ok(1), Ok(2), Ok(3)]
combined = all_ok(results)  # Ok([1, 2, 3])

results = [Ok(1), Err("fail"), Ok(3)]
combined = all_ok(results)  # Err("fail")

Batch Mapping

from philiprehberger_result import map_batch

results = [Ok(1), Ok(2), Ok(3)]
mapped = map_batch(results, lambda x: x * 10)  # Ok([10, 20, 30])

results = [Ok(1), Err("fail"), Ok(3)]
mapped = map_batch(results, lambda x: x * 10)  # Err("fail")

Flattening Nested Results

nested = Ok(Ok(42))
flat = nested.flatten()  # Ok(42)

nested = Ok(Err("inner error"))
flat = nested.flatten()  # Err("inner error")

outer_err = Err("outer")
flat = outer_err.flatten()  # Err("outer")

Transpose nested results

from philiprehberger_result import transpose

transpose(Ok(Ok(5)))       # Ok(5)
transpose(Ok(Err("bad")))  # Err("bad")
transpose(Err("outer"))    # Err("outer")

# Method form:
Ok(Ok(5)).transpose()      # Ok(5)
Ok(Err("bad")).transpose() # Err("bad")

Unlike flatten(), transpose() collapses both inner branches and raises TypeError if the inner value is not itself a Result.

Combining Multiple Results

from philiprehberger_result import combine

result = combine(Ok(1), Ok("hello"), Ok(True))
# Ok((1, "hello", True))

result = combine(Ok(1), Err("fail"), Ok(3))
# Err("fail")

Collecting Results from Iterables

from philiprehberger_result import collect

results = [Ok(1), Ok(2), Ok(3)]
collected = collect(results)  # Ok([1, 2, 3])

results = [Ok(1), Err("fail"), Ok(3)]
collected = collect(results)  # Err("fail")

Adding Error Context

result = Err("not found").with_context("loading config")
# Err("loading config: not found")

ok_result = Ok(42).with_context("ignored for Ok")
# Ok(42)

API

Function / Class	Description
Ok(value)	Success variant — wraps a value
Err(error)	Error variant — wraps an error
.is_ok() / .is_err()	Type check
.unwrap()	Get value or raise
.unwrap_or(default)	Get value or return default
.unwrap_err()	Get error or raise
.map(fn)	Transform Ok value
.map_err(fn)	Transform Err value
.flat_map(fn)	Chain Result-returning functions
.or_else(fn)	Fallback on Err, pass-through on Ok
.flatten()	Flatten nested Results: Ok(Ok(v)) -> Ok(v)
.transpose() / transpose(result)	Collapse nested Result: Ok(Ok(v)) -> Ok(v), Ok(Err(e)) -> Err(e), Err(e) -> Err(e)
.match(ok=fn, err=fn)	Pattern dispatch
.to_dict()	Serialize to {"ok": v} or {"err": e}
ok(value) / err(error)	Shorthand constructors
try_catch(fn)	Wrap callable in Result
try_catch_async(fn)	Async version
from_awaitable(aw)	Wrap awaitable in Result
all_ok(results)	Collect list of Results into Result of list
map_batch(results, fn)	Apply fn to all Ok values; short-circuit on first Err
combine(*results)	Merge multiple Results into Ok(tuple) or first Err
collect(iterable)	Convert iterable of Results into Result of list or first Err
.with_context(msg)	Wrap Err with context string; pass-through on Ok

Development

pip install -e .
python -m pytest tests/ -v

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT