safetywrap 1.5.0

Rust-inspired typesafe result types

safetywrap

Fully typesafe, Rust-inspired wrapper types for Python values

Summary

This library provides two main wrappers: Result and Option. These types allow you to specify typesafe code that effectively handles errors or absent data, without resorting to deeply nested if-statements and lots of try-except blocks.

This is accomplished by allowing you to operate on an Option or Result in a sort of quantum superposition, where an Option could be Some or Nothing or a Result could be Ok or Err. In either case, all of the methods on the type work just the same, allowing you to handle both cases elegantly.

A Result[T, E] may be an instance of Ok[T] or Err[E], while an Option[T] may be an instance of Some[T] or Nothing. Either way, you get to treat them just the same until you really need to get the wrapped value.

So, rather than this:

for something in "value", None:
    if something is not None:
        val = something.upper()
    else:
        val = "DEFAULT"
    print(val)

You can do this:

for something in Some("value"), Nothing():
    print(something.map(str.upper).unwrap_or("DEFAULT"))

And rather than this:

for jsondata in '{"value": "myvalue"}', '{badjson':
    try:
        config = capitalize_keys(json.loads(jsondata))
    except Exception:
        config = get_default_config()
    print(config["value"])

You can do this:

for jsondata in '{"value": "myvalue"}', '{badjson':
    print(
        Result.of(json.loads, jsondata)
        .map(capitalize_keys)
        .unwrap_or_else(get_default_config)["value"]
    )

These two examples are super minimal samples of how using these typesafe wrappers can make things easier to write and reason about. Please see the Examples section for more, and Usage for the full suite of offered functionality.

These types are heavily influenced by the Result and Option types in Rust.

Thorough type specifications for mypy or your favorite python type-checker are provided, so that you can decorate function inputs and outputs as returning Result and Option types and get useful feedback when supplying arguments or passing return values.

Sponsorship

This project was developed for and is graciously sponsored by my employer, Bestow, Inc.. At Bestow, we aim to democratize life insurance by providing simple, easy coverage, purchasable online in five minutes with no doctors' visits and no hassles.

We're pretty much always hiring great developers, so if you'd like to work with us, please check out our careers page!

Table of Contents

• safetywrap
  • Summary
    • Sponsorship
  • Table of Contents
  • Examples
    • Get an enum member by its value, returning the member or None
    • Get an enum member by its value, returning an Option
    • Serialize a dict that may be missing keys, using default values
    • Make an HTTP request, and if the status code is 200, convert the body to JSON and return the data key. If there is an error or the data key does not exist, return an error string
  • Usage
    • Result[T, E]
      • Result Constructors
        • Ok
        • Err
        • Result.of
        • Result.collect
        • Result.err_if
        • Result.ok_if
      • Result Methods
        • Result.and_
        • Result.or_
        • Result.and_then
        • Result.flatmap
        • Result.or_else
        • Result.err
        • Result.ok
        • Result.expect
        • Result.raise_if_err
        • Result.expect_err
        • Result.is_err
        • Result.is_ok
        • Result.iter
        • Result.map
        • Result.map_err
        • Result.unwrap
        • Result.unwrap_err
        • Result.unwrap_or
        • Result.unwrap_or_else
      • Result Magic Methods
    • Option[T]
      • Option Constructors
        • Some
        • Nothing
        • Option.of
        • Option.nothing_if
        • Option.some_if
        • Option.collect
      • Option Methods
        • Option.and_
        • Option.or_
        • Option.xor
        • Option.and_then
        • Option.flatmap
        • Option.or_else
        • Option.expect
        • Option.raise_if_nothing
        • Option.filter
        • Option.is_nothing
        • Option.is_some
        • Option.iter
        • Option.map
        • Option.map_or
        • Option.map_or_else
        • Option.ok_or
        • Option.ok_or_else
        • Option.unwrap
        • Option.unwrap_or
        • Option.unwrap_or_else
      • Option Magic Methods
  • Performance
    • Results
    • Discussion
  • Contributing

Examples

In general, these examples build from simple to complex. See Usage below for the full API specification.

Get an enum member by its value, returning the member or None

import typing as t
from enum import Enum

from result_types import Option, Result, Some

T = t.TypeVar("T", bound=Enum)

def enum_member_for_val(enum: t.Type[T], value: t.Any) -> t.Optional[t.Any]:
    """Return Some(enum_member) or Nothing()."""
    # Enums throw a `ValueError` if the value isn't present, so
    # we'll either have `Ok(enum_member)` or `Err(ValueError)`.
    # We unwrap and return the member if it's Ok, otherwise, we just
    # return None
    return Result.of(enum, value).unwrap_or(None)

