trcks.fp.monads.awaitable

def construct(value: _T, /) -> Awaitable[_T]:
    """Create a [collections.abc.Awaitable][] from a value.

    Args:
        value: The value to create the [collections.abc.Awaitable][] from.

    Returns:
        The [collections.abc.Awaitable][] created from the value.

    Examples:
        >>> import asyncio
        >>> from collections.abc import Awaitable
        >>> from trcks.fp.monads import awaitable as a
        >>> awtbl = a.construct("Hello, world!")
        >>> isinstance(awtbl, Awaitable)
        True
        >>> asyncio.run(a.to_coroutine(awtbl))
        'Hello, world!'
    """
    return _construct(value)

def map_(
    callable_: Callable[Concatenate[_T1, _P], _T2],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], Awaitable[_T2]]:
    """Turn synchronous function into a function
    expecting and returning [collections.abc.Awaitable][].

    Args:
        callable_:
            The synchronous function to be transformed into
            a function expecting and returning a [collections.abc.Awaitable][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        The given function transformed into
            a function expecting and returning a [collections.abc.Awaitable][].

    Note:
        The underscore in the function name helps to avoid collisions
        with the built-in function [map][].

    Examples:
        >>> import asyncio
        >>> from collections.abc import Awaitable
        >>> from trcks.fp.monads import awaitable as a
        >>> def transform(s: str) -> str:
        ...     return f"Length: {len(s)}"
        ...
        >>> transform_mapped = a.map_(transform)
        >>> awaitable_input = a.construct("Hello, world!")
        >>> awaitable_output = transform_mapped(awaitable_input)
        >>> isinstance(awaitable_output, Awaitable)
        True
        >>> asyncio.run(a.to_coroutine(awaitable_output))
        'Length: 13'

    """
    return map_to_awaitable(compose(callable_, construct), *args, **kwargs)

