trcks.fp.monads.tuple_

def construct(value: _T, /) -> tuple[_T,]:
    """Create a [tuple][] from a single value.

    Args:
        value: A single value.

    Returns:
        Contains the single value.

    Examples:
        >>> from trcks.fp.monads import tuple_ as t
        >>> t.construct(42)
        (42,)
    """
    return (value,)

def construct_from_iterable(it: Iterable[_T], /) -> tuple[_T, ...]:
    """Create a homogeneous [tuple][] from an iterable.

    Args:
        it: The iterable to create the [tuple][] from.

    Returns:
        The [tuple][] created from the iterable.

    Examples:
        >>> from trcks.fp.monads import tuple_ as t
        >>> t.construct_from_iterable([1, 2, 3])
        (1, 2, 3)
    """
    return tuple(it)

def map_(
    callable_: Callable[Concatenate[_T1, _P], _T2],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[tuple[_T1, ...]], tuple[_T2, ...]]:
    """Create function that maps homogeneous [tuple][]s to
    homogeneous [tuple][]s of the same length.

    Args:
        callable_: Function to apply to each element.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps homogeneous [tuple][]s to homogeneous [tuple][]s of the same length
            according to the given function.

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

    Examples:
        >>> from collections.abc import Callable
        >>> from trcks.fp.monads import tuple_ as t
        >>> def double_integer(n: int) -> int:
        ...     return n * 2
        ...
        >>> double_integers: Callable[
        ...     [tuple[int, ...]], tuple[int, ...]
        ... ] = t.map_(double_integer)
        >>> double_integers((1, 2, 3))
        (2, 4, 6)
    """
    return map_to_iterable(compose(callable_, construct), *args, **kwargs)