Get an enum member by its value, returning an Option

import typing as t
from enum import Enum

from result_types import Option, Result, Some

T = t.TypeVar("T", bound=Enum)

def enum_member_for_val(enum: t.Type[T], value: t.Any) -> Option[T]:
    """Return Some(enum_member) or Nothing()."""
    # Enums throw a `ValueError` if the value isn't present, so
    # we'll either have `Ok(enum_member)` or `Err(ValueError)`.
    # Calling `ok()` on a `Result` returns an `Option`
    return Result.of(enum, value).ok()

Serialize a dict that may be missing keys, using default values

import json
from result_types import Result

def serialize(data: t.Dict[str, t.Union[int, str, float]]) -> str:
    """Serialize the data.

    Absent keys are "[absent]", rather than null. This allows us to maintain
    information about whether a key was present or actually set to None.
    """
    keys = ("first", "second", "third", "fourth")
    # We can even use Result to catch any JSON serialization errors, so that
    # this function will _always_ return a string!
    Result.of(
        json.dumps,
        # Result.of() will intercept the KeyError and return an Err. We use
        # `unwrap_or()` to discard the error and return the "[absent]" string
        # instead; if the key was present, the Result was Ok, and we just
        # return that value.
        {k: Result.of(lambda: data[k]).unwrap_or("[absent]") for k in keys}
    ).unwrap_or("Could not serialize JSON from data!")

Make an HTTP request, and if the status code is 200, convert the body to JSON and return the data key. If there is an error or the data key does not exist, return an error string

from functools import partial

import requests
from requests import Response
from result_types import Option, Result


def get_data(url: str) -> str:
    """Get the data!"""
    # We need to do manual type assignment sometimes when the code
    # we're wrapping does not provide types.
    # If the wrapped function raises any Exception, `res` will be
    # Err(Exception). Otherwise it will be `Ok(Response)`.
    res: Result[Response, Exception] = Result.of(requests.get, url)
    return (
        # We start as a `Result[Response, Exception]`
        res
        # And if we were an Err, map to a `Result[Response, str]`
        .map_err(str)
        # If we were Ok, and_then (aka flatmap) to a new `Result[Response, str]`
        .and_then(lambda res: (
            # Our return value starts as a `Result[Response, Response]`
            Result.ok_if(lambda r: r.status_code == 200, res).map_err(
                # So we map it to a `Result[Response, str]`
                lambda r: str(f"Bad status code: {r.status_code}")
            )
        ))
        # We are now a `Result[Response, str]`, where we are only Ok if
        # our status code was 200.
        # Now we transition to a `Result[dict, str]`
        .and_then(lambda res: Result.of(res.json).map_err(str))
        # And to a `Result[Option[str], str]`
        .map(lambda js: Option.of(js.get("data")).map(str))
        # And to a `Result[str, str]`
        .and_then(lambda data: data.ok_or("No data key in JSON!"))
        # If we are an error, convert us to an Ok with the error string
        .or_else(Ok)
        # And now we get either the Ok string or the Err string!
        .unwrap()
    )

Usage

Result[T, E]

A Result represents some value that may either be in an Ok state or an Err state.

Result Constructors

Ok

Ok(value: T) -> Result[T, E]

Construct an Ok Result directly with the value.

Example:

def check_value_not_negative(val: int) -> Result[int, str]:
    """Check that a value is not negative, or return an Err."""
    if val >= 0:
        return Ok(val)
    return Err(f"{val} is negative!")

Err

Err(value: E) -> Result[T, E]

Construct an Err Result directly with the value.

Example:

def check_value_not_negative(val: int) -> Result[int, str]:
    """Check that a value is not negative, or return an Err."""
    if val >= 0:
        return Ok(val)
    return Err(f"{val} is negative!")

Result.of

Result.of(fn: Callable[..., T], *args: t.Any, catch: t.Type[E], **kwargs) -> Result[T, E]

Call a function with the provided arguments. If no error is thrown, return Ok(result). Otherwise, return Err(exception). By default, Exception is caught, but different error types may be provided with the catch keyword argument.

The type of E MUST be Exception or one of its subclasses.

This constructor is designed to be useful in wrapping other APIs, builtin functions, etc.

