Make your
errors visible.

Quick Start

Python functions can raise exceptions or return None — and neither appears in the type signature. explicit_result gives you types that tell the truth.

# What can go wrong here?
# The signature won't tell you.
def get_user(uid: int) -> User:
    # might raise DatabaseError
    # might raise UserNotFoundError
    # might return None silently
    ...

from explicit_result import Ok, Err, Result

# The contract is explicit.
def get_user(uid: int) -> Result[User, str]:
    row = db.find(uid)
    if row is None:
        return Err("user not found")
    return Ok(User.from_row(row))

Core types at a glance

from explicit_result import Ok, Err, Result, Some, Nothing, Option, safe

# Result — a value OR an error
def parse_port(raw: str) -> Result[int, str]:
    try:
        port = int(raw)
    except ValueError:
        return Err(f"Port must be an integer, got: {raw!r}")
    if not 1 <= port <= 65535:
        return Err(f"Port {port} is out of range")
    return Ok(port)

parse_port("8080")    # Ok(8080)
parse_port("abc")     # Err("Port must be an integer, got: 'abc'")
parse_port("99999")   # Err("Port 99999 is out of range")

# Option — a value that might not exist
def find_user(uid: int) -> Option[str]:
    users = {1: "Archy", 2: "Chuks"}
    return Some(users[uid]) if uid in users else Nothing

find_user(1)    # Some("Archy")
find_user(99)   # Nothing

# @safe — wrap existing exception-throwing functions
@safe(catch=ValueError)
def parse_float(s: str) -> float:
    return float(s)

parse_float("3.14")   # Ok(3.14)
parse_float("abc")    # Err(ValueError(...))

# Bridge nullable values
Result.from_optional(os.environ.get("PORT"), "PORT not set")
# Ok("8080") or Err("PORT not set")

Option[T]

Option[T] represents a value that may or may not exist. It is an explicit, type-safe alternative to returning None.

Some("Archy")   # Some("Archy")
Some(0)         # Some(0) — 0 is a real value!
Some([])        # Some([]) — empty list is real

Nothing          # no value
result is Nothing  # True — singleton

Option.of(value) — A safe way to wrap any value. Returns Nothing if the value is None, otherwise Some(value).

Option.of(None)    # Nothing
Option.of("data")  # Some("data")

When to use Option vs Result

Use Option when absence is normal and expected — a user preference that might not be set, a cache entry that might not exist. The absence is not a failure.

Use Result when failure should carry a reason — a file that couldn't be read, a form field that failed validation. The caller needs to know why it failed.

Extracting Values

These methods let you get the contained value out of a Result or Option.

.unwrap()

Returns the value if Ok/Some. Raises UnwrapError if Err/Nothing. Use when you are logically certain the result is ok — for example, right after checking is_ok(), or in a test.

Ok(42).unwrap()      # 42
Err("x").unwrap()    # raises UnwrapError: "Called unwrap() on an Err value: 'x'"

.unwrap_or(default)

Returns the value, or the provided default. The default is always evaluated — if computing it is expensive, use unwrap_or_else.

Ok(42).unwrap_or(0)      # 42
Err("x").unwrap_or(0)    # 0
Nothing.unwrap_or("—")   # "—"

.unwrap_or_else(f)

Returns the value, or calls f to compute a default. f is only called on failure.

Err("not found").unwrap_or_else(lambda e: f"default ({e})")
# "default (not found)"

Nothing.unwrap_or_else(lambda: expensive_default())
# f is never called when the result is Ok/Some

.unwrap_or_raise(exc)

Returns the value, or raises the given exception. Useful at API boundaries where you need to produce a specific exception type.

user = get_user(uid).unwrap_or_raise(HTTPException(status=404))

.expect(message)

Like .unwrap() but includes your message in the UnwrapError. Use to document why this must be Ok.

config = load_config().expect(
    "Config must be loadable at startup — check your env vars"
)

Chaining

Chaining is the most powerful feature. It lets you write sequential logic that can fail at any step, without nested try/except blocks or if-None checks.

.and_then(f) — the core composition operator

If Ok/Some, calls f with the value and returns the result (which must itself be a Result/Option). If Err/Nothing, returns immediately — f is never called. Also known as flatmap or bind.

def parse_int(s: str) -> Result[int, str]:
    try:
        return Ok(int(s))
    except ValueError:
        return Err(f"not a number: {s!r}")

def ensure_positive(n: int) -> Result[int, str]:
    return Ok(n) if n > 0 else Err(f"must be positive, got {n}")

# Railway-oriented: chain steps — the first failure short-circuits
parse_int("5").and_then(ensure_positive).and_then(lambda n: Ok(n * 2))
# Ok(10)

parse_int("-3").and_then(ensure_positive).and_then(lambda n: Ok(n * 2))
# Err("must be positive, got -3")  — ensure_positive short-circuits