def map_to_awaitable(
    callable_: Callable[Concatenate[_T1, _P], Awaitable[_T2]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[tuple[_T1, ...]], AwaitableTuple[_T2]]:
    """Create function that maps each element of a homogeneous [tuple][]
    to a new element of a [trcks.AwaitableTuple][].

    Args:
        callable_: Asynchronous function to apply to each element.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps homogeneous [tuple][]s to [trcks.AwaitableTuple][]s of the same length
            according to the given asynchronous function.

    Examples:
        >>> import asyncio
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> from trcks.fp.monads import tuple_ as t
        >>> async def slowly_add_one(n: int) -> int:
        ...     await asyncio.sleep(0.001)
        ...     return n + 1
        ...
        >>> add_one_to_each = t.map_to_awaitable(slowly_add_one)
        >>> a_tpl = add_one_to_each((1, 2, 3))
        >>> asyncio.run(at.to_coroutine_tuple(a_tpl))
        (2, 3, 4)
    """
    return compose(
        at.construct_from_iterable, at.map_to_awaitable(callable_, *args, **kwargs)
    )

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

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

    Returns:
        Maps homogeneous [tuple][]s to [trcks.AwaitableTuple][]s of varying length
            according to the given asynchronous function.

    Examples:
        >>> import asyncio
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> from trcks.fp.monads import tuple_ as t
        >>> async def slowly_duplicate(n: int) -> tuple[int, int]:
        ...     await asyncio.sleep(0.001)
        ...     return n, n
        ...
        >>> duplicate_each = t.map_to_awaitable_iterable(slowly_duplicate)
        >>> a_tpl = duplicate_each((1, 2))
        >>> asyncio.run(at.to_coroutine_tuple(a_tpl))
        (1, 1, 2, 2)
    """
    return compose(
        at.construct_from_iterable,
        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[[tuple[_T1, ...]], AwaitableResultTuple[_F, _S]]:
    """Create function that maps each element of a homogeneous [tuple][]
    to a [trcks.AwaitableResult][] value.

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

    Returns:
        Maps homogeneous [tuple][]s to [trcks.AwaitableResultTuple][]s with

            - the first [trcks.Failure][] returned by the function, or
            - a [trcks.SuccessTuple][] if the function returns [trcks.Success][]
                for all elements.

    Examples:
        >>> import asyncio
        >>> from trcks import Result
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import tuple_ as t
        >>> async def slowly_double_if_positive(n: int) -> Result[str, int]:
        ...     await asyncio.sleep(0.001)
        ...     if n > 0:
        ...         return "success", n * 2
        ...     return "failure", "negative"
        ...
        >>> double_if_positive = t.map_to_awaitable_result(slowly_double_if_positive)
        >>> a_r_tpl_1 = double_if_positive((1, 2))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('success', (2, 4))
        >>> a_r_tpl_2 = double_if_positive((1, -1, 2))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('failure', 'negative')
    """
    c: Composable2[
        [tuple[_T1, ...]],
        AwaitableResultTuple[Never, _T1],
        AwaitableResultTuple[_F, _S],
    ] = (
        art.construct_successes_from_iterable,
        art.map_successes_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[[tuple[_T1, ...]], AwaitableResultTuple[_F, _S]]:
    """Create function that maps each element of a homogeneous [tuple][]
    to a [trcks.AwaitableResultIterable][] and flattens the result.

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

    Returns:
        Maps homogeneous [tuple][]s to [trcks.AwaitableResultTuple][]s with

            - the first [trcks.Failure][] returned by the function, or
            - a flattened [trcks.SuccessTuple][] if the function returns
                [trcks.SuccessTuple][] for all elements.

    Examples:
        >>> import asyncio
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import tuple_ as t
        >>> async def slowly_expand_if_positive(n: int) -> ResultTuple[str, int]:
        ...     await asyncio.sleep(0.001)
        ...     if n > 0:
        ...         return "success", (n, -n)
        ...     return "failure", "negative"
        ...
        >>> expand_if_positive = (
        ...     t.map_to_awaitable_result_iterable(slowly_expand_if_positive)
        ... )
        >>> a_r_tpl_1 = expand_if_positive((1, 2))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('success', (1, -1, 2, -2))
        >>> a_r_tpl_2 = expand_if_positive((1, -1, 2))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('failure', 'negative')
    """
    c: Composable2[
        [tuple[_T1, ...]],
        AwaitableResultTuple[Never, _T1],
        AwaitableResultTuple[_F, _S],
    ] = (
        art.construct_successes_from_iterable,
        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[[tuple[_T1, ...]], AwaitableResultTuple[_F, _S]]:
    """Deprecated alias for
    [trcks.fp.monads.tuple_.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[[tuple[_T1, ...]], AwaitableTuple[_T2]]:
    """Deprecated alias for [trcks.fp.monads.tuple_.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[[tuple[_T1, ...]], tuple[_T2, ...]]:
    """Create function that maps homogeneous [tuple][]s to
    homogeneous [tuple][]s of varying length.

    Args:
        callable_: Function to apply to each element.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps homogeneous [tuple][]s to homogeneous [tuple][]s of varying length
            according to the given function.

    Examples:
        >>> from collections.abc import Callable
        >>> from trcks.fp.monads import tuple_ as t
        >>> def duplicate_integer(n: int) -> tuple[int, int]:
        ...     return n, n
        ...
        >>> duplicate_integers: Callable[
        ...     [tuple[int, ...]], tuple[int, ...]
        ... ] = t.map_to_iterable(duplicate_integer)
        >>> duplicate_integers((1, 2, 3))
        (1, 1, 2, 2, 3, 3)
    """

    def mapped_callable(t1s: tuple[_T1, ...]) -> tuple[_T2, ...]:
        return tuple(t2 for t1 in t1s for t2 in callable_(t1, *args, **kwargs))

    return mapped_callable

def map_to_result(
    callable_: Callable[Concatenate[_T1, _P], Result[_F, _S]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[tuple[_T1, ...]], ResultTuple[_F, _S]]:
    """Create function that maps each element of a homogeneous [tuple][]
    to a [trcks.Result][] value.

    Args:
        callable_: Synchronous function to apply to each element.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps homogeneous [tuple][]s to [trcks.ResultTuple][]s with

            - the first [trcks.Failure][] returned by the function, or
            - a [trcks.SuccessTuple][] with all transformed elements if the
                function returns [trcks.Success][] for all elements.

    Examples:
        >>> from trcks import Result
        >>> from trcks.fp.monads import tuple_ as t
        >>> def double_if_positive(n: int) -> Result[str, int]:
        ...     if n > 0:
        ...         return "success", n * 2
        ...     return "failure", "negative"
        ...
        >>> double_if_positive_tuple = t.map_to_result(double_if_positive)
        >>> double_if_positive_tuple((1, 2, 3))
        ('success', (2, 4, 6))
        >>> double_if_positive_tuple((1, -1, 2))
        ('failure', 'negative')
    """
    c: Composable2[
        [tuple[_T1, ...]],
        ResultTuple[Never, _T1],
        ResultTuple[_F, _S],
    ] = (
        rt.construct_successes_from_iterable,
        rt.map_successes_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[[tuple[_T1, ...]], ResultTuple[_F, _S]]:
    """Create function that maps each element of a homogeneous [tuple][]
    to a [trcks.ResultIterable][] and flattens the result.

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

    Returns:
        Maps homogeneous [tuple][]s to [trcks.ResultTuple][]s with

            - the first [trcks.Failure][] returned by the function, or
            - a flattened [trcks.SuccessTuple][] if the function returns
                [trcks.SuccessTuple][] for all elements.

    Examples:
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import tuple_ as t
        >>> def expand_if_positive(n: int) -> ResultTuple[str, int]:
        ...     if n > 0:
        ...         return "success", (n, -n)
        ...     return "failure", "negative"
        ...
        >>> expand_if_positive_tuple = t.map_to_result_iterable(expand_if_positive)
        >>> expand_if_positive_tuple((1, 2))
        ('success', (1, -1, 2, -2))
        >>> expand_if_positive_tuple((1, -1, 2))
        ('failure', 'negative')
    """
    c: Composable2[
        [tuple[_T1, ...]],
        ResultTuple[Never, _T1],
        ResultTuple[_F, _S],
    ] = (
        rt.construct_successes_from_iterable,
        rt.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[[tuple[_T1, ...]], ResultTuple[_F, _S]]:
    """Deprecated alias for [trcks.fp.monads.tuple_.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[[tuple[_T1, ...]], tuple[_T2, ...]]:
    """Deprecated alias for [trcks.fp.monads.tuple_.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[[tuple[_T1, ...]], tuple[_T1, ...]]:
    """Create function that applies a side effect to each element of a homogeneous
    [tuple][].

    Args:
        callable_: Side effect to apply to each element.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Applies the given side effect to each element of a homogeneous [tuple][] and
            returns the original homogeneous [tuple][].

    Examples:
        >>> from collections.abc import Callable
        >>> from trcks.fp.monads import tuple_ as t
        >>> def log_integer(n: int) -> None:
        ...     print(f"Received: {n}")
        ...
        >>> log_and_pass_integers: Callable[
        ...     [tuple[int, ...]], tuple[int, ...]
        ... ] = t.tap(log_integer)
        >>> tpl = log_and_pass_integers((1, 2, 3))
        Received: 1
        Received: 2
        Received: 3
        >>> tpl
        (1, 2, 3)
    """
    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[[tuple[_T1, ...]], AwaitableTuple[_T1]]:
    """Create function that applies an asynchronous side effect
    to each element of a homogeneous [tuple][].

    Args:
        callable_: Asynchronous side effect to apply to each element.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Applies the given side effect to each element of a homogeneous [tuple][] and
            returns a [trcks.AwaitableTuple][] of the original elements.

    Examples:
        >>> import asyncio
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> from trcks.fp.monads import tuple_ as t
        >>> async def slowly_log_integer(n: int) -> None:
        ...     await asyncio.sleep(0.001)
        ...     print(f"Received: {n}")
        ...
        >>> log_each = t.tap_to_awaitable(slowly_log_integer)
        >>> a_tpl = log_each((1, 2, 3))
        >>> asyncio.run(at.to_coroutine_tuple(a_tpl))
        Received: 1
        Received: 2
        Received: 3
        (1, 2, 3)
    """
    return compose(
        at.construct_from_iterable, at.tap_to_awaitable(callable_, *args, **kwargs)
    )

def tap_to_awaitable_iterable(
    callable_: Callable[Concatenate[_T1, _P], AwaitableIterable[object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[tuple[_T1, ...]], AwaitableTuple[_T1]]:
    """Create function that applies an asynchronous side effect
    with return type [trcks.AwaitableIterable][]
    to each element of a homogeneous [tuple][].

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

    Returns:
        Applies the given side effect to each element of a homogeneous [tuple][] and
            returns a [trcks.AwaitableTuple][] of the original elements,
            each repeated once per element in the side effect output.

    Examples:
        >>> import asyncio
        >>> from trcks.fp.monads import awaitable_tuple as at
        >>> from trcks.fp.monads import tuple_ as t
        >>> async def write_to_disk(n: int) -> tuple[str, str]:
        ...     await asyncio.sleep(0.001)
        ...     print(f"Wrote {n} to disk.")
        ...     return str(n), str(n)
        ...
        >>> write_each_to_disk = t.tap_to_awaitable_iterable(write_to_disk)
        >>> a_tpl = write_each_to_disk((1, 2, 3))
        >>> asyncio.run(at.to_coroutine_tuple(a_tpl))
        Wrote 1 to disk.
        Wrote 2 to disk.
        Wrote 3 to disk.
        (1, 1, 2, 2, 3, 3)
    """
    return compose(
        at.construct_from_iterable,
        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[[tuple[_T1, ...]], AwaitableResultTuple[_F, _T1]]:
    """Create function that applies an asynchronous side effect
    with return type [trcks.Result][]
    to each element of a homogeneous [tuple][].

    Args:
        callable_: Asynchronous side effect to apply to each element,
            returning a [trcks.Result][].
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps homogeneous [tuple][]s to [trcks.AwaitableResultTuple][]s with

            - *the returned* [trcks.Failure][] if the applied side effect returns
                a [trcks.Failure][] for an element, or
            - *the original* homogeneous [tuple][] if the applied side effect
                returns [trcks.Success][] for all elements.

    Examples:
        >>> import asyncio
        >>> from trcks import Result
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import tuple_ as t
        >>> async def slowly_check_if_positive(n: int) -> Result[str, None]:
        ...     await asyncio.sleep(0.001)
        ...     if n > 0:
        ...         return "success", None
        ...     return "failure", "negative"
        ...
        >>> check_if_positive = t.tap_to_awaitable_result(slowly_check_if_positive)
        >>> a_r_tpl_1 = check_if_positive((1, 2))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('success', (1, 2))
        >>> a_r_tpl_2 = check_if_positive((1, -1, 2))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('failure', 'negative')
    """
    c: Composable2[
        [tuple[_T1, ...]],
        AwaitableResultTuple[Never, _T1],
        AwaitableResultTuple[_F, _T1],
    ] = (
        art.construct_successes_from_iterable,
        art.tap_successes_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[[tuple[_T1, ...]], AwaitableResultTuple[_F, _T1]]:
    """Create function that applies an asynchronous side effect
    with return type [trcks.AwaitableResultIterable][]
    to each element of a homogeneous [tuple][].

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

    Returns:
        Maps homogeneous [tuple][]s to [trcks.AwaitableResultTuple][]s with

            - *the returned* [trcks.Failure][] if the applied side effect returns
                a [trcks.Failure][] for an element, or
            - *the original* homogeneous [tuple][] with each element repeated once
                per side effect output element if the applied side effect returns
                [trcks.SuccessTuple][] for all elements.

    Examples:
        >>> import asyncio
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import awaitable_result_tuple as art
        >>> from trcks.fp.monads import tuple_ as t
        >>> async def audit(n: int) -> ResultTuple[str, None]:
        ...     await asyncio.sleep(0.001)
        ...     if n > 0:
        ...         return "success", (None, None)
        ...     return "failure", "negative"
        ...
        >>> audit_successes = t.tap_to_awaitable_result_iterable(audit)
        >>> a_r_tpl_1 = audit_successes((1, 2))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_1))
        ('success', (1, 1, 2, 2))
        >>> a_r_tpl_2 = audit_successes((1, -1, 2))
        >>> asyncio.run(art.to_coroutine_result_tuple(a_r_tpl_2))
        ('failure', 'negative')
    """
    c: Composable2[
        [tuple[_T1, ...]],
        AwaitableResultTuple[Never, _T1],
        AwaitableResultTuple[_F, _T1],
    ] = (
        art.construct_successes_from_iterable,
        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[[tuple[_T1, ...]], AwaitableResultTuple[_F, _T1]]:
    """Deprecated alias for
    [trcks.fp.monads.tuple_.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[[tuple[_T1, ...]], AwaitableTuple[_T1]]:
    """Deprecated alias for [trcks.fp.monads.tuple_.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[[tuple[_T1, ...]], tuple[_T1, ...]]:
    """Create function that applies a side effect
    with return type [collections.abc.Iterable][]
    to each element of a homogeneous [tuple][].

    Args:
        callable_: Side effect to apply to each element.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Applies the given side effect to each element of a homogeneous [tuple][].
            Returns each element as many times as the side effect returns elements.

    Examples:
        >>> from collections.abc import Callable
        >>> from trcks.fp.monads import tuple_ as t
        >>> def get_divisors(n: int) -> tuple[int, ...]:
        ...     candidates = range(1, n + 1)
        ...     return tuple(c for c in candidates if n % c == 0)
        ...
        >>> repeat_integers_according_to_number_of_divisors: Callable[
        ...     [tuple[int, ...]], tuple[int, ...]
        ... ] = t.tap_to_iterable(get_divisors)
        >>> repeat_integers_according_to_number_of_divisors((1, 2, 3, 4))
        (1, 2, 2, 3, 3, 4, 4, 4)
    """

    def bypassed_callable(t1: _T1) -> tuple[_T1, ...]:
        return tuple(t1 for _t2 in callable_(t1, *args, **kwargs))

    return map_to_iterable(bypassed_callable)

def tap_to_result(
    callable_: Callable[Concatenate[_T1, _P], Result[_F, object]],
    /,
    *args: _P.args,
    **kwargs: _P.kwargs,
) -> Callable[[tuple[_T1, ...]], ResultTuple[_F, _T1]]:
    """Create function that applies a synchronous side effect
    with return type [trcks.Result][]
    to each element of a homogeneous [tuple][].

    Args:
        callable_: Synchronous side effect to apply to each element.
        *args:
            Positional arguments to be passed to `callable_`.
        **kwargs:
            Keyword arguments to be passed to `callable_`.

    Returns:
        Maps homogeneous [tuple][]s to [trcks.ResultTuple][]s with

            - *the returned* [trcks.Failure][] if the applied side effect returns
                a [trcks.Failure][] for an element, or
            - *the original* homogeneous [tuple][] if the applied side effect
                returns [trcks.Success][] for all elements.

    Examples:
        >>> from trcks import Result
        >>> from trcks.fp.monads import tuple_ as t
        >>> def audit(n: int) -> Result[str, None]:
        ...     if n > 0:
        ...         return "success", None
        ...     return "failure", "negative"
        ...
        >>> audit_successes = t.tap_to_result(audit)
        >>> audit_successes((1, 2))
        ('success', (1, 2))
        >>> audit_successes((1, -1, 2))
        ('failure', 'negative')
    """
    c: Composable2[
        [tuple[_T1, ...]],
        ResultTuple[Never, _T1],
        ResultTuple[_F, _T1],
    ] = (
        rt.construct_successes_from_iterable,
        rt.tap_successes_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[[tuple[_T1, ...]], ResultTuple[_F, _T1]]:
    """Create function that applies a synchronous side effect
    with return type [trcks.ResultIterable][]
    to each element of a homogeneous [tuple][].

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

    Returns:
        Maps homogeneous [tuple][]s to [trcks.ResultTuple][]s with

            - *the returned* [trcks.Failure][] if the applied side effect returns
                a [trcks.Failure][] for an element, or
            - *the original* homogeneous [tuple][] with each element repeated once
                per side effect output element if the applied side effect returns
                [trcks.SuccessTuple][] for all elements.

    Examples:
        >>> from trcks import ResultTuple
        >>> from trcks.fp.monads import tuple_ as t
        >>> def audit(n: int) -> ResultTuple[str, None]:
        ...     if n > 0:
        ...         return "success", (None, None)
        ...     return "failure", "negative"
        ...
        >>> audit_successes = t.tap_to_result_iterable(audit)
        >>> audit_successes((7,))
        ('success', (7, 7))
        >>> audit_successes((1, -1))
        ('failure', 'negative')
    """
    c: Composable2[
        [tuple[_T1, ...]],
        ResultTuple[Never, _T1],
        ResultTuple[_F, _T1],
    ] = (
        rt.construct_successes_from_iterable,
        rt.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[[tuple[_T1, ...]], ResultTuple[_F, _T1]]:
    """Deprecated alias for [trcks.fp.monads.tuple_.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[[tuple[_T1, ...]], tuple[_T1, ...]]:
    """Deprecated alias for [trcks.fp.monads.tuple_.tap_to_iterable][]."""
    return tap_to_iterable(callable_, *args, **kwargs)  # pragma: no cover