Note that due to a bug in mypy (see https://github.com/python/mypy/issues/3737), sometimes you need to explicitly specify the catch keyword argument, even if you're setting it to its default (Exception). This does not happen consistently, but when it does, you will see mypy thinking that the type of the Result is Result[SomeType, <nothing>].

Example:

import json

def parse_json(string: str) -> Result[dict, Exception]:
    """Parse a JSON object into a dict."""
    return Result.of(json.loads, string)

Result.collect

Result.collect(iterable: Iterable[T, E]) -> Result[Tuple[T, ...], E]

Convert an iterable of Results into a single Result. If all Results were Ok, Ok values are collected into a Tuple in the final Result. If any Results were Err, the Err result is returned directly.

Example:

assert Result.collect([Ok(1), Ok(2), Ok(3)]) == Ok((1, 2, 3))
assert Result.collect([Ok(1), Err("no"), Ok(3)]) == Err("no")

Result.err_if

Result.err_if(predicate: t.Callable[[T], bool], value: T) -> Result[T, T]

Run a predicate on some value, and return Err(val) if the predicate returns True, or Ok(val) if the predicate returns False.

Example:

from requests import Response

def checked_response(response: Response) -> Result[Response, Response]:
    """Try to get a response from the server."""
    return Result.err_if(lambda r: r.status_code >= 300, response)

Result.ok_if

Result.ok_if(predicate: t.Callable[[T], bool], value: T) -> Result[T, T]

Run a predicate on some value, and return Ok(val) if the predicate returns True, or Err(val) if the predicate returns False.

Example:

def checked_data(data: dict) -> Result[dict, dict]:
    """Check if data has expected keys."""
    expected_keys = ("one", "two", "three")
    return Result.ok_if(lambda d: all(k in d for k in expected_keys), data)

Result Methods

Result.and_

Result.and_(self, res: Result[U, E]) -> Result[U, E]

If this Result is Ok, return res. If this result is Err, return this Result. This can be used to short circuit a chain of Results on encountering the first error.

Example:

assert Ok(5).and_(Ok(6)) == Ok(6)
assert Err(1).and_(Ok(6)) == Err(1)
assert Err(1).and_(Err(2)).and_(Ok(5)) == Err(1)
assert Ok(5).and_(Err(1)).and_(Ok(6)) == Err(1)

Result.or_

Result.or_(self, res: Result[T, F]) -> Result[T, F]

If this Result is Err, return res. Otherwise, return this Result.

Example:

assert Err(1).or_(Ok(5)) == Ok(5)
assert Err(1).or_(Err(2)) == Err(2)
assert Ok(5).or_(Ok(6)) == Ok(5)
assert Ok(5).or_(Err(1)) == Ok(5)

Result.and_then

Result.and_then(self, fn: t.Callable[[T], Result[U, E]]) -> Result[U, E]

If this Result is Ok, call the provided function with the wrapped value of this Result and return the Result of that function. This allows easily chaining multiple Result-generating calls together to yield a final Result. This method is an alias of Result.flatmap

Example:

assert Ok(5).and_then(lambda val: Ok(val + 1)) == Ok(6)
assert Err(1).and_then(lambda val: Ok(val + 1)) == Err(1)

Result.flatmap

Result.flatmap(self, fn: t.Callable[[T], Result[U, E]]) -> Result[U, E]

If this Result is Ok, call the provided function with the wrapped value of this Result and return the Result of that function. This allows easily chaining multiple Result-generating calls together to yield a final Result. This method is an alias of Result.and_then

Example:

assert Ok(5).flatmap(lambda val: Ok(val + 1)) == Ok(6)
assert Err(1).flatmap(lambda val: Ok(val + 1)) == Err(1)

Result.or_else

Result.or_else(self, fn: t.Callable[[E], Result[T, F]]) -> Result[T, F])

If this result is Err, call the provided function with the wrapped error value of this Result and return the Result of that function. This allows easily handling potential errors in a way that still returns a final Result.

Example:

assert Ok(5).or_else(Ok) == Ok(5)
assert Err(1).or_else(Ok) == Ok(1)

Result.err

Result.err(self) -> Option[E]

Convert this Result into an Option, returning Some(err_val) if this Result is Err, or Nothing() if this Result is Ok.

Example:

assert Ok(5).err() == Nothing()
assert Err(1).err() == Some(1)

Result.ok

Result.ok(self) -> Option[T]

Convert this Result into an Option, returning Some(val) if this Result is Ok, or Nothing() if this result is Err.

Example:

assert Ok(5).ok() == Some(5)
assert Err(1).ok() == Nothing()

Result.expect

Result.expect(self, msg: str, exc_cls: t.Type[Exception] = RuntimeError) -> T

Return the wrapped value if this Result is Ok. Otherwise, raise an error, instantiated with the provided message and the stringified error value. By default, a RuntimeError is raised, but an alternative error may be provided using the exc_cls keyword argument. This method is an alias for Result.raise_if_err.

Example:

import pytest

with pytest.raises(RuntimeError) as exc:
    Err(5).expect("Bad value")
    assert str(exc.value) == "Bad value: 5"

assert Ok(1).expect("Bad value") == 1

Result.raise_if_err

Result.raise_if_err(self, msg: str, exc_cls: t.Type[Exception] = RuntimeError) -> T

Return the wrapped value if this Result is Ok. Otherwise, raise an error, instantiated with the provided message and the stringified error value. By default, a RuntimeError is raised, but an alternative error may be provided using the exc_cls keyword argument. This method is an alias for Result.expect.

Example:

import pytest

with pytest.raises(RuntimeError) as exc:
    Err(5).raise_if_err("Bad value")
    assert str(exc.value) == "Bad value: 5"

assert Ok(1).raise_if_err("Bad value") == 1

Result.expect_err

Result.expect_err(self, msg: str, exc_cls: t.Type[Exception] = RuntimeError) -> E

Return the wrapped value if this Result is Err. Otherwise, raise an error, instantiated with the provided message and the stringified Ok value. By default, a RuntimeError is raised, but an alternative error may be provided using the exc_cls keyword argument.

Example:

import pytest

with pytest.raises(RuntimeError) as exc:
    Ok(5).expect_err("Unexpected good value")
    assert str(exc.value) == "Unexpected good value: 5"

assert Err(1).expect_err("Unexpected good value") == 1

Result.is_err

Result.is_err(self) -> bool

Return True if this Result is Err, or False if this Result is Ok.

Example:

assert Err(1).is_err() is True
assert Ok(1).is_err() is False

Result.is_ok

Result.is_ok(self) -> bool

Return True if this Result is Ok, or False if this Result is Err.

Example:

assert Ok(1).is_err() is True
assert Err(1).is_err() is False

Result.iter

Result.iter(self) -> Iterator[T]

Return an iterator with length 1 over the wrapped value if this Result is Ok. Otherwise, return a 0-length iterator.

Example:

assert tuple(Ok(1).iter()) == (1,)
assert tuple(Err(1).iter()) == ()

Result.map

Result.map(self, fn: t.Callable[[T], U]) -> Result[U, E]

If this Result is Ok, apply the provided function to the wrapped value, and return a new Ok Result with the result of the function. If this Result is Err, do not apply the function and return this Result unchanged.

Warning: no error checking is performed while applying the provided function, and exceptions applying the function are not caught. If you need to map with error handling, consider using and_then (aka flatmap) in conjunction with the Result.of constructor, e.g. assert Ok(0).and_then(partial(Result.of, lambda i: 10 / i)) == Err(ZeroDivisionError('division by zero'))

Example:

assert Ok(1).map(str) == Ok("1")
assert Err(1).map(str) == Err(1)

Result.map_err

Result.map_err(self, fn: t.Callable[[E], F]) -> Result[T, F]

If this Result is Err, apply the provided function to the wrapped value, and return a new Err Result with the result of the function. If this Result is Ok, do not apply the function and return this Result unchanged.

Warning: no error checking is performed while applying the provided function, and exceptions applying the function are not caught.

Example:

assert Err(1).map_err(lambda i: i + 1) == Err(2)
assert Ok(1).map_err(lambda i: i + 1) == Ok(1)

Result.unwrap

Result.unwrap(self) -> T

If this Result is Ok, return the wrapped value. If this Result is Err, throw a RuntimeError.

Example:

import pytest

assert Ok(1).unwrap() == 1

with pytest.raises(RuntimeError):
    Err(1).unwrap()

Result.unwrap_err

Result.unwrap_err(self) -> E

If this Result is Err, return the wrapped value. If this Result is Ok, throw a RuntimeError.

Example:

import pytest

assert Err(1).unwrap() == 1

with pytest.raises(RuntimeError):
    Ok(1).unwrap()

Result.unwrap_or

Result.unwrap_or(self, alternative: U) -> t.Union[T, U]

If this Result is Ok, return the wrapped value. Otherwise, if this Result is Err, return the provided alternative.

