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