Skip to content

Err

err

Err variant of the Result type — represents a failed computation.

Wrap an error with Err(error) to short-circuit chains of map and
flat_map calls. This is the left side of the Either monad (the
Left in Haskell / Scala), carrying the reason the computation could not
proceed.

Err

Bases: Result[ValueType, ErrorType]

Represents a failed result, holding an error of type ErrorType.

Source code in src/forging_blocks/foundation/result/err.py 
 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
104
105
106
107
108
109
110
111
112
113
114
115
116
class Err[ValueType, ErrorType](Result[ValueType, ErrorType]):
    """Represents a failed result, holding an error of type ``ErrorType``."""

    __match_args__ = ("_error",)

    def __init__(self, error: ErrorType) -> None:
        """Wrap ``error`` as a failed ``Result``."""
        self._error = error

    def __repr__(self) -> str:
        """Return a debug-friendly repr like ``Err(error)``."""
        return f"Err({self._error!r})"

    def __str__(self) -> str:
        """Return a user-friendly string like ``Err(error)``."""
        return f"Err({self._error})"

    def __eq__(self, other: object) -> bool:
        """Two Errs are equal when their wrapped errors are equal."""
        if not isinstance(other, Err):
            return False
        other_err: ErrType = other  # type: ignore[assignment]
        return self._error == other_err._error

    def __hash__(self) -> int:
        """Hash based on the wrapped error."""
        return hash(self._error)

    @property
    def is_ok(self) -> bool:
        """Always ``False`` — this variant does not hold a success value."""
        return False

    @property
    def is_err(self) -> bool:
        """Always ``True`` — this variant holds an error."""
        return True

    @property
    def value(self) -> ValueType:
        """Raises `ResultAccessError` — there is no success value to access."""
        raise ResultAccessError.cannot_access_value()

    @property
    def error(self) -> ErrorType:
        """The wrapped error."""
        return self._error

    def map[MappedValueType](
        self,
        fn: Callable[[ValueType], MappedValueType],
    ) -> Result[MappedValueType, ErrorType]:
        """Pass through unchanged — there is no value to transform.

        This is the Functor map on the error path — the error propagates
        unchanged while ``fn`` is silently ignored.
        """
        return Err(self._error)

    def map_error[MappedErrorType](
        self,
        fn: Callable[[ErrorType], MappedErrorType],
    ) -> Result[ValueType, MappedErrorType]:
        """Apply ``fn`` to the wrapped error and wrap the result in a new Err."""
        return Err(fn(self._error))

    def flat_map[MappedValueType](
        self,
        fn: Callable[[ValueType], Result[MappedValueType, ErrorType]],
    ) -> Result[MappedValueType, ErrorType]:
        """Pass through unchanged — short-circuit the chain."""
        return Err(self._error)

    def get_value_or(self, default: ValueType) -> ValueType:
        """Return ``default`` — there is no success value.

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

        Returns:
            ``default``, since there is no success value to unwrap.
        """
        return default

    def get_value_or_else(
        self,
        fn: Callable[[ErrorType], ValueType],
    ) -> ValueType:
        """Call ``fn`` with the wrapped error to compute a fallback.

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

        Returns:
            The result of ``fn(error)``.
        """
        return fn(self._error)

is_ok: bool property

Always False — this variant does not hold a success value.

is_err: bool property

Always True — this variant holds an error.

value: ValueType property

Raises ResultAccessError — there is no success value to access.

error: ErrorType property

The wrapped error.

__init__(error: ErrorType) -> None

Wrap error as a failed Result.

Source code in src/forging_blocks/foundation/result/err.py 
24
25
26
def __init__(self, error: ErrorType) -> None:
    """Wrap ``error`` as a failed ``Result``."""
    self._error = error

__repr__() -> str

Return a debug-friendly repr like Err(error).

Source code in src/forging_blocks/foundation/result/err.py 
28
29
30
def __repr__(self) -> str:
    """Return a debug-friendly repr like ``Err(error)``."""
    return f"Err({self._error!r})"

__str__() -> str

Return a user-friendly string like Err(error).

Source code in src/forging_blocks/foundation/result/err.py 
32
33
34
def __str__(self) -> str:
    """Return a user-friendly string like ``Err(error)``."""
    return f"Err({self._error})"

__eq__(other: object) -> bool

Two Errs are equal when their wrapped errors are equal.

Source code in src/forging_blocks/foundation/result/err.py 
36
37
38
39
40
41
def __eq__(self, other: object) -> bool:
    """Two Errs are equal when their wrapped errors are equal."""
    if not isinstance(other, Err):
        return False
    other_err: ErrType = other  # type: ignore[assignment]
    return self._error == other_err._error

__hash__() -> int

Hash based on the wrapped error.

Source code in src/forging_blocks/foundation/result/err.py 
43
44
45
def __hash__(self) -> int:
    """Hash based on the wrapped error."""
    return hash(self._error)

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

Pass through unchanged — there is no value to transform.

This is the Functor map on the error path — the error propagates
unchanged while fn is silently ignored.

Source code in src/forging_blocks/foundation/result/err.py 
67
68
69
70
71
72
73
74
75
76
def map[MappedValueType](
    self,
    fn: Callable[[ValueType], MappedValueType],
) -> Result[MappedValueType, ErrorType]:
    """Pass through unchanged — there is no value to transform.

    This is the Functor map on the error path — the error propagates
    unchanged while ``fn`` is silently ignored.
    """
    return Err(self._error)

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

Apply fn to the wrapped error and wrap the result in a new Err.

Source code in src/forging_blocks/foundation/result/err.py 
78
79
80
81
82
83
def map_error[MappedErrorType](
    self,
    fn: Callable[[ErrorType], MappedErrorType],
) -> Result[ValueType, MappedErrorType]:
    """Apply ``fn`` to the wrapped error and wrap the result in a new Err."""
    return Err(fn(self._error))

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

Pass through unchanged — short-circuit the chain.

Source code in src/forging_blocks/foundation/result/err.py 
85
86
87
88
89
90
def flat_map[MappedValueType](
    self,
    fn: Callable[[ValueType], Result[MappedValueType, ErrorType]],
) -> Result[MappedValueType, ErrorType]:
    """Pass through unchanged — short-circuit the chain."""
    return Err(self._error)

get_value_or(default: ValueType) -> ValueType

Return default — there is no success value.

Parameters:

Name Type Description Default
default ValueType

The value to return when this result is an error.

 required

Returns:

Type Description
ValueType

default, since there is no success value to unwrap.
Source code in src/forging_blocks/foundation/result/err.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def get_value_or(self, default: ValueType) -> ValueType:
    """Return ``default`` — there is no success value.

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

    Returns:
        ``default``, since there is no success value to unwrap.
    """
    return default

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

Call fn with the wrapped error to compute a 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 result of fn(error).
Source code in src/forging_blocks/foundation/result/err.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
def get_value_or_else(
    self,
    fn: Callable[[ErrorType], ValueType],
) -> ValueType:
    """Call ``fn`` with the wrapped error to compute a fallback.

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

    Returns:
        The result of ``fn(error)``.
    """
    return fn(self._error)