Why¶

One of the most frequent questions Python developers ask: why would we need this?

Basically, the answer is that returns provides useful abstractions that solve some problems every developer has:

1. Maybe helps to work with None in a type-safe way

2. Result helps to work with exceptions in a type-safe way

3. IO helps to separate pure code from impure code to make your architecture better

4. Future helps to write await free code

5. RequiresContext helps to inject dependencies in a very readable, explicit, type-safe, and clean way

6. Pipelines can be used independently or together with the types above to create complex, declarative, and type-safe data pipelines

On top of that we provide useful interfaces that allows you to switch implementation on the fly. For example, you can write code that works the same way for sync and async execution flows. While being fully type-safe at the same time.

And you can write your own primitives that will solve any other problem you can possible have based on our existing or your custom interfaces.

In other words, returns unlocks insane powers of typed-functional programming to a regular Python developer.

Installation¶

returns is a pure Python library. Install it as usual:

pip install returns  # or better use poetry

Typechecking and other integrations¶

This step is optional. If you use mypy for type-checking, than you will need to configure it. We really recommend using mypy with this project though. Because we have put a lot of efforts into the typing part.

Check out our docs on mypy.

We also have built-in integrations with pytest and hypothesis. Also, there is developer tooling you might enjoy.

Theory¶

Do you want to learn new awesome concepts? Then, start reading our “Userguide”!

It has everything you need! Reading order matters.

However, this is optional. You can still use returns without a deep-dive into theory.

Building your own stuff¶

You can extend returns and build your own stuff! Particularly, you can add new interfaces, new containers, and new integrations. See this guide.

Join our chat to get help or advice.

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 a container¶

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

We have returns.interfaces.mappable.MappableN.map() to compose containers with regular functions.

Here’s how it looks:

>>> 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)
>>> assert str(result) == '<Success: 2>'

>>> result: Result[int, Any] = result.map(lambda state: state + 1)
>>> assert str(result) == '<Success: 3>'

The same works with built-in functions as well:

>>> from returns.io import IO

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

The second method is bind. It is a bit different. We pass a function that returns another container to it. returns.interfaces.bindable.BindableN.bind() is used to literally bind two different containers together.

Here’s how it looks:

from returns.result import Result, Success

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

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

You can read more about methods that some other containers support and interfaces behind them.

Instantiating a container¶

All returns.interfaces.applicative.ApplicativeN containers support special .from_value method to construct a new container from a raw value.

>>> from returns.result import Result
>>> assert str(Result.from_value(1)) == '<Success: 1>'

There are also other methods in other interfaces. For example, here are some of them:

• returns.interfaces.specific.maybe.MaybeLikeN.from_optional() creates a value from Optional value

>>> from returns.maybe import Maybe, Some, Nothing
>>> assert Maybe.from_optional(1) == Some(1)
>>> assert Maybe.from_optional(None) == Nothing

• returns.interfaces.failable.DiverseFailableN.from_failure() creates a failing container from a value

>>> from returns.result import Result, Failure
>>> assert Result.from_failure(1) == Failure(1)

There are many other constructors! Check out concrete types and their interfaces.

Working with multiple containers¶

>>> def sum_two_numbers(first: int, second: int) -> int:
...     return first + second

>>> from returns.io import IO

>>> one = IO(1)
>>> two = IO(2)

>>> from returns.curry import curry
>>> from returns.io import IO

>>> @curry
... def sum_two_numbers(first: int, second: int) -> int:
...     return first + second

>>> one = IO(1)
>>> two = IO(2)
>>> assert two.apply(one.apply(IO(sum_two_numbers))) == IO(3)

>>> from returns.curry import partial

>>> one = IO(1)
>>> two = IO(2)
>>> assert two.apply(one.apply(
...     IO(lambda x: partial(sum_two_numbers, x)),
... )) == IO(3)

>>> one = IO(1)
>>> two = IO(2)
>>> assert two.apply(one.apply(
...     IO(lambda x: lambda y: sum_two_numbers(x, y)),
... )) == IO(3)

>>> import random
>>> from returns.io import IO

>>> def random_number() -> IO[int]:
...     return IO(2)  # Example, basically alias of ``random.randint(1, 5)``

