Stop Letting Python Functions Lie to You: Introducing explicit-result

Python is beautiful, readable, and highly expressive. But its built-in error handling mechanism, exceptions, has a fundamental flaw: Exceptions are invisible.

Take a look at this standard Python function signature:

def get_user(user_id: int) -> User:
    ...

What does this signature tell you? It promises to return a User. But does it? What happens if the database connection drops? What if user_id doesn't exist? What if there's a permission issue?

You can’t know without digging into the implementation, hoping the docstrings are accurate, or waiting for a surprise stack trace in production. The type system provides zero guarantees about what can fail.

That’s where explicit-result comes in.

The Philosophy of explicit-result

explicit-result is a zero-dependency, fully-typed Python library that brings Result and Option primitives to your Python code. It is designed around three core ideas:

1. Errors should be part of the contract. A function that can fail should declare its possible errors right in its return type.
2. The API should feel native to Python. This isn’t a clunky port of Rust or Haskell. It’s built to feel perfectly natural in idiomatic Python.
3. Adopt incrementally. You don’t need to rewrite your entire codebase to benefit. Wrap existing code with simple decorators and refactor at your own pace.

Result: Bringing Errors to Light

With explicit-result, your function signatures stop hiding the truth. Instead of hoping a caller catches an implicit ValueError, you declare it:

from explicit_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)

The signature Result[float, str] is an ironclad contract: "I will give you either a float or a string error. I will not surprise you."

Safely Handling Results

Once you get a Result, you have powerful, explicit ways to handle it. You can explicitly unpack values safely:

result = divide(10, 2)

# Unpack with a fallback
value = result.unwrap_or(0.0)

# Unpack explicitly, providing context if it panics
validated = result.expect("Division must never fail in this critical path")

On Python 3.10+, explicit-result works flawlessly with Structural Pattern Matching, allowing you to write beautiful, exhaustive handlers:

match divide(10, 2):
    case Ok(value):
        print(f"Success: {value}")
    case Err(error):
        print(f"Failed: {error}")

Bridging the Gap: The @safe Decorator

What if you're using third-party code that heavily relies on implicit exceptions? explicit-result makes it trivial to convert exception-throwing code into predictable Result boundaries.

from explicit_result import safe

@safe(catch=ValueError)
def parse_float(s: str) -> float:
    return float(s)

parse_float("3.14")   # Ok(3.14)
parse_float("abc")    # Err(ValueError("could not convert string to float..."))

Your low-level exceptions instantly become trackable, manageable objects that map directly into your type checker.

Chaining and Do-Notation: Kiss Try/Except Hell Goodbye

The true power of Result shines when operations are chained. You can cleanly sequence logic without ever writing nested try/except blocks.

If you don't want to use method chaining, explicit-result provides pure Python Do-notation using generators, which fully embraces python controls like if/else and loops!

from explicit_result import do, Result

@do()
def get_user_profile() -> Result[dict, str]:
    user = yield fetch_user()            # Returns dict if Ok, short-circuits if Err
    profile = yield fetch_profile(user["id"])
    return {**user, **profile}           # Automatically wrapped in Ok

Option: The End of the None Mystery

Returning None when something fails is tempting, but None is completely silent about why something didn't work. Furthermore, sometimes None is an entirely valid value!

Option[T] solves this by giving you explicit Some(value) and Nothing.

from explicit_result import Option, Some, Nothing

def find_user(user_id: int) -> Option[str]:
    users = {1: "Archy", 2: "Chuks"}
    return Some(users[user_id]) if user_id in users else Nothing

Never get lost in ambiguous NullType errors again. When a function returns Option[T], you know the absence of a value is a completely valid business case, not a crash.

Why You Should Try It Today

If you’re building production systems in Python, confidence and predictability matter. explicit-result removes the guesswork from error handling and forces developers to deal with edge cases explicitly, before the bug ships.

It is completely lightweight, installs instantly with pip install explicit-result, has zero external dependencies, and integrates beautifully with linters like Pyright and Mypy.

Stop letting your functions lie. Make your error paths as robust as your happy paths.

👉

chukwunwike / explicit-result

Result and Option types for Python zero dependencies, fully typed.

explicit-result

Result and Option types for Python — zero dependencies, fully typed.

Read the Full Documentation here

---

Python functions lie. A function typed as -> int might return an integer, raise a ValueError, raise a ConnectionError, or return None depending on conditions the caller cannot see. The type system gives you no warning. You discover the truth at runtime, usually in production.

explicit-result fixes this by making errors visible in the function signature itself.

from explicit_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)   # Ok(5.0)
result = divide(10, 0)   # Err("division by zero")

The signature Result[float, str] is a…

View on GitHub