Result¶

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.

API Reference¶

graph TD; Success Result Failure GenericContainerTwoSlots --> Result Result --> Failure Result --> Success

class Result(inner_value)[source]¶

Bases: returns.primitives.container.GenericContainerTwoSlots

Base class for Failure and Success.

class Failure(inner_value)[source]¶

Bases: returns.result.Result

Represents a calculation which has failed.

It should contain an error code or message. To help with readability you may alternatively use the alias ‘Failure’.

map(function)[source]¶: Returns the ‘Failure’ instance that was used to call the method.

bind(function)[source]¶: Returns the ‘Failure’ instance that was used to call the method.

fix(function)[source]¶

Applies function to the inner value.

Applies ‘function’ to the contents of the ‘Success’ instance and returns a new ‘Success’ object containing the result. ‘function’ should accept a single “normal” (non-monad) argument and return a non-monad result.

rescue(function)[source]¶

Applies ‘function’ to the result of a previous calculation.

‘function’ should accept a single “normal” (non-monad) argument and return Result a ‘Failure’ or ‘Success’ type object.

value_or(default_value)[source]¶: Returns the value if we deal with ‘Success’ or default otherwise.

unwrap()[source]¶: Raises an exception, since it does not have a value inside.

failure()[source]¶: Unwraps inner error value from failed monad.

class Success(inner_value)[source]¶

Bases: returns.result.Result

Represents a calculation which has succeeded and contains the result.

To help with readability you may alternatively use the alias ‘Success’.

map(function)[source]¶

Applies function to the inner value.

bind(function)[source]¶

Applies ‘function’ to the result of a previous calculation.

‘function’ should accept a single “normal” (non-monad) argument and return Result a ‘Failure’ or ‘Success’ type object.

fix(function)[source]¶: Returns the ‘Success’ instance that was used to call the method.

rescue(function)[source]¶: Returns the ‘Success’ instance that was used to call the method.

value_or(default_value)[source]¶: Returns the value if we deal with ‘Success’ or default otherwise.

unwrap()[source]¶: Returns the unwrapped value from the inside of this monad.

failure()[source]¶: Raises an exception, since it does not have an error inside.

← Container: the concept Helper functions →