parse_int("abc").and_then(ensure_positive).and_then(lambda n: Ok(n * 2))
# Err("not a number: 'abc'")       — parse_int short-circuits

.or_else(f) — recover from failure

If Err/Nothing, calls f to attempt recovery. If Ok/Some, returns self unchanged.

# Try primary source, fall back to secondary
value = (
    get_from_cache(key)
    .or_else(lambda _: get_from_database(key))
    .unwrap_or("default")
)

# Option recovery
Nothing.or_else(lambda: Some("fallback"))   # Some("fallback")

Option extras — .zip() and .flatten()

# .zip() — combine two Somes into a tuple
Some(1).zip(Some("a"))   # Some((1, "a"))
Some(1).zip(Nothing)     # Nothing

# .flatten() — unwrap Option[Option[T]]
Some(Some(42)).flatten()   # Some(42)
Some(Nothing).flatten()   # Nothing

Pattern Matching

explicit_result supports Python's structural pattern matching with no extra setup. The __match_args__ attribute is set on all variants.

# Result
match get_user(1):
    case Ok(user):
        print(f"Found: {user.name}")
    case Err(error):
        print(f"Error: {error}")

# Option
match find_config("theme"):
    case Some(value):
        apply_theme(value)
    case _:
        apply_default_theme()

# Nested matching
match (result_a, result_b):
    case (Ok(a), Ok(b)):
        process(a, b)
    case (Err(e), _) | (_, Err(e)):
        handle_error(e)

@safe_async

The async equivalent of @safe. Wraps an async def function.

import asyncio
from explicit_result import safe_async

@safe_async(catch=(aiohttp.ClientError, asyncio.TimeoutError))
async def fetch_json(url: str) -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            response.raise_for_status()
            return await response.json()

# Returns Awaitable[Result[dict, aiohttp.ClientError | asyncio.TimeoutError]]
result = await fetch_json("https://api.example.com/data")

description = (
    result
    .map(lambda data: data["weather"]["description"])
    .unwrap_or("unavailable")
)

Async Helpers

For bridging asynchronous tasks with synchronous Result pipelines.

from_awaitable(coro) / map_async / and_then_async

import asyncio
from explicit_result import from_awaitable, map_async, and_then_async

async def fetch_data() -> str: ...

async def process():
    # Wrap an awaitable that might raise into a Result
    res = await from_awaitable(fetch_data(), catch=Exception)
    
    # Chain async functions onto a Result
    async def async_transform(x: str) -> int: return len(x)
    async def async_fetch_more(x: int) -> Result[int, str]: return Ok(x * 2)
    
    mapped = await map_async(res, async_transform)
    chained = await and_then_async(mapped, async_fetch_more)

collect_all

Like collect, but gathers all errors instead of stopping at the first. Essential for form validation where you want every field error in one pass.

from explicit_result import collect_all

collect_all([Ok(1), Err("a"), Ok(3), Err("b")])
# Err(["a", "b"])  — all errors collected

collect_all([Ok(1), Ok(2), Ok(3)])
# Ok([1, 2, 3])

# Form validation — report all errors at once
results = [
    validate_username(form.username),
    validate_email(form.email),
    validate_age(form.age),
]

match collect_all(results):
    case Ok([username, email, age]):
        create_account(username, email, age)
    case Err(errors):
        show_errors(errors)   # all validation errors at once

Philosophy

Real-World Patterns

Railway-oriented chaining

# Each step can fail. The first failure short-circuits the chain.
result = (
    parse_int(raw_input)           # Step 1: parse
    .and_then(ensure_positive)     # Step 2: validate
    .and_then(lookup_in_database) # Step 3: query
    .map(lambda row: row.to_dict()) # Step 4: transform
    .unwrap_or_else(lambda e: {"error": e})
)

Nested lookups with Option

# Without Option: nested if-None checks
user = users.get(uid)
if user is not None:
    dept = depts.get(user.dept_id)
    if dept is not None:
        lead = leaders.get(dept.lead_id)
        if lead is not None:
            email = lead.email

# With Option: linear chain
email = (
    get_user(uid)
    .and_then(lambda u: get_dept(u.dept_id))
    .and_then(lambda d: get_leader(d.lead_id))
    .map(lambda lead: lead.email)
    .unwrap_or("no email")
)

Collect all form errors

from explicit_result import collect_all

errors = collect_all([
    validate_username(form.username),
    validate_email(form.email),
    validate_age(form.age),
    validate_password(form.password),
])

# Either all pass — or you get ALL failures in one list
if errors.is_err():
    return Response({"errors": errors.unwrap_err()}, status=400)

Performance Benchmarks

explicit-result adds negligible overhead compared to raw Python features (~300ns per operation).

* Benchmarks run on Python 3.12.6

API Reference

Result[T, E]

Static constructors:

Instance methods:

Option[T]

Combinators