def map_to_awaitable(
    callable_: Callable[Concatenate[_T1, _P], Awaitable[_T2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], Awaitable[_T2]]:
    """Turn [collections.abc.Awaitable][]-returning function into
    function expecting and returning [collections.abc.Awaitable][].

    Args:
        callable_:
            The [collections.abc.Awaitable][]-returning function to be transformed into
            a function expecting and returning a [collections.abc.Awaitable][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        The given function transformed into
            a function expecting and returning a [collections.abc.Awaitable][].


    Examples:
        >>> import asyncio
        >>> from collections.abc import Awaitable
        >>> from trcks.fp.monads import awaitable as a
        >>> async def write_to_disk(output: str) -> None:
        ...     await asyncio.sleep(0.001)
        ...     print(f"Wrote '{output}' to disk.")
        ...
        >>> write_to_disk_mapped = a.map_to_awaitable(write_to_disk)
        >>> awaitable_input = a.construct("Hello, world!")
        >>> awaitable_output = write_to_disk_mapped(awaitable_input)
        >>> isinstance(awaitable_output, Awaitable)
        True
        >>> asyncio.run(a.to_coroutine(awaitable_output))
        Wrote 'Hello, world!' to disk.
    """

    async def mapped_callable(awaitable: Awaitable[_T1]) -> _T2:
        return await callable_(await awaitable, *args, **kwargs)

    return mapped_callable

def map_to_awaitable_iterable(
    callable_: Callable[Concatenate[_T1, _P], AwaitableIterable[_T2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableTuple[_T2]]:
    """Create function that maps the value of an [collections.abc.Awaitable][]
    to a [trcks.AwaitableIterable][] and flattens the result.

    Args:
        callable_: Asynchronous function to apply to the awaited value,
            returning a [trcks.AwaitableIterable][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [collections.abc.Awaitable][]s to [trcks.AwaitableTuple][]s
            of varying length according to the given asynchronous function.

    Examples:
        >>> import asyncio
        >>> from trcks.fp.monads import awaitable as a
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> async def slowly_duplicate(n: int) -> tuple[int, ...]:
        ...     await asyncio.sleep(0.001)
        ...     return (n, n)
        ...
        >>> duplicate = a.map_to_awaitable_iterable(slowly_duplicate)
        >>> a_tpl = duplicate(a.construct(21))
        >>> asyncio.run(at.to_coroutine_tuple(a_tpl))
        (21, 21)
    """
    return compose(
        at.construct_from_awaitable,
        at.map_to_awaitable_iterable(callable_, *args, **kwargs),
    )

def map_to_awaitable_result(
    callable_: Callable[Concatenate[_T1, _P], AwaitableResult[_F, _S]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableResult[_F, _S]]:
    """Create function that maps the value of an [collections.abc.Awaitable][]
    to a [trcks.AwaitableResult][] value.

    Args:
        callable_: Asynchronous function to apply to the awaited value,
            returning a [trcks.AwaitableResult][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [collections.abc.Awaitable][]s to [trcks.AwaitableResult][]s
            according to the given asynchronous function.

    Examples:
        >>> import asyncio
        >>> from trcks import Result
        >>> from trcks.fp.monads import awaitable as a
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> async def slowly_assert_non_negative(
        ...     x: float,
        ... ) -> Result[str, float]:
        ...     await asyncio.sleep(0.001)
        ...     if x < 0:
        ...         return "failure", "negative value"
        ...     return "success", x
        ...
        >>> assert_non_negative = a.map_to_awaitable_result(
        ...     slowly_assert_non_negative
        ... )
        >>> a_rslt = assert_non_negative(a.construct(42.0))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt))
        ('success', 42.0)
    """
    c: Composable2[
        [Awaitable[_T1]],
        AwaitableResult[Never, _T1],
        AwaitableResult[_F, _S],
    ] = (
        ar.construct_success_from_awaitable,
        ar.map_success_to_awaitable_result(callable_, *args, **kwargs),
    )
    return compose(*c)

def map_to_awaitable_result_iterable(
    callable_: Callable[Concatenate[_T1, _P], AwaitableResultIterable[_F, _S]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableResultTuple[_F, _S]]:
    """Create function that maps the value of an [collections.abc.Awaitable][]
    to a [trcks.AwaitableResultIterable][] and flattens the result.

    Args:
        callable_: Asynchronous function to apply to the awaited value,
            returning a [trcks.AwaitableResultIterable][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [collections.abc.Awaitable][]s to [trcks.AwaitableResultTuple][]s with

            - the [trcks.Failure][] returned by the function, or
            - a [trcks.SuccessTuple][] containing the elements of
                the [trcks.SuccessIterable][] returned by the function.

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableResultTuple
        >>> from trcks.fp.monads import awaitable as a
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> async def validate(x: float) -> AwaitableResultTuple[str, float]:
        ...     await asyncio.sleep(0.001)
        ...     if x < 0:
        ...         return "failure", "negative value"
        ...     return "success", (x, x * 2)
        ...
        >>> validate_value = a.map_to_awaitable_result_iterable(validate)
        >>> a_r_tpl = validate_value(a.construct(5.0))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl))
        ('success', (5.0, 10.0))
    """
    c: Composable2[
        [Awaitable[_T1]],
        AwaitableResultTuple[Never, _T1],
        AwaitableResultTuple[_F, _S],
    ] = (
        art.construct_successes_from_awaitable,
        art.map_successes_to_awaitable_result_iterable(callable_, *args, **kwargs),
    )
    return compose(*c)

@deprecated("Use map_to_awaitable_result_iterable instead")
def map_to_awaitable_result_tuple(
    callable_: Callable[Concatenate[_T1, _P], AwaitableResultTuple[_F, _S]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableResultTuple[_F, _S]]:
    """Deprecated alias for
    [trcks.fp.monads.awaitable.map_to_awaitable_result_iterable][].
    """
    return map_to_awaitable_result_iterable(
        callable_, *args, **kwargs
    )  # pragma: no cover

@deprecated("Use map_to_awaitable_iterable instead")
def map_to_awaitable_tuple(
    callable_: Callable[Concatenate[_T1, _P], AwaitableTuple[_T2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableTuple[_T2]]:
    """Deprecated alias for [trcks.fp.monads.awaitable.map_to_awaitable_iterable][]."""
    return map_to_awaitable_iterable(callable_, *args, **kwargs)  # pragma: no cover

def map_to_iterable(
    callable_: Callable[Concatenate[_T1, _P], Iterable[_T2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableTuple[_T2]]:
    """Create function that maps the value of an [collections.abc.Awaitable][]
    to a [collections.abc.Iterable][] and flattens the result.

    Args:
        callable_: Synchronous function to apply to the awaited value,
            returning a [collections.abc.Iterable][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [collections.abc.Awaitable][]s to [trcks.AwaitableTuple][]s
            of varying length according to the given function.

    Examples:
        >>> import asyncio
        >>> from trcks.fp.monads import awaitable as a
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> duplicate_with_negative = a.map_to_iterable(lambda n: (n, -n))
        >>> a_tpl = duplicate_with_negative(a.construct(3))
        >>> asyncio.run(at.to_coroutine_tuple(a_tpl))
        (3, -3)
    """
    return compose(
        at.construct_from_awaitable, at.map_to_iterable(callable_, *args, **kwargs)
    )

def map_to_result(
    callable_: Callable[Concatenate[_T1, _P], Result[_F, _S]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableResult[_F, _S]]:
    """Create function that maps the value of an [collections.abc.Awaitable][]
    to a [trcks.Result][] value.

    Args:
        callable_: Synchronous function to apply to the awaited value,
            returning a [trcks.Result][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [collections.abc.Awaitable][]s to [trcks.AwaitableResult][]s
            according to the given function.

    Examples:
        >>> import asyncio
        >>> from trcks.fp.monads import awaitable as a
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> assert_non_negative = a.map_to_result(
        ...     lambda n: (
        ...         ("success", n) if n >= 0 else ("failure", "negative value")
        ...     )
        ... )
        >>> a_rslt = assert_non_negative(a.construct(-1))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt))
        ('failure', 'negative value')
    """
    c: Composable2[
        [Awaitable[_T1]],
        AwaitableResult[Never, _T1],
        AwaitableResult[_F, _S],
    ] = (
        ar.construct_success_from_awaitable,
        ar.map_success_to_result(callable_, *args, **kwargs),
    )
    return compose(*c)

def map_to_result_iterable(
    callable_: Callable[Concatenate[_T1, _P], ResultIterable[_F, _S]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableResultTuple[_F, _S]]:
    """Create function that maps the value of an [collections.abc.Awaitable][]
    to a [trcks.ResultIterable][] and flattens the result.

    Args:
        callable_: Synchronous function to apply to the awaited value,
            returning a [trcks.ResultIterable][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [collections.abc.Awaitable][]s to [trcks.AwaitableResultTuple][]s with

            - the [trcks.Failure][] returned by the function, or
            - a [trcks.SuccessTuple][] containing the elements of
                the [trcks.SuccessIterable][] returned by the function.

    Examples:
        >>> import asyncio
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import awaitable as a
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> def validate(x: float) -> ResultTuple[str, float]:
        ...     if x < 0:
        ...         return "failure", "negative value"
        ...     return "success", (x, x * 2)
        ...
        >>> validate_value = a.map_to_result_iterable(validate)
        >>> a_r_tpl = validate_value(a.construct(5.0))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl))
        ('success', (5.0, 10.0))
    """
    c: Composable2[
        [Awaitable[_T1]],
        AwaitableResultTuple[Never, _T1],
        AwaitableResultTuple[_F, _S],
    ] = (
        art.construct_successes_from_awaitable,
        art.map_successes_to_result_iterable(callable_, *args, **kwargs),
    )
    return compose(*c)

@deprecated("Use map_to_result_iterable instead")
def map_to_result_tuple(
    callable_: Callable[Concatenate[_T1, _P], ResultTuple[_F, _S]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableResultTuple[_F, _S]]:
    """Deprecated alias for [trcks.fp.monads.awaitable.map_to_result_iterable][]."""
    return map_to_result_iterable(callable_, *args, **kwargs)  # pragma: no cover

@deprecated("Use map_to_iterable instead")
def map_to_tuple(
    callable_: Callable[Concatenate[_T1, _P], tuple[_T2, ...]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableTuple[_T2]]:
    """Deprecated alias for [trcks.fp.monads.awaitable.map_to_iterable][]."""
    return map_to_iterable(callable_, *args, **kwargs)  # pragma: no cover

def tap(
    callable_: Callable[Concatenate[_T1, _P], object],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], Awaitable[_T1]]:
    """Turn synchronous function into a function
    expecting a [collections.abc.Awaitable][] and
    returning the same [collections.abc.Awaitable][].

    Args:
        callable_:
            The synchronous function to be transformed into a function
            expecting a [collections.abc.Awaitable][] and
            returning the same [collections.abc.Awaitable][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        The given function transformed into a function
            expecting a [collections.abc.Awaitable][] and
            returning the same [collections.abc.Awaitable][].

    Examples:
        >>> import asyncio
        >>> from collections.abc import Awaitable
        >>> from trcks.fp.monads import awaitable as a
        >>> def print_string(s: str) -> None:
        ...     print(f"String: {s}")
        ...
        >>> print_string_tapped = a.tap(print_string)
        >>> awaitable_input = a.construct("Hello, world!")
        >>> awaitable_output = print_string_tapped(awaitable_input)
        >>> isinstance(awaitable_output, Awaitable)
        True
        >>> value = asyncio.run(a.to_coroutine(awaitable_output))
        String: Hello, world!
        >>> value
        'Hello, world!'
    """
    return map_(i.tap(callable_, *args, **kwargs))

def tap_to_awaitable(
    callable_: Callable[Concatenate[_T1, _P], Awaitable[object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], Awaitable[_T1]]:
    """Turn [collections.abc.Awaitable][]-returning function into a function
    expecting a [collections.abc.Awaitable][] and
    returning the same [collections.abc.Awaitable][].

    Args:
        callable_:
            The asynchronous function to be transformed into a function
            expecting a [collections.abc.Awaitable][] and
            returning the same [collections.abc.Awaitable][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        The given function transformed into a function
            expecting a [collections.abc.Awaitable][] and
            returning the same [collections.abc.Awaitable][].

    Examples:
        >>> import asyncio
        >>> from collections.abc import Awaitable
        >>> from trcks.fp.monads import awaitable as a
        >>> async def write_to_disk(output: str) -> None:
        ...     await asyncio.sleep(0.001)
        ...     print(f"Wrote '{output}' to disk.")
        ...
        >>> write_to_disk_tapped = a.tap_to_awaitable(write_to_disk)
        >>> awaitable_input = a.construct("Hello, world!")
        >>> awaitable_output = write_to_disk_tapped(awaitable_input)
        >>> isinstance(awaitable_output, Awaitable)
        True
        >>> value = asyncio.run(a.to_coroutine(awaitable_output))
        Wrote 'Hello, world!' to disk.
        >>> value
        'Hello, world!'
    """

    async def bypassed_callable(value: _T1) -> _T1:
        _ = await callable_(value, *args, **kwargs)
        return value

    return map_to_awaitable(bypassed_callable)

def tap_to_awaitable_iterable(
    callable_: Callable[Concatenate[_T1, _P], AwaitableIterable[object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableTuple[_T1]]:
    """Create function that applies an asynchronous side effect
    with return type [trcks.AwaitableIterable][]
    to the value of an [collections.abc.Awaitable][].

    Args:
        callable_: Asynchronous side effect to apply to the awaited value,
            returning a [trcks.AwaitableIterable][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [collections.abc.Awaitable][]s to [trcks.AwaitableTuple][]s with
            the original awaited value repeated once per element
            in the side effect output.

    Examples:
        >>> import asyncio
        >>> from trcks.fp.monads import awaitable as a
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> async def slowly_duplicate_with_log(n: int) -> tuple[int, ...]:
        ...     await asyncio.sleep(0.001)
        ...     print(f"Processing: {n}")
        ...     return (n, n)
        ...
        >>> process_and_duplicate = a.tap_to_awaitable_iterable(
        ...     slowly_duplicate_with_log
        ... )
        >>> a_tpl = process_and_duplicate(a.construct(21))
        >>> asyncio.run(at.to_coroutine_tuple(a_tpl))
        Processing: 21
        (21, 21)
    """
    return compose(
        at.construct_from_awaitable,
        at.tap_to_awaitable_iterable(callable_, *args, **kwargs),
    )

def tap_to_awaitable_result(
    callable_: Callable[Concatenate[_T1, _P], AwaitableResult[_F, object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableResult[_F, _T1]]:
    """Create function that applies an asynchronous side effect
    with return type [trcks.AwaitableResult][]
    to the value of an [collections.abc.Awaitable][].

    Args:
        callable_: Asynchronous side effect to apply to the awaited value,
            returning a [trcks.AwaitableResult][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [collections.abc.Awaitable][]s to [trcks.AwaitableResult][]s with

            - *the returned* [trcks.Failure][] if the applied side effect returns
                a [trcks.Failure][], or
            - *the original* awaited value as [trcks.AwaitableSuccess][]
                if the applied side effect returns [trcks.Success][].

    Examples:
        >>> import asyncio
        >>> from typing import Literal
        >>> from trcks import Result
        >>> from trcks.fp.monads import awaitable as a
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> WriteErrorLiteral = Literal["write error"]
        >>> async def write_to_disk(s: str, path: str) -> Result[
        ...     WriteErrorLiteral, None
        ... ]:
        ...     if path != "output.txt":
        ...         return "failure", "write error"
        ...     await asyncio.sleep(0.001)
        ...     print(f"Wrote '{s}' to file {path}.")
        ...     return "success", None
        ...
        >>> tap_write_to_error_file = a.tap_to_awaitable_result(
        ...     write_to_disk,
        ...     "error.txt",
        ... )
        >>> a_rslt_1 = tap_write_to_error_file(a.construct("Hello, world!"))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_1))
        ('failure', 'write error')
        >>> tap_write_to_output_file = a.tap_to_awaitable_result(
        ...     write_to_disk,
        ...     "output.txt",
        ... )
        >>> a_rslt_2 = tap_write_to_output_file(a.construct("Hello, world!"))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_2))
        Wrote 'Hello, world!' to file output.txt.
        ('success', 'Hello, world!')
    """
    c: Composable2[
        [Awaitable[_T1]],
        AwaitableResult[Never, _T1],
        AwaitableResult[_F, _T1],
    ] = (
        ar.construct_success_from_awaitable,
        ar.tap_success_to_awaitable_result(callable_, *args, **kwargs),
    )
    return compose(*c)

def tap_to_awaitable_result_iterable(
    callable_: Callable[Concatenate[_T1, _P], AwaitableResultIterable[_F, object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableResultTuple[_F, _T1]]:
    """Create function that applies an asynchronous side effect
    with return type [trcks.AwaitableResultIterable][]
    to the value of an [collections.abc.Awaitable][].

    Args:
        callable_: Asynchronous side effect to apply to the awaited value,
            returning a [trcks.AwaitableResultIterable][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [collections.abc.Awaitable][]s to [trcks.AwaitableResultTuple][]s with

            - *the returned* [trcks.Failure][] if the applied side effect returns
                a [trcks.Failure][], or
            - *the original* awaited value repeated once per element
                in the side effect output if the applied side effect returns
                [trcks.SuccessIterable][].

    Examples:
        >>> import asyncio
        >>> from trcks import AwaitableResultTuple
        >>> from trcks.fp.monads import awaitable as a
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> async def write_twice(s: str) -> AwaitableResultTuple[str, None]:
        ...     await asyncio.sleep(0.001)
        ...     print(f"Wrote '{s}' twice.")
        ...     return "success", (None, None)
        ...
        >>> write_twice_tapped = a.tap_to_awaitable_result_iterable(write_twice)
        >>> a_r_tpl = write_twice_tapped(a.construct("Hello, world!"))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl))
        Wrote 'Hello, world!' twice.
        ('success', ('Hello, world!', 'Hello, world!'))
    """
    c: Composable2[
        [Awaitable[_T1]],
        AwaitableResultTuple[Never, _T1],
        AwaitableResultTuple[_F, _T1],
    ] = (
        art.construct_successes_from_awaitable,
        art.tap_successes_to_awaitable_result_iterable(callable_, *args, **kwargs),
    )
    return compose(*c)

@deprecated("Use tap_to_awaitable_result_iterable instead")
def tap_to_awaitable_result_tuple(
    callable_: Callable[Concatenate[_T1, _P], AwaitableResultTuple[_F, object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableResultTuple[_F, _T1]]:
    """Deprecated alias for
    [trcks.fp.monads.awaitable.tap_to_awaitable_result_iterable][].
    """
    return tap_to_awaitable_result_iterable(
        callable_, *args, **kwargs
    )  # pragma: no cover

@deprecated("Use tap_to_awaitable_iterable instead")
def tap_to_awaitable_tuple(
    callable_: Callable[Concatenate[_T1, _P], AwaitableTuple[object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableTuple[_T1]]:
    """Deprecated alias for [trcks.fp.monads.awaitable.tap_to_awaitable_iterable][]."""
    return tap_to_awaitable_iterable(callable_, *args, **kwargs)  # pragma: no cover

def tap_to_iterable(
    callable_: Callable[Concatenate[_T1, _P], Iterable[object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableTuple[_T1]]:
    """Create function that applies a synchronous side effect
    with return type [collections.abc.Iterable][]
    to the value of an [collections.abc.Awaitable][].

    Args:
        callable_: Synchronous side effect to apply to the awaited value,
            returning a [collections.abc.Iterable][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [collections.abc.Awaitable][]s to [trcks.AwaitableTuple][]s with
            the original awaited value repeated once per element
            in the side effect output.

    Examples:
        >>> import asyncio
        >>> from trcks.fp.monads import awaitable as a
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> def duplicate_with_log(n: int) -> tuple[int, ...]:
        ...     print(f"Processing: {n}")
        ...     return (n, n)
        ...
        >>> process_and_duplicate = a.tap_to_iterable(duplicate_with_log)
        >>> a_tpl = process_and_duplicate(a.construct(42))
        >>> asyncio.run(at.to_coroutine_tuple(a_tpl))
        Processing: 42
        (42, 42)
    """
    return compose(
        at.construct_from_awaitable, at.tap_to_iterable(callable_, *args, **kwargs)
    )

def tap_to_result(
    callable_: Callable[Concatenate[_T1, _P], Result[_F, object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableResult[_F, _T1]]:
    """Create function that applies a synchronous side effect
    with return type [trcks.Result][]
    to the value of an [collections.abc.Awaitable][].

    Args:
        callable_: Synchronous side effect to apply to the awaited value,
            returning a [trcks.Result][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [collections.abc.Awaitable][]s to [trcks.AwaitableResult][]s with

            - *the returned* [trcks.Failure][] if the applied side effect returns
                a [trcks.Failure][], or
            - *the original* awaited value as [trcks.AwaitableSuccess][]
                if the applied side effect returns [trcks.Success][].

    Examples:
        >>> import asyncio
        >>> from trcks import Result
        >>> from trcks.fp.monads import awaitable as a
        >>> from trcks.fp.monads import awaitable_result as ar
        >>> def print_positive_float(x: float) -> Result[str, None]:
        ...     if x <= 0:
        ...         return "failure", "not positive"
        ...     return "success", print(f"Positive float: {x}")
        ...
        >>> tap_positive_float = a.tap_to_result(print_positive_float)
        >>> a_rslt_1 = tap_positive_float(a.construct(-2.3))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_1))
        ('failure', 'not positive')
        >>> a_rslt_2 = tap_positive_float(a.construct(3.5))
        >>> asyncio.run(ar.to_coroutine_result(a_rslt_2))
        Positive float: 3.5
        ('success', 3.5)
    """
    c: Composable2[
        [Awaitable[_T1]],
        AwaitableResult[Never, _T1],
        AwaitableResult[_F, _T1],
    ] = (
        ar.construct_success_from_awaitable,
        ar.tap_success_to_result(callable_, *args, **kwargs),
    )
    return compose(*c)

def tap_to_result_iterable(
    callable_: Callable[Concatenate[_T1, _P], ResultIterable[_F, object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableResultTuple[_F, _T1]]:
    """Create function that applies a synchronous side effect
    with return type [trcks.ResultIterable][]
    to the value of an [collections.abc.Awaitable][].

    Args:
        callable_: Synchronous side effect to apply to the awaited value,
            returning a [trcks.ResultIterable][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps [collections.abc.Awaitable][]s to [trcks.AwaitableResultTuple][]s with

            - *the returned* [trcks.Failure][] if the applied side effect returns
                a [trcks.Failure][], or
            - *the original* awaited value repeated once per element
                in the side effect output if the applied side effect returns
                [trcks.SuccessIterable][].

    Examples:
        >>> import asyncio
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import awaitable as a
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> def write_twice(s: str) -> ResultTuple[str, None]:
        ...     print(f"Wrote '{s}' twice.")
        ...     return "success", (None, None)
        ...
        >>> write_twice_tapped = a.tap_to_result_iterable(write_twice)
        >>> a_r_tpl = write_twice_tapped(a.construct("Hello, world!"))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl))
        Wrote 'Hello, world!' twice.
        ('success', ('Hello, world!', 'Hello, world!'))
    """
    c: Composable2[
        [Awaitable[_T1]],
        AwaitableResultTuple[Never, _T1],
        AwaitableResultTuple[_F, _T1],
    ] = (
        art.construct_successes_from_awaitable,
        art.tap_successes_to_result_iterable(callable_, *args, **kwargs),
    )
    return compose(*c)

@deprecated("Use tap_to_result_iterable instead")
def tap_to_result_tuple(
    callable_: Callable[Concatenate[_T1, _P], ResultTuple[_F, object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableResultTuple[_F, _T1]]:
    """Deprecated alias for [trcks.fp.monads.awaitable.tap_to_result_iterable][]."""
    return tap_to_result_iterable(callable_, *args, **kwargs)  # pragma: no cover

@deprecated("Use tap_to_iterable instead")
def tap_to_tuple(
    callable_: Callable[Concatenate[_T1, _P], tuple[object, ...]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[Awaitable[_T1]], AwaitableTuple[_T1]]:
    """Deprecated alias for [trcks.fp.monads.awaitable.tap_to_iterable][]."""
    return tap_to_iterable(callable_, *args, **kwargs)  # pragma: no cover

async def to_coroutine(awtbl: Awaitable[_T], /) -> _T:
    """Turn a [collections.abc.Awaitable][] into a [collections.abc.Coroutine][].

    This is useful for functions that expect a coroutine
    (e.g. [asyncio.run][] in Python 3.13 and older).

    Args:
        awtbl: The [collections.abc.Awaitable][] to be transformed
            into a [collections.abc.Coroutine][].

    Returns:
        The given [collections.abc.Awaitable][] transformed
            into a [collections.abc.Coroutine][].

    Note:
        The type [collections.abc.Awaitable][] is
        a supertype of [collections.abc.Coroutine][].

    Examples:
        Transform an [asyncio.Future][] into a [collections.abc.Coroutine][] and run it:

        >>> import asyncio
        >>> from trcks.fp.monads import awaitable as a
        >>> loop = asyncio.new_event_loop()
        >>> future: asyncio.Future[str] = loop.create_future()
        >>> future.set_result("Hello, world!")
        >>> future
        <Future finished result='Hello, world!'>
        >>> coro = a.to_coroutine(future)
        >>> coro
        <coroutine object to_coroutine at 0x...>
        >>> loop.run_until_complete(coro)
        'Hello, world!'
        >>> loop.close()
    """
    return await awtbl