Interfaces

We provide a lot of generic interfaces to write our bundled and your own custom types.

These interfaces are designed:

  1. To be subclassed

  2. To provide abstract methods to implement in your own types

  3. To enforce correctness on final types

  4. To attach critical laws to be checked

We use Higher Kinded Types to define abstract methods.

Reading about interfaces will be the most useful if you plan to create your own containers.

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]

Note

Useful links before you start here:

Naming convention

We follow a very specific naming convention in our interface names.

If interface does not depend on the number of types it works with and is always the same, we name it as is. For example, Equable is always the same and does not depend on the number of type arguments. We use adjectives to name these interfaces.

Secondly, if interface depends on the number of type arguments, it is named with N suffix in the end. It would always have numeric aliases for each number of arguments supported. For example, MappableN, Mappable1, Mappable2, and Mappable3.

The last criteria we have to decided on naming is “whether this interface always the same or it can have slight variations”? That’s why we have ResultLikeN and ResultBasedN interfaces. Because ResultBasedN has two extra methods compared to ResultLikeN. We use Like suffix for interfaces that describes some similar types. We use Based suffix for interfaces that descire almost concrete types.

Laws

Some interfaces define its laws as values. These laws can be viewed as tests that are attached to the specific interface.

We are able to check them of any type that implements a given interfaces with laws by our own check_all_laws hypothesis plugin.

In this docs we are going to describe each general interface and its laws.

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)

Laws

To make sure your Mappable implementation is right, you can apply the Mappable laws on it to test.

  1. Identity Law: When we pass the identity function to the map method, the Mappable instance has to be the same, unchanged.

>>> from returns.functions import identity

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

  1. Associative Law: Given two functions, x and y, calling the map method with x function and after that calling with y function must have the same result if we compose them together.

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

Laws

To make sure your Applicative implementation is right, you can apply the Applicative laws on it to test.

  1. Identity Law: When we pass an applicative instance with wrapped identity function to the apply method, the Applicative has to be the same, unchanged.

>>> from returns.functions import identity

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

  1. Interchange Law: We can start our composition with both raw value and a function.

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

  1. Homomorphism Law: The homomorphism law says that applying a wrapped function to a wrapped value is the same as applying the function to the value in the normal way and then using .from_value on the result.

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

  1. Composition Law: Applying two functions twice is the same as applying their composition once.

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

Plus all laws from MappableN interface.

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.

Laws

To make sure other people will be able to use your implementation, it should respect three new laws.

  1. Left Identity: If we bind a function to our bindable must have to be the same result as passing the value directly to the function.

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

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

  1. Right Identity: If we pass the bindable constructor through bind must have to be the same result as instantiating the bindable on our own.

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

  1. Associative Law: Given two functions, x and y, calling the bind method with x function and after that calling with y function must have the same result if we bind with a function that passes the value to x and then bind the result with y.

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

Plus all laws from MappableN and ApplicativeN interfaces.

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.

Specific interfaces

We also have a whole package of different specific interfaces that will help you to create containers based on our internal types, like Result.

FAQ

Why do you have general and specific interfaces?

We have .interfaces.* types that can be applied to any possible type. There’s nothing they know about other types or returns package.

We also have a special .interfaces.specific package where we have types that know about other types in returns.

For example, MappableN from .interfaces only knows about .map method. It does not require anything else.

But, ResultLikeN from .interfaces.specific.result does require to have .bind_result method which relies on our Result type.

That’s the only difference. Build your own types with any of those interfaces.

Why some interfaces do not have type alias for 1 or 2 type arguments?

Some types like ResultLikeN do not have type aliases for one type argument in a form of ResultLike1.

Why does Mappable1 exists and ResultLike1 does not?

Because Mappable1 does make sense. But, ResultLike1 requiers at least two (value and error) types to exist. The same applies for ReaderLike1 and ReaderResultLike1 and ReaderResultLike2.

We don’t support type aliases for types that won’t make sense.

What’s the difference between MappableN and BindableN?

While MappableN you have to pass a pure function, like:

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

with Bindable we have to pass a function that returns another container:

>>> from returns.maybe import Maybe

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

The main difference is the return type. The consequence of this is big! BindableN allows to change the container type. While MappableN cannot do that.

So, Some.bind(function) can be evaluated to both Some and Nothing. While Some.map(function) will always stay as Some.

What is the difference between ResultLikeN and ResultBasedN?

ResultLikeN is just an intention of having a result (e.g. FutureResult), it’s not the result yet. While ResultBasedN is a concrete result (e.g. IOResult), it has the desired result value.

Because of this difference between them is why we can’t unwrap a ResultLikeN container, it does not have the real result yet.

See the example below using FutureResult to get a IOResult:

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

Note

The same difference applies to all *ResultLikeN vs *ResultBasedN (e.g. IOResultLikeN and IOResultBasedN)

API Reference

Overview

Here’s a full overview of all our interfaces:

classDiagram Lawful <|-- ApplicativeN UnwrappableResult <|-- IOResultBasedN Generic <|-- AwaitableFutureN FutureResultLikeN <|-- ReaderFutureResultLikeN IOResultLikeN <|-- ReaderIOResultLikeN ResultLikeN <|-- UnwrappableResult Generic <|-- LashableN IOLikeN <|-- FutureLikeN ResultLikeN <|-- ReaderResultLikeN AwaitableFutureN <|-- FutureBasedN IOBasedN <|-- IOResultBasedN MaybeLikeN <|-- MaybeBasedN FutureLikeN <|-- FutureResultLikeN LawSpecDef <|-- _DiverseFailableLawSpec ReaderLike2 <|-- CallableReader2 Equable <|-- UnwrappableResult Contextable <|-- CallableReader3 ReaderIOResultLikeN <|-- ReaderFutureResultLikeN CallableReader3 <|-- ReaderFutureResultBasedN ReaderIOResultLikeN <|-- ReaderIOResultBasedN IOLikeN <|-- IOBasedN SwappableN <|-- DiverseFailableN Equable <|-- IOBasedN ReaderLike3 <|-- CallableReader3 MappableN <|-- BiMappableN Lawful <|-- ReaderBased2 DiverseFailableN <|-- ResultLikeN BindableN <|-- ContainerN ContainerN <|-- IOLikeN IOResultLikeN <|-- IOResultBasedN Lawful <|-- ReaderResultBasedN ContainerN <|-- FailableN Lawful <|-- FailableN Generic <|-- Unwrappable ReaderFutureResultLikeN <|-- ReaderFutureResultBasedN IOLikeN <|-- IOResultLikeN Lawful <|-- DiverseFailableN FailableN <|-- SingleFailableN FailableN <|-- DiverseFailableN Generic <|-- Contextable CallableReader3 <|-- ReaderIOResultBasedN ResultLikeN <|-- IOResultLikeN Equable <|-- MaybeBasedN Lawful <|-- ReaderFutureResultBasedN Lawful <|-- MaybeLikeN FutureResultLikeN <|-- FutureResultBasedN CallableReader3 <|-- ReaderResultBasedN Lawful <|-- MappableN AltableN <|-- BiMappableN UnwrappableResult <|-- ResultBasedN Contextable <|-- CallableReader2 ContainerN <|-- ReaderLike2 CallableReader2 <|-- ReaderBased2 FutureBasedN <|-- FutureResultBasedN ReaderResultLikeN <|-- ReaderIOResultLikeN Unwrappable <|-- UnwrappableResult FutureLikeN <|-- FutureBasedN IOResultLikeN <|-- FutureResultLikeN LashableN <|-- FailableN LawSpecDef <|-- _FailableLawSpec LawSpecDef <|-- _SingleFailableLawSpec ReaderResultLikeN <|-- ReaderResultBasedN ReaderLike3 <|-- ReaderResultLikeN SingleFailableN <|-- MaybeLikeN Unwrappable <|-- MaybeBasedN Lawful <|-- AltableN ApplicativeN <|-- ContainerN Lawful <|-- ContainerN Generic <|-- BindableN Lawful <|-- ReaderIOResultBasedN MappableN <|-- ApplicativeN ContainerN <|-- ReaderLike3 LawSpecDef <|-- _LawSpec

Let’s review it one by one.

Equable

classDiagram Lawful <|-- Equable LawSpecDef <|-- _LawSpec
class _LawSpec[source]

Bases: returns.primitives.laws.LawSpecDef

Equality laws.

Description: https://bit.ly/34D40iT

static reflexive_law(first)[source]

Value should be equal to itself.

Parameters

first (~_EqualType) –

Return type

None

static symmetry_law(first, second)[source]

If A == B then B == A.

Parameters

  • first (~_EqualType) –

  • second (~_EqualType) –

Return type

None

static transitivity_law(first, second, third)[source]

If A == B and B == C then A == C.

Parameters

  • first (~_EqualType) –

  • second (~_EqualType) –

  • third (~_EqualType) –

Return type

None

class Equable(*args, **kwds)[source]

Bases: returns.primitives.laws.Lawful[Equable]

Interface for types that can be compared with real values.

Not all types can, because some don’t have the value at a time: - Future has to be awaited to get the value - Reader has to be called to get the value

_laws: ClassVar[Sequence[returns.primitives.laws.Law]] = (<returns.primitives.laws.Law1 object>, <returns.primitives.laws.Law2 object>, <returns.primitives.laws.Law3 object>)

Some classes and interfaces might have laws, some might not have any.

abstract equals(other)[source]

Type-safe equality check for values of the same type.

Parameters

  • self (~_EqualType) –

  • other (~_EqualType) –

Return type

bool

Mappable

classDiagram Lawful <|-- MappableN LawSpecDef <|-- _LawSpec
class _LawSpec[source]