Example:

assert Ok(1).unwrap_or(5) == 1
assert Err(1).unwrap_or(5) == 5

Result.unwrap_or_else

Result.unwrap_or_else(self, fn: t.Callable[[E], U]) -> t.Union[T, U]

If this Result is Ok, return the wrapped value. Otherwise, if this Result is Err, call the supplied function with the wrapped error value and return the result.

Example:

assert Ok(1).unwrap_or_else(str) == 1
assert Err(1).unwrap_or_else(str) == "1"

Result Magic Methods

Result.iter

Result.__iter__(self) -> t.Iterator[T]

Implement the iterator protocol, allowing iteration over the results of Result.iter. If this Result is Ok, return an iterator of length 1 containing the wrapped value. Otherwise, if this Result is Err, return a 0-length iterator.

Example:

# Can be passed to methods that take iterators
assert tuple(Ok(1)) == (1,)
assert tuple(Err(1)) == ()

# Can be used in `for in` constructs, including comprehensions
assert [val for val in Ok(5)] == [5]
assert [val for val in Err(5)] == []


# More for-in usage.
for val in Ok(5):
    pass
assert val == 5

val = None
for val in Err(1):
    pass
assert val is None

Result.eq

Result.__eq__(self, other: Any) -> bool

Enable equality checking using ==.

Compare the Result with other. Return True if other is the same type of Result with the same wrapped value. Otherwise, return False.

Example:

assert (Ok(5) == Ok(5)) is True
assert (Ok(5) == Ok(6)) is False
assert (Ok(5) == Err(5)) is False
assert (Ok(5) == 5) is False

Result.ne

Result.__ne__(self, other: Any) -> bool

Enable inequality checking using !=.

Compare the Result with other. Return False if other is the same type of Result with the same wrapped value. Otherwise, return True.

Example:

assert (Ok(5) != Ok(5)) is False
assert (Ok(5) != Ok(6)) is True
assert (Ok(5) != Err(5)) is True
assert (Ok(5) != 5) is True

Result.str

Result.__str__(self) -> str

Enable useful stringification via str().

Example:

assert str(Ok(5)) == "Ok(5)"
assert str(Err(5)) == "Err(5)"

Result.repr

Result.__repr__(self) -> str

Enable useful stringification via repr().

Example:

assert repr(Ok(5)) == "Ok(5)"
assert repr(Err(5)) == "Err(5)"

Option[T]

An Option represents either Some value or Nothing.

Option Constructors

Some

Some(value: T) -> Option[T]

Construct a Some Option directly with a value.

Example:

def file_contents(path: str) -> Option[str]:
    """Return the file contents or Nothing."""
    try:
        with open(path) as f:
            return Some(f.read())
    except IOError:
        return Nothing()

Nothing

Nothing() -> Option[T]

Construct a Nothing Option directly with a value.

Note: as an implementation detail, Nothing is implemented as a singleton, to avoid instantiation time for any Nothing created after the first. However since this is an implementation detail, Nothing Options should still be compared with == rather than is.

Example:

def file_contents(path: str) -> Option[str]:
    """Return the file contents or Nothing."""
    try:
        with open(path) as f:
            return Some(f.read())
    except IOError:
        return Nothing()

Option.of

Option.of(value: t.Optional[T]) -> Option[T]

Convert an optional value into an Option. If the value is not None, return Some(value). Otherwise, if the value is None, return Nothing().

Example:

assert Option.of(None) == Nothing()
assert Option.of({}.get("a")) == Nothing()
assert Option.of("a") == Some("a")
assert Option.of({"a": "b"}) == Some("b")

Option.nothing_if

Option.nothing_if(predicate: t.Callable[[T], bool], value: T) -> Option[T]

Call the provided predicate function with the provided value. If the predicate returns True, return Nothing(). If the predicate returns False, return Some(value).

Example:

assert Option.nothing_if(lambda val: val.startswith("_"), "_private") == Nothing()
assert Option.nothing_if(lambda val: val.startswith("_"), "public") == Some("public")

Option.some_if

Option.some_if(predicate: t.Callable[[T], bool], value: T) -> Option[T]

Call the provided predicate function with the provided value. If the predicate returns True, return Some(value). If the predicate returns False, return Nothing().

Example:

assert Option.some_if(bool, [1, 2, 3]) == Some([1, 2, 3])
assert Option.some_if(bool, []) == Nothing()

Option.collect