>>> numbers = [random_number() for _ in range(10)]
>>> assert len(numbers) == 10
>>> assert all(isinstance(number, IO) for number in numbers)

>>> from typing import Callable
>>> from returns.iterables import Fold

>>> def sum_two_numbers(first: int) -> Callable[[int], int]:
...     return lambda second: first + second

>>> assert Fold.loop(
...     numbers,  # let's loop on our ``IO`` values
...     IO(0),  # starting from ``0`` value
...     sum_two_numbers,  # and getting the sum of each two numbers in a loop
... ) == IO(20)

>>> assert Fold.loop(
...     numbers,
...     IO(5),  # now we will start from ``5``, not ``0`
...     sum_two_numbers,
... ) == IO(25)

>>> from typing import List
>>> from returns.maybe import Maybe, Some, Nothing, maybe

>>> source = {'a': 1, 'b': 2}
>>> fetched_values: List[Maybe[int]] = [
...     maybe(source.get)(key)
...     for key in ('a', 'b')
... ]

>>> from returns.iterables import Fold

>>> assert Fold.collect(fetched_values, Some(())) == Some((1, 2))

>>> fetched_values: List[Maybe[int]] = [
...     maybe(source.get)(key)
...     for key in ('a', 'c')  # 'c' is missing!
... ]
>>> assert Fold.collect(fetched_values, Some(())) == Nothing

>>> fetched_values: Maybe[int] = [
...     maybe(source.get)(key)
...     for key in ('a', 'c')  # 'c' is missing!
... ]
>>> assert Fold.collect_all(fetched_values, Some(())) == Some((1,))

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.

We also provide returns.primitives.types.Immutable mixin that users can use to quickly make their classes immutable.

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 level:

Check out our docs on using our mypy plugins.

Further reading¶

• Railway oriented programming

API Reference¶

BaseContainer is a base class for all other containers. It defines some basic things like representation, hashing, pickling, etc.

class BaseContainer(inner_value)[source]¶

Bases: Immutable

Utility class to provide all needed magic methods to the context.

__slots__ = ('_inner_value',)¶

__init__(inner_value)[source]¶

Wraps the given value in the Container.

‘value’ is any arbitrary value of any type including functions.

__repr__()[source]¶

Used to display details of object.

Return type:

str

__eq__(other)[source]¶

Used to compare two ‘Container’ objects.

Parameters:

other (Any) –

Return type:

bool

__hash__()[source]¶

Used to use this value as a key.

Return type:

int

__getstate__()[source]¶

That’s how this object will be pickled.

Return type:

_PickleState

__setstate__(state)[source]¶

Loading state from pickled data.

Parameters:

state (Union[_PickleState, Any]) –

Return type:

None

__abstractmethods__ = frozenset({})¶

__annotations__ = {'_inner_value': typing.Any}¶

__module__ = 'returns.primitives.container'¶

container_equality(self, other)[source]¶

Function to compare similar containers.

Compares both their types and their inner values.

Parameters:

• self (KindN[TypeVar(_EqualType, bound= Equable), Any, Any, Any]) –

• other (KindN[TypeVar(_EqualType, bound= Equable), Any, Any, Any]) –

Return type:

bool

Error handling¶

When talking about error handling we use a concept of Railway oriented programming. It means that flow of our program has two tracks:

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

2. Failed one: where something went wrong

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

>>> from returns.result import Failure
>>> assert Failure(1).alt(str) == Failure('1')

>>> 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)

>>> value: Result[int, Exception] = Failure(ZeroDivisionError())
>>> result: Result[int, Exception] = value.lash(tolerate_exception)
>>> assert result == Success(0)

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

from returns.result import Result

first: Result[int, int]
second: Result[int, int]

reveal_type(first.map(str))
# => Result[str, int]

reveal_type(second.alt(str))
# => Result[int, str]

Unwrapping values¶

And we have two more functions to unwrap inner state of containers into a regular types:

• .unwrap returns a value if it is possible, raises returns.primitives.exceptions.UnwrapFailedError otherwise

>>> from returns.result import Failure, Success
>>> from returns.maybe import Some, Nothing

>>> assert Success(1).value_or(None) == 1
>>> assert Some(0).unwrap() == 0