Bases: returns.primitives.laws.LawSpecDef

Mappable or functor laws.

https://en.wikibooks.org/wiki/Haskell/The_Functor_class#The_functor_laws

static identity_law(mappable)[source]

Mapping identity over a value must return the value unchanged.

Parameters

mappable (MappableN[~_FirstType, ~_SecondType, ~_ThirdType]) –

Return type

None

static associative_law(mappable, first, second)[source]

Mapping twice or mapping a composition is the same thing.

Parameters

  • mappable (MappableN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • first (Callable[[~_FirstType], ~_NewType1]) –

  • second (Callable[[~_NewType1], ~_NewType2]) –

Return type

None

class MappableN(*args, **kwds)[source]

Bases: Generic[returns.interfaces.mappable._FirstType, returns.interfaces.mappable._SecondType, returns.interfaces.mappable._ThirdType], returns.primitives.laws.Lawful[MappableN[_FirstType, _SecondType, _ThirdType]]

Allows to chain wrapped values in containers with regular functions.

Behaves like a functor.

See also

_laws: ClassVar[Sequence[returns.primitives.laws.Law]] = (<returns.primitives.laws.Law1 object>, <returns.primitives.laws.Law3 object>)

Some classes and interfaces might have laws, some might not have any.

abstract map(function)[source]

Allows to run a pure function over a container.

Parameters

  • self (~_MappableType) –

  • function (Callable[[~_FirstType], ~_UpdatedType]) –

Return type

KindN[~_MappableType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

Mappable1

Type alias for kinds with one type argument.

alias of returns.interfaces.mappable.MappableN[returns.interfaces.mappable._FirstType, NoReturn, NoReturn]

Mappable2

Type alias for kinds with two type arguments.

alias of returns.interfaces.mappable.MappableN[returns.interfaces.mappable._FirstType, returns.interfaces.mappable._SecondType, NoReturn]

Mappable3

Type alias for kinds with three type arguments.

alias of returns.interfaces.mappable.MappableN[returns.interfaces.mappable._FirstType, returns.interfaces.mappable._SecondType, returns.interfaces.mappable._ThirdType]

Bindable

classDiagram Generic <|-- BindableN
class BindableN(*args, **kwds)[source]

Bases: Generic[returns.interfaces.bindable._FirstType, returns.interfaces.bindable._SecondType, returns.interfaces.bindable._ThirdType]

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

Bindable allows you to bind together a series of calculations while maintaining the context of that specific container.

In contrast to returns.interfaces.lashable.LashableN, works with the first type argument.

abstract bind(function)[source]

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

And returns a new container.

Parameters

  • self (~_BindableType) –

  • function (Callable[[~_FirstType], KindN[~_BindableType, ~_UpdatedType, ~_SecondType, ~_ThirdType]]) –

Return type

KindN[~_BindableType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

Bindable1

Type alias for kinds with one type argument.

alias of returns.interfaces.bindable.BindableN[returns.interfaces.bindable._FirstType, NoReturn, NoReturn]

Bindable2

Type alias for kinds with two type arguments.

alias of returns.interfaces.bindable.BindableN[returns.interfaces.bindable._FirstType, returns.interfaces.bindable._SecondType, NoReturn]

Bindable3

Type alias for kinds with three type arguments.

alias of returns.interfaces.bindable.BindableN[returns.interfaces.bindable._FirstType, returns.interfaces.bindable._SecondType, returns.interfaces.bindable._ThirdType]

Applicative

classDiagram Lawful <|-- ApplicativeN MappableN <|-- ApplicativeN LawSpecDef <|-- _LawSpec
class _LawSpec[source]

Bases: returns.primitives.laws.LawSpecDef

Applicative mappable laws.

Definition: https://bit.ly/3hC8F8E Discussion: https://bit.ly/3jffz3L

static identity_law(container)[source]

Identity law.

If we apply wrapped identity function to a container, nothing happens.

Parameters

container (ApplicativeN[~_FirstType, ~_SecondType, ~_ThirdType]) –

Return type

None

static interchange_law(raw_value, container, function)[source]

Interchange law.

Basically we check that we can start our composition with both raw_value and function.

Great explanation: https://stackoverflow.com/q/27285918/4842742

Parameters

  • raw_value (~_FirstType) –

  • container (ApplicativeN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • function (Callable[[~_FirstType], ~_NewType1]) –

Return type

None

static homomorphism_law(raw_value, container, function)[source]

Homomorphism law.

The homomorphism law says that applying a wrapped function to a wrapped value is the same as applying the function to the value in the normal way and then using .from_value on the result.

Parameters

  • raw_value (~_FirstType) –

  • container (ApplicativeN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • function (Callable[[~_FirstType], ~_NewType1]) –

Return type

None

static composition_law(container, first, second)[source]

Composition law.

Applying two functions twice is the same as applying their composition once.

Parameters

  • container (ApplicativeN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • first (Callable[[~_FirstType], ~_NewType1]) –

  • second (Callable[[~_NewType1], ~_NewType2]) –

Return type

None

class ApplicativeN(*args, **kwds)[source]

Bases: returns.interfaces.mappable.MappableN[returns.interfaces.applicative._FirstType, returns.interfaces.applicative._SecondType, returns.interfaces.applicative._ThirdType], returns.primitives.laws.Lawful[ApplicativeN[_FirstType, _SecondType, _ThirdType]]

Allows to create unit containers from raw values and to apply wrapped funcs.

See also

_laws: ClassVar[Sequence[returns.primitives.laws.Law]] = (<returns.primitives.laws.Law1 object>, <returns.primitives.laws.Law3 object>, <returns.primitives.laws.Law3 object>, <returns.primitives.laws.Law3 object>)

Some classes and interfaces might have laws, some might not have any.

abstract apply(container)[source]

Allows to apply a wrapped function over a container.

Parameters

  • self (~_ApplicativeType) –

  • container (KindN[~_ApplicativeType, Callable[[~_FirstType], ~_UpdatedType], ~_SecondType, ~_ThirdType]) –

Return type

KindN[~_ApplicativeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

abstract classmethod from_value(inner_value)[source]

Unit method to create new containers from any raw value.

Parameters

  • cls (Type[~_ApplicativeType]) –

  • inner_value (~_UpdatedType) –

Return type

KindN[~_ApplicativeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

Applicative1

Type alias for kinds with one type argument.

alias of returns.interfaces.applicative.ApplicativeN[returns.interfaces.applicative._FirstType, NoReturn, NoReturn]

Applicative2

Type alias for kinds with two type arguments.

alias of returns.interfaces.applicative.ApplicativeN[returns.interfaces.applicative._FirstType, returns.interfaces.applicative._SecondType, NoReturn]

Applicative3

Type alias for kinds with three type arguments.

alias of returns.interfaces.applicative.ApplicativeN[returns.interfaces.applicative._FirstType, returns.interfaces.applicative._SecondType, returns.interfaces.applicative._ThirdType]

Altable

classDiagram Lawful <|-- AltableN LawSpecDef <|-- _LawSpec
class _LawSpec[source]

Bases: returns.primitives.laws.LawSpecDef

Mappable or functor laws.

https://en.wikibooks.org/wiki/Haskell/The_Functor_class#The_functor_laws

static identity_law(altable)[source]

Mapping identity over a value must return the value unchanged.

Parameters

altable (AltableN[~_FirstType, ~_SecondType, ~_ThirdType]) –

Return type

None

static associative_law(altable, first, second)[source]

Mapping twice or mapping a composition is the same thing.

Parameters

  • altable (AltableN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • first (Callable[[~_SecondType], ~_NewType1]) –

  • second (Callable[[~_NewType1], ~_NewType2]) –

Return type

None

class AltableN(*args, **kwds)[source]

Bases: Generic[returns.interfaces.altable._FirstType, returns.interfaces.altable._SecondType, returns.interfaces.altable._ThirdType], returns.primitives.laws.Lawful[AltableN[_FirstType, _SecondType, _ThirdType]]

Modifies the second type argument with a pure function.

_laws: ClassVar[Sequence[returns.primitives.laws.Law]] = (<returns.primitives.laws.Law1 object>, <returns.primitives.laws.Law3 object>)

Some classes and interfaces might have laws, some might not have any.

abstract alt(function)[source]

Allows to run a pure function over a container.

Parameters

  • self (~_AltableType) –

  • function (Callable[[~_SecondType], ~_UpdatedType]) –

Return type

KindN[~_AltableType, ~_FirstType, ~_UpdatedType, ~_ThirdType]

Altable2

Type alias for kinds with two type arguments.

alias of returns.interfaces.altable.AltableN[returns.interfaces.altable._FirstType, returns.interfaces.altable._SecondType, NoReturn]

Altable3

Type alias for kinds with three type arguments.

alias of returns.interfaces.altable.AltableN[returns.interfaces.altable._FirstType, returns.interfaces.altable._SecondType, returns.interfaces.altable._ThirdType]

BiMappable

classDiagram MappableN <|-- BiMappableN AltableN <|-- BiMappableN
class BiMappableN(*args, **kwds)[source]

Bases: returns.interfaces.mappable.MappableN[returns.interfaces.bimappable._FirstType, returns.interfaces.bimappable._SecondType, returns.interfaces.bimappable._ThirdType], returns.interfaces.altable.AltableN[returns.interfaces.bimappable._FirstType, returns.interfaces.bimappable._SecondType, returns.interfaces.bimappable._ThirdType]

Allows to change both types of a container at the same time.

Uses .map to change first type and .alt to change second type.

See also

BiMappable2

Type alias for kinds with two type arguments.

alias of returns.interfaces.bimappable.BiMappableN[returns.interfaces.bimappable._FirstType, returns.interfaces.bimappable._SecondType, NoReturn]

BiMappable3

Type alias for kinds with three type arguments.

alias of returns.interfaces.bimappable.BiMappableN[returns.interfaces.bimappable._FirstType, returns.interfaces.bimappable._SecondType, returns.interfaces.bimappable._ThirdType]

Swappable

classDiagram BiMappableN <|-- SwappableN LawSpecDef <|-- _LawSpec Lawful <|-- SwappableN
class _LawSpec[source]

Bases: returns.primitives.laws.LawSpecDef

Laws for SwappableN type.

static double_swap_law(container)[source]

Swaaping container twice.

It ensure that we get the initial value back. In other words, swapping twice does nothing.

Parameters

container (SwappableN[~_FirstType, ~_SecondType, ~_ThirdType]) –

Return type

None

class SwappableN(*args, **kwds)[source]

Bases: returns.interfaces.bimappable.BiMappableN[returns.interfaces.swappable._FirstType, returns.interfaces.swappable._SecondType, returns.interfaces.swappable._ThirdType], returns.primitives.laws.Lawful[SwappableN[_FirstType, _SecondType, _ThirdType]]

Interface that allows swapping first and second type values.

_laws: ClassVar[Sequence[returns.primitives.laws.Law]] = (<returns.primitives.laws.Law1 object>,)

Some classes and interfaces might have laws, some might not have any.

abstract swap()[source]

Swaps first and second types in SwappableN.

Parameters

self (~_SwappableType) –

Return type

KindN[~_SwappableType, ~_SecondType, ~_FirstType, ~_ThirdType]

Swappable2

Type alias for kinds with two type arguments.

alias of returns.interfaces.swappable.SwappableN[returns.interfaces.swappable._FirstType, returns.interfaces.swappable._SecondType, NoReturn]

Swappable3

Type alias for kinds with three type arguments.

alias of returns.interfaces.swappable.SwappableN[returns.interfaces.swappable._FirstType, returns.interfaces.swappable._SecondType, returns.interfaces.swappable._ThirdType]

Lashable

classDiagram Generic <|-- LashableN
class LashableN(*args, **kwds)[source]

Bases: Generic[returns.interfaces.lashable._FirstType, returns.interfaces.lashable._SecondType, returns.interfaces.lashable._ThirdType]

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

Rescueable allows you to bind together a series of calculations while maintaining the context of that specific container.

In contrast to returns.interfaces.bindable.BinbdaleN, works with the second type value.

abstract lash(function)[source]

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

And returns a new container.

Parameters

  • self (~_LashableType) –

  • function (Callable[[~_SecondType], KindN[~_LashableType, ~_FirstType, ~_UpdatedType, ~_ThirdType]]) –

Return type

KindN[~_LashableType, ~_FirstType, ~_UpdatedType, ~_ThirdType]

Lashable2

Type alias for kinds with two type arguments.

alias of returns.interfaces.lashable.LashableN[returns.interfaces.lashable._FirstType, returns.interfaces.lashable._SecondType, NoReturn]

Lashable3

Type alias for kinds with three type arguments.

alias of returns.interfaces.lashable.LashableN[returns.interfaces.lashable._FirstType, returns.interfaces.lashable._SecondType, returns.interfaces.lashable._ThirdType]

Unwrappable

classDiagram Generic <|-- Unwrappable
class Unwrappable(*args, **kwds)[source]

Bases: Generic[returns.interfaces.unwrappable._FirstType, returns.interfaces.unwrappable._SecondType]

Represents containers that can unwrap and return its wrapped value.

There are no aliases or UnwrappableN for Unwrappable interface. Because it always uses two and just two types.

Not all types can be Unwrappable because we do require to raise UnwrapFailedError if unwrap is not possible.

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.

Note

As a part of the contract, failed unwrap calls must raise returns.primitives.exceptions.UnwrapFailedError exception.

This method is the opposite of failure().

Parameters

self (~_UnwrappableType) –

Return type

~_FirstType

abstract failure()[source]

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

Note

As a part of the contract, failed failure calls must raise returns.primitives.exceptions.UnwrapFailedError exception.

This method is the opposite of unwrap().

Parameters

self (~_UnwrappableType) –

Return type

~_SecondType

Container

classDiagram BindableN <|-- ContainerN ApplicativeN <|-- ContainerN LawSpecDef <|-- _LawSpec Lawful <|-- ContainerN
class _LawSpec[source]

Bases: returns.primitives.laws.LawSpecDef

Container laws.

Definition: https://wiki.haskell.org/Monad_laws Good explanation: https://bit.ly/2Qsi5re

static left_identity_law(raw_value, container, function)[source]

Left identity.

The first law states that if we take a value, put it in a default context with return and then feed it to a function by using bind, it’s the same as just taking the value and applying the function to it.

Parameters

  • raw_value (~_FirstType) –

  • container (ContainerN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • function (Callable[[~_FirstType], KindN[ContainerN, ~_NewType1, ~_SecondType, ~_ThirdType]]) –

Return type

None

static right_identity_law(container)[source]

Right identity.

The second law states that if we have a container value and we use bind to feed it to .from_value, the result is our original container value.

Parameters

container (ContainerN[~_FirstType, ~_SecondType, ~_ThirdType]) –

Return type

None

static associative_law(container, first, second)[source]

Associativity law.

The final monad law says that when we have a chain of container functions applications with bind, it shouldn’t matter how they’re nested.

Parameters

  • container (ContainerN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • first (Callable[[~_FirstType], KindN[ContainerN, ~_NewType1, ~_SecondType, ~_ThirdType]]) –

  • second (Callable[[~_NewType1], KindN[ContainerN, ~_NewType2, ~_SecondType, ~_ThirdType]]) –

Return type

None

class ContainerN(*args, **kwds)[source]

Bases: returns.interfaces.applicative.ApplicativeN[returns.interfaces.container._FirstType, returns.interfaces.container._SecondType, returns.interfaces.container._ThirdType], returns.interfaces.bindable.BindableN[returns.interfaces.container._FirstType, returns.interfaces.container._SecondType, returns.interfaces.container._ThirdType], returns.primitives.laws.Lawful[ContainerN[_FirstType, _SecondType, _ThirdType]]

Handy alias for types with .bind, .map, and .apply methods.

Should be a base class for almost any containers you write.

See also

_laws: ClassVar[Sequence[returns.primitives.laws.Law]] = (<returns.primitives.laws.Law3 object>, <returns.primitives.laws.Law1 object>, <returns.primitives.laws.Law3 object>)

Some classes and interfaces might have laws, some might not have any.

Container1

Type alias for kinds with one type argument.

alias of returns.interfaces.container.ContainerN[returns.interfaces.container._FirstType, NoReturn, NoReturn]

Container2

Type alias for kinds with two type arguments.

alias of returns.interfaces.container.ContainerN[returns.interfaces.container._FirstType, returns.interfaces.container._SecondType, NoReturn]

Container3

Type alias for kinds with three type arguments.

alias of returns.interfaces.container.ContainerN[returns.interfaces.container._FirstType, returns.interfaces.container._SecondType, returns.interfaces.container._ThirdType]

Failable

classDiagram LashableN <|-- FailableN Lawful <|-- DiverseFailableN LawSpecDef <|-- _FailableLawSpec FailableN <|-- SingleFailableN LawSpecDef <|-- _SingleFailableLawSpec FailableN <|-- DiverseFailableN SwappableN <|-- DiverseFailableN Lawful <|-- FailableN ContainerN <|-- FailableN LawSpecDef <|-- _DiverseFailableLawSpec
class _FailableLawSpec[source]

Bases: returns.primitives.laws.LawSpecDef

Failable laws.

We need to be sure that .lash won’t lash success types.

static lash_short_circuit_law(raw_value, container, function)[source]

Ensures that you cannot lash a success.

Parameters

  • raw_value (~_FirstType) –

  • container (FailableN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • function (Callable[[~_SecondType], KindN[FailableN, ~_FirstType, ~_NewFirstType, ~_ThirdType]]) –

Return type

None

class FailableN(*args, **kwds)[source]

Bases: returns.interfaces.container.ContainerN[returns.interfaces.failable._FirstType, returns.interfaces.failable._SecondType, returns.interfaces.failable._ThirdType], returns.interfaces.lashable.LashableN[returns.interfaces.failable._FirstType, returns.interfaces.failable._SecondType, returns.interfaces.failable._ThirdType], returns.primitives.laws.Lawful[FailableN[_FirstType, _SecondType, _ThirdType]]

Base type for types that can fail.

It is a raw type and should not be used directly. Use SingleFailableN and DiverseFailableN instead.

_laws: ClassVar[Sequence[returns.primitives.laws.Law]] = (<returns.primitives.laws.Law3 object>,)

Some classes and interfaces might have laws, some might not have any.

Failable2

Type alias for kinds with two type arguments.

alias of returns.interfaces.failable.FailableN[returns.interfaces.failable._FirstType, returns.interfaces.failable._SecondType, NoReturn]

Failable3

Type alias for kinds with three type arguments.

alias of returns.interfaces.failable.FailableN[returns.interfaces.failable._FirstType, returns.interfaces.failable._SecondType, returns.interfaces.failable._ThirdType]

class _SingleFailableLawSpec[source]

Bases: returns.primitives.laws.LawSpecDef

Single Failable laws.

We need to be sure that .map and .bind works correctly for empty property.

static map_short_circuit_law(container, function)[source]

Ensures that you cannot map from the empty property.

Parameters

  • container (SingleFailableN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • function (Callable[[~_FirstType], ~_NewFirstType]) –

Return type

None

static bind_short_circuit_law(container, function)[source]

Ensures that you cannot bind from the empty property.

Parameters

  • container (SingleFailableN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • function (Callable[[~_FirstType], KindN[SingleFailableN, ~_NewFirstType, ~_SecondType, ~_ThirdType]]) –

Return type

None

static apply_short_circuit_law(container, function)[source]

Ensures that you cannot apply from the empty property.

Parameters

  • container (SingleFailableN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • function (Callable[[~_FirstType], ~_NewFirstType]) –

Return type

None

class SingleFailableN(*args, **kwds)[source]

Bases: returns.interfaces.failable.FailableN[returns.interfaces.failable._FirstType, returns.interfaces.failable._SecondType, returns.interfaces.failable._ThirdType]

Base type for types that have just only one failed value.

Like Maybe types where the only failed value is Nothing.

_laws: ClassVar[Sequence[returns.primitives.laws.Law]] = (<returns.primitives.laws.Law2 object>, <returns.primitives.laws.Law2 object>, <returns.primitives.laws.Law2 object>)

Some classes and interfaces might have laws, some might not have any.

abstract property empty: returns.interfaces.failable.SingleFailableN[returns.interfaces.failable._FirstType, returns.interfaces.failable._SecondType, returns.interfaces.failable._ThirdType]

This property represents the failed value. :param self: :type self: ~_SingleFailableType

Return type

SingleFailableN[~_FirstType, ~_SecondType, ~_ThirdType]

SingleFailable2

Type alias for kinds with two types arguments.

alias of returns.interfaces.failable.SingleFailableN[returns.interfaces.failable._FirstType, returns.interfaces.failable._SecondType, NoReturn]

SingleFailable3

Type alias for kinds with three type arguments.

alias of returns.interfaces.failable.SingleFailableN[returns.interfaces.failable._FirstType, returns.interfaces.failable._SecondType, returns.interfaces.failable._ThirdType]

class _DiverseFailableLawSpec[source]

Bases: returns.primitives.laws.LawSpecDef

Diverse Failable laws.

We need to be sure that .map, .bind, .apply and .alt works correctly for both success and failure types.

static map_short_circuit_law(raw_value, container, function)[source]

Ensures that you cannot map a failure.

Parameters

  • raw_value (~_SecondType) –

  • container (DiverseFailableN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • function (Callable[[~_FirstType], ~_NewFirstType]) –

Return type

None

static bind_short_circuit_law(raw_value, container, function)[source]

Ensures that you cannot bind a failure.

See: https://wiki.haskell.org/Typeclassopedia#MonadFail

Parameters

  • raw_value (~_SecondType) –

  • container (DiverseFailableN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • function (Callable[[~_FirstType], KindN[DiverseFailableN, ~_NewFirstType, ~_SecondType, ~_ThirdType]]) –

Return type

None

static apply_short_circuit_law(raw_value, container, function)[source]

Ensures that you cannot apply a failure.

Parameters

  • raw_value (~_SecondType) –

  • container (DiverseFailableN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • function (Callable[[~_FirstType], ~_NewFirstType]) –

Return type

None

static alt_short_circuit_law(raw_value, container, function)[source]

Ensures that you cannot alt a success.

Parameters

  • raw_value (~_SecondType) –

  • container (DiverseFailableN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • function (Callable[[~_SecondType], ~_NewFirstType]) –

Return type

None

class DiverseFailableN(*args, **kwds)[source]

Bases: returns.interfaces.failable.FailableN[returns.interfaces.failable._FirstType, returns.interfaces.failable._SecondType, returns.interfaces.failable._ThirdType], returns.interfaces.swappable.SwappableN[returns.interfaces.failable._FirstType, returns.interfaces.failable._SecondType, returns.interfaces.failable._ThirdType], returns.primitives.laws.Lawful[DiverseFailableN[_FirstType, _SecondType, _ThirdType]]

Base type for types that have any failed value.

Like Result types.

_laws: ClassVar[Sequence[returns.primitives.laws.Law]] = (<returns.primitives.laws.Law3 object>, <returns.primitives.laws.Law3 object>, <returns.primitives.laws.Law3 object>, <returns.primitives.laws.Law3 object>)

Some classes and interfaces might have laws, some might not have any.

abstract classmethod from_failure(inner_value)[source]

Unit method to create new containers from any raw value.

Parameters

  • cls (Type[~_DiverseFailableType]) –

  • inner_value (~_UpdatedType) –

Return type

KindN[~_DiverseFailableType, ~_FirstType, ~_UpdatedType, ~_ThirdType]

DiverseFailable2

Type alias for kinds with two type arguments.

alias of returns.interfaces.failable.DiverseFailableN[returns.interfaces.failable._FirstType, returns.interfaces.failable._SecondType, NoReturn]

DiverseFailable3

Type alias for kinds with three type arguments.

alias of returns.interfaces.failable.DiverseFailableN[returns.interfaces.failable._FirstType, returns.interfaces.failable._SecondType, returns.interfaces.failable._ThirdType]

Maybe specific

classDiagram Equable <|-- MaybeBasedN Lawful <|-- MaybeLikeN SingleFailableN <|-- MaybeLikeN Unwrappable <|-- MaybeBasedN MaybeLikeN <|-- MaybeBasedN LawSpecDef <|-- _LawSpec
class _LawSpec[source]

Bases: returns.primitives.laws.LawSpecDef

Maybe laws.

We need to be sure that .map, .bind, .bind_optional, and .lash works correctly for both successful and failed types.

static map_short_circuit_law(container, function)[source]

Ensures that you cannot map from failures.

Parameters

  • container (MaybeLikeN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • function (Callable[[~_FirstType], ~_NewType1]) –

Return type

None

static bind_short_circuit_law(container, function)[source]

Ensures that you cannot bind from failures.

Parameters

  • container (MaybeLikeN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • function (Callable[[~_FirstType], KindN[MaybeLikeN, ~_NewType1, ~_SecondType, ~_ThirdType]]) –

Return type

None

static bind_optional_short_circuit_law(container, function)[source]

Ensures that you cannot bind from failures.

Parameters

  • container (MaybeLikeN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • function (Callable[[~_FirstType], Optional[~_NewType1]]) –

Return type

None

static lash_short_circuit_law(raw_value, container, function)[source]

Ensures that you cannot lash a success.

Parameters

  • raw_value (~_FirstType) –

  • container (MaybeLikeN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • function (Callable[[~_SecondType], KindN[MaybeLikeN, ~_FirstType, ~_NewType1, ~_ThirdType]]) –

Return type

None

static unit_structure_law(container, function)[source]

Ensures None is treated specially.

Parameters

  • container (MaybeLikeN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • function (Callable[[~_FirstType], None]) –

Return type

None

class MaybeLikeN(*args, **kwds)[source]

Bases: returns.interfaces.failable.SingleFailableN[returns.interfaces.specific.maybe._FirstType, returns.interfaces.specific.maybe._SecondType, returns.interfaces.specific.maybe._ThirdType], returns.primitives.laws.Lawful[MaybeLikeN[_FirstType, _SecondType, _ThirdType]]

Type for values that do look like a Maybe.

For example, RequiresContextMaybe should be created from this interface. Cannot be unwrapped or compared.

_laws: ClassVar[Sequence[returns.primitives.laws.Law]] = (<returns.primitives.laws.Law2 object>, <returns.primitives.laws.Law2 object>, <returns.primitives.laws.Law2 object>, <returns.primitives.laws.Law3 object>, <returns.primitives.laws.Law2 object>)

Some classes and interfaces might have laws, some might not have any.

abstract bind_optional(function)[source]

Binds a function that returns Optional values.

Parameters

  • self (~_MaybeLikeType) –

  • function (Callable[[~_FirstType], Optional[~_UpdatedType]]) –

Return type

KindN[~_MaybeLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

abstract classmethod from_optional(inner_value)[source]

Unit method to create containers from Optional value.

Parameters

  • cls (Type[~_MaybeLikeType]) –

  • inner_value (Optional[~_ValueType]) –

Return type

KindN[~_MaybeLikeType, ~_ValueType, ~_SecondType, ~_ThirdType]

MaybeLike2

Type alias for kinds with two type arguments.

alias of returns.interfaces.specific.maybe.MaybeLikeN[returns.interfaces.specific.maybe._FirstType, returns.interfaces.specific.maybe._SecondType, NoReturn]

MaybeLike3

Type alias for kinds with three type arguments.

alias of returns.interfaces.specific.maybe.MaybeLikeN[returns.interfaces.specific.maybe._FirstType, returns.interfaces.specific.maybe._SecondType, returns.interfaces.specific.maybe._ThirdType]

class MaybeBasedN(*args, **kwds)[source]

Bases: returns.interfaces.specific.maybe.MaybeLikeN[returns.interfaces.specific.maybe._FirstType, returns.interfaces.specific.maybe._SecondType, returns.interfaces.specific.maybe._ThirdType], returns.interfaces.unwrappable.Unwrappable[returns.interfaces.specific.maybe._FirstType, None], returns.interfaces.equable.Equable

Concrete interface for Maybe type.

Can be unwrapped and compared.

abstract or_else_call(function)[source]

Calls a function in case there nothing to unwrap.

Parameters

function (Callable[[], ~_ValueType]) –

Return type

Union[~_FirstType, ~_ValueType]

MaybeBased2

Type alias for kinds with two type arguments.

alias of returns.interfaces.specific.maybe.MaybeBasedN[returns.interfaces.specific.maybe._FirstType, returns.interfaces.specific.maybe._SecondType, NoReturn]

MaybeBased3

Type alias for kinds with three type arguments.

alias of returns.interfaces.specific.maybe.MaybeBasedN[returns.interfaces.specific.maybe._FirstType, returns.interfaces.specific.maybe._SecondType, returns.interfaces.specific.maybe._ThirdType]

Result specific

classDiagram Unwrappable <|-- UnwrappableResult ResultLikeN <|-- UnwrappableResult DiverseFailableN <|-- ResultLikeN UnwrappableResult <|-- ResultBasedN Equable <|-- UnwrappableResult

An interface that represents a pure computation result.

For impure result see returns.interfaces.specific.ioresult.IOResultLikeN type.

class ResultLikeN(*args, **kwds)[source]

Bases: returns.interfaces.failable.DiverseFailableN[returns.interfaces.specific.result._FirstType, returns.interfaces.specific.result._SecondType, returns.interfaces.specific.result._ThirdType]

Base types for types that looks like Result but cannot be unwrapped.

Like RequiresContextResult or FutureResult.

abstract bind_result(function)[source]

Runs Result returning function over a container.

Parameters

  • self (~_ResultLikeType) –

  • function (Callable[[~_FirstType], ForwardRef]) –

Return type

KindN[~_ResultLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

abstract classmethod from_result(inner_value)[source]

Unit method to create new containers from any raw value.

Parameters

  • cls (Type[~_ResultLikeType]) –

  • inner_value (ForwardRef) –

Return type

KindN[~_ResultLikeType, ~_ValueType, ~_ErrorType, ~_ThirdType]

ResultLike2

Type alias for kinds with two type arguments.

alias of returns.interfaces.specific.result.ResultLikeN[returns.interfaces.specific.result._FirstType, returns.interfaces.specific.result._SecondType, NoReturn]

ResultLike3

Type alias for kinds with three type arguments.

alias of returns.interfaces.specific.result.ResultLikeN[returns.interfaces.specific.result._FirstType, returns.interfaces.specific.result._SecondType, returns.interfaces.specific.result._ThirdType]

class UnwrappableResult(*args, **kwds)[source]

Bases: returns.interfaces.specific.result.ResultLikeN[returns.interfaces.specific.result._FirstType, returns.interfaces.specific.result._SecondType, returns.interfaces.specific.result._ThirdType], returns.interfaces.unwrappable.Unwrappable[returns.interfaces.specific.result._FirstUnwrappableType, returns.interfaces.specific.result._SecondUnwrappableType], returns.interfaces.equable.Equable

Intermediate type with 5 type arguments that represents unwrappable result.

It is a raw type and should not be used directly. Use ResultBasedN and IOResultBasedN instead.

class ResultBasedN(*args, **kwds)[source]

Bases: returns.interfaces.specific.result.UnwrappableResult[returns.interfaces.specific.result._FirstType, returns.interfaces.specific.result._SecondType, returns.interfaces.specific.result._ThirdType, returns.interfaces.specific.result._FirstType, returns.interfaces.specific.result._SecondType]

Base type for real Result types.

Can be unwrapped.

ResultBased2

Type alias for kinds with two type arguments.

alias of returns.interfaces.specific.result.ResultBasedN[returns.interfaces.specific.result._FirstType, returns.interfaces.specific.result._SecondType, NoReturn]

ResultBased3

Type alias for kinds with three type arguments.

alias of returns.interfaces.specific.result.ResultBasedN[returns.interfaces.specific.result._FirstType, returns.interfaces.specific.result._SecondType, returns.interfaces.specific.result._ThirdType]

IO specific

classDiagram ContainerN <|-- IOLikeN IOLikeN <|-- IOBasedN Equable <|-- IOBasedN
class IOLikeN(*args, **kwds)[source]

Bases: returns.interfaces.container.ContainerN[returns.interfaces.specific.io._FirstType, returns.interfaces.specific.io._SecondType, returns.interfaces.specific.io._ThirdType]

Represents interface for types that looks like fearless IO.

This type means that IO cannot fail. Like random numbers, date, etc. Don’t use this type for IO that can. Instead, use returns.interfaces.specific.ioresult.IOResultBasedN type.

abstract bind_io(function)[source]

Allows to apply a wrapped function over a container.

Parameters

  • self (~_IOLikeType) –

  • function (Callable[[~_FirstType], ForwardRef]) –

Return type

KindN[~_IOLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

abstract classmethod from_io(inner_value)[source]

Unit method to create new containers from successful IO.

Parameters

  • cls (Type[~_IOLikeType]) –

  • inner_value (ForwardRef) –

Return type

KindN[~_IOLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

IOLike1

Type alias for kinds with one type argument.

alias of returns.interfaces.specific.io.IOLikeN[returns.interfaces.specific.io._FirstType, NoReturn, NoReturn]

IOLike2

Type alias for kinds with two type arguments.

alias of returns.interfaces.specific.io.IOLikeN[returns.interfaces.specific.io._FirstType, returns.interfaces.specific.io._SecondType, NoReturn]

IOLike3

Type alias for kinds with three type arguments.

alias of returns.interfaces.specific.io.IOLikeN[returns.interfaces.specific.io._FirstType, returns.interfaces.specific.io._SecondType, returns.interfaces.specific.io._ThirdType]

class IOBasedN(*args, **kwds)[source]

Bases: returns.interfaces.specific.io.IOLikeN[returns.interfaces.specific.io._FirstType, returns.interfaces.specific.io._SecondType, returns.interfaces.specific.io._ThirdType], returns.interfaces.equable.Equable

Represents the base interface for types that do fearless IO.

This type means that IO cannot fail. Like random numbers, date, etc. Don’t use this type for IO that can. Instead, use returns.interfaces.specific.ioresult.IOResultBasedN type.

This interface also supports direct comparison of two values. While IOLikeN is different. It can be lazy and cannot be compared.

IOBased1

Type alias for kinds with one type argument.

alias of returns.interfaces.specific.io.IOBasedN[returns.interfaces.specific.io._FirstType, NoReturn, NoReturn]

IOBased2

Type alias for kinds with two type arguments.

alias of returns.interfaces.specific.io.IOBasedN[returns.interfaces.specific.io._FirstType, returns.interfaces.specific.io._SecondType, NoReturn]

IOBased3

Type alias for kinds with three type arguments.

alias of returns.interfaces.specific.io.IOBasedN[returns.interfaces.specific.io._FirstType, returns.interfaces.specific.io._SecondType, returns.interfaces.specific.io._ThirdType]

IOResult specific

classDiagram UnwrappableResult <|-- IOResultBasedN ResultLikeN <|-- IOResultLikeN IOBasedN <|-- IOResultBasedN IOResultLikeN <|-- IOResultBasedN IOLikeN <|-- IOResultLikeN

An interface for types that do IO and can fail.

It is a base interface for both sync and async IO stacks.

class IOResultLikeN(*args, **kwds)[source]

Bases: returns.interfaces.specific.io.IOLikeN[returns.interfaces.specific.ioresult._FirstType, returns.interfaces.specific.ioresult._SecondType, returns.interfaces.specific.ioresult._ThirdType], returns.interfaces.specific.result.ResultLikeN[returns.interfaces.specific.ioresult._FirstType, returns.interfaces.specific.ioresult._SecondType, returns.interfaces.specific.ioresult._ThirdType]

Base type for types that look like IOResult but cannot be unwrapped.

Like FutureResult or RequiresContextIOResult.

abstract bind_ioresult(function)[source]

Runs IOResult returning function over a container.

Parameters

  • self (~_IOResultLikeType) –

  • function (Callable[[~_FirstType], ForwardRef]) –

Return type

KindN[~_IOResultLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

abstract compose_result(function)[source]

Allows to compose the underlying Result with a function.

Parameters

  • self (~_IOResultLikeType) –

  • function (Callable[[ForwardRef], KindN[~_IOResultLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]]) –

Return type

KindN[~_IOResultLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

abstract classmethod from_ioresult(inner_value)[source]

Unit method to create new containers from IOResult type.

Parameters

  • cls (Type[~_IOResultLikeType]) –

  • inner_value (ForwardRef) –

Return type

KindN[~_IOResultLikeType, ~_ValueType, ~_ErrorType, ~_ThirdType]

abstract classmethod from_failed_io(inner_value)[source]

Unit method to create new containers from failed IO.

Parameters

  • cls (Type[~_IOResultLikeType]) –

  • inner_value (ForwardRef) –

Return type

KindN[~_IOResultLikeType, ~_FirstType, ~_ErrorType, ~_ThirdType]

IOResultLike2

Type alias for kinds with two type arguments.

alias of returns.interfaces.specific.ioresult.IOResultLikeN[returns.interfaces.specific.ioresult._FirstType, returns.interfaces.specific.ioresult._SecondType, NoReturn]

IOResultLike3

Type alias for kinds with three type arguments.

alias of returns.interfaces.specific.ioresult.IOResultLikeN[returns.interfaces.specific.ioresult._FirstType, returns.interfaces.specific.ioresult._SecondType, returns.interfaces.specific.ioresult._ThirdType]

class IOResultBasedN(*args, **kwds)[source]

Bases: returns.interfaces.specific.ioresult.IOResultLikeN[returns.interfaces.specific.ioresult._FirstType, returns.interfaces.specific.ioresult._SecondType, returns.interfaces.specific.ioresult._ThirdType], returns.interfaces.specific.io.IOBasedN[returns.interfaces.specific.ioresult._FirstType, returns.interfaces.specific.ioresult._SecondType, returns.interfaces.specific.ioresult._ThirdType], returns.interfaces.specific.result.UnwrappableResult[returns.interfaces.specific.ioresult._FirstType, returns.interfaces.specific.ioresult._SecondType, returns.interfaces.specific.ioresult._ThirdType, IO[_FirstType], IO[_SecondType]]

Base type for real IOResult types.

Can be unwrapped.

IOResultBased2

Type alias for kinds with two type arguments.

alias of returns.interfaces.specific.ioresult.IOResultBasedN[returns.interfaces.specific.ioresult._FirstType, returns.interfaces.specific.ioresult._SecondType, NoReturn]

IOResultBased3

Type alias for kinds with three type arguments.

alias of returns.interfaces.specific.ioresult.IOResultBasedN[returns.interfaces.specific.ioresult._FirstType, returns.interfaces.specific.ioresult._SecondType, returns.interfaces.specific.ioresult._ThirdType]

Future specific

classDiagram IOLikeN <|-- FutureLikeN AwaitableFutureN <|-- FutureBasedN FutureLikeN <|-- FutureBasedN Generic <|-- AwaitableFutureN

Represents the base interfaces for types that do fearless async operations.

This type means that Future cannot fail. Don’t use this type for async that can. Instead, use returns.interfaces.specific.future_result.FutureResultBasedN type.

class FutureLikeN(*args, **kwds)[source]

Bases: returns.interfaces.specific.io.IOLikeN[returns.interfaces.specific.future._FirstType, returns.interfaces.specific.future._SecondType, returns.interfaces.specific.future._ThirdType]

Base type for ones that does look like Future.

But at the time this is not a real Future and cannot be awaited.

abstract bind_future(function)[source]

Allows to bind Future returning function over a container.

Parameters

  • self (~_FutureLikeType) –

  • function (Callable[[~_FirstType], ForwardRef]) –

Return type

KindN[~_FutureLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

abstract bind_async_future(function)[source]

Allows to bind async Future returning function over container.

Parameters

  • self (~_FutureLikeType) –

  • function (Callable[[~_FirstType], Awaitable[ForwardRef]]) –

Return type

KindN[~_FutureLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

abstract bind_async(function)[source]

Binds async function returning the same type of container.

Parameters

  • self (~_FutureLikeType) –

  • function (Callable[[~_FirstType], Awaitable[KindN[~_FutureLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]]]) –

Return type

KindN[~_FutureLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

abstract bind_awaitable(function)[source]

Allows to bind async function over container.

Parameters

  • self (~_FutureLikeType) –

  • function (Callable[[~_FirstType], Awaitable[~_UpdatedType]]) –

Return type

KindN[~_FutureLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

abstract classmethod from_future(inner_value)[source]

Unit method to create new containers from successful Future.

Parameters

  • cls (Type[~_FutureLikeType]) –

  • inner_value (ForwardRef) –

Return type

KindN[~_FutureLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

FutureLike1

Type alias for kinds with one type argument.

alias of returns.interfaces.specific.future.FutureLikeN[returns.interfaces.specific.future._FirstType, NoReturn, NoReturn]

FutureLike2

Type alias for kinds with two type arguments.

alias of returns.interfaces.specific.future.FutureLikeN[returns.interfaces.specific.future._FirstType, returns.interfaces.specific.future._SecondType, NoReturn]

FutureLike3

Type alias for kinds with three type arguments.

alias of returns.interfaces.specific.future.FutureLikeN[returns.interfaces.specific.future._FirstType, returns.interfaces.specific.future._SecondType, returns.interfaces.specific.future._ThirdType]

class AwaitableFutureN(*args, **kwds)[source]

Bases: Generic[returns.interfaces.specific.future._FirstType, returns.interfaces.specific.future._SecondType, returns.interfaces.specific.future._ThirdType]

Type that provides the required API for Future to be async.

Should not be used directly. Use FutureBasedN instead.

abstract async awaitable()[source]

Underling logic under await expression.

Parameters

self (~_AsyncFutureType) –

Return type

IOLikeN[~_FirstType, ~_SecondType, ~_ThirdType]

AsyncFuture1

Type alias for kinds with one type argument.

alias of returns.interfaces.specific.future.AwaitableFutureN[returns.interfaces.specific.future._FirstType, NoReturn, NoReturn]

AsyncFuture2

Type alias for kinds with two type arguments.

alias of returns.interfaces.specific.future.AwaitableFutureN[returns.interfaces.specific.future._FirstType, returns.interfaces.specific.future._SecondType, NoReturn]

AsyncFuture3

Type alias for kinds with three type arguments.

alias of returns.interfaces.specific.future.AwaitableFutureN[returns.interfaces.specific.future._FirstType, returns.interfaces.specific.future._SecondType, returns.interfaces.specific.future._ThirdType]

class FutureBasedN(*args, **kwds)[source]

Bases: returns.interfaces.specific.future.FutureLikeN[returns.interfaces.specific.future._FirstType, returns.interfaces.specific.future._SecondType, returns.interfaces.specific.future._ThirdType], returns.interfaces.specific.future.AwaitableFutureN[returns.interfaces.specific.future._FirstType, returns.interfaces.specific.future._SecondType, returns.interfaces.specific.future._ThirdType]

Base type for real Future objects.

They can be awaited.

FutureBased1

Type alias for kinds with one type argument.

alias of returns.interfaces.specific.future.FutureBasedN[returns.interfaces.specific.future._FirstType, NoReturn, NoReturn]

FutureBased2

Type alias for kinds with two type arguments.

alias of returns.interfaces.specific.future.FutureBasedN[returns.interfaces.specific.future._FirstType, returns.interfaces.specific.future._SecondType, NoReturn]

FutureBased3

Type alias for kinds with three type arguments.

alias of returns.interfaces.specific.future.FutureBasedN[returns.interfaces.specific.future._FirstType, returns.interfaces.specific.future._SecondType, returns.interfaces.specific.future._ThirdType]

FutureResult specific

classDiagram IOResultLikeN <|-- FutureResultLikeN FutureLikeN <|-- FutureResultLikeN FutureBasedN <|-- FutureResultBasedN FutureResultLikeN <|-- FutureResultBasedN

Represents the base interfaces for types that do fear-some async operations.

This type means that FutureResult can (and will!) fail with exceptions.

Use this type to mark that this specific async opetaion can fail.

class FutureResultLikeN(*args, **kwds)[source]

Bases: returns.interfaces.specific.future.FutureLikeN[returns.interfaces.specific.future_result._FirstType, returns.interfaces.specific.future_result._SecondType, returns.interfaces.specific.future_result._ThirdType], returns.interfaces.specific.ioresult.IOResultLikeN[returns.interfaces.specific.future_result._FirstType, returns.interfaces.specific.future_result._SecondType, returns.interfaces.specific.future_result._ThirdType]

Base type for ones that does look like FutureResult.

But at the time this is not a real Future and cannot be awaited. It is also cannot be unwrapped, because it is not a real IOResult.

abstract bind_future_result(function)[source]

Allows to bind FutureResult functions over a container.

Parameters

  • self (~_FutureResultLikeType) –

  • function (Callable[[~_FirstType], ForwardRef]) –

Return type

KindN[~_FutureResultLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

abstract bind_async_future_result(function)[source]

Allows to bind async FutureResult functions over container.

Parameters

  • self (~_FutureResultLikeType) –

  • function (Callable[[~_FirstType], Awaitable[ForwardRef]]) –

Return type

KindN[~_FutureResultLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

abstract classmethod from_failed_future(inner_value)[source]

Creates new container from a failed Future.

Parameters

  • cls (Type[~_FutureResultLikeType]) –

  • inner_value (ForwardRef) –

Return type

KindN[~_FutureResultLikeType, ~_FirstType, ~_ErrorType, ~_ThirdType]

classmethod from_future_result(inner_value)[source]

Creates container from FutureResult instance.

Parameters

  • cls (Type[~_FutureResultLikeType]) –

  • inner_value (ForwardRef) –

Return type

KindN[~_FutureResultLikeType, ~_ValueType, ~_ErrorType, ~_ThirdType]

FutureResultLike2

Type alias for kinds with two type arguments.

alias of returns.interfaces.specific.future_result.FutureResultLikeN[returns.interfaces.specific.future_result._FirstType, returns.interfaces.specific.future_result._SecondType, NoReturn]

FutureResultLike3

Type alias for kinds with three type arguments.

alias of returns.interfaces.specific.future_result.FutureResultLikeN[returns.interfaces.specific.future_result._FirstType, returns.interfaces.specific.future_result._SecondType, returns.interfaces.specific.future_result._ThirdType]

class FutureResultBasedN(*args, **kwds)[source]

Bases: returns.interfaces.specific.future.FutureBasedN[returns.interfaces.specific.future_result._FirstType, returns.interfaces.specific.future_result._SecondType, returns.interfaces.specific.future_result._ThirdType], returns.interfaces.specific.future_result.FutureResultLikeN[returns.interfaces.specific.future_result._FirstType, returns.interfaces.specific.future_result._SecondType, returns.interfaces.specific.future_result._ThirdType]

Base type for real FutureResult objects.

They can be awaited. Still cannot be unwrapped.

FutureResultBased2

Type alias for kinds with two type arguments.

alias of returns.interfaces.specific.future_result.FutureResultBasedN[returns.interfaces.specific.future_result._FirstType, returns.interfaces.specific.future_result._SecondType, NoReturn]

FutureResultBased3

Type alias for kinds with three type arguments.

alias of returns.interfaces.specific.future_result.FutureResultBasedN[returns.interfaces.specific.future_result._FirstType, returns.interfaces.specific.future_result._SecondType, returns.interfaces.specific.future_result._ThirdType]

Reader specific

classDiagram CallableReader2 <|-- ReaderBased2 Generic <|-- Contextable ReaderLike3 <|-- CallableReader3 Lawful <|-- ReaderBased2 Contextable <|-- CallableReader2 ReaderLike2 <|-- CallableReader2 ContainerN <|-- ReaderLike2 LawSpecDef <|-- _LawSpec ContainerN <|-- ReaderLike3 Contextable <|-- CallableReader3

This module is special.

Reader does not produce ReaderLikeN interface as other containers.

Because Reader can be used with two or three type arguments: - RequiresContext[value, env] - RequiresContextResult[value, error, env]

Because the second type argument changes its meaning based on the used KindN instance, we need to have two separate interfaces for two separate use-cases: - ReaderLike2 is used for types where the second type argument is env - ReaderLike3 is used for types where the third type argument is env

We also have two methods and two poinfree helpers for bind_context composition: one for each interface.

Furthermore, Reader cannot have ReaderLike1 type, because we need both value and env types at all cases.

See also

class Contextable(*args, **kwds)[source]

Bases: Generic[returns.interfaces.specific.reader._ValueType, returns.interfaces.specific.reader._EnvType]

Special type we use as a base one for all callble Reader instances.

It only has a single method. And is a base type for every single one of them.

But, each Reader defines the return type differently. For example:

  • Reader has just _ReturnType

  • ReaderResult has Result[_FirstType, _SecondType]

  • ReaderIOResult has IOResult[_FirstType, _SecondType]

And so on.

class ReaderLike2(*args, **kwds)[source]

Bases: returns.interfaces.container.ContainerN[returns.interfaces.specific.reader._FirstType, returns.interfaces.specific.reader._SecondType, NoReturn]

Reader interface for Kind2 based types.

It has two type arguments and treats the second type argument as env type.

abstract property no_args: NoDeps

Is required to call Reader with no explicit arguments. :param self: :type self: ~_ReaderLike2Type

Return type

ForwardRef

abstract bind_context(function)[source]

Allows to apply a wrapped function over a Reader container.

Parameters

  • self (~_ReaderLike2Type) –

  • function (Callable[[~_FirstType], ForwardRef]) –

Return type

KindN[~_ReaderLike2Type, ~_UpdatedType, ~_SecondType, Any]

abstract modify_env(function)[source]

Transforms the environment before calling the container.

Parameters

  • self (~_ReaderLike2Type) –

  • function (Callable[[~_UpdatedType], ~_SecondType]) –

Return type

KindN[~_ReaderLike2Type, ~_FirstType, ~_UpdatedType, Any]

abstract classmethod ask()[source]

Returns the dependencies inside the container.

Parameters

cls (Type[~_ReaderLike2Type]) –

Return type

KindN[~_ReaderLike2Type, ~_SecondType, ~_SecondType, Any]

abstract classmethod from_context(inner_value)[source]

Unit method to create new containers from successful Reader.

Parameters

  • cls (Type[~_ReaderLike2Type]) –

  • inner_value (ForwardRef) –

Return type

KindN[~_ReaderLike2Type, ~_ValueType, ~_EnvType, Any]

class CallableReader2(*args, **kwds)[source]

Bases: returns.interfaces.specific.reader.ReaderLike2[returns.interfaces.specific.reader._FirstType, returns.interfaces.specific.reader._SecondType], returns.interfaces.specific.reader.Contextable[returns.interfaces.specific.reader._ValueType, returns.interfaces.specific.reader._EnvType]

Intermediate interface for ReaderLike2 + __call__ method.

Has 4 type variables to type Reader and __call__ independently. Since, we don’t have any other fancy ways of doing it.

Should not be used directly other than defining your own Reader interfaces.

class ReaderLike3(*args, **kwds)[source]

Bases: returns.interfaces.container.ContainerN[returns.interfaces.specific.reader._FirstType, returns.interfaces.specific.reader._SecondType, returns.interfaces.specific.reader._ThirdType]

Reader interface for Kind3 based types.

It has three type arguments and treats the third type argument as env type. The second type argument is not used here.

abstract property no_args: NoDeps

Is required to call Reader with no explicit arguments. :param self: :type self: ~_ReaderLike3Type

Return type

ForwardRef

abstract bind_context(function)[source]

Allows to apply a wrapped function over a Reader container.

Parameters

  • self (~_ReaderLike3Type) –

  • function (Callable[[~_FirstType], ForwardRef]) –

Return type

KindN[~_ReaderLike3Type, ~_UpdatedType, ~_SecondType, ~_ThirdType]

abstract modify_env(function)[source]

Transforms the environment before calling the container.

Parameters

  • self (~_ReaderLike3Type) –

  • function (Callable[[~_UpdatedType], ~_ThirdType]) –

Return type

KindN[~_ReaderLike3Type, ~_FirstType, ~_SecondType, ~_UpdatedType]

abstract classmethod ask()[source]

Returns the dependencies inside the container.

Parameters

cls (Type[~_ReaderLike3Type]) –

Return type

KindN[~_ReaderLike3Type, ~_ThirdType, ~_SecondType, ~_ThirdType]

abstract classmethod from_context(inner_value)[source]

Unit method to create new containers from successful Reader.

Parameters

  • cls (Type[~_ReaderLike3Type]) –

  • inner_value (ForwardRef) –

Return type

KindN[~_ReaderLike3Type, ~_ValueType, ~_SecondType, ~_EnvType]

class CallableReader3(*args, **kwds)[source]

Bases: returns.interfaces.specific.reader.ReaderLike3[returns.interfaces.specific.reader._FirstType, returns.interfaces.specific.reader._SecondType, returns.interfaces.specific.reader._ThirdType], returns.interfaces.specific.reader.Contextable[returns.interfaces.specific.reader._ValueType, returns.interfaces.specific.reader._EnvType]

Intermediate interface for ReaderLike3 + __call__ method.

Has 5 type variables to type Reader and __call__ independently. Since, we don’t have any other fancy ways of doing it.

Should not be used directly other than defining your own Reader interfaces.

class _LawSpec[source]

Bases: returns.primitives.laws.LawSpecDef

Concrete laws for ReaderBased2.

See: https://github.com/haskell/mtl/pull/61/files

static purity_law(container, env)[source]

Calling a Reader twice has the same result with the same env.

Parameters

  • container (ReaderBased2[~_FirstType, ~_SecondType]) –

  • env (~_SecondType) –

Return type

None

static asking_law(container, env)[source]

Asking for an env, always returns the env.

Parameters

  • container (ReaderBased2[~_FirstType, ~_SecondType]) –

  • env (~_SecondType) –

Return type

None

class ReaderBased2(*args, **kwds)[source]

Bases: returns.interfaces.specific.reader.CallableReader2[returns.interfaces.specific.reader._FirstType, returns.interfaces.specific.reader._SecondType, returns.interfaces.specific.reader._FirstType, returns.interfaces.specific.reader._SecondType], returns.primitives.laws.Lawful[ReaderBased2[_FirstType, _SecondType]]

This interface is very specific to our Reader type.

The only thing that differs from ReaderLike2 is that we know the specific types for its __call__ method.

_laws: ClassVar[Sequence[returns.primitives.laws.Law]] = (<returns.primitives.laws.Law2 object>, <returns.primitives.laws.Law2 object>)

Some classes and interfaces might have laws, some might not have any.

ReaderResult specific

classDiagram ReaderResultLikeN <|-- ReaderResultBasedN CallableReader3 <|-- ReaderResultBasedN ReaderLike3 <|-- ReaderResultLikeN ResultLikeN <|-- ReaderResultLikeN Lawful <|-- ReaderResultBasedN LawSpecDef <|-- _LawSpec
class ReaderResultLikeN(*args, **kwds)[source]

Bases: returns.interfaces.specific.reader.ReaderLike3[returns.interfaces.specific.reader_result._FirstType, returns.interfaces.specific.reader_result._SecondType, returns.interfaces.specific.reader_result._ThirdType], returns.interfaces.specific.result.ResultLikeN[returns.interfaces.specific.reader_result._FirstType, returns.interfaces.specific.reader_result._SecondType, returns.interfaces.specific.reader_result._ThirdType]

Base interface for all types that do look like ReaderResult instance.

Cannot be called.

abstract bind_context_result(function)[source]

Binds a ReaderResult returning function over a container.

Parameters

  • self (~_ReaderResultLikeType) –

  • function (Callable[[~_FirstType], ForwardRef]) –

Return type

KindN[~_ReaderResultLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

abstract classmethod from_failed_context(inner_value)[source]

Unit method to create new containers from failed Reader.

Parameters

  • cls (Type[~_ReaderResultLikeType]) –

  • inner_value (ForwardRef) –

Return type

KindN[~_ReaderResultLikeType, ~_FirstType, ~_ErrorType, ~_EnvType]

abstract classmethod from_result_context(inner_value)[source]

Unit method to create new containers from ReaderResult.

Parameters

  • cls (Type[~_ReaderResultLikeType]) –

  • inner_value (ForwardRef) –

Return type

KindN[~_ReaderResultLikeType, ~_ValueType, ~_ErrorType, ~_EnvType]

ReaderResultLike3

Type alias for kinds with three type arguments.

alias of returns.interfaces.specific.reader_result.ReaderResultLikeN[returns.interfaces.specific.reader_result._FirstType, returns.interfaces.specific.reader_result._SecondType, returns.interfaces.specific.reader_result._ThirdType]

class _LawSpec[source]

Bases: returns.primitives.laws.LawSpecDef

Concrete laws for ReaderResulBasedN.

See: https://github.com/haskell/mtl/pull/61/files

static purity_law(container, env)[source]

Calling a Reader twice has the same result with the same env.

Parameters

  • container (ReaderResultBasedN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • env (~_ThirdType) –

Return type

None

static asking_law(container, env)[source]

Asking for an env, always returns the env.

Parameters

  • container (ReaderResultBasedN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • env (~_ThirdType) –

Return type

None

class ReaderResultBasedN(*args, **kwds)[source]

Bases: returns.interfaces.specific.reader_result.ReaderResultLikeN[returns.interfaces.specific.reader_result._FirstType, returns.interfaces.specific.reader_result._SecondType, returns.interfaces.specific.reader_result._ThirdType], returns.interfaces.specific.reader.CallableReader3[returns.interfaces.specific.reader_result._FirstType, returns.interfaces.specific.reader_result._SecondType, returns.interfaces.specific.reader_result._ThirdType, Result[_FirstType, _SecondType], returns.interfaces.specific.reader_result._ThirdType], returns.primitives.laws.Lawful[ReaderResultBasedN[_FirstType, _SecondType, _ThirdType]]

This interface is very specific to our ReaderResult type.

The only thing that differs from ReaderResultLikeN is that we know the specific types for its __call__ method.

In this case the return type of __call__ is Result.

_laws: ClassVar[Sequence[returns.primitives.laws.Law]] = (<returns.primitives.laws.Law2 object>, <returns.primitives.laws.Law2 object>)

Some classes and interfaces might have laws, some might not have any.

ReaderResultBased3

Type alias for kinds with three type arguments.

alias of returns.interfaces.specific.reader_result.ReaderResultBasedN[returns.interfaces.specific.reader_result._FirstType, returns.interfaces.specific.reader_result._SecondType, returns.interfaces.specific.reader_result._ThirdType]

ReaderIOResult specific

classDiagram CallableReader3 <|-- ReaderIOResultBasedN ReaderIOResultLikeN <|-- ReaderIOResultBasedN IOResultLikeN <|-- ReaderIOResultLikeN Lawful <|-- ReaderIOResultBasedN LawSpecDef <|-- _LawSpec ReaderResultLikeN <|-- ReaderIOResultLikeN
class ReaderIOResultLikeN(*args, **kwds)[source]

Bases: returns.interfaces.specific.reader_result.ReaderResultLikeN[returns.interfaces.specific.reader_ioresult._FirstType, returns.interfaces.specific.reader_ioresult._SecondType, returns.interfaces.specific.reader_ioresult._ThirdType], returns.interfaces.specific.ioresult.IOResultLikeN[returns.interfaces.specific.reader_ioresult._FirstType, returns.interfaces.specific.reader_ioresult._SecondType, returns.interfaces.specific.reader_ioresult._ThirdType]

Base interface for all types that do look like ReaderIOResult instance.

Cannot be called.

abstract bind_context_ioresult(function)[source]

Binds a ReaderIOResult returning function over a container.

Parameters

  • self (~_ReaderIOResultLikeType) –

  • function (Callable[[~_FirstType], ForwardRef]) –

Return type

KindN[~_ReaderIOResultLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

abstract classmethod from_ioresult_context(inner_value)[source]

Unit method to create new containers from ReaderIOResult.

Parameters

  • cls (Type[~_ReaderIOResultLikeType]) –

  • inner_value (ForwardRef) –

Return type

KindN[~_ReaderIOResultLikeType, ~_ValueType, ~_ErrorType, ~_EnvType]

ReaderIOResultLike3

Type alias for kinds with three type arguments.

alias of returns.interfaces.specific.reader_ioresult.ReaderIOResultLikeN[returns.interfaces.specific.reader_ioresult._FirstType, returns.interfaces.specific.reader_ioresult._SecondType, returns.interfaces.specific.reader_ioresult._ThirdType]

class _LawSpec[source]

Bases: returns.primitives.laws.LawSpecDef

Concrete laws for ReaderIOResultBasedN.

See: https://github.com/haskell/mtl/pull/61/files

static asking_law(container, env)[source]

Asking for an env, always returns the env.

Parameters

  • container (ReaderIOResultBasedN[~_FirstType, ~_SecondType, ~_ThirdType]) –

  • env (~_ThirdType) –

Return type

None

class ReaderIOResultBasedN(*args, **kwds)[source]

Bases: returns.interfaces.specific.reader_ioresult.ReaderIOResultLikeN[returns.interfaces.specific.reader_ioresult._FirstType, returns.interfaces.specific.reader_ioresult._SecondType, returns.interfaces.specific.reader_ioresult._ThirdType], returns.interfaces.specific.reader.CallableReader3[returns.interfaces.specific.reader_ioresult._FirstType, returns.interfaces.specific.reader_ioresult._SecondType, returns.interfaces.specific.reader_ioresult._ThirdType, IOResult[_FirstType, _SecondType], returns.interfaces.specific.reader_ioresult._ThirdType], returns.primitives.laws.Lawful[ReaderIOResultBasedN[_FirstType, _SecondType, _ThirdType]]

This interface is very specific to our ReaderIOResult type.

The only thing that differs from ReaderIOResultLikeN is that we know the specific types for its __call__ method.

In this case the return type of __call__ is IOResult.

_laws: ClassVar[Sequence[returns.primitives.laws.Law]] = (<returns.primitives.laws.Law2 object>,)

Some classes and interfaces might have laws, some might not have any.

ReaderIOResultBased3

Type alias for kinds with three type arguments.

alias of returns.interfaces.specific.reader_ioresult.ReaderIOResultBasedN[returns.interfaces.specific.reader_ioresult._FirstType, returns.interfaces.specific.reader_ioresult._SecondType, returns.interfaces.specific.reader_ioresult._ThirdType]

ReaderFutureResult specific

classDiagram FutureResultLikeN <|-- ReaderFutureResultLikeN Lawful <|-- ReaderFutureResultBasedN CallableReader3 <|-- ReaderFutureResultBasedN ReaderFutureResultLikeN <|-- ReaderFutureResultBasedN ReaderIOResultLikeN <|-- ReaderFutureResultLikeN LawSpecDef <|-- _LawSpec
class ReaderFutureResultLikeN(*args, **kwds)[source]

Bases: returns.interfaces.specific.reader_ioresult.ReaderIOResultLikeN[returns.interfaces.specific.reader_future_result._FirstType, returns.interfaces.specific.reader_future_result._SecondType, returns.interfaces.specific.reader_future_result._ThirdType], returns.interfaces.specific.future_result.FutureResultLikeN[returns.interfaces.specific.reader_future_result._FirstType, returns.interfaces.specific.reader_future_result._SecondType, returns.interfaces.specific.reader_future_result._ThirdType]

Interface for all types that do look like ReaderFutureResult instance.

Cannot be called.

abstract bind_context_future_result(function)[source]

Bind a ReaderFutureResult returning function over a container.

Parameters

  • self (~_ReaderFutureResultLikeType) –

  • function (Callable[[~_FirstType], ForwardRef]) –

Return type

KindN[~_ReaderFutureResultLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

abstract bind_async_context_future_result(function)[source]

Bind async ReaderFutureResult function.

Parameters

  • self (~_ReaderFutureResultLikeType) –

  • function (Callable[[~_FirstType], Awaitable[ForwardRef]]) –

Return type

KindN[~_ReaderFutureResultLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]

abstract classmethod from_future_result_context(inner_value)[source]

Unit method to create new containers from ReaderFutureResult.

Parameters

  • cls (Type[~_ReaderFutureResultLikeType]) –

  • inner_value (ForwardRef) –

Return type

KindN[~_ReaderFutureResultLikeType, ~_ValueType, ~_ErrorType, ~_EnvType]

ReaderFutureResultLike3

Type alias for kinds with three type arguments.

alias of returns.interfaces.specific.reader_future_result.ReaderFutureResultLikeN[returns.interfaces.specific.reader_future_result._FirstType, returns.interfaces.specific.reader_future_result._SecondType, returns.interfaces.specific.reader_future_result._ThirdType]

class _LawSpec[source]

Bases: returns.primitives.laws.LawSpecDef

Concrete laws for ReaderFutureResultBasedN.

See: https://github.com/haskell/mtl/pull/61/files

static asking_law(container, env)[source]

Asking for an env, always returns the env.

Parameters
Return type

None

class ReaderFutureResultBasedN(*args, **kwds)[source]

Bases: returns.interfaces.specific.reader_future_result.ReaderFutureResultLikeN[returns.interfaces.specific.reader_future_result._FirstType, returns.interfaces.specific.reader_future_result._SecondType, returns.interfaces.specific.reader_future_result._ThirdType], returns.interfaces.specific.reader.CallableReader3[returns.interfaces.specific.reader_future_result._FirstType, returns.interfaces.specific.reader_future_result._SecondType, returns.interfaces.specific.reader_future_result._ThirdType, FutureResult[_FirstType, _SecondType], returns.interfaces.specific.reader_future_result._ThirdType], returns.primitives.laws.Lawful[ReaderFutureResultBasedN[_FirstType, _SecondType, _ThirdType]]

This interface is very specific to our ReaderFutureResult type.

The only thing that differs from ReaderFutureResultLikeN is that we know the specific types for its __call__ method.

In this case the return type of __call__ is FutureResult.

_laws: ClassVar[Sequence[returns.primitives.laws.Law]] = (<returns.primitives.laws.Law2 object>,)

Some classes and interfaces might have laws, some might not have any.

ReaderFutureResultBased3

Type alias for kinds with three type arguments.

alias of returns.interfaces.specific.reader_future_result.ReaderFutureResultBasedN[returns.interfaces.specific.reader_future_result._FirstType, returns.interfaces.specific.reader_future_result._SecondType, returns.interfaces.specific.reader_future_result._ThirdType]

← Higher Kinded Types Maybe →