Container: the concept¶

Basics¶

The main idea behind a container is that it wraps some internal state. That’s what ._inner_value is used for.

And we have several functions to create new containers based on the previous state. And we can see how this state is evolving during the execution.

Working with containers¶

We use two methods to create a new container from the previous one. bind and map.

The difference is simple:

• map works with functions that return regular value

• bind works with functions that return new container of the same type

.bind is used to literally bind two different containers together.

from returns.result import Result, Success

def may_fail(user_id: int) -> Result[int, str]:
    ...

# Can be assumed as either Success[int] or Failure[str]:
result: Result[int, str] = Success(1).bind(may_fail)

And we have .map to use containers with regular functions.

from typing import Any
from returns.result import Success, Result

def double(state: int) -> int:
    return state * 2

result: Result[int, Any] = Success(1).map(double)
# => Success(2)
result: Result[int, Any] = result.map(lambda state: state + 1)
# => Success(3)

The same work with built-in functions as well:

from returns.io import IO

IO('bytes').map(list)
# => <IO: ['b', 'y', 't', 'e', 's']>

Note:

All containers support these methods.

Railway oriented programming¶

When talking about error handling we use a concept of Railway oriented programming. It mean that our code can go on two tracks:

1. Successful one: where everything goes perfectly: HTTP requests work, database is always serving us data, parsing values does not failed

2. Failed one: where something went wrong

We can switch from track to track: we can fail something or we can rescue the situation.

from returns.result import Failure, Result

def double(state: int) -> float:
    return state * 2.0

result: Result[float, int] = Failure(1).fix(double)
# => Success(2.0)

from returns.result import Result, Failure, Success

def tolerate_exception(state: Exception) -> Result[int, Exception]:
    if isinstance(state, ZeroDivisionError):
        return Success(0)
    return Failure(state)

result: Result[int, Exception] = Failure(
    ZeroDivisionError(),
).rescue(tolerate_exception)
# => Success(0)

result2: Result[int, Exception] = Failure(
    ValueError(),
).rescue(tolerate_exception)
# => Failure(ValueError())

Not all containers support these methods.
IO cannot be fixed or rescued.

from returns.result import Failure, Success

Success(1).value_or(None)
# => 1

Success(0).unwrap()
# => 0

Failure(1).value_or(default_value=100)
# => 100

Failure(1).unwrap()
# => Traceback (most recent call last): UnwrapFailedError

Failure(1).failure()
# => 1

Success(1).failure()
# => Traceback (most recent call last): UnwrapFailedError

Not all containers support these methods.
IO cannot be unwrapped.

Immutability¶

We like to think of returns as immutable structures. You cannot mutate the inner state of the created container, because we redefine __setattr__ and __delattr__ magic methods.

You cannot also set new attributes to container instances, since we are using __slots__ for better performance and strictness.

Well, nothing is really immutable in python, but you were warned.

Type safety¶

We try to make our containers optionally type safe.

What does it mean?

1. It is still good old python, do whatever you want without mypy

2. If you are using mypy you will be notified about type violations

We also ship PEP561 compatible .pyi files together with the source code. In this case these types will be available to users when they install our application.

We also ship custom mypy plugins to overcome some existing problems, please make sure to use them, since they increase your developer experience and type-safety:

• decorator_plugin to solve untyped decorator issue

[mypy]
plugins =
  returns.contrib.mypy.decorator_plugin

You can have a look at the suggested mypy configuration in our own repository.

Composition¶

You can and should compose different containers together. Here’s the full table of compositions that make sense:

• IO[Result[A, B]] ✅

• Result[IO[A], B] ✅

• IO[Maybe[A]] ✅

• Maybe[IO[A]] ✅

• IO[IO[A]] 🚫

• Result[A, IO[A]] 🚫

• Result[Maybe[A], B] 🚫

• Result[A, Maybe[B]] 🚫

• Result[Result[A, B], C] 🚫

• Result[A, Result[B, C]] 🚫

• Maybe[Result[A, B]] 🚫

You can use converters to convert Maybe and Result containers. So, you don’t have to compose them.

Converters¶

We have several helper functions to convert containers from Maybe to Result and back again:

• maybe_to_result that converts Maybe to Result

• result_to_maybe that converts Result to Maybe

That’s how they work:

from returns.converters import maybe_to_result, result_to_maybe
from returns.maybe import Maybe
from returns.result import Result

result: Result[int, Exception]
maybe: Maybe[int] = result_to_maybe(result)
new_result: Result[int, None] = maybe_to_result(maybe)

Take a note, that type changes. Also, take a note that Success(None) will be converted to Nothing.

API Reference¶

class Container(inner_value)[source]¶

Bases: returns.primitives.container._BaseContainer

Represents a “context” in which calculations can be executed.

You won’t create ‘Container’ instances directly. Instead, sub-classes implement specific contexts. containers allow you to bind together a series of calculations while maintaining the context of that specific container.

This is an abstract class with the API declaration.

_inner_value¶

Wrapped internal immutable state.

abstract map(function)[source]¶

Applies ‘function’ to the contents of the functor.

And returns a new functor value. Works for containers that represent success. Is the opposite of fix().

abstract bind(function)[source]¶

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

And returns a new container. Works for containers that represent success. Is the opposite of rescue().

class FixableContainer[source]¶

Bases: object

Represents containers that can be fixed and rescued.

abstract fix(function)[source]¶

Applies ‘function’ to the contents of the functor.

And returns a new functor value. Works for containers that represent failure. Is the opposite of map().

abstract rescue(function)[source]¶

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

And returns a new container. Works for containers that represent failure. Is the opposite of bind().

abstract failure()[source]¶

Custom magic method to unwrap inner value from the failed container.

This method is the opposite of unwrap().

class ValueUnwrapContainer[source]¶

Bases: object

Represents containers that can unwrap and return its wrapped value.

abstract value_or(default_value)[source]¶

Forces to unwrap value from container or return a default.

abstract unwrap()[source]¶

Custom magic method to unwrap inner value from container.

Should be redefined for ones that actually have values. And for ones that raise an exception for no values.

This method is the opposite of failure().

class GenericContainerOneSlot(inner_value)[source]¶

Bases: typing.Generic, returns.primitives.container.Container

Base class for containers with one typed slot.

Use this type for generic inheritance only. Use Container as a general type for polymorphism.

class GenericContainerTwoSlots(inner_value)[source]¶

Bases: typing.Generic, returns.primitives.container.Container

Base class for containers with two typed slot.

Use this type for generic inheritance only. Use Container as a general type for polymorphism.