Option.collect(options: t.Iterable[Option[T]]) -> Option[t.Tuple[T, ...]]

Collect a series of Options into single Option.

If all options are Some[T], the result is Some[Tuple[T, ...j]]. If any options are Nothing, the result is Nothing.

Example:

assert Option.collect([Some(1), Some(2), Some(3)]) == Some((1, 2, 3))
assert Option.collect([Some(1), Nothing(), Some(3)]) == Nothing()

Option Methods

Option.and_

Option.and_(alternative: Option[U]) -> Option[U]

If this Option is Nothing, return it unchanged. Otherwise, if this Option is Some, return the provided alternative Option.

Example:

assert Some(1).and_(Some(2)) == Some(2)
assert Nothing().and_(Some(2)) == Nothing()
assert Some(1).and_(Nothing()) == Nothing()
assert Nothing().and_(Nothing()) == Nothing()
assert Some(1).and_(Nothing()).and_(Some(2)) == Nothing()

Option.or_

Option.or_(alternative: Option[T]) -> Option[T]

If this Option is Nothing, return the provided alternative Option. Otherwise, if this Option is Some, return it unchanged.

Example:

assert Some(1).or_(Some(2)) == Some(1)
assert Some(1).or_(Nothing()) == Some(1)
assert Nothing().or_(Some(1)) == Some(1)
assert Nothing().or_(Nothing()) == Nothing()

Option.xor

Option.xor(alternative: Option[T]) -> Option[T]

Exclusive or. Return Some Option iff (if and only if) exactly one of this Option and hte provided alternative are Some. Otherwise, return Nothing.

Example:

assert Some(1).xor(Nothing()) == Some(1)
assert Nothing().xor(Some(1)) == Some(1)
assert Some(1).xor(Some(2)) == Nothing()
assert Nothing().xor(Nothing()) == Nothing()

Option.and_then

Option.and_then(self, fn: t.Callable[[T], Option[U]]) -> Option[U]

If this Option is Some, call the provided, Option-returning function with the contained value and return whatever Option it returns. If this Option is Nothing, return it unchanged. This method is an alias for Option.flatmap

Example:

assert Some(1).and_then(lambda i: Some(i + 1)) == Some(2)
assert Nothing().and_then(lambda i: Some(i + 1)) == Nothing()

Option.flatmap

Option.flatmap(self, fn: t.Callable[[T], Option[U]]) -> Option[U]

If this Option is Some, call the provided, Option-returning function with the contained value and return whatever Option it returns. If this Option is Nothing, return it unchanged. This method is an alias for Option.and_then

Example:

assert Some(1).flatmap(Some) == Some(1)
assert Nothing().flatmap(Some) == Nothing()

Option.or_else

Option.or_else(self, fn: t.Callable[[], Option[T]]) -> Option[T]

If this Option is Nothing, call the provided, Option-returning function and return whatever Option it returns. If this Option is Some, return it unchanged.

Example:

assert Nothing().or_else(lambda: Some(1)) == Some(1)
assert Some(1).or_else(lambda: Some(2)) == Some(1)

Option.expect

Option.expect(self, msg: str, exc_cls: t.Type[Exception] = RuntimeError) -> T

If this Option is Some, return the wrapped value. Otherwise, if this Option is Nothing, raise an error instantiated with the provided message. By default, a RuntimeError is raised, but a custom exception class may be provided via the exc_cls keyword argument. This method is an alias of Option.raise_if_nothing.

Example:

import pytest

with pytest.raises(RuntimeError) as exc:
    Nothing().expect("Nothing here")
    assert str(exc.value) == "Nothing here"

assert Some(1).expect("Nothing here") == 1

Option.raise_if_nothing

Option.raise_if_nothing(self, msg: str, exc_cls: t.Type[Exception] = RuntimeError) -> T

If this Option is Some, return the wrapped value. Otherwise, if this Option is Nothing, raise an error instantiated with the provided message. By default, a RuntimeError is raised, but a custom exception class may be provided via the exc_cls keyword argument. This method is an alias of Option.expect.

Example:

import pytest

with pytest.raises(RuntimeError) as exc:
    Nothing().raise_if_nothing("Nothing here")
    assert str(exc.value) == "Nothing here"

assert Some(1).raise_if_nothing("Nothing here") == 1

Option.filter

Option.filter(self, predicate: t.Callable[[T], bool]) -> Option[T]

If this Option is Some, call the provided predicate function with the wrapped value. If the predicate returns True, return Some containing the wrapped value of this Option. If the predicate returns False, return Nothing. If this Option is Nothing, return it unchanged.