>>> Failure(1).unwrap()
Traceback (most recent call last):
  ...
returns.primitives.exceptions.UnwrapFailedError

>>> Nothing.unwrap()
Traceback (most recent call last):
  ...
returns.primitives.exceptions.UnwrapFailedError

For failing containers you can use returns.interfaces.unwrappable.Unwrapable.failure() to unwrap the failed state:

>>> assert Failure(1).failure() == 1
>>> Success(1).failure()
Traceback (most recent call last):
  ...
returns.primitives.exceptions.UnwrapFailedError

Be careful, since this method will raise an exception when you try to .failure() a successful container.

>>> from returns.result import Success, Failure
>>> assert Success(1).value_or(None) == 1
>>> assert Failure(1).value_or(None) is None

Further reading¶

• Railway oriented programming in F#

• Against Railway-Oriented Programming

Regular types¶

We can start with the very basic example. Let’s say we have a function that transforms type A into a type B. These types A and B can be some specific ones, for example:

>>> def from_a_to_b(arg: int) -> str:
...      return str(arg)

>>> assert from_a_to_b(1) == '1'

That’s what we already know and use. Let’s scale things up!

Generics¶

The next thing we can do with types is to write generic types. What are generic types? Basically, they are some types that contain other types inside. Like List[int] is a list of integers: [1, 2, 3]. We know that List[int] has a shape of a list and contents of int.

We can also write functions that work with generics:

>>> from typing import List

>>> def all_to_str(arg: List[int]) -> List[str]:
...     return [str(item) for item in arg]

>>> assert all_to_str([1, 2]) == ['1', '2']

There’s one more thing about generics we want to notice at this point. Different generics do have different numbers of type arguments:

• List has a single type argument: List[Value] or Maybe[Value]

• Dict has two type arguments: Dict[Key, Value] or Result[Value, Error]

• Generator has three type arguments: Generator[Yield, Send, Return] or RequiresContextResult[Value, Error, Env]

That’s what we call a kind. So, List and Maybe have a kind of 1, Dict and Result have kind of 2, Generator and RequiresContextResult have a kind of 3.

So, let’s go one level further.

Operations on generics¶

Let’s say you have a function that copies all values of a passed argument. We can define this function as:

>>> from typing import TypeVar
>>> ValueType = TypeVar('ValueType')

>>> def copy(arg: ValueType) -> ValueType:
...    ...

This function can work with any type. It receives something and then returns the same value back. That’s the whole point of copying!

But, there are different functions, that do different things with types. For example, we can write a function that converts a value inside any Container1 (a base class for all our containers) from int to str:

We can also write functions that work with generics:

>>> from returns.interfaces.container import Container1

>>> def to_str(container: Container1[int]) -> Container1[str]:
...     return container.map(str)

And here’s how it can be used:

>>> from returns.maybe import Maybe
>>> from returns.io import IO

>>> assert to_str(Maybe.from_value(1)) == Maybe.from_value('1')
>>> assert to_str(IO.from_value(1)) == IO.from_value('1')

It works just fine! But! It has a very important thing inside. All calls to to_str will return Container1 type, not something specific:

reveal_type(to_str(Maybe.from_value(1)))  # Container1[str]
reveal_type(to_str(IO.from_value(1)))     # Container1[str]

But, we know that this is not true. When we pass a Maybe in - we get the Maybe back. When we pass a IO in - we get the IO back.

How can we fix this problem? With @overload!

>>> from typing import overload
>>> from returns.maybe import Maybe
>>> from returns.io import IO

>>> @overload
... def to_str(arg: Maybe[int]) -> Maybe[str]:
...    ...

>>> @overload
... def to_str(arg: IO[int]) -> IO[str]:
...    ...

We kinda fixed it! Now, our calls will reveal the correct types for these three examples:

reveal_type(to_str(Maybe.from_value(1)))  # Maybe[str]
reveal_type(to_str(IO.from_value(1)))     # IO[str]

But, there’s an important limitation with this solution: no other types are allowed in this function anymore. So, you will try to use it with any other type, it won’t be possible.

Current limitations¶

To overcome current @overload decorators limitations, we can imagine a syntax like this:

from typing import TypeVar
from returns.interfaces.container import Container1

