We provide a lot of generic interfaces to write our bundled and your own custom types.
These interfaces are designed:
To be subclassed
To provide abstract methods to implement in your own types
To enforce correctness on final types
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.
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:
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.
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.
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)
To make sure your Mappable
implementation is right,
you can apply the Mappable
laws on it to test.
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)
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 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)
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)
To make sure your Applicative
implementation is right,
you can apply the Applicative
laws on it to test.
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)
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)),
... )
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),
... )
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.
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.
To make sure other people will be able to use your implementation, it should respect three new laws.
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)
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)
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.
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.
We also have a whole package of different specific interfaces
that will help you to create containers based on our internal types,
like Result
.
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.
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.
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
.
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
)
Here’s a full overview of all our interfaces:
Let’s review it one by one.
Bases: returns.primitives.laws.LawSpecDef
Equality laws.
Description: https://bit.ly/34D40iT
Value should be equal to itself.
first (~_EqualType) –
None
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
Some classes and interfaces might have laws, some might not have any.
Bases: returns.primitives.laws.LawSpecDef
Mappable or functor laws.
https://en.wikibooks.org/wiki/Haskell/The_Functor_class#The_functor_laws
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.
Some classes and interfaces might have laws, some might not have any.
Type alias for kinds with one type argument.
alias of returns.interfaces.mappable.MappableN
[returns.interfaces.mappable._FirstType
, NoReturn
, NoReturn
]
Type alias for kinds with two type arguments.
alias of returns.interfaces.mappable.MappableN
[returns.interfaces.mappable._FirstType
, returns.interfaces.mappable._SecondType
, NoReturn
]
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
]
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.
Type alias for kinds with one type argument.
alias of returns.interfaces.bindable.BindableN
[returns.interfaces.bindable._FirstType
, NoReturn
, NoReturn
]
Type alias for kinds with two type arguments.
alias of returns.interfaces.bindable.BindableN
[returns.interfaces.bindable._FirstType
, returns.interfaces.bindable._SecondType
, NoReturn
]
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
]
Bases: returns.primitives.laws.LawSpecDef
Applicative mappable laws.
Definition: https://bit.ly/3hC8F8E Discussion: https://bit.ly/3jffz3L
Identity law.
If we apply wrapped identity
function to a container,
nothing happens.
container (ApplicativeN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
None
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
raw_value (~_FirstType) –
container (ApplicativeN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
function (Callable
[[~_FirstType], ~_NewType1]) –
None
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.
raw_value (~_FirstType) –
container (ApplicativeN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
function (Callable
[[~_FirstType], ~_NewType1]) –
None
Composition law.
Applying two functions twice is the same as applying their composition once.
container (ApplicativeN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
first (Callable
[[~_FirstType], ~_NewType1]) –
second (Callable
[[~_NewType1], ~_NewType2]) –
None
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
Some classes and interfaces might have laws, some might not have any.
Type alias for kinds with one type argument.
alias of returns.interfaces.applicative.ApplicativeN
[returns.interfaces.applicative._FirstType
, NoReturn
, NoReturn
]
Type alias for kinds with two type arguments.
alias of returns.interfaces.applicative.ApplicativeN
[returns.interfaces.applicative._FirstType
, returns.interfaces.applicative._SecondType
, NoReturn
]
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
]
Bases: returns.primitives.laws.LawSpecDef
Mappable or functor laws.
https://en.wikibooks.org/wiki/Haskell/The_Functor_class#The_functor_laws
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.
Some classes and interfaces might have laws, some might not have any.
Type alias for kinds with two type arguments.
alias of returns.interfaces.altable.AltableN
[returns.interfaces.altable._FirstType
, returns.interfaces.altable._SecondType
, NoReturn
]
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
]
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.
Type alias for kinds with two type arguments.
alias of returns.interfaces.bimappable.BiMappableN
[returns.interfaces.bimappable._FirstType
, returns.interfaces.bimappable._SecondType
, NoReturn
]
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
]
Bases: returns.primitives.laws.LawSpecDef
Laws for SwappableN
type.
Swaaping container twice.
It ensure that we get the initial value back. In other words, swapping twice does nothing.
container (SwappableN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
None
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.
Some classes and interfaces might have laws, some might not have any.
Type alias for kinds with two type arguments.
alias of returns.interfaces.swappable.SwappableN
[returns.interfaces.swappable._FirstType
, returns.interfaces.swappable._SecondType
, NoReturn
]
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
]
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.
Type alias for kinds with two type arguments.
alias of returns.interfaces.lashable.LashableN
[returns.interfaces.lashable._FirstType
, returns.interfaces.lashable._SecondType
, NoReturn
]
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
]
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.
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()
.
self (~_UnwrappableType) –
~_FirstType
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()
.
self (~_UnwrappableType) –
~_SecondType
Bases: returns.primitives.laws.LawSpecDef
Container laws.
Definition: https://wiki.haskell.org/Monad_laws Good explanation: https://bit.ly/2Qsi5re
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.
raw_value (~_FirstType) –
container (ContainerN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
function (Callable
[[~_FirstType], KindN
[ContainerN
, ~_NewType1, ~_SecondType, ~_ThirdType]]) –
None
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.
container (ContainerN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
None
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.
container (ContainerN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
first (Callable
[[~_FirstType], KindN
[ContainerN
, ~_NewType1, ~_SecondType, ~_ThirdType]]) –
second (Callable
[[~_NewType1], KindN
[ContainerN
, ~_NewType2, ~_SecondType, ~_ThirdType]]) –
None
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
Some classes and interfaces might have laws, some might not have any.
Type alias for kinds with one type argument.
alias of returns.interfaces.container.ContainerN
[returns.interfaces.container._FirstType
, NoReturn
, NoReturn
]
Type alias for kinds with two type arguments.
alias of returns.interfaces.container.ContainerN
[returns.interfaces.container._FirstType
, returns.interfaces.container._SecondType
, NoReturn
]
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
]
Bases: returns.primitives.laws.LawSpecDef
Failable laws.
We need to be sure that .lash
won’t lash success types.
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.
Some classes and interfaces might have laws, some might not have any.
Type alias for kinds with two type arguments.
alias of returns.interfaces.failable.FailableN
[returns.interfaces.failable._FirstType
, returns.interfaces.failable._SecondType
, NoReturn
]
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
]
Bases: returns.primitives.laws.LawSpecDef
Single Failable laws.
We need to be sure that .map
and .bind
works correctly for empty
property.
Ensures that you cannot map from the empty property.
container (SingleFailableN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
function (Callable
[[~_FirstType], ~_NewFirstType]) –
None
Ensures that you cannot bind from the empty property.
container (SingleFailableN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
function (Callable
[[~_FirstType], KindN
[SingleFailableN
, ~_NewFirstType, ~_SecondType, ~_ThirdType]]) –
None
Ensures that you cannot apply from the empty property.
container (SingleFailableN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
function (Callable
[[~_FirstType], ~_NewFirstType]) –
None
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
.
Some classes and interfaces might have laws, some might not have any.
This property represents the failed value. :param self: :type self: ~_SingleFailableType
SingleFailableN
[~_FirstType, ~_SecondType, ~_ThirdType]
Type alias for kinds with two types arguments.
alias of returns.interfaces.failable.SingleFailableN
[returns.interfaces.failable._FirstType
, returns.interfaces.failable._SecondType
, NoReturn
]
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
]
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.
Ensures that you cannot map a failure.
raw_value (~_SecondType) –
container (DiverseFailableN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
function (Callable
[[~_FirstType], ~_NewFirstType]) –
None
Ensures that you cannot bind a failure.
See: https://wiki.haskell.org/Typeclassopedia#MonadFail
raw_value (~_SecondType) –
container (DiverseFailableN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
function (Callable
[[~_FirstType], KindN
[DiverseFailableN
, ~_NewFirstType, ~_SecondType, ~_ThirdType]]) –
None
Ensures that you cannot apply a failure.
raw_value (~_SecondType) –
container (DiverseFailableN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
function (Callable
[[~_FirstType], ~_NewFirstType]) –
None
Ensures that you cannot alt a success.
raw_value (~_SecondType) –
container (DiverseFailableN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
function (Callable
[[~_SecondType], ~_NewFirstType]) –
None
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.
Some classes and interfaces might have laws, some might not have any.
Type alias for kinds with two type arguments.
alias of returns.interfaces.failable.DiverseFailableN
[returns.interfaces.failable._FirstType
, returns.interfaces.failable._SecondType
, NoReturn
]
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
]
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.
Ensures that you cannot map from failures.
container (MaybeLikeN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
function (Callable
[[~_FirstType], ~_NewType1]) –
None
Ensures that you cannot bind from failures.
container (MaybeLikeN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
function (Callable
[[~_FirstType], KindN
[MaybeLikeN
, ~_NewType1, ~_SecondType, ~_ThirdType]]) –
None
Ensures that you cannot bind from failures.
container (MaybeLikeN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
function (Callable
[[~_FirstType], Optional
[~_NewType1]]) –
None
Ensures that you cannot lash a success.
raw_value (~_FirstType) –
container (MaybeLikeN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
function (Callable
[[~_SecondType], KindN
[MaybeLikeN
, ~_FirstType, ~_NewType1, ~_ThirdType]]) –
None
Ensures None
is treated specially.
container (MaybeLikeN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
function (Callable
[[~_FirstType], None
]) –
None
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.
Some classes and interfaces might have laws, some might not have any.
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
]
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
]
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.
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
]
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
]
An interface that represents a pure computation result.
For impure result see
returns.interfaces.specific.ioresult.IOResultLikeN
type.
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
.
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
]
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
]
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.
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.
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
]
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
]
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.
Type alias for kinds with one type argument.
alias of returns.interfaces.specific.io.IOLikeN
[returns.interfaces.specific.io._FirstType
, NoReturn
, NoReturn
]
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
]
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
]
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.
Type alias for kinds with one type argument.
alias of returns.interfaces.specific.io.IOBasedN
[returns.interfaces.specific.io._FirstType
, NoReturn
, NoReturn
]
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
]
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
]
An interface for types that do IO
and can fail.
It is a base interface for both sync and async IO
stacks.
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
.
Runs IOResult
returning function over a container.
self (~_IOResultLikeType) –
function (Callable
[[~_FirstType], ForwardRef
]) –
KindN
[~_IOResultLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]
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
]
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
]
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.
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
]
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
]
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.
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.
Allows to bind Future
returning function over a container.
self (~_FutureLikeType) –
function (Callable
[[~_FirstType], ForwardRef
]) –
KindN
[~_FutureLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]
Allows to bind async Future
returning function over container.
self (~_FutureLikeType) –
function (Callable
[[~_FirstType], Awaitable
[ForwardRef
]]) –
KindN
[~_FutureLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]
Type alias for kinds with one type argument.
alias of returns.interfaces.specific.future.FutureLikeN
[returns.interfaces.specific.future._FirstType
, NoReturn
, NoReturn
]
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
]
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
]
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.
Type alias for kinds with one type argument.
alias of returns.interfaces.specific.future.AwaitableFutureN
[returns.interfaces.specific.future._FirstType
, NoReturn
, NoReturn
]
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
]
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
]
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.
Type alias for kinds with one type argument.
alias of returns.interfaces.specific.future.FutureBasedN
[returns.interfaces.specific.future._FirstType
, NoReturn
, NoReturn
]
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
]
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
]
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.
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
.
Allows to bind FutureResult
functions over a container.
self (~_FutureResultLikeType) –
function (Callable
[[~_FirstType], ForwardRef
]) –
KindN
[~_FutureResultLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]
Allows to bind async FutureResult
functions over container.
self (~_FutureResultLikeType) –
function (Callable
[[~_FirstType], Awaitable
[ForwardRef
]]) –
KindN
[~_FutureResultLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]
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
]
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
]
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.
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
]
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
]
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.
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.
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.
Is required to call Reader
with no explicit arguments.
:param self:
:type self: ~_ReaderLike2Type
ForwardRef
Allows to apply a wrapped function over a Reader
container.
self (~_ReaderLike2Type) –
function (Callable
[[~_FirstType], ForwardRef
]) –
KindN
[~_ReaderLike2Type, ~_UpdatedType, ~_SecondType, Any
]
Transforms the environment before calling the container.
self (~_ReaderLike2Type) –
function (Callable
[[~_UpdatedType], ~_SecondType]) –
KindN
[~_ReaderLike2Type, ~_FirstType, ~_UpdatedType, Any
]
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.
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.
Is required to call Reader
with no explicit arguments.
:param self:
:type self: ~_ReaderLike3Type
ForwardRef
Allows to apply a wrapped function over a Reader
container.
self (~_ReaderLike3Type) –
function (Callable
[[~_FirstType], ForwardRef
]) –
KindN
[~_ReaderLike3Type, ~_UpdatedType, ~_SecondType, ~_ThirdType]
Transforms the environment before calling the container.
self (~_ReaderLike3Type) –
function (Callable
[[~_UpdatedType], ~_ThirdType]) –
KindN
[~_ReaderLike3Type, ~_FirstType, ~_SecondType, ~_UpdatedType]
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.
Bases: returns.primitives.laws.LawSpecDef
Concrete laws for ReaderBased2
.
See: https://github.com/haskell/mtl/pull/61/files
Calling a Reader
twice has the same result with the same env.
container (ReaderBased2
[~_FirstType, ~_SecondType]) –
env (~_SecondType) –
None
Asking for an env, always returns the env.
container (ReaderBased2
[~_FirstType, ~_SecondType]) –
env (~_SecondType) –
None
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.
Some classes and interfaces might have laws, some might not have any.
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.
Binds a ReaderResult
returning function over a container.
self (~_ReaderResultLikeType) –
function (Callable
[[~_FirstType], ForwardRef
]) –
KindN
[~_ReaderResultLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]
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
]
Bases: returns.primitives.laws.LawSpecDef
Concrete laws for ReaderResulBasedN
.
See: https://github.com/haskell/mtl/pull/61/files
Calling a Reader
twice has the same result with the same env.
container (ReaderResultBasedN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
env (~_ThirdType) –
None
Asking for an env, always returns the env.
container (ReaderResultBasedN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
env (~_ThirdType) –
None
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
.
Some classes and interfaces might have laws, some might not have any.
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
]
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.
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
]
Bases: returns.primitives.laws.LawSpecDef
Concrete laws for ReaderIOResultBasedN
.
See: https://github.com/haskell/mtl/pull/61/files
Asking for an env, always returns the env.
container (ReaderIOResultBasedN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
env (~_ThirdType) –
None
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
.
Some classes and interfaces might have laws, some might not have any.
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
]
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.
Bind a ReaderFutureResult
returning function over a container.
self (~_ReaderFutureResultLikeType) –
function (Callable
[[~_FirstType], ForwardRef
]) –
KindN
[~_ReaderFutureResultLikeType, ~_UpdatedType, ~_SecondType, ~_ThirdType]
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
]
Bases: returns.primitives.laws.LawSpecDef
Concrete laws for ReaderFutureResultBasedN
.
See: https://github.com/haskell/mtl/pull/61/files
Asking for an env, always returns the env.
container (ReaderFutureResultBasedN
[~_FirstType, ~_SecondType, ~_ThirdType]) –
env (~_ThirdType) –
None
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
.
Some classes and interfaces might have laws, some might not have any.
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
]