Result
is obviously a result of some series of computations.
It might succeed with some resulting value.
Or it might return an error with some extra details.
Result
consist of two types: Success
and Failure
.
Success
represents successful operation result
and Failure
indicates that something has failed.
from returns.result import Result, Success, Failure
def find_user(user_id: int) -> Result['User', str]:
user = User.objects.filter(id=user_id)
if user.exists():
return Success(user[0])
return Failure('User was not found')
user_search_result = find_user(1)
# => Success(User{id: 1, ...})
user_search_result = find_user(0) # id 0 does not exist!
# => Failure('User was not found')
When is it useful?
When you do not want to use exceptions to break your execution scope.
Or when you do not want to use None
to represent empty values,
since it will raise TypeError
somewhere
and other None
exception-friends.
Make sure to check out how to compose container with pipe and @pipeline! Read more about them if you want to compose your containers easily.
safe
is used to convert
regular functions that can throw exceptions to functions
that return Result
type.
Supports both async and regular functions.
from returns.result import safe
@safe # Will convert type to: Callable[[int], Result[float, Exception]]
def divide(number: int) -> float:
return number / number
divide(1)
# => Success(1.0)
divide(0)
# => Failure(ZeroDivisionError)
Typing will only work correctly if decorator_plugin is used. This happens due to mypy issue.
Use Success
or Failure
together with the explicit annotation.
Python’s type system does not allow us to do much, so this is required:
def callback(arg: int) -> Result[float, int]:
return Success(float(arg))
first: Result[int, int] = Success(1)
first.bind(callback)
Otherwise it would raise a mypy
error:
first = Success(1)
first.bind(callback)
# Argument 1 to "bind" of "Result" has incompatible type
# "Callable[[int], Result[float, int]]";
# expected "Callable[[int], Result[float, NoReturn]]"
This happens because mypy
is unable to implicitly
cast NoReturn
to any other type.
Result
(inner_value)[source]¶Bases: typing.Generic
, returns.primitives.container.BaseContainer
Base class for _Failure
and _Success
.
Result
does not have
map
(function)[source]¶Abstract method to compose container with a pure function.
Result
[~_NewValueType, +_ErrorType]
bind
(function)[source]¶Abstract method to compose a container with another container.
Result
[~_NewValueType, +_ErrorType]
fix
(function)[source]¶Abstract method to compose failed container and a pure function.
This pure function should return a new state for a successful container.
Result
[~_NewValueType, +_ErrorType]
alt
(function)[source]¶Abstract method to compose failed container and a pure function.
This pure function should return a new state for a new failed container.
Result
[+_ValueType, ~_NewErrorType]
rescue
(function)[source]¶Abstract method to compose a failed container with another container.
This method is the oposite of .bind()
.
Result
[+_ValueType, ~_NewErrorType]
Success
(inner_value)[source]¶Public unit function of protected _Success type.
Result
[+_ValueType]