T = TypeVar('T', bound=Container1)

def all_to_str(arg: T[int]) -> T[str]:
    ...

Sadly, this does not work. Because TypeVar cannot be used with []. We have to find some other way.

Higher Kinded Types¶

So, that’s where returns saves the day!

The main idea is that we can rewrite T[int] as Kind1[T, int]. Let’s see how it works:

>>> from returns.primitives.hkt import Kind1
>>> from returns.interfaces.container import ContainerN
>>> from typing import TypeVar

>>> T = TypeVar('T', bound=ContainerN)

>>> def to_str(container: Kind1[T, int]) -> Kind1[T, str]:
...     return container.map(str)

Now, this will work almost correctly! Why almost? Because the revealed type will be Kind1.

reveal_type(to_str(Maybe.from_value(1)))  # Kind1[Maybe, str]
reveal_type(to_str(IO.from_value(1)))     # Kind1[IO, str]

That’s not something we want. We don’t need Kind1, we need real Maybe or IO values.

The final solution is to decorate to_str with @kinded:

>>> from returns.primitives.hkt import kinded

>>> @kinded
... def to_str(container: Kind1[T, int]) -> Kind1[T, str]:
...     return container.map(str)

Now, it will be fully working:

reveal_type(to_str(Maybe.from_value(1)))  # Maybe[str]
reveal_type(to_str(IO.from_value(1)))     # IO[str]

And the thing about this approach is that it will be:

1. Fully type-safe. It works with correct interface ContainerN, returns the correct type, has correct type transformation

2. Is opened for further extension and even custom types

Kinds¶

As it was said Maybe[int], Result[str, int], and RequiresContextResult[str, int, bool] are different in terms of a number of type arguments. We support different kinds:

• Kind1[Maybe, int] is similar to Maybe[int]

• Kind2[Result, str, int] is similar to Result[str, int]

• Kind3[RequiresContextResult, str, int, bool] is similar to RequiresContextResult[str, int, bool]

You can use any of them freely.

Later you will learn how to create your own types that support kinds!

Further reading¶

• Higher Kinded Types in Python

FAQ¶

>>> from typing import TypeVar
>>> from returns.primitives.hkt import KindN, kinded
>>> from returns.interfaces.mappable import MappableN

>>> _FirstType = TypeVar('_FirstType')
>>> _SecondType = TypeVar('_SecondType')
>>> _ThirdType = TypeVar('_ThirdType')
>>> _MappableKind = TypeVar('_MappableKind', bound=MappableN)

>>> @kinded
... def works_with_interface(
...     container: KindN[_MappableKind, _FirstType, _SecondType, _ThirdType],
... ) -> KindN[_MappableKind, str, _SecondType, _ThirdType]:
...     return container.map(str)

>>> from returns.maybe import Maybe
>>> from returns.io import IO
>>> from returns.result import Success

>>> assert works_with_interface(Maybe.from_value(1)) == Maybe.from_value('1')
>>> assert works_with_interface(IO.from_value(1)) == IO.from_value('1')
>>> assert works_with_interface(Success(1)) == Success('1')

>>> from returns.maybe import Maybe

>>> @kinded
... def works_with_maybe(
...     container: KindN[Maybe, _FirstType, _SecondType, _ThirdType],
... ) -> KindN[Maybe, str, _SecondType, _ThirdType]:
...     return container.map(str)

>>> assert works_with_maybe(Maybe.from_value(1)) == Maybe.from_value('1')

API Reference¶

class KindN[source]¶

Bases: Generic[_InstanceType, _TypeArgType1, _TypeArgType2, _TypeArgType3]

Emulation support for Higher Kinded Types.

Consider KindN to be an alias of Generic type. But with some extra goodies.

KindN is the top-most type for other Kind types like Kind1, Kind2, Kind3, etc.

The only difference between them is how many type arguments they can hold. Kind1 can hold just two type arguments: Kind1[IO, int] which is almost equals to IO[int]. Kind2 can hold just two type arguments: Kind2[IOResult, int, str] which is almost equals to IOResult[int, str]. And so on.

The idea behind KindN is that one cannot write this code:

from typing import TypeVar

T = TypeVar('T')
V = TypeVar('V')

