Make sure to get familiar with Railway oriented programming.
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
flow
or pipe!
Read more about them if you want to compose your containers easily.
Result
values can be matched using the new feature of Python 3.10,
Structural Pattern Matching,
see the example below:
from returns.result import Failure, Success, safe
@safe
def div(first_number: int, second_number: int) -> int:
return first_number // second_number
match div(1, 0):
# Matches if the result stored inside `Success` is `10`
case Success(10):
print('Result is "10"')
# Matches any `Success` instance and binds its value to the `value` variable
case Success(value):
print('Result is "{0}"'.format(value))
# Matches if the result stored inside `Failure` is `ZeroDivisionError`
case Failure(ZeroDivisionError):
print('"ZeroDivisionError" was raised')
# Matches any `Failure` instance
case Failure(_):
print('The division was a failure')
There are several useful alises for Result
type with some common values:
returns.result.ResultE
is an alias for Result[... Exception]
,
just use it when you want to work with Result
containers
that use exceptions as error type.
It is named ResultE
because it is ResultException
and ResultError
at the same time.
Typing will only work correctly if our mypy plugin is used. This happens due to mypy issue.
safe
is used to convert
regular functions that can throw exceptions to functions
that return Result
type.
Supports only regular functions.
If you need to mark async
functions as safe
,
use future_safe
instead.
>>> from returns.result import Success, safe
>>> @safe # Will convert type to: Callable[[int], Result[float, Exception]]
... def divide(number: int) -> float:
... return number / number
>>> assert divide(1) == Success(1.0)
>>> str(divide(0))
'<Failure: division by zero>'
If you want to safe handle only a set of exceptions:
>>> @safe(exceptions=(ZeroDivisionError,)) # Other exceptions will be raised
... def divide(number: int) -> float:
... if number > 10:
... raise ValueError('Too big')
... return number / number
>>> assert divide(5) == Success(1.0)
>>> assert divide(0).failure()
>>> divide(15)
Traceback (most recent call last):
...
ValueError: Too big
Use Success
or Failure
.
Alternatively returns.result.Result.from_value()
or returns.result.Result.from_failure()
.
It might be a good idea to use unit functions together with the explicit annotation. Python’s type system does not allow us to do much, so this is required:
>>> from returns.result import Result, Success
>>> def callback(arg: int) -> Result[float, int]:
... return Success(float(arg))
>>> first: Result[int, int] = Success(1)
>>> assert first.bind(callback) == Success(1.0)
Otherwise first
will have Result[int, Any]
type.
Which is okay in some situations.
You might want to sometimes use unify
Pointfree functions
instead of .bind
to compose error types together.
While .bind
enforces error type to stay the same,
unify
is designed
to return a Union
of a revious error type and a new one.
It gives an extra flexibility, but also provokes more thinking and can be problematic in some cases.
Like so:
>>> from returns.result import Result, Success, Failure
>>> from returns.pointfree import unify
>>> def div(number: int) -> Result[float, ZeroDivisionError]:
... if number:
... return Success(1 / number)
... return Failure(ZeroDivisionError('division by zero'))
>>> container: Result[int, ValueError] = Success(1)
>>> assert unify(div)(container) == Success(1.0)
>>> # => Revealed type is:
>>> # Result[float, Union[ValueError, ZeroDivisionError]]
So, that’s a way to go, if you need this composition.
We use the map
method when we’re working with pure functions, a function
is pure if it doesn’t produce any side-effect (e.g. Exceptions). On the other
hand, we use the bind
method if a function returns a Result
instance
which translates its potential side-effect into a raw value.
See the example below:
>>> import json
>>> from typing import Dict
>>> from returns.result import Failure, Result, Success, safe
>>> # `cast_to_bool` doesn't produce any side-effect
>>> def cast_to_bool(arg: int) -> bool:
... return bool(arg)
>>> # `parse_json` can produce Exceptions, so we use the `safe` decorator
>>> # to prevent any kind of exceptions
>>> @safe
... def parse_json(arg: str) -> Dict[str, str]:
... return json.loads(arg)
>>> assert Success(1).map(cast_to_bool) == Success(True)
>>> assert Success('{"example": "example"}').bind(parse_json) == Success({"example": "example"})
>>> assert Success('').bind(parse_json).alt(str) == Failure('Expecting value: line 1 column 1 (char 0)')
Bases: returns.primitives.container.BaseContainer
, returns.primitives.hkt.SupportsKindN
[Result
, returns.result._ValueType
, returns.result._ErrorType
, NoReturn
], returns.interfaces.specific.result.ResultBasedN
[returns.result._ValueType
, returns.result._ErrorType
, NoReturn
]
Base class for Failure
and Success
.
Result
does not have a public constructor.
Use Success()
and Failure()
to construct the needed values.
Success type that is used to represent the successful computation.
inner_value (+_ValueType) –
alias of returns.result.Success
Failure type that is used to represent the failed computation.
inner_value (+_ErrorType) –
alias of returns.result.Failure
Typesafe equality comparison with other Result objects.
Returns a list with stack trace when Failure()
was called.
Optional
[List
[FrameInfo
]]
Swaps value and error types.
So, values become errors and errors become values.
It is useful when you have to work with errors a lot.
And since we have a lot of .bind_
related methods
and only a single .lash
- it is easier to work with values.
>>> from returns.result import Success, Failure
>>> assert Success(1).swap() == Failure(1)
>>> assert Failure(1).swap() == Success(1)
Result
[+_ErrorType, +_ValueType]
Composes successful container with a pure function.
>>> from returns.result import Failure, Success
>>> def mappable(string: str) -> str:
... return string + 'b'
>>> assert Success('a').map(mappable) == Success('ab')
>>> assert Failure('a').map(mappable) == Failure('a')
function (Callable
[[+_ValueType], ~_NewValueType]) –
Result
[~_NewValueType, +_ErrorType]
Calls a wrapped function in a container on this container.
>>> from returns.result import Failure, Success
>>> def appliable(string: str) -> str:
... return string + 'b'
>>> assert Success('a').apply(Success(appliable)) == Success('ab')
>>> assert Failure('a').apply(Success(appliable)) == Failure('a')
>>> assert Success('a').apply(Failure(1)) == Failure(1)
>>> assert Failure(1).apply(Failure(2)) == Failure(1)
Composes successful container with a function that returns a container.
>>> from returns.result import Result, Success, Failure
>>> def bindable(arg: str) -> Result[str, str]:
... if len(arg) > 1:
... return Success(arg + 'b')
... return Failure(arg + 'c')
>>> assert Success('aa').bind(bindable) == Success('aab')
>>> assert Success('a').bind(bindable) == Failure('ac')
>>> assert Failure('a').bind(bindable) == Failure('a')
Alias for bind_result method, it is the same as bind here.
Composes failed container with a pure function to modify failure.
>>> from returns.result import Failure, Success
>>> def altable(arg: str) -> str:
... return arg + 'b'
>>> assert Success('a').alt(altable) == Success('a')
>>> assert Failure('a').alt(altable) == Failure('ab')
function (Callable
[[+_ErrorType], ~_NewErrorType]) –
Result
[+_ValueType, ~_NewErrorType]
Composes failed container with a function that returns a container.
>>> from returns.result import Result, Success, Failure
>>> def lashable(arg: str) -> Result[str, str]:
... if len(arg) > 1:
... return Success(arg + 'b')
... return Failure(arg + 'c')
>>> assert Success('a').lash(lashable) == Success('a')
>>> assert Failure('a').lash(lashable) == Failure('ac')
>>> assert Failure('aa').lash(lashable) == Success('aab')
Get value or default value.
>>> from returns.result import Failure, Success
>>> assert Success(1).value_or(2) == 1
>>> assert Failure(1).value_or(2) == 2
default_value (~_NewValueType) –
Union
[+_ValueType, ~_NewValueType]
Get value or raise exception.
>>> from returns.result import Failure, Success
>>> assert Success(1).unwrap() == 1
>>> Failure(1).unwrap()
Traceback (most recent call last):
...
returns.primitives.exceptions.UnwrapFailedError
+_ValueType
Get failed value or raise exception.
>>> from returns.result import Failure, Success
>>> assert Failure(1).failure() == 1
>>> Success(1).failure()
Traceback (most recent call last):
...
returns.primitives.exceptions.UnwrapFailedError
+_ErrorType
One more value to create success unit values.
It is useful as a united way to create a new value from any container.
>>> from returns.result import Result, Success
>>> assert Result.from_value(1) == Success(1)
You can use this method or Success()
,
choose the most convenient for you.
inner_value (~_NewValueType) –
Result
[~_NewValueType, Any
]
One more value to create failure unit values.
It is useful as a united way to create a new value from any container.
>>> from returns.result import Result, Failure
>>> assert Result.from_failure(1) == Failure(1)
You can use this method or Failure()
,
choose the most convenient for you.
inner_value (~_NewErrorType) –
Result
[Any
, ~_NewErrorType]
Creates a new Result
instance from existing Result
instance.
>>> from returns.result import Result, Failure, Success
>>> assert Result.from_result(Success(1)) == Success(1)
>>> assert Result.from_result(Failure(1)) == Failure(1)
This is a part of
returns.interfaces.specific.result.ResultBasedN
interface.
Bases: returns.result.Result
[Any
, returns.result._ErrorType
]
Represents a calculation which has failed.
It should contain an error code or message.
inner_value (+_ErrorType) –
Alias for bind method. Part of the ResultBasedN interface.
Bases: returns.result.Result
[returns.result._ValueType
, Any
]
Represents a calculation which has succeeded and contains the result.
Contains the computation value.
inner_value (+_ValueType) –
Alias for bind method. Part of the ResultBasedN interface.
Alias for a popular case when Result
has Exception
as error type.
alias of returns.result.Result
[returns.result._ValueType
, Exception
]
Decorator to convert exception-throwing function to Result
container.
Should be used with care, since it only catches Exception
subclasses.
It does not catch BaseException
subclasses.
If you need to mark async
function as safe
,
use returns.future.future_safe()
instead.
This decorator only works with sync functions. Example:
>>> from returns.result import Result, Success, safe
>>> @safe
... def might_raise(arg: int) -> float:
... return 1 / arg
>>> assert might_raise(1) == Success(1.0)
>>> assert isinstance(might_raise(0), Result.failure_type)
You can also use it with explicit exception types as the first argument:
>>> from returns.result import Result, Success, safe
>>> @safe(exceptions=(ZeroDivisionError,))
... def might_raise(arg: int) -> float:
... return 1 / arg
>>> assert might_raise(1) == Success(1.0)
>>> assert isinstance(might_raise(0), Result.failure_type)
In this case, only exceptions that are explicitly listed are going to be caught.
Similar to returns.io.impure_safe()
and returns.future.future_safe()
decorators.
function (Optional
[Callable
[[~_FuncParams], +_ValueType]]) –
exceptions (Optional
[Tuple
[Type
[Exception
], …]]) –
Union
[Callable
[[~_FuncParams], Result
[+_ValueType, Exception
]], Callable
[[Callable
[[~_FuncParams], +_ValueType]], Callable
[[~_FuncParams], Result
[+_ValueType, Exception
]]]]