trcks.fp.monads.result

module documentation
(source)

Monadic functions for trcks.Result.

Provides utilities for functional composition of trcks.Result-returning functions.

Example

Create and process a value of type trcks.Result:

>>> import math
>>> from trcks.fp.composition import pipe
>>> from trcks.fp.monads import result as r
>>> rslt = pipe((
...     r.construct_success(-5.0),
...     r.map_success_to_result(
...             lambda x:
...                 ("success", x)
...                 if x >= 0
...                 else ("failure", "negative value")
...     ),
...     r.map_success(math.sqrt),
... ))
>>> rslt
('failure', 'negative value')

If your static type checker cannot infer the type of the argument passed to trcks.fp.composition.pipe, you can explicitly assign a type:

>>> import math
>>> from trcks import Result, Success
>>> from trcks.fp.composition import Pipeline2, pipe
>>> from trcks.fp.monads import result as r
>>> p: Pipeline2[Success[float], Result[str, float], Result[str, float]] = (
...     r.construct_success(-5.0),
...     r.map_success_to_result(
...             lambda x:
...                 ("success", x)
...                 if x >= 0
...                 else ("failure", "negative value")
...     ),
...     r.map_success(math.sqrt),
... )
>>> rslt = pipe(p)
>>> rslt
('failure', 'negative value')
Function construct_failure Create a Failure object from a value.
Function construct_success Create a Success object from a value.
Function map_failure Create function that maps Failure values to Failure values.
Function map_failure_to_result Create function that maps Failure values to Failure and Success values.
Function map_success Create function that maps Success values to Success values.
Function map_success_to_result Create function that maps Success values to Failure and Success values.
Constant _F Undocumented
Constant _F1 Undocumented
Constant _F2 Undocumented
Constant _S Undocumented
Constant _S1 Undocumented
Constant _S2 Undocumented
def construct_failure(value: _F) -> Failure[_F]: (source)

Create a Failure object from a value.

Example

>>> from trcks.fp.monads import result as r
>>> r.construct_failure(42)
('failure', 42)
Parameters
value:_FValue to be wrapped in a Failure object.
Returns
Failure[_F]A new Failure instance containing the given value.
def construct_success(value: _S) -> Success[_S]: (source)

Create a Success object from a value.

Example

>>> from trcks.fp.monads import result as r
>>> r.construct_success(42)
('success', 42)
Parameters
value:_SValue to be wrapped in a Success object.
Returns
Success[_S]A new Success instance containing the given value.
def map_failure(f: Callable[[_F1], _F2]) -> Callable[[Result[_F1, _S1]], Result[_F2, _S1]]: (source)

Create function that maps Failure values to Failure values.

Success values are left unchanged.

Example

>>> from trcks.fp.monads import result as r
>>> add_prefix_to_failure = r.map_failure(lambda s: f"Prefix: {s}")
>>> add_prefix_to_failure(("failure", "negative value"))
('failure', 'Prefix: negative value')
>>> add_prefix_to_failure(("success", 25.0))
('success', 25.0)
Parameters
f:Callable[[_F1], _F2]Function to apply to the Failure values.
Returns
Callable[[Result[_F1, _S1]], Result[_F2, _S1]]Maps Failure values to new Failure values according to the given function and leaves Success values unchanged.
def map_failure_to_result(f: Callable[[_F1], Result[_F2, _S2]]) -> Callable[[Result[_F1, _S1]], Result[_F2, _S1 | _S2]]: (source)

Create function that maps Failure values to Failure and Success values.

Success values are left unchanged.

Example

>>> from trcks.fp.monads import result as r
>>> replace_not_found_by_default_value = r.map_failure_to_result(
...     lambda s: ("success", 0.0) if s == "not found" else ("failure", s)
... )
>>> replace_not_found_by_default_value(("failure", "not found"))
('success', 0.0)
>>> replace_not_found_by_default_value(("failure", "other failure"))
('failure', 'other failure')
>>> replace_not_found_by_default_value(("success", 25.0))
('success', 25.0)
Parameters
f:Callable[[_F1], Result[_F2, _S2]]Function to apply to the Failure values.
Returns
Callable[[Result[_F1, _S1]], Result[_F2, _S1 | _S2]]Maps Failure values to Failure and Success values according to the given function and leaves Success values unchanged.
def map_success(f: Callable[[_S1], _S2]) -> Callable[[Result[_F1, _S1]], Result[_F1, _S2]]: (source)

Create function that maps Success values to Success values.

Failure values are left unchanged.

Example

>>> from trcks.fp.monads import result as r
>>> def increase(n: int) -> int:
...     return n + 1
...
>>> increase_success = r.map_success(increase)
>>> increase_success(("failure", "not found"))
('failure', 'not found')
>>> increase_success(("success", 42))
('success', 43)
Parameters
f:Callable[[_S1], _S2]Function to apply to the Success value.
Returns
Callable[[Result[_F1, _S1]], Result[_F1, _S2]]Leaves Failure values unchanged and maps Success values to new Success values according to the given function.
def map_success_to_result(f: Callable[[_S1], Result[_F2, _S2]]) -> Callable[[Result[_F1, _S1]], Result[_F1 | _F2, _S2]]: (source)

Create function that maps Success values to Failure and Success values.

Failure values are left unchanged.

Example

>>> import math
>>> from trcks import Result
>>> from trcks.fp.monads import result as r
>>> def _get_square_root(x: float) -> Result[str, float]:
...     if x < 0:
...         return "failure", "negative value"
...     return "success", math.sqrt(x)
...
>>> get_square_root = r.map_success_to_result(_get_square_root)
>>> get_square_root(("failure", "not found"))
('failure', 'not found')
>>> get_square_root(("success", -25.0))
('failure', 'negative value')
>>> get_square_root(("success", 25.0))
('success', 5.0)
Parameters
f:Callable[[_S1], Result[_F2, _S2]]Function to apply to the Success value.
Returns
Callable[[Result[_F1, _S1]], Result[_F1 | _F2, _S2]]Leaves Failure values unchanged and maps Success values to Failure and Success values according to the given function.
_F = (source)

Undocumented

Value
TypeVar('_F')
_F1 = (source)

Undocumented

Value
TypeVar('_F1')
_F2 = (source)

Undocumented

Value
TypeVar('_F2')
_S = (source)

Undocumented

Value
TypeVar('_S')
_S1 = (source)

Undocumented

Value
TypeVar('_S1')
_S2 = (source)

Undocumented

Value
TypeVar('_S2')