def impossible(generic: T, value: V) -> T[V]:
    return generic(value)

But, with KindN this becomes possible in a form of Kind1[T, V].

Note

To make sure it works correctly, your type has to be a subtype of KindN.

We use a custom mypy plugin to make sure types are correct. Otherwise, it is currently impossible to properly type this.

We use “emulated Higher Kinded Types” concept. Read the whitepaper: https://bit.ly/2ABACx2

KindN does not exist in runtime. It is used just for typing. There are (and must be) no instances of this type directly.

Implementation details

We didn’t use ABCMeta to disallow its creation, because we don’t want to have a possible metaclass conflict with other metaclasses. Current API allows you to mix KindN anywhere.

We allow _InstanceType of KindN to be Instance type or TypeVarType with bound=....

See also

• https://arrow-kt.io/docs/0.10/patterns/glossary/#higher-kinds

• https://github.com/gcanti/fp-ts/blob/master/docs/guides/HKT.md

• https://bow-swift.io/docs/fp-concepts/higher-kinded-types

• https://github.com/pelotom/hkts

Kind1¶

Type alias for kinds with one type argument.

alias of KindN[_InstanceType, _TypeArgType1, Any, Any]

Kind2¶

Type alias for kinds with two type arguments.

alias of KindN[_InstanceType, _TypeArgType1, _TypeArgType2, Any]

Kind3¶

Type alias for kinds with three type arguments.

alias of KindN[_InstanceType, _TypeArgType1, _TypeArgType2, _TypeArgType3]

class SupportsKindN[source]¶

Bases: KindN[_InstanceType, _TypeArgType1, _TypeArgType2, _TypeArgType3]

Base class for your containers.

Notice, that we use KindN / Kind1 to annotate values, but we use SupportsKindN / SupportsKind1 to inherit from.

Implementation details

The only thing this class does is: making sure that the resulting classes won’t have __getattr__ available during the typechecking phase.

Needless to say, that __getattr__ during runtime - never exists at all.

SupportsKind1¶

Type alias used for inheritance with one type argument.

alias of SupportsKindN[_InstanceType, _TypeArgType1, NoReturn, NoReturn]

SupportsKind2¶

Type alias used for inheritance with two type arguments.

alias of SupportsKindN[_InstanceType, _TypeArgType1, _TypeArgType2, NoReturn]

SupportsKind3¶

Type alias used for inheritance with three type arguments.

alias of SupportsKindN[_InstanceType, _TypeArgType1, _TypeArgType2, _TypeArgType3]

dekind(kind)[source]¶

Turns Kind1[IO, int] type into real IO[int] type.

Should be used when you are left with accidental KindN instance when you really want to have the real type.

Works with type arguments of any length.

We use a custom mypy plugin to make sure types are correct. Otherwise, it is currently impossible to properly type this.

In runtime it just returns the passed argument, nothing really happens:

>>> from returns.io import IO
>>> from returns.primitives.hkt import Kind1

>>> container: Kind1[IO, int] = IO(1)
>>> assert dekind(container) is container

However, please, do not use this function unless you know exactly what you are doing and why do you need it.

Parameters:

kind (KindN[TypeVar(_InstanceType, covariant=True), TypeVar(_TypeArgType1, covariant=True), TypeVar(_TypeArgType2, covariant=True), TypeVar(_TypeArgType3, covariant=True)]) –

Return type:

TypeVar(_InstanceType, covariant=True)

class Kinded(*args, **kwargs)[source]¶

Bases: Protocol[_FunctionDefType]

Protocol that tracks kinded functions calls.

We use a custom mypy plugin to make sure types are correct. Otherwise, it is currently impossible to properly type this.

kinded(function)[source]¶

Decorator to be used when you want to dekind the function’s return type.

Does nothing in runtime, just returns its argument.

We use a custom mypy plugin to make sure types are correct. Otherwise, it is currently impossible to properly type this.

Here’s an example of how it should be used:

>>> from typing import TypeVar
>>> from returns.primitives.hkt import KindN, kinded
>>> from returns.interfaces.bindable import BindableN

>>> _Binds = TypeVar('_Binds', bound=BindableN)  # just an example
>>> _Type1 = TypeVar('_Type1')
>>> _Type2 = TypeVar('_Type2')
>>> _Type3 = TypeVar('_Type3')

