Skip to content

Result

Result type inspired by Rust's Result enum.

A disciplined alternative to raising exceptions — the Result type makes success
and failure explicit in your function signatures. Conceptually it is the same
idea as :class:Either in Scala or Haskell, specialised so that the right
side holds a success value and the left side holds an error.

Use :class:Ok to wrap a success value and :class:Err to wrap an error, then
compose operations with :meth:map, :meth:flat_map, and :meth:map_error
instead of writing try/except blocks.

result

Result type inspired by Rust's Result enum.

A disciplined alternative to raising exceptions — the Result type makes success
and failure explicit in your function signatures. Conceptually it is the same
idea as :class:Either in Scala or Haskell, specialised so that the right
side holds a success value and the left side holds an error.

Use :class:Ok to wrap a success value and :class:Err to wrap an error, then
compose operations with :meth:map, :meth:flat_map, and :meth:map_error
instead of writing try/except blocks.

Result

Bases: Protocol

Protocol that defines the shared interface for :class:Ok and :class:Err.

Source code in src/forging_blocks/foundation/result/result.py 
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
@runtime_checkable
class Result[ValueType, ErrorType](Protocol):
    """Protocol that defines the shared interface for :class:`Ok` and :class:`Err`."""

    @property
    def is_ok(self) -> bool:
        """Return ``True`` when this Result holds a success value (is :class:`Ok`)."""
        ...

    @property
    def is_err(self) -> bool:
        """Return ``True`` when this Result holds an error (is :class:`Err`)."""
        ...

    @property
    def value(self) -> ValueType:
        """Unwrap and return the success value.

        Raises :class:`ResultAccessError` if this Result is an :class:`Err`.
        """
        ...

    @property
    def error(self) -> ErrorType:
        """Unwrap and return the error.

        Raises :class:`ResultAccessError` if this Result is an :class:`Ok`.
        """
        ...

    def map[MappedValueType](
        self,
        fn: Callable[[ValueType], MappedValueType],
    ) -> "Result[MappedValueType, ErrorType]":
        """Transform the success value with ``fn``, passing errors through unchanged.

        This is the Functor map — ``fmap`` in Haskell, ``.map`` on Scala's
        ``Option`` / ``Either``.
        """
        ...

    def map_error[MappedErrorType](
        self,
        fn: Callable[[ErrorType], MappedErrorType],
    ) -> "Result[ValueType, MappedErrorType]":
        """Transform the error with ``fn``, passing success values through unchanged."""
        ...

    def flat_map[MappedValueType](
        self,
        fn: Callable[[ValueType], "Result[MappedValueType, ErrorType]"],
    ) -> "Result[MappedValueType, ErrorType]":
        """Chain a fallible operation that itself returns a Result.

        If Ok, call ``fn`` with the value; if Err, short-circuit unchanged.
        This is Monad's bind — ``>>=`` in Haskell, ``flatMap`` in Scala.
        """
        ...

    def get_value_or(self, default: ValueType) -> ValueType:
        """Return the wrapped success value if Ok, otherwise return the provided default.

        Args:
            default: The value to return if this result is an error.

        Returns:
            The unwrapped success value if Ok; otherwise, `default`.
        """
        ...

    def get_value_or_else(
        self,
        fn: Callable[[ErrorType], ValueType],
    ) -> ValueType:
        """Return the wrapped success value if Ok, otherwise compute one from the error.

        Applies `fn` to the wrapped error (if present) to compute and return a recovery value.
        Useful for transforming or logging errors before fallback.

        Args:
            fn: A callable that accepts the error and returns a recovery value of the same type
                as the success case.

        Returns:
            The unwrapped success value if Ok; otherwise, the result of `fn(error)`.
        """
        ...

is_ok: bool property

Return True when this Result holds a success value (is :class:Ok).

is_err: bool property

Return True when this Result holds an error (is :class:Err).

value: ValueType property

Unwrap and return the success value.

Raises :class:ResultAccessError if this Result is an :class:Err.