Example:

def is_even(val: int) -> bool:
    """Return whether the value is even."""
    return val % 2 == 0

assert Some(2).filter(is_even) == Some(2)
assert Some(1).filter(is_even) == Nothing()
assert Nothing().filter(is_even) == Nothing()

Option.is_nothing

Option.is_nothing(self) -> bool

If this Option is Nothing, return True. Otherwise, if this Option is Some, return False.

Example:

assert Nothing().is_nothing() is True
assert Some(1).is_nothing() is False

Option.is_some

Option.is_some(self) -> bool

If this Option is Some. Otherwise, if this Option is Nothing, return False.

Example:

assert Some(1).is_some() is True
assert Nothing().is_some() is False

Option.iter

Option.iter(self) -> t.Iterator[T]

If this Option is Some, return an iterator of length one over the wrapped value. Otherwise, if this Option is Nothing, return a 0-length iterator.

Example:

assert tuple(Some(1).iter()) == (1,)
assert tuple(Nothing().iter()) == ()

Option.map

Option.map(self, fn: t.Callable[[T], U]) -> Option[U]

If this Option is Some, apply the provided function to the wrapped value, and return Some wrapping the result of the function. If this Option is Nothing, return this Option unchanged.

Example:

assert Some(1).map(str) == Some("1")
assert Nothing().map(str) == Nothing()
assert Some(1).map(str).map(lambda x: x + "a").map(str.upper) == Some("1A")

Option.map_or

Option.map_or(self, default: U, fn: t.Callable[[T], U]) -> U

If this Option is Some, apply the provided function to the wrapped value and return the result. If this Option is Nothing, return the provided default value.

Example:

assert Some(1).map_or("no value", str) == "1"
assert Nothing().map_or("no value", str) == "no value"

Option.map_or_else

Option.map_or_else(self, default: t.Callable[[], U], fn: t.Callable[[T], U]) -> U

If this Option is Some, apply the provided function to the wrapped value and return the result. If this Option is Nothing, call the provided default function with no arguments and return the result.

Example:

from datetime import datetime, date

assert Some("2005-08-28").map_or_else(
    date.today,
    lambda t: datetime.strptime(t, "%Y-%m-%d").date()
) == datetime(2005, 8, 28).date()

assert Nothing().map_or_else(
    date.today,
    lambda t: datetime.strptime(t, "%Y-%m-%d").date()
) == date.today()

Option.ok_or

Option.ok_or(self, err: E) -> Result[T, E]

If this Option is Some, return an Ok Result wrapping the contained value. Otherwise, return an Err result wrapping the provided error.

Example:

assert Some(1).ok_or("no value!") == Ok(1)
assert Nothing().ok_or("no value!") == Err("no value!")

Option.ok_or_else

Option.ok_or_else(self, err_fn: t.Callable[[], E]) -> Result[T, E]

If this Option is Some, return an Ok Result wrapping the contained value. Otherwise, call the provided err_fn and wrap its return value in an Err Result.

Example:

from functools import partial

def make_err_msg(msg: str) -> str:
    """Make an error message with some starting text."""
    return f"[MY_APP_ERROR] -- {msg}"

assert Some(1).ok_or_else(partial(make_err_msg, "no value!")) == Ok(1)
assert Nothing().ok_or_else(partial(make_err_msg, "no value!")) == Err(
    "[MY_APP_ERROR] -- no value!"
)

Option.unwrap

Option.unwrap(self) -> T

If this Option is Some, return the wrapped value. Otherwise, raise a RuntimeError.

Example:

import pytest

assert Some(1).unwrap() == 1

with pytest.raises(RuntimeError):
    Nothing().unwrap()

Option.unwrap_or

Option.unwrap_or(self, default: U) -> t.Union[T, U]

If this Option is Some, return the wrapped value. Otherwise, return the provided default.

Example:

assert Some(1),unwrap_or(-1) == 1
assert Nothing().unwrap_or(-1) == -1

Option.unwrap_or_else

Option.unwrap_or_else(self, fn: t.Callable[[], U]) -> t.Union[T, U]

If this Option is Some, return the wrapped value. Otherwise, return the result of the provided function.

Example:

from datetime import date

assert Some(date(2001, 1, 1)).unwrap_or_else(date.today) == date(2001, 1, 1)
assert Nothing().unwrap_or_else(date.today) == date.today()

Option Magic Methods