>>> @kinded
... def bindable_identity(
...    container: KindN[_Binds, _Type1, _Type2, _Type3],
... ) -> KindN[_Binds, _Type1, _Type2, _Type3]:
...     return container  # just do nothing

As you can see, here we annotate our return type as -> KindN[_Binds, _Type1, _Type2, _Type3], it would be true without @kinded decorator.

But, @kinded decorator dekinds the return type and infers the real type behind it:

>>> from returns.io import IO, IOResult

>>> assert bindable_identity(IO(1)) == IO(1)
>>> # => Revealed type: 'IO[int]'

>>> iores: IOResult[int, str] = IOResult.from_value(1)
>>> assert bindable_identity(iores) == iores
>>> # => Revealed type: 'IOResult[int, str]'

The difference is very clear in methods modules, like:

• Raw returns.methods.bind.internal_bind() that returns KindN instance

• User-facing returns.methods.bind.bind() that returns the container type

You must use this decorator for your own kinded functions as well.

Parameters:

function (TypeVar(_FunctionType, bound= Callable)) –

Return type:

Kinded[TypeVar(_FunctionType, bound= Callable)]

General information¶

All the non-specific interfaces (e.g. MappableN, BindableN, ApplicativeN) can have Nth types, at the maximum of three possible types. What does this mean?

MappableN interface, for example, can have one, two or three possible types. See the example below:

>>> from typing import NoReturn

>>> from returns.interfaces.mappable import (
...    MappableN, Mappable1, Mappable2, Mappable3,
... )

>>> one_type: MappableN[int, NoReturn, NoReturn]
>>> two_types: MappableN[int, str, NoReturn]
>>> three_types: MappableN[int, str, bool]

>>> # We have a shortcut for each amount of arguments to reduce the boilerplate
>>> one_type: Mappable1[int]
>>> two_types: Mappable2[int, str]
>>> three_type: Mappable3[int, str, bool]

Mappable¶

Something is considered mappable if we can map it using a function, generally map is a method that accepts a function.

An example in this library is Maybe, that implements the Mappable interface:

>>> from returns.maybe import Maybe, Some

>>> def can_be_mapped(string: str) -> str:
...     return string + '!'

>>> maybe_str: Maybe[str] = Some('example')
>>> assert maybe_str.map(can_be_mapped) == Some('example!')

MappableN interface helps us to create our own mappable container like Maybe.

>>> from typing import Callable, TypeVar

>>> from returns.interfaces.mappable import Mappable1
>>> from returns.primitives.hkt import SupportsKind1
>>> from returns.primitives.container import BaseContainer

>>> _NumberType = TypeVar('_NumberType')
>>> _NewNumberType = TypeVar('_NewNumberType')

>>> class Number(
...     BaseContainer,
...     SupportsKind1['Number', _NumberType],
...     Mappable1[_NumberType],
... ):
...     def __init__(self, inner_value: _NumberType) -> None:
...         super().__init__(inner_value)
...
...     def map(  # This method is required by Mappable
...         self,
...         function: Callable[[_NumberType], _NewNumberType]
...     ) -> 'Number[_NewNumberType]':
...         return Number(function(self._inner_value))

With our Number mappable class we can compose easily math functions with it.

>>> def my_math_function(number: int) -> int:
...     return number - 1

>>> number: Number[int] = Number(-41)
>>> assert number.map(my_math_function).map(abs) == Number(42)

>>> from returns.functions import identity

>>> mappable_number: Number[int] = Number(1)
>>> assert mappable_number.map(identity) == Number(1)

>>> from returns.functions import compose

>>> def add_one(number: int) -> int:
...     return number + 1

>>> def multiply_by_ten(number: int) -> int:
...     return number * 10

>>> mappable_number: Number[int] = Number(9)
>>> assert mappable_number.map(
...    add_one,
... ).map(
...    multiply_by_ten,
... ) == mappable_number.map(
...     compose(add_one, multiply_by_ten),
... )

Bindable¶

Bindable is something that we can bind with a function. Like Maybe, so BindableN interface will help us to create our custom bindable.

>>> from typing import Callable, TypeVar