error: ErrorType property

Unwrap and return the error.

Raises :class:ResultAccessError if this Result is an :class:Ok.

map(fn: Callable[[ValueType], MappedValueType]) -> Result[MappedValueType, ErrorType]

Transform the success value with fn, passing errors through unchanged.

This is the Functor map — fmap in Haskell, .map on Scala's
Option / Either.

Source code in src/forging_blocks/foundation/result/result.py 
47
48
49
50
51
52
53
54
55
56
def map[MappedValueType](
    self,
    fn: Callable[[ValueType], MappedValueType],
) -> "Result[MappedValueType, ErrorType]":
    """Transform the success value with ``fn``, passing errors through unchanged.

    This is the Functor map — ``fmap`` in Haskell, ``.map`` on Scala's
    ``Option`` / ``Either``.
    """
    ...

map_error(fn: Callable[[ErrorType], MappedErrorType]) -> Result[ValueType, MappedErrorType]

Transform the error with fn, passing success values through unchanged.

Source code in src/forging_blocks/foundation/result/result.py 
58
59
60
61
62
63
def map_error[MappedErrorType](
    self,
    fn: Callable[[ErrorType], MappedErrorType],
) -> "Result[ValueType, MappedErrorType]":
    """Transform the error with ``fn``, passing success values through unchanged."""
    ...

flat_map(fn: Callable[[ValueType], Result[MappedValueType, ErrorType]]) -> Result[MappedValueType, ErrorType]

Chain a fallible operation that itself returns a Result.

If Ok, call fn with the value; if Err, short-circuit unchanged.
This is Monad's bind — >>= in Haskell, flatMap in Scala.

Source code in src/forging_blocks/foundation/result/result.py 
65
66
67
68
69
70
71
72
73
74
def flat_map[MappedValueType](
    self,
    fn: Callable[[ValueType], "Result[MappedValueType, ErrorType]"],
) -> "Result[MappedValueType, ErrorType]":
    """Chain a fallible operation that itself returns a Result.

    If Ok, call ``fn`` with the value; if Err, short-circuit unchanged.
    This is Monad's bind — ``>>=`` in Haskell, ``flatMap`` in Scala.
    """
    ...

get_value_or(default: ValueType) -> ValueType

Return the wrapped success value if Ok, otherwise return the provided default.

Parameters:

Name Type Description Default
default ValueType

The value to return if this result is an error.

 required

Returns:

Type Description
ValueType

The unwrapped success value if Ok; otherwise, default.
Source code in src/forging_blocks/foundation/result/result.py 
76
77
78
79
80
81
82
83
84
85
def get_value_or(self, default: ValueType) -> ValueType:
    """Return the wrapped success value if Ok, otherwise return the provided default.

    Args:
        default: The value to return if this result is an error.

    Returns:
        The unwrapped success value if Ok; otherwise, `default`.
    """
    ...

get_value_or_else(fn: Callable[[ErrorType], ValueType]) -> ValueType

Return the wrapped success value if Ok, otherwise compute one from the error.

Applies fn to the wrapped error (if present) to compute and return a recovery value.
Useful for transforming or logging errors before fallback.

Parameters:

Name Type Description Default
fn Callable[[ErrorType], ValueType]

A callable that accepts the error and returns a recovery value of the same type
as the success case.

 required

Returns:

Type Description
ValueType

The unwrapped success value if Ok; otherwise, the result of fn(error).
Source code in src/forging_blocks/foundation/result/result.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def get_value_or_else(
    self,
    fn: Callable[[ErrorType], ValueType],
) -> ValueType:
    """Return the wrapped success value if Ok, otherwise compute one from the error.

    Applies `fn` to the wrapped error (if present) to compute and return a recovery value.
    Useful for transforming or logging errors before fallback.

    Args:
        fn: A callable that accepts the error and returns a recovery value of the same type
            as the success case.

    Returns:
        The unwrapped success value if Ok; otherwise, the result of `fn(error)`.
    """
    ...