Option.iter

Option.__iter__(self) -> t.Iterator[T]

Implement the iterator protocol, allowing iteration over the results of Option.iter. If this Option is Ok, return an iterator of length 1 containing the wrapped value. Otherwise, if this Option is Nothing, return a 0-length iterator.

Example:

# Can be passed to methods that take iterators
assert tuple(Some(1)) == (1,)
assert tuple(Nothing()j) == ()

# Can be used in `for in` constructs, including comprehensions
assert [val for val in Some(1)] == [1]
assert [val for val in Nothing()] == []


# More for-in usage.
for val in Some(1):
    pass
assert val == 1

val = None
for val in Nothing():
    pass
assert val is None

Option.eq

Option.__eq__(self, other: Any) -> bool

Enable equality checking using ==.

Compare this Option with other. Return True if other is the same type of Option with the same wrapped value. Otherwise, return False.

Example:

assert (Some(1) == Some(1)) is True
assert (Some(1) == Some(2)) is False
assert (Some(1) == Nothing()) is False
assert (Some(1) == 1) is False

Option.ne

Option.__ne__(self, other: Any) -> bool

Enable inequality checking using !=.

Compare the Option with other. Return False if other is the same type of Option with the same wrapped value. Otherwise, return True.

Example:

assert (Some(1) != Some(1)) is False
assert (Some(1) != Some(2)) is True
assert (Some(1) != Nothing()) is True
assert (Some(1) != 1) is True

Option.str

Option.__str__(self) -> str

Enable useful stringification via str().

Example:

assert str(Some(1)) == "Some(1)"
assert str(Nothing()) == "Nothing()"

Option.repr

Option.__repr__(self) -> str

Enable useful stringification via repr().

Example:

assert repr(Some(1)) == "Some(1)"
assert repr(Nothing()) == "Nothing()"

Performance

Benchmarks may be run with make bench. Benchmarking utilities are provided in bench/.

Currently, the sample.py benchmark defines two data stores, one using classical python error handling (or lack thereof), and the other using this library's wrapper types. Some simple operations are performed using each data store for comparison.

runner.sh runs the benchmarks two ways. First, it uses hyperfine to run the benchmarks as a normal python script 100 times and display information about the run time. It then uses python's builtin timeit module to measure the code execution time in isolation over one million runs, without the added overhead of spinning up the interpreter to parse and run the script.

Results

The Result and Option wrapper types add minimal overhead to execution time, which will not be noticeable for most real-world workloads. However, care should be taken if using these types in "hot paths."

Run in isolation, the sample code using Result and Option types is about six times slower than builtin exception handling:

Method	Number of Executions	Average Execution Time	Relative to Classical
Classical	1,000,000 (1E6)	3.79E-6 s (3.79 μs)	1x
Wrapper	1,000,000 (1E6)	2.31E-5 s (23.1 μs)	6.09x

When run as part of a Python script, there is no significant difference between using code with these wrapper types versus code that uses builtin exception handling and nested if statements.

Method	Number of Executions	Average Execution Time	Relative to Classical
Classical	100	32.2 ms	1x
Wrapper	100	32.5 ms	1.01x

Discussion

Care has been taken to make the wrapper types in this library as performant as possible. All types use __slots__ to avoid allocating a dictionary for instance variables, and wrapper variants (e.g. Ok and Err for Result) are implemented as separate subclasses of Result rather than a shared class in order to avoid needing to perform if/else branching or isinstance() checks, which are notoriously slow in Python.

That being said, using these types is doing more than the builtin error handling! Instances are being constructed and methods are being accessed. Both of these are relatively quick in Python, but definitely not quicker than doing nothing, so this library will probably never be quite as performant as raw exception handling. That being said, that is not its aim! The goal is to be as quick as possible, preferably within striking distance of regular old idiomatic python, while providing significantly more ergonomics and type safety around handling errors and absent data.

Contributing

Contributions are welcome! To get started, you'll just need a local install of Python 3.

Once you've forked and cloned the repo, you can run:

• make test - run tests using your local interpreter
• make fmt - format code using black
• make lint - check code with a variety of analysis tools
• make bench - run benchmarks

See the Makefile for other commands.

The CI system requires that make lint and make test run successfully (exit status of 0) in order to merge code.

result_types is compatible with Python >= 3.6. You can run against all supported python versions with make test-all-versions. This requires that docker be installed on your local system. Alternatively, if you have all required Python versions installed, you may run make tox to run against your local interpreters.