Class Future

returns/future.py:68–467

Container to easily compose ``async`` functions. Represents a better abstraction over a simple coroutine. Is framework, event-loop, and IO-library agnostics. Works with ``asyncio``, ``curio``, ``trio``, or any other tool. Internally we use ``anyio`` to test that it works a

@final
class Future(  # type: ignore[type-var]
    BaseContainer,
    SupportsKind1['Future', _ValueType_co],
    FutureBased1[_ValueType_co],
):
    """
    Container to easily compose ``async`` functions.

    Represents a better abstraction over a simple coroutine.

    Is framework, event-loop, and IO-library agnostics.
    Works with ``asyncio``, ``curio``, ``trio``, or any other tool.
    Internally we use ``anyio`` to test
    that it works as expected for any io stack.

    Note that ``Future[a]`` represents a computation
    that never fails and returns ``IO[a]`` type.
    Use ``FutureResult[a, b]`` for operations that might fail.
    Like DB access or network operations.

    Is not related to ``asyncio.Future`` in any kind.

    .. rubric:: Tradeoffs

    Due to possible performance issues we move all coroutines definitions
    to a separate module.

    See also:
        - https://gcanti.github.io/fp-ts/modules/Task.ts.html
        - https://zio.dev/docs/overview/overview_basic_concurrency

    """

    __slots__ = ()

    _inner_value: Awaitable[_ValueType_co]

    def __init__(self, inner_value: Awaitable[_ValueType_co]) -> None:
        """
        Public constructor for this type. Also required for typing.

        .. code:: python

          >>> import anyio
          >>> from returns.future import Future
          >>> from returns.io import IO

          >>> async def coro(arg: int) -> int:
          ...     return arg + 1

          >>> container = Future(coro(1))
          >>> assert anyio.run(container.awaitable) == IO(2)

        """
        super().__init__(ReAwaitable(inner_value))

    def __await__(self) -> Generator[None, None, IO[_ValueType_co]]:
        """