>>> from returns.interfaces.bindable import Bindable1
>>> from returns.primitives.hkt import SupportsKind1, Kind1, dekind
>>> from returns.primitives.container import BaseContainer

>>> _NumberType = TypeVar('_NumberType')
>>> _NewNumberType = TypeVar('_NewNumberType')

>>> class Number(
...     BaseContainer,
...     SupportsKind1['Number', _NumberType],
...     Bindable1[_NumberType],
... ):
...     def __init__(self, inner_value: _NumberType) -> None:
...         super().__init__(inner_value)
...
...     def bind(  # This method is required by Bindable
...         self,
...         function: Kind1[
...             'Number',
...             Callable[[_NumberType], 'Number[_NewNumberType]'],
...         ],
...     ) -> 'Number[_NewNumberType]':
...         return dekind(function(self._inner_value))

And here’s how we can use it:

>>> def double(arg: int) -> Number[int]:
...    return Number(arg * 2)

>>> number = Number(5)
>>> assert number.bind(double) == Number(10)

Applicative¶

Something is considered applicative if it is a functor already and, moreover, we can apply another container to it and construct a new value with .from_value method.

An example in this library is Maybe, that implements the Mappable and Applicative interfaces:

>>> from returns.maybe import Maybe, Some

>>> maybe_str = Maybe.from_value('example')
>>> maybe_func = Maybe.from_value(len)  # we use function as a value!

>>> assert maybe_str.apply(maybe_func) == Some(7)

As you see, apply takes a container with a function inside and applies it to the current value inside the container.

This way we really execute Maybe.from_value(len('example')).

ApplicativeN which is a subtype of MappableN interface helps us to create our own applicative container like Maybe.

>>> from typing import Callable, TypeVar

>>> from returns.interfaces.applicative import Applicative1
>>> from returns.primitives.hkt import SupportsKind1, Kind1, dekind
>>> from returns.primitives.container import BaseContainer

>>> _NumberType = TypeVar('_NumberType')
>>> _NewNumberType = TypeVar('_NewNumberType')

>>> class Number(
...     BaseContainer,
...     SupportsKind1['Number', _NumberType],
...     Applicative1[_NumberType],
... ):
...     def __init__(self, inner_value: _NumberType) -> None:
...         super().__init__(inner_value)
...
...     def map(  # This method is required by Mappable
...         self,
...         function: Callable[[_NumberType], _NewNumberType]
...     ) -> 'Number[_NewNumberType]':
...         return Number(function(self._inner_value))
...
...     def apply(  # This method is required by Applicative
...         self,
...         container: Kind1[
...             'Number',
...             Callable[[_NumberType], _NewNumberType],
...         ],
...     ) -> 'Number[_NewNumberType]':
...         return Number.from_value(
...             dekind(container._inner_value(self._inner_value)),
...         )
...
...     @classmethod
...     def from_value(  # This method is required by Applicative
...         cls,
...         inner_value: _NewNumberType,
...     ) -> 'Number[_NewNumberType]':
...         return Number(inner_value)

With our Number mappable class we can compose easily math functions with it.

>>> def my_math_function(number: int) -> int:
...     return number - 1

>>> number = Number(3)
>>> number_function = Number.from_value(my_math_function)

>>> assert number.apply(number_function) == Number(2)

>>> from returns.functions import identity

>>> applicative_number: Number[int] = Number(1)
>>> assert applicative_number.apply(
...     applicative_number.from_value(identity),
... ) == Number(1)

>>> def function(arg: int) -> int:
...     return arg + 1

>>> raw_value = 5

>>> assert Number.from_value(raw_value).apply(
...     Number.from_value(function),
... ) == Number.from_value(function).apply(
...     Number.from_value(lambda inner: inner(raw_value)),
... )

>>> def function(arg: int) -> int:
...     return arg + 1

>>> raw_value = 5

>>> assert Number.from_value(
...     function(raw_value),
... ) == Number.from_value(raw_value).apply(
...     Number.from_value(function),
... )

>>> from returns.functions import compose

>>> def first(arg: int) -> int:
...     return arg * 2

>>> def second(arg: int) -> int:
...     return arg + 1

