) -> KindN[_FutureKind, _UpdatedType, _SecondType, _ThirdType]:
"""
Bind an async function returning ``Future`` over a container.
.. code:: python
>>> import anyio
>>> from returns.methods import bind_async_future
>>> from returns.future import Future
>>> from returns.io import IO
>>> async def example(argument: int) -> Future[int]:
... return Future.from_value(argument + 1)
>>> assert anyio.run(
... bind_async_future(Future.from_value(1), example).awaitable,
... ) == IO(2)
Note, that this function works
for all containers with ``.bind_async_future`` method.
See :class:`returns.primitives.interfaces.specific.future.FutureLikeN`
for more info.
"""
return container.bind_async_future(function)
#: Kinded version of :func:`~internal_bind_async_future`,
#: use it to infer real return type.
bind_async_future = kinded(internal_bind_async_future)
If you wish to use the user-facing ``apply``
that infers the return type correctly,
use :func:`~bind` function instead.
.. code:: python
>>> from returns.methods.apply import internal_apply, apply
>>> from returns.maybe import Some, Nothing
>>> def example(argument: int) -> int:
... return argument + 1
>>> applied = apply(Some(1), Some(example))
>>> assert applied == internal_apply(Some(1), Some(example)) == Some(2)
>>> applied = apply(Nothing, Some(example))
>>> assert applied == internal_apply(Nothing, Some(example)) == Nothing
Note, that this function works for all containers with ``.apply`` method.
See :class:`returns.primitives.interfaces.Applicative.ApplicativeN`
for more info.
"""
new_instance, rebound = debound(container)
return rebound(new_instance.apply(other))
#: Kinded version of :func:`~internal_apply`, use it to infer real return type.
apply = kinded(internal_apply)
function: Callable[[Result[_FirstType, _SecondType]],
Kind3[_IOResultLikeKind, _NewFirstType, _SecondType,
_ThirdType], ],
) -> Kind3[_IOResultLikeKind, _NewFirstType, _SecondType, _ThirdType]:
"""
Composes inner ``Result`` with ``IOResultLike`` returning function.
Can be useful when you need an access to both states of the result.
.. code:: python
>>> from returns.io import IOResult, IOSuccess, IOFailure
>>> from returns.methods import compose_result
>>> from returns.result import Result
>>> def count(container: Result[int, int]) -> IOResult[int, int]:
... return IOResult.from_result(
... container.map(lambda x: x + 1).alt(abs),
... )
>>> assert compose_result(IOSuccess(1), count) == IOSuccess(2)
>>> assert compose_result(IOFailure(-1), count) == IOFailure(1)
"""
return container.compose_result(function)
#: Kinded version of :func:`~internal_compose_result`,
# use it to infer real return type.
compose_result = kinded(internal_compose_result)
>>> from returns.future import FutureResult
>>> from returns.context import ReaderFutureResult
>>> from returns.io import IOSuccess, IOFailure
>>> from returns.pointfree import bind_future_result
>>> def function(x: int) -> FutureResult[str, int]:
... return FutureResult.from_value(str(x + 1))
>>> bound = bind_future_result(function)(
... ReaderFutureResult.from_value(1),
... )
>>> assert anyio.run(bound, ReaderFutureResult.empty) == IOSuccess('2')
>>> bound = bind_future_result(function)(
... ReaderFutureResult.from_failure(1),
... )
>>> assert anyio.run(bound, ReaderFutureResult.empty) == IOFailure(1)
Note, that this function works
for all containers with ``.bind_future_result`` method.
See :class:`returns.primitives.interfaces.specific.future.FutureResultLikeN`
for more info.
"""
return container.bind_future_result(function)
#: Kinded version of :func:`~internal_bind_future_result`,
#: use it to infer real return type.
bind_future_result = kinded(internal_bind_future_result)
) -> KindN[_FutureKind, _UpdatedType, _SecondType, _ThirdType]:
"""
Bind a sync function over a container.
.. code:: python
>>> import anyio
>>> from returns.methods import bind_future
>>> from returns.future import Future
>>> from returns.io import IO
>>> def example(argument: int) -> Future[int]:
... return Future.from_value(argument + 1)
>>> assert anyio.run(
... bind_future(Future.from_value(1), example).awaitable,
... ) == IO(2)
Note, that this function works
for all containers with ``.bind_future`` method.
See :class:`returns.primitives.interfaces.specific.future.FutureLikeN`
for more info.
"""
return container.bind_future(function)
#: Kinded version of :func:`~internal_bind_future`,
#: use it to infer real return type.
bind_future = kinded(internal_bind_future)
like in :func:`returns.pointfree.bind.bind`.
It returns ``KindN[]`` instance, not a real type.
If you wish to use the user-facing ``bind_io``
that infers the return type correctly,
use :func:`~bind_io` function instead.
.. code:: python
>>> from returns.methods.bind_io import bind_io
>>> from returns.io import IO
>>> def example(argument: int) -> IO[int]:
... return IO(argument + 1)
>>> assert bind_io(IO(1), example) == IO(2)
Note, that this function works
for all containers with ``.bind_io`` method.
See :class:`returns.primitives.interfaces.specific.io.IOBasedN`
for more info.
"""
new_instance, rebound = debound(container)
return rebound(new_instance.bind_io(function))
#: Kinded version of :func:`~internal_bind_io`,
#: use it to infer real return type.
bind_io = kinded(internal_bind_io)
... return RequiresContext(lambda deps: arg * deps)
>>> assert modify_env2(multiply(3), int)('4') == 12
Note, that this function works with only ``Kind2`` containers
with ``.modify_env`` method.
See :class:`returns.primitives.interfaces.specific.reader.ReaderBased2`
for more info.
"""
return container.modify_env(function)
#: Kinded version of :func:`~internal_modify_env2`,
#: use it to infer real return type.
modify_env2 = kinded(internal_modify_env2)
def internal_modify_env3(
container: Kind3[_Reader3Kind, _FirstType, _SecondType, _ThirdType],
function: Callable[[_UpdatedType], _ThirdType],
) -> Kind3[_Reader3Kind, _FirstType, _SecondType, _UpdatedType]:
"""
Modifies the third type argument of a ``ReaderBased3``.
.. code:: python
>>> from returns.methods import modify_env
>>> from returns.context import RequiresContextResultE
>>> from returns.result import Success, safe
to be used inside a kinded context:
like in :func:`returns.pointfree.bind.bind`.
It returns ``KindN[]`` instance, not a real type.
If you wish to use the user-facing ``rescue``
that infers the return type correctly,
use :func:`~rescue` function instead.
.. code:: python
>>> from returns.methods.rescue import rescue
>>> from returns.result import Result, Success, Failure
>>> def example(argument: int) -> Result[str, int]:
... return Failure(argument + 1)
>>> assert rescue(Failure(1), example) == Failure(2)
>>> assert rescue(Success('a'), example) == Success('a')
Note, that this function works for all containers with ``.rescue`` method.
See :class:`returns.primitives.interfaces.rescuable.RescuableN`
for more info.
"""
new_instance, rebound = debound(container)
return rebound(new_instance.rescue(function))
#: Kinded version of :func:`~internal_rescue`, use it to infer real return type.
rescue = kinded(internal_rescue)
... return Reader(lambda deps: argument + deps)
>>> assert bind_context2(Reader.from_value(2), example)(3) == 5
Note, that this function works with only ``Kind2`` containers
with ``.bind_context`` method.
See :class:`returns.primitives.interfaces.specific.reader.ReaderBased2`
for more info.
"""
return container.bind_context(function)
#: Kinded version of :func:`~internal_bind_context2`,
#: use it to infer real return type.
bind_context2 = kinded(internal_bind_context2)
def internal_bind_context3(
container: Kind3[_Reader3Kind, _FirstType, _SecondType, _ThirdType],
function: Callable[
[_FirstType],
'RequiresContext[_UpdatedType, _ThirdType]',
],
) -> Kind3[_Reader3Kind, _UpdatedType, _SecondType, _ThirdType]:
"""
Bind a ``RequiresContext`` returning function over a container.
.. code:: python
>>> from returns.methods import bind_context3
success_value: _ValueType,
error_value: _ErrorType,
) -> Kind2[_ResultKind, _ValueType, _ErrorType]:
"""
Help us to reduce the boilerplate when choosing paths with ``ResultLikeN``.
.. code:: python
>>> from returns.methods import cond
>>> from returns.result import Failure, Result, Success
>>> def is_numeric(string: str) -> Result[str, str]:
... return cond(
... Result,
... string.isnumeric(),
... 'It is a number',
... 'It is not a number',
... )
>>> assert is_numeric('42') == Success('It is a number')
>>> assert is_numeric('non numeric') == Failure('It is not a number')
"""
if is_success:
return container_type.from_value(success_value)
return container_type.from_failure(error_value)
#: Kinded version of :func:`~internal_cond`, use it to infer real return type.
cond = kinded(internal_cond)
def internal_iterable_kind(
cls,
sequence: Iterable[
KindN[_ContainerKind, _FirstType, _SecondType, _ThirdType],
],
strategy: Type[
BaseIterableStrategyN[_FirstType, _SecondType, _ThirdType],
],
) -> KindN[_ContainerKind, Sequence[_FirstType], _SecondType, _ThirdType]:
"""
Evaluate container actions from iterable, collecting results.
This function should not be used directly.
Use ``.from_iterable`` container methods instead.
It is a helper function for :class:`returns.interfaces.iterable.Iterable`.
See ``returns.iterables`` module for a list of supported strategies.
Note: ``cls`` is not typed because of how ``mypy`` resolves the types.
For some reason, there are a lot of problems with it.
And since this is an internal function, we don't really care.
"""
return strategy(sequence, cls.from_value(()))()
#: Kinded version of the same `iterable_kind`
iterable_kind = kinded(internal_iterable_kind)
_AltableKind = TypeVar('_AltableKind', bound=AltableN)
def internal_alt(
container: KindN[_AltableKind, _FirstType, _SecondType, _ThirdType],
function: Callable[[_SecondType], _UpdatedType],
) -> KindN[_AltableKind, _FirstType, _UpdatedType, _ThirdType]:
"""
Maps a function over a container.
.. code:: python
>>> from returns.methods.alt import alt
>>> from returns.result import Failure, Success
>>> def example(argument: int) -> int:
... return argument + 1
>>> assert alt(Success(1), example) == Success(1)
>>> assert alt(Failure(1), example) == Failure(2)
Note, that this function works for all containers with ``.alt`` method.
See :class:`returns.primitives.interfaces.altable.AltableN` for more info.
"""
return container.alt(function)
#: Kinded version of :func:`~internal_alt`, use it to infer real return type.
alt = kinded(internal_alt)
It returns ``KindN[]`` instance, not a real type.
If you wish to use the user-facing ``map``
that infers the return type correctly,
use :func:`~map_` function instead.
.. code:: python
>>> from returns.methods.map import internal_map, map_
>>> from returns.maybe import Some, Nothing
>>> def example(argument: int) -> int:
... return argument + 1
>>> bound = map_(Some(1), example)
>>> assert bound == internal_map(Some(1), example) == Some(2)
>>> bound = map_(Nothing, example)
>>> assert bound == internal_map(Nothing, example) == Nothing
Note, that this function works for all containers with ``.map`` method.
See :class:`returns.primitives.interfaces.mappable.MappableN` for more info.
"""
new_instance, rebound = debound(container)
return rebound(new_instance.map(function))
#: Kinded version of :func:`~internal_map`, use it to infer real return type.
map_ = kinded(internal_map)
) -> KindN[_FutureKind, _UpdatedType, _SecondType, _ThirdType]:
"""
Bind an async function over a container.
.. code:: python
>>> import anyio
>>> from returns.methods import bind_async
>>> from returns.future import Future
>>> from returns.io import IO
>>> async def example(argument: int) -> Future[int]:
... return Future.from_value(argument + 1)
>>> assert anyio.run(
... bind_async(Future.from_value(1), example).awaitable,
... ) == IO(2)
Note, that this function works
for all containers with ``.bind_async`` method.
See :class:`returns.primitives.interfaces.specific.future.FutureLikeN`
for more info.
"""
return container.bind_async(function)
#: Kinded version of :func:`~internal_bind_async`,
#: use it to infer real return type.
bind_async = kinded(internal_bind_async)
def internal_bind(
container: KindN[_BindableKind, _FirstType, _SecondType, _ThirdType],
function: Callable[[_FirstType], KindN[_BindableKind, _UpdatedType,
_SecondType, _ThirdType], ],
) -> KindN[_BindableKind, _UpdatedType, _SecondType, _ThirdType]:
"""
Bind a function over a container.
.. code:: python
>>> from returns.methods import bind
>>> from returns.maybe import Maybe, Some, Nothing
>>> def example(argument: int) -> Maybe[int]:
... return Some(argument + 1)
>>> assert bind(Some(1), example) == Some(2)
>>> assert bind(Nothing, example) == Nothing
Note, that this function works for all containers with ``.bind`` method.
See :class:`returns.primitives.interfaces.bindable.BindableN` for more info.
"""
return container.bind(function)
#: Kinded version of :func:`~internal_bind`, use it to infer real return type.
bind = kinded(internal_bind)
If you wish to use the user-facing ``bind_result``
that infers the return type correctly,
use :func:`~bind_result` function instead.
.. code:: python
>>> from returns.methods.bind_result import bind_result
>>> from returns.result import Result, Success
>>> from returns.io import IOSuccess, IOFailure
>>> def example(argument: int) -> Result[int, str]:
... return Success(argument + 1)
>>> assert bind_result(IOSuccess(1), example) == IOSuccess(2)
>>> assert bind_result(IOFailure('a'), example) == IOFailure('a')
Note, that this function works
for all containers with ``.bind_result`` method.
See :class:`returns.primitives.interfaces.specific.result.ResultBasedN`
for more info.
"""
new_instance, rebound = debound(container)
return rebound(new_instance.bind_result(function))
#: Kinded version of :func:`~internal_bind_result`,
#: use it to infer real return type.
bind_result = kinded(internal_bind_result)
>>> swapped: IOResult[str, int] = swap(container)
>>> assert swapped == IOFailure(1)
>>> container: IOResult[int, str] = IOFailure('error')
>>> assert swap(container) == IOSuccess('error')
And here's how you can handle errors easily:
.. code:: python
>>> from returns.methods import swap
>>> from returns.io import IOResult, IOSuccess
>>> from returns.result import Result, Success
>>> def function(error: str) -> Result[str, int]:
... return Success('Very bad error: ' + error)
>>> container: IOResult[int, str] = IOFailure('boom')
>>> # You cannot `.rescue_result`, but you can `.bind_result` instead!
>>> assert swap(
... swap(container).bind_result(function),
... ) == IOFailure('Very bad error: boom')
This method supports all ``ResultLikeN`` containers.
"""
return container.swap()
#: Kinded version of :func:`~internal_swap`, use it to infer real return type.
swap = kinded(internal_swap)