>>> instance = Number(5)
>>> assert instance.apply(
...     Number.from_value(compose(first, second)),
... ) == instance.apply(
...     Number.from_value(first),
... ).apply(
...     Number.from_value(second),
... )

Container¶

ContainerN is a central piece of our library. It is an interface that combines ApplicativeN and BindableN together.

So, in other words: Container is an Apllicative that you can bind!

>>> from typing import Callable, TypeVar

>>> from returns.interfaces.container import Container1
>>> from returns.primitives.hkt import SupportsKind1, Kind1, dekind
>>> from returns.primitives.container import BaseContainer

>>> _NumberType = TypeVar('_NumberType')
>>> _NewNumberType = TypeVar('_NewNumberType')

>>> class Number(
...     BaseContainer,
...     SupportsKind1['Number', _NumberType],
...     Container1[_NumberType],
... ):
...     def __init__(self, inner_value: _NumberType) -> None:
...         super().__init__(inner_value)
...
...     def map(  # This method is required by Mappable
...         self,
...         function: Callable[[_NumberType], _NewNumberType]
...     ) -> 'Number[_NewNumberType]':
...         return Number(function(self._inner_value))
...
...     def bind(  # This method is required by Bindable
...         self,
...         function: Kind1[
...             'Number',
...             Callable[[_NumberType], 'Number[_NewNumberType]'],
...         ],
...     ) -> 'Number[_NewNumberType]':
...         return dekind(function(self._inner_value))
...
...     def apply(  # This method is required by Applicative
...         self,
...         container: Kind1[
...             'Number',
...             Callable[[_NumberType], _NewNumberType],
...         ],
...     ) -> 'Number[_NewNumberType]':
...         return Number.from_value(
...             container._inner_value(self._inner_value),
...         )
...
...     @classmethod
...     def from_value(  # This method is required by Applicative
...         cls,
...         inner_value: _NewNumberType,
...     ) -> 'Number[_NewNumberType]':
...         return Number(inner_value)

This code gives us an opportunity to use Number with map, apply, and bind as we already did in the examples above.

>>> def can_be_bound(value: int) -> Number[int]:
...     return Number(value)

>>> assert Number.from_value(5).bind(can_be_bound) == can_be_bound(5)

>>> number = Number(2)
>>> assert number.bind(Number) == Number(2)

>>> def minus_one(arg: int) -> Number[int]:
...     return Number(arg - 1)

>>> def half(arg: int) -> Number[int]:
...     return Number(arg // 2)

>>> number = Number(9)
>>> assert number.bind(minus_one).bind(half) == number.bind(
...    lambda value: minus_one(value).bind(half),
... )

More!¶

We have way more interfaces with different features! We have covered all of them in the technical docs.

So, use them to enforce type-safety of your own containers.

FAQ¶

>>> def can_be_mapped(string: str) -> str:
...     return string

>>> from returns.maybe import Maybe

>>> def can_be_bound(string: str) -> Maybe[str]:
...     return Some(string + '!')

>>> import anyio
>>> from returns.future import FutureResult
>>> from returns.interfaces.specific.future_result import FutureResultBasedN
>>> from returns.interfaces.specific.ioresult import (
...    IOResultBasedN,
...    IOResultLikeN,
... )
>>> from returns.interfaces.specific.result import ResultLikeN, ResultBasedN
>>> from returns.io import IOSuccess, IOResult
>>> from returns.result import Success, Result

>>> async def coro(arg: int) -> Result[int, str]:
...     return Success(arg + 1)

>>> # `result_like` does not have the result we want (Result[int, str])
>>> # it's just the intention of having one,
>>> # we have to await it to get the real result
>>> result_like: FutureResult[int, str] = FutureResult(coro(1))
>>> assert isinstance(result_like, FutureResultBasedN)
>>> assert isinstance(result_like, IOResultLikeN)
>>> assert isinstance(result_like, ResultLikeN)

>>> # `anyio.run(...)` will await our coroutine and give the real result to us
>>> result: IOResult[int, str] = anyio.run(result_like.awaitable)
>>> assert isinstance(result, IOResultBasedN)
>>> assert isinstance(result, ResultLikeN)

>>> # Compare it with the real result:
>>> assert isinstance(Success(1), ResultBasedN)

API Reference¶