# type: ignore [var-annotated]

"""
The `future.py` module provides functionality for handling asynchronous futures, 
including a decorator for converting callables into `ASyncFuture` objects and 
utilities for managing asynchronous computations.

Functions:
    future(callable: Union[Callable[P, Awaitable[T]], Callable[P, T]] = None, **kwargs: Unpack[ModifierKwargs]) -> Callable[P, Union[T, "ASyncFuture[T]"]]: 
        A decorator to convert a callable into an `ASyncFuture`, with optional modifiers.
    _gather_check_and_materialize(*things: Unpack[MaybeAwaitable[T]]) -> List[T]: 
        Gathers and materializes a list of awaitable or non-awaitable items.
    _check_and_materialize(thing: T) -> T: 
        Checks if an item is awaitable and materializes it.
    _materialize(meta: "ASyncFuture[T]") -> T: 
        Materializes the result of an `ASyncFuture`.

Classes:
    ASyncFuture: Represents an asynchronous future result.

TODO include a simple mathematics example a one complex example with numerous variables and operations
TODO include attribute access examples
TODO describe a bit more about both of the above 2 TODOs somewhere in this module-level docstring
TODO describe why a user would want to use these (to write cleaner code that doesn't require as many ugly gathers)
TODO include comparisons between the 'new way' with this future class and the 'old way' with gathers
"""

import asyncio
import concurrent.futures
from functools import partial, wraps
from inspect import isawaitable

import a_sync.asyncio
from a_sync._typing import *


def future(
    callable: AnyFn[P, T] = None,
    **kwargs: Unpack[ModifierKwargs],
) -> Callable[P, Union[T, "ASyncFuture[T]"]]:
    """
    A decorator function to convert a callable into an `ASyncFuture`, with optional modifiers.

    This function wraps the provided callable in an `_ASyncFutureWrappedFn` instance,
    which returns an `ASyncFuture` when called. The `ASyncFuture` allows the result
    of the callable to be awaited or accessed synchronously.

    Args:
        callable: The callable to convert. Defaults to None.
        **kwargs: Additional keyword arguments for the modifier.

    Returns:
        A callable that returns either the result or an `ASyncFuture`.

    Example:
        >>> @future
        ... async def async_function():
        ...     return 42
        >>> result = async_function()
        >>> isinstance(result, ASyncFuture)
        True

    See Also:
        :class:`ASyncFuture`
    """
    return _ASyncFutureWrappedFn(callable, **kwargs)


async def _gather_check_and_materialize(*things: Unpack[MaybeAwaitable[T]]) -> List[T]:
    """
    Gathers and materializes a list of awaitable or non-awaitable items.

    This function takes a list of items that may be awaitable or not, and
    returns a list of their results. Awaitable items are awaited, while
    non-awaitable items are returned as-is.

    Args:
        *things: Items to gather and materialize.

    Example:
        >>> async def async_fn(x):
        ...     return x
        >>> await _gather_check_and_materialize(async_fn(1), 2, async_fn(3))
        [1, 2, 3]
    """
    return await asyncio.gather(*[_check_and_materialize(thing) for thing in things])


async def _check_and_materialize(thing: T) -> T:
    """
    Checks if an item is awaitable and materializes it.

    If the item is awaitable, it is awaited and the result is returned.
    Otherwise, the item is returned as-is.

    Args:
        thing: The item to check and materialize.

    Example:
        >>> async def async_fn():
        ...     return 42
        >>> await _check_and_materialize(async_fn())
        42
    """
    return await thing if isawaitable(thing) else thing


def _materialize(meta: "ASyncFuture[T]") -> T:
    """
    Materializes the result of an `ASyncFuture`.

    This function attempts to run the event loop until the `ASyncFuture` is complete.
    If the event loop is already running, it raises a RuntimeError.

    Args:
        meta: The `ASyncFuture` to materialize.

    Raises:
        RuntimeError: If the event loop is running and the result cannot be awaited.

    Example:
        >>> future = ASyncFuture(asyncio.sleep(1, result=42))
        >>> _materialize(future)
        42

    See Also:
        :class:`ASyncFuture`
    """
    try:
        return asyncio.get_event_loop().run_until_complete(meta)
    except RuntimeError as e:
        raise RuntimeError(
            f"{meta} result is not set and the event loop is running, you will need to await it first"
        ) from e


MetaNumeric = Union[
    Numeric, "ASyncFuture[int]", "ASyncFuture[float]", "ASyncFuture[Decimal]"
]


@final
class ASyncFuture(concurrent.futures.Future, Awaitable[T]):
    """
    A class representing an asynchronous future result.

    Inherits from both `concurrent.futures.Future` and `Awaitable[T]`, allowing it to be used in both synchronous and asynchronous contexts.

    The `ASyncFuture` class provides additional functionality for arithmetic operations,
    comparisons, and conversions, making it versatile for various use cases.

    Example:
        >>> async def async_fn():
        ...     return 42
        >>> future = ASyncFuture(async_fn())
        >>> await future
        42

    Note:
        Arithmetic operations are implemented, allowing for mathematical operations on future results.
        You no longer have to choose between optimized async code and clean, readable code.

    Example:
        >>> future1 = ASyncFuture(asyncio.sleep(1, result=10))
        >>> future2 = ASyncFuture(asyncio.sleep(1, result=5))
        >>> future3 = ASyncFuture(asyncio.sleep(1, result=10))
        >>> future4 = ASyncFuture(asyncio.sleep(1, result=2))
        >>> result = (future1 + future2) / future3 ** future4
        >>> await result
        0.15

    Attribute Access:
        The `ASyncFuture` allows attribute access on the materialized result.

    Example:
        >>> class Example:
        ...     def __init__(self, value):
        ...         self.value = value
        >>> future = ASyncFuture(asyncio.sleep(1, result=Example(42)))
        >>> future.value
        42

    See Also:
        :func:`future` for creating `ASyncFuture` instances.
    """

    __slots__ = "__awaitable__", "__dependencies", "__dependants", "__task"

    def __init__(
        self, awaitable: Awaitable[T], dependencies: List["ASyncFuture"] = []
    ) -> None:  # sourcery skip: default-mutable-arg
        """
        Initializes an `ASyncFuture` with an awaitable and optional dependencies.

        Args:
            awaitable: The awaitable object.
            dependencies: A list of dependencies. Defaults to [].

        Example:
            >>> async def async_fn():
            ...     return 42
            >>> future = ASyncFuture(async_fn())
            >>> await future
            42
        """

        self.__awaitable__ = awaitable
        """The awaitable object."""

        self.__dependencies = dependencies
        """A list of dependencies."""

        for dependency in dependencies:
            assert isinstance(dependency, ASyncFuture)
            dependency.__dependants.append(self)

        self.__dependants: List[ASyncFuture] = []
        """A list of dependants."""

        self.__task = None
        """The task associated with the awaitable."""

        super().__init__()

    def __hash__(self) -> int:
        return hash(self.__awaitable__)

    def __repr__(self) -> str:
        string = f"<{self.__class__.__name__} {self._state} for {self.__awaitable__}"
        if self.cancelled():
            pass
        elif self.done():
            string += (
                f" exception={self.exception()}"
                if self.exception()
                else f" result={super().result()}"
            )
        return f"{string}>"

    def __list_dependencies(self, other) -> List["ASyncFuture"]:
        """
        Lists dependencies for the `ASyncFuture`.

        Args:
            other: The other dependency to list.

        Returns:
            A list of dependencies including the current and other `ASyncFuture`.
        """
        return [self, other] if isinstance(other, ASyncFuture) else [self]

    @property
    def result(self) -> Union[Callable[[], T], Any]:
        # sourcery skip: assign-if-exp, reintroduce-else
        """
        If this future is not done, it will work like `cf.Future.result`. It will block, await the awaitable, and return the result when ready.
        If this future is done and the result has attribute `result`, will return `getattr(future_result, 'result')`
        If this future is done and the result does NOT have attribute `result`, will again work like `cf.Future.result`

        Example:
            >>> future = ASyncFuture(asyncio.sleep(1, result=42))
            >>> future.result()
            42
        """
        if self.done():
            if hasattr(r := super().result(), "result"):
                # can be property, method, whatever. should work.
                return r.result
            # the result should be callable like an asyncio.Future
            return super().result
        return lambda: _materialize(self)

    def __getattr__(self, attr: str) -> Any:
        """
        Allows access to attributes of the materialized result.

        Args:
            attr: The attribute name to access.

        Returns:
            The attribute value from the materialized result.

        Example:
            >>> class Example:
            ...     def __init__(self, value):
            ...         self.value = value
            >>> future = ASyncFuture(asyncio.sleep(1, result=Example(42)))
            >>> future.value
            42
        """
        return getattr(_materialize(self), attr)

    def __getitem__(self, key) -> Any:
        """
        Allows item access on the materialized result.

        Args:
            key: The key to access.

        Returns:
            The item from the materialized result.

        Example:
            >>> future = ASyncFuture(asyncio.sleep(1, result={'key': 'value'}))
            >>> future['key']
            'value'
        """
        return _materialize(self)[key]

    # NOTE: broken, do not use. I think
    def __setitem__(self, key, value) -> None:
        """
        Allows setting an item on the materialized result.

        Args:
            key: The key to set.
            value: The value to set.

        Example:
            >>> future = ASyncFuture(asyncio.sleep(1, result={'key': 'value'}))
            >>> future['key'] = 'new_value'
        """
        _materialize(self)[key] = value

    # not sure what to call these
    def __contains__(self, key: Any) -> bool:
        """
        Checks if a key is in the materialized result.

        Args:
            key: The key to check.

        Returns:
            True if the key is in the materialized result, False otherwise.

        Example:
            >>> future = ASyncFuture(asyncio.sleep(1, result={'key': 'value'}))
            >>> 'key' in future
            True
        """
        return _materialize(
            ASyncFuture(
                self.__contains(key), dependencies=self.__list_dependencies(key)
            )
        )

    def __await__(self) -> Generator[Any, None, T]:
        """
        Makes the `ASyncFuture` awaitable.

        Example:
            >>> future = ASyncFuture(asyncio.sleep(1, result=42))
            >>> await future
            42
        """
        return self.__await().__await__()

    async def __await(self) -> T:
        if not self.done():
            self.set_result(await self.__task__)
        return self._result

    @property
    def __task__(self) -> "asyncio.Task[T]":
        """
        Returns the asyncio task associated with the awaitable, creating it if necessary.

        Example:
            >>> future = ASyncFuture(asyncio.sleep(1, result=42))
            >>> task = future.__task__
            >>> isinstance(task, asyncio.Task)
            True
        """
        if self.__task is None:
            self.__task = a_sync.asyncio.create_task(self.__awaitable__)
        return self.__task

    def __iter__(self):
        """
        Returns an iterator for the materialized result.

        Example:
            >>> future = ASyncFuture(asyncio.sleep(1, result=[1, 2, 3]))
            >>> for item in future:
            ...     print(item)
            1
            2
            3
        """
        return _materialize(self).__iter__()

    def __next__(self):
        """
        Returns the next item from the materialized result.

        Example:
            >>> future = ASyncFuture(asyncio.sleep(1, result=iter([1, 2, 3])))
            >>> next(future)
            1
        """
        return _materialize(self).__next__()

    def __enter__(self):
        """
        Enters the context of the materialized result.

        Example:
            >>> class SomeContext:
            ...     def __enter__(self):
            ...         return self
            ...     def __exit__(self, exc_type, exc_val, exc_tb):
            ...         pass
            >>> future = ASyncFuture(asyncio.sleep(1, result=SomeContext()))
            >>> with future as context:
            ...     context.do_something()
        """
        return _materialize(self).__enter__()

    def __exit__(self, *args):
        """
        Exits the context of the materialized result.

        Example:
            >>> class SomeContext:
            ...     def __enter__(self):
            ...         return self
            ...     def __exit__(self, exc_type, exc_val, exc_tb):
            ...         pass
            >>> future = ASyncFuture(asyncio.sleep(1, result=SomeContext()))
            >>> with future as context:
            ...     pass
            >>> # Context is exited here
        """
        return _materialize(self).__exit__(*args)

    @overload
    def __add__(self: "ASyncFuture[int]", other: int) -> "ASyncFuture[int]": ...

    @overload
    def __add__(self: "ASyncFuture[float]", other: float) -> "ASyncFuture[float]": ...

    @overload
    def __add__(self: "ASyncFuture[float]", other: int) -> "ASyncFuture[float]": ...

    @overload
    def __add__(self: "ASyncFuture[int]", other: float) -> "ASyncFuture[float]": ...

    @overload
    def __add__(
        self: "ASyncFuture[Decimal]", other: Decimal
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    def __add__(self: "ASyncFuture[Decimal]", other: int) -> "ASyncFuture[Decimal]": ...

    @overload
    def __add__(self: "ASyncFuture[int]", other: Decimal) -> "ASyncFuture[Decimal]": ...

    @overload
    def __add__(
        self: "ASyncFuture[int]", other: Awaitable[int]
    ) -> "ASyncFuture[int]": ...

    @overload
    def __add__(
        self: "ASyncFuture[float]", other: Awaitable[float]
    ) -> "ASyncFuture[float]": ...

    @overload
    def __add__(
        self: "ASyncFuture[float]", other: Awaitable[int]
    ) -> "ASyncFuture[float]": ...

    @overload
    def __add__(
        self: "ASyncFuture[int]", other: Awaitable[float]
    ) -> "ASyncFuture[float]": ...

    @overload
    def __add__(
        self: "ASyncFuture[Decimal]", other: Awaitable[Decimal]
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    def __add__(
        self: "ASyncFuture[Decimal]", other: Awaitable[int]
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    def __add__(
        self: "ASyncFuture[int]", other: Awaitable[Decimal]
    ) -> "ASyncFuture[Decimal]": ...

    def __add__(self, other: MetaNumeric) -> "ASyncFuture":
        """
        Adds the result of this `ASyncFuture` to another value or `ASyncFuture`.

        Args:
            other: The value or `ASyncFuture` to add.

        Returns:
            A new `ASyncFuture` representing the sum.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=10))
            >>> future2 = ASyncFuture(asyncio.sleep(1, result=5))
            >>> result = future1 + future2
            >>> await result
            15
        """
        return ASyncFuture(
            self.__add(other), dependencies=self.__list_dependencies(other)
        )

    @overload
    def __sub__(self: "ASyncFuture[int]", other: int) -> "ASyncFuture[int]": ...

    @overload
    def __sub__(self: "ASyncFuture[float]", other: float) -> "ASyncFuture[float]": ...

    @overload
    def __sub__(self: "ASyncFuture[float]", other: int) -> "ASyncFuture[float]": ...

    @overload
    def __sub__(self: "ASyncFuture[int]", other: float) -> "ASyncFuture[float]": ...

    @overload
    def __sub__(
        self: "ASyncFuture[Decimal]", other: Decimal
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    def __sub__(self: "ASyncFuture[Decimal]", other: int) -> "ASyncFuture[Decimal]": ...

    @overload
    def __sub__(self: "ASyncFuture[int]", other: Decimal) -> "ASyncFuture[Decimal]": ...

    @overload
    def __sub__(
        self: "ASyncFuture[int]", other: Awaitable[int]
    ) -> "ASyncFuture[int]": ...

    @overload
    def __sub__(
        self: "ASyncFuture[float]", other: Awaitable[float]
    ) -> "ASyncFuture[float]": ...

    @overload
    def __sub__(
        self: "ASyncFuture[float]", other: Awaitable[int]
    ) -> "ASyncFuture[float]": ...

    @overload
    def __sub__(
        self: "ASyncFuture[int]", other: Awaitable[float]
    ) -> "ASyncFuture[float]": ...

    @overload
    def __sub__(
        self: "ASyncFuture[Decimal]", other: Awaitable[Decimal]
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    def __sub__(
        self: "ASyncFuture[Decimal]", other: Awaitable[int]
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    def __sub__(
        self: "ASyncFuture[int]", other: Awaitable[Decimal]
    ) -> "ASyncFuture[Decimal]": ...

    def __sub__(self, other: MetaNumeric) -> "ASyncFuture":
        """
        Subtracts another value or `ASyncFuture` from the result of this `ASyncFuture`.

        Args:
            other: The value or `ASyncFuture` to subtract.

        Returns:
            A new `ASyncFuture` representing the difference.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=10))
            >>> future2 = ASyncFuture(asyncio.sleep(1, result=5))
            >>> result = future1 - future2
            >>> await result
            5
        """
        return ASyncFuture(
            self.__sub(other), dependencies=self.__list_dependencies(other)
        )

    def __mul__(self, other) -> "ASyncFuture":
        """
        Multiplies the result of this `ASyncFuture` by another value or `ASyncFuture`.

        Args:
            other: The value or `ASyncFuture` to multiply.

        Returns:
            A new `ASyncFuture` representing the product.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=10))
            >>> future2 = ASyncFuture(asyncio.sleep(1, result=5))
            >>> result = future1 * future2
            >>> await result
            50
        """
        return ASyncFuture(
            self.__mul(other), dependencies=self.__list_dependencies(other)
        )

    def __pow__(self, other) -> "ASyncFuture":
        """
        Raises the result of this `ASyncFuture` to the power of another value or `ASyncFuture`.

        Args:
            other: The exponent value or `ASyncFuture`.

        Returns:
            A new `ASyncFuture` representing the power.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=2))
            >>> future2 = ASyncFuture(asyncio.sleep(1, result=3))
            >>> result = future1 ** future2
            >>> await result
            8
        """
        return ASyncFuture(
            self.__pow(other), dependencies=self.__list_dependencies(other)
        )

    def __truediv__(self, other) -> "ASyncFuture":
        """
        Divides the result of this `ASyncFuture` by another value or `ASyncFuture`.

        Args:
            other: The divisor value or `ASyncFuture`.

        Returns:
            A new `ASyncFuture` representing the quotient.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=10))
            >>> future2 = ASyncFuture(asyncio.sleep(1, result=2))
            >>> result = future1 / future2
            >>> await result
            5.0
        """
        return ASyncFuture(
            self.__truediv(other), dependencies=self.__list_dependencies(other)
        )

    def __floordiv__(self, other) -> "ASyncFuture":
        """
        Performs floor division of the result of this `ASyncFuture` by another value or `ASyncFuture`.

        Args:
            other: The divisor value or `ASyncFuture`.

        Returns:
            A new `ASyncFuture` representing the floor division result.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=10))
            >>> future2 = ASyncFuture(asyncio.sleep(1, result=3))
            >>> result = future1 // future2
            >>> await result
            3
        """
        return ASyncFuture(
            self.__floordiv(other), dependencies=self.__list_dependencies(other)
        )

    def __pow__(self, other) -> "ASyncFuture":
        """
        Raises the result of this `ASyncFuture` to the power of another value or `ASyncFuture`.

        Args:
            other: The exponent value or `ASyncFuture`.

        Returns:
            A new `ASyncFuture` representing the power.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=2))
            >>> future2 = ASyncFuture(asyncio.sleep(1, result=3))
            >>> result = future1 ** future2
            >>> await result
            8
        """
        return ASyncFuture(
            self.__pow(other), dependencies=self.__list_dependencies(other)
        )

    @overload
    def __radd__(self: "ASyncFuture[int]", other: int) -> "ASyncFuture[int]": ...

    @overload
    def __radd__(self: "ASyncFuture[float]", other: float) -> "ASyncFuture[float]": ...

    @overload
    def __radd__(self: "ASyncFuture[float]", other: int) -> "ASyncFuture[float]": ...

    @overload
    def __radd__(self: "ASyncFuture[int]", other: float) -> "ASyncFuture[float]": ...

    @overload
    def __radd__(
        self: "ASyncFuture[Decimal]", other: Decimal
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    def __radd__(
        self: "ASyncFuture[Decimal]", other: int
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    def __radd__(
        self: "ASyncFuture[int]", other: Decimal
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    def __radd__(
        self: "ASyncFuture[int]", other: Awaitable[int]
    ) -> "ASyncFuture[int]": ...

    @overload
    def __radd__(
        self: "ASyncFuture[float]", other: Awaitable[float]
    ) -> "ASyncFuture[float]": ...

    @overload
    def __radd__(
        self: "ASyncFuture[float]", other: Awaitable[int]
    ) -> "ASyncFuture[float]": ...

    @overload
    def __radd__(
        self: "ASyncFuture[int]", other: Awaitable[float]
    ) -> "ASyncFuture[float]": ...

    @overload
    def __radd__(
        self: "ASyncFuture[Decimal]", other: Awaitable[Decimal]
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    def __radd__(
        self: "ASyncFuture[Decimal]", other: Awaitable[int]
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    def __radd__(
        self: "ASyncFuture[int]", other: Awaitable[Decimal]
    ) -> "ASyncFuture[Decimal]": ...

    def __radd__(self, other) -> "ASyncFuture":
        """
        Adds another value or `ASyncFuture` to the result of this `ASyncFuture`.

        Args:
            other: The value or `ASyncFuture` to add.

        Returns:
            A new `ASyncFuture` representing the sum.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=10))
            >>> result = 5 + future1
            >>> await result
            15
        """
        return ASyncFuture(
            self.__radd(other), dependencies=self.__list_dependencies(other)
        )

    @overload
    def __rsub__(self: "ASyncFuture[int]", other: int) -> "ASyncFuture[int]": ...

    @overload
    def __rsub__(self: "ASyncFuture[float]", other: float) -> "ASyncFuture[float]": ...

    @overload
    def __rsub__(self: "ASyncFuture[float]", other: int) -> "ASyncFuture[float]": ...

    @overload
    def __rsub__(self: "ASyncFuture[int]", other: float) -> "ASyncFuture[float]": ...

    @overload
    def __rsub__(
        self: "ASyncFuture[Decimal]", other: Decimal
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    def __rsub__(
        self: "ASyncFuture[Decimal]", other: int
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    def __rsub__(
        self: "ASyncFuture[int]", other: Decimal
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    def __rsub__(
        self: "ASyncFuture[int]", other: Awaitable[int]
    ) -> "ASyncFuture[int]": ...

    @overload
    def __rsub__(
        self: "ASyncFuture[float]", other: Awaitable[float]
    ) -> "ASyncFuture[float]": ...

    @overload
    def __rsub__(
        self: "ASyncFuture[float]", other: Awaitable[int]
    ) -> "ASyncFuture[float]": ...

    @overload
    def __rsub__(
        self: "ASyncFuture[int]", other: Awaitable[float]
    ) -> "ASyncFuture[float]": ...

    @overload
    def __rsub__(
        self: "ASyncFuture[Decimal]", other: Awaitable[Decimal]
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    def __rsub__(
        self: "ASyncFuture[Decimal]", other: Awaitable[int]
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    def __rsub__(
        self: "ASyncFuture[int]", other: Awaitable[Decimal]
    ) -> "ASyncFuture[Decimal]": ...

    def __rsub__(self, other) -> "ASyncFuture":
        """
        Subtracts the result of this `ASyncFuture` from another value or `ASyncFuture`.

        Args:
            other: The value or `ASyncFuture` to subtract from.

        Returns:
            A new `ASyncFuture` representing the difference.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=10))
            >>> result = 20 - future1
            >>> await result
            10
        """
        return ASyncFuture(
            self.__rsub(other), dependencies=self.__list_dependencies(other)
        )

    def __rmul__(self, other) -> "ASyncFuture":
        """
        Multiplies another value or `ASyncFuture` by the result of this `ASyncFuture`.

        Args:
            other: The value or `ASyncFuture` to multiply.

        Returns:
            A new `ASyncFuture` representing the product.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=10))
            >>> result = 2 * future1
            >>> await result
            20
        """
        return ASyncFuture(
            self.__rmul(other), dependencies=self.__list_dependencies(other)
        )

    def __rtruediv__(self, other) -> "ASyncFuture":
        """
        Divides another value or `ASyncFuture` by the result of this `ASyncFuture`.

        Args:
            other: The value or `ASyncFuture` to divide.

        Returns:
            A new `ASyncFuture` representing the quotient.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=2))
            >>> result = 10 / future1
            >>> await result
            5.0
        """
        return ASyncFuture(
            self.__rtruediv(other), dependencies=self.__list_dependencies(other)
        )

    def __rfloordiv__(self, other) -> "ASyncFuture":
        """
        Performs floor division of another value or `ASyncFuture` by the result of this `ASyncFuture`.

        Args:
            other: The value or `ASyncFuture` to divide.

        Returns:
            A new `ASyncFuture` representing the floor division result.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=3))
            >>> result = 10 // future1
            >>> await result
            3
        """
        return ASyncFuture(
            self.__rfloordiv(other), dependencies=self.__list_dependencies(other)
        )

    def __rpow__(self, other) -> "ASyncFuture":
        """
        Raises another value or `ASyncFuture` to the power of the result of this `ASyncFuture`.

        Args:
            other: The base value or `ASyncFuture`.

        Returns:
            A new `ASyncFuture` representing the power.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=3))
            >>> result = 2 ** future1
            >>> await result
            8
        """
        return ASyncFuture(
            self.__rpow(other), dependencies=self.__list_dependencies(other)
        )

    def __eq__(self, other) -> "ASyncFuture":
        """
        Compares the result of this `ASyncFuture` with another value or `ASyncFuture` for equality.

        Args:
            other: The value or `ASyncFuture` to compare.

        Returns:
            A new `ASyncFuture` representing the equality comparison result.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=10))
            >>> future2 = ASyncFuture(asyncio.sleep(1, result=10))
            >>> result = future1 == future2
            >>> await result
            True
        """
        return bool(
            ASyncFuture(self.__eq(other), dependencies=self.__list_dependencies(other))
        )

    def __gt__(self, other) -> "ASyncFuture":
        """
        Compares the result of this `ASyncFuture` with another value or `ASyncFuture` for greater than.

        Args:
            other: The value or `ASyncFuture` to compare.

        Returns:
            A new `ASyncFuture` representing the greater than comparison result.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=10))
            >>> future2 = ASyncFuture(asyncio.sleep(1, result=5))
            >>> result = future1 > future2
            >>> await result
            True
        """
        return ASyncFuture(
            self.__gt(other), dependencies=self.__list_dependencies(other)
        )

    def __ge__(self, other) -> "ASyncFuture":
        """
        Compares the result of this `ASyncFuture` with another value or `ASyncFuture` for greater than or equal.

        Args:
            other: The value or `ASyncFuture` to compare.

        Returns:
            A new `ASyncFuture` representing the greater than or equal comparison result.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=10))
            >>> future2 = ASyncFuture(asyncio.sleep(1, result=10))
            >>> result = future1 >= future2
            >>> await result
            True
        """
        return ASyncFuture(
            self.__ge(other), dependencies=self.__list_dependencies(other)
        )

    def __lt__(self, other) -> "ASyncFuture":
        """
        Compares the result of this `ASyncFuture` with another value or `ASyncFuture` for less than.

        Args:
            other: The value or `ASyncFuture` to compare.

        Returns:
            A new `ASyncFuture` representing the less than comparison result.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=5))
            >>> future2 = ASyncFuture(asyncio.sleep(1, result=10))
            >>> result = future1 < future2
            >>> await result
            True
        """
        return ASyncFuture(
            self.__lt(other), dependencies=self.__list_dependencies(other)
        )

    def __le__(self, other) -> "ASyncFuture":
        """
        Compares the result of this `ASyncFuture` with another value or `ASyncFuture` for less than or equal.

        Args:
            other: The value or `ASyncFuture` to compare.

        Returns:
            A new `ASyncFuture` representing the less than or equal comparison result.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=5))
            >>> future2 = ASyncFuture(asyncio.sleep(1, result=5))
            >>> result = future1 <= future2
            >>> await result
            True
        """
        return ASyncFuture(
            self.__le(other), dependencies=self.__list_dependencies(other)
        )

    # Maths

    @overload
    async def __add(self: "ASyncFuture[int]", other: int) -> "ASyncFuture[int]": ...

    @overload
    async def __add(
        self: "ASyncFuture[float]", other: float
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __add(self: "ASyncFuture[float]", other: int) -> "ASyncFuture[float]": ...

    @overload
    async def __add(self: "ASyncFuture[int]", other: float) -> "ASyncFuture[float]": ...

    @overload
    async def __add(
        self: "ASyncFuture[Decimal]", other: Decimal
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __add(
        self: "ASyncFuture[Decimal]", other: int
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __add(
        self: "ASyncFuture[int]", other: Decimal
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __add(
        self: "ASyncFuture[int]", other: Awaitable[int]
    ) -> "ASyncFuture[int]": ...

    @overload
    async def __add(
        self: "ASyncFuture[float]", other: Awaitable[float]
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __add(
        self: "ASyncFuture[float]", other: Awaitable[int]
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __add(
        self: "ASyncFuture[int]", other: Awaitable[float]
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __add(
        self: "ASyncFuture[Decimal]", other: Awaitable[Decimal]
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __add(
        self: "ASyncFuture[Decimal]", other: Awaitable[int]
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __add(
        self: "ASyncFuture[int]", other: Awaitable[Decimal]
    ) -> "ASyncFuture[Decimal]": ...

    async def __add(self, other) -> "Any":
        a, b = await _gather_check_and_materialize(self, other)
        return a + b

    @overload
    async def __sub(self: "ASyncFuture[int]", other: int) -> "ASyncFuture[int]": ...

    @overload
    async def __sub(
        self: "ASyncFuture[float]", other: float
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __sub(self: "ASyncFuture[float]", other: int) -> "ASyncFuture[float]": ...

    @overload
    async def __sub(self: "ASyncFuture[int]", other: float) -> "ASyncFuture[float]": ...

    @overload
    async def __sub(
        self: "ASyncFuture[Decimal]", other: Decimal
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __sub(
        self: "ASyncFuture[Decimal]", other: int
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __sub(
        self: "ASyncFuture[int]", other: Decimal
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __sub(
        self: "ASyncFuture[int]", other: Awaitable[int]
    ) -> "ASyncFuture[int]": ...

    @overload
    async def __sub(
        self: "ASyncFuture[float]", other: Awaitable[float]
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __sub(
        self: "ASyncFuture[float]", other: Awaitable[int]
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __sub(
        self: "ASyncFuture[int]", other: Awaitable[float]
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __sub(
        self: "ASyncFuture[Decimal]", other: Awaitable[Decimal]
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __sub(
        self: "ASyncFuture[Decimal]", other: Awaitable[int]
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __sub(
        self: "ASyncFuture[int]", other: Awaitable[Decimal]
    ) -> "ASyncFuture[Decimal]": ...

    async def __sub(self, other) -> "Any":
        a, b = await _gather_check_and_materialize(self, other)
        return a - b

    async def __mul(self, other) -> "Any":
        a, b = await _gather_check_and_materialize(self, other)
        return a * b

    async def __truediv(self, other) -> "Any":
        a, b = await _gather_check_and_materialize(self, other)
        return a / b

    async def __floordiv(self, other) -> "Any":
        a, b = await _gather_check_and_materialize(self, other)
        return a // b

    async def __pow(self, other) -> "Any":
        a, b = await _gather_check_and_materialize(self, other)
        return a**b

    # rMaths
    @overload
    async def __radd(self: "ASyncFuture[int]", other: int) -> "ASyncFuture[int]": ...

    @overload
    async def __radd(
        self: "ASyncFuture[float]", other: float
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __radd(
        self: "ASyncFuture[float]", other: int
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __radd(
        self: "ASyncFuture[int]", other: float
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __radd(
        self: "ASyncFuture[Decimal]", other: Decimal
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __radd(
        self: "ASyncFuture[Decimal]", other: int
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __radd(
        self: "ASyncFuture[int]", other: Decimal
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __radd(
        self: "ASyncFuture[int]", other: Awaitable[int]
    ) -> "ASyncFuture[int]": ...

    @overload
    async def __radd(
        self: "ASyncFuture[float]", other: Awaitable[float]
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __radd(
        self: "ASyncFuture[float]", other: Awaitable[int]
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __radd(
        self: "ASyncFuture[int]", other: Awaitable[float]
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __radd(
        self: "ASyncFuture[Decimal]", other: Awaitable[Decimal]
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __radd(
        self: "ASyncFuture[Decimal]", other: Awaitable[int]
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __radd(
        self: "ASyncFuture[int]", other: Awaitable[Decimal]
    ) -> "ASyncFuture[Decimal]": ...

    async def __radd(self, other) -> "Any":
        a, b = await _gather_check_and_materialize(other, self)
        return a + b

    @overload
    async def __rsub(self: "ASyncFuture[int]", other: int) -> "ASyncFuture[int]": ...

    @overload
    async def __rsub(
        self: "ASyncFuture[float]", other: float
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __rsub(
        self: "ASyncFuture[float]", other: int
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __rsub(
        self: "ASyncFuture[int]", other: float
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __rsub(
        self: "ASyncFuture[Decimal]", other: Decimal
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __rsub(
        self: "ASyncFuture[Decimal]", other: int
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __rsub(
        self: "ASyncFuture[int]", other: Decimal
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __rsub(
        self: "ASyncFuture[int]", other: Awaitable[int]
    ) -> "ASyncFuture[int]": ...

    @overload
    async def __rsub(
        self: "ASyncFuture[float]", other: Awaitable[float]
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __rsub(
        self: "ASyncFuture[float]", other: Awaitable[int]
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __rsub(
        self: "ASyncFuture[int]", other: Awaitable[float]
    ) -> "ASyncFuture[float]": ...

    @overload
    async def __rsub(
        self: "ASyncFuture[Decimal]", other: Awaitable[Decimal]
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __rsub(
        self: "ASyncFuture[Decimal]", other: Awaitable[int]
    ) -> "ASyncFuture[Decimal]": ...

    @overload
    async def __rsub(
        self: "ASyncFuture[int]", other: Awaitable[Decimal]
    ) -> "ASyncFuture[Decimal]": ...

    async def __rsub(self, other) -> "Any":
        a, b = await _gather_check_and_materialize(other, self)
        return a - b

    async def __rmul(self, other) -> "Any":
        a, b = await _gather_check_and_materialize(other, self)
        return a * b

    async def __rtruediv(self, other) -> "Any":
        a, b = await _gather_check_and_materialize(other, self)
        return a / b

    async def __rfloordiv(self, other) -> "Any":
        a, b = await _gather_check_and_materialize(other, self)
        return a // b

    async def __rpow(self, other) -> "Any":
        a, b = await _gather_check_and_materialize(other, self)
        return a**b

    async def __iadd(self, other) -> "Any":
        a, b = await _gather_check_and_materialize(self, other)
        self._result = a + b
        return self._result

    async def __isub(self, other) -> "Any":
        a, b = await _gather_check_and_materialize(self, other)
        self._result = a - b
        return self._result

    async def __imul(self, other) -> "Any":
        a, b = await _gather_check_and_materialize(self, other)
        self._result = a * b
        return self._result

    async def __itruediv(self, other) -> "Any":
        a, b = await _gather_check_and_materialize(self, other)
        self._result = a / b
        return self._result

    async def __ifloordiv(self, other) -> "Any":
        a, b = await _gather_check_and_materialize(self, other)
        self._result = a // b
        return self._result

    async def __ipow(self, other) -> "Any":
        a, b = await _gather_check_and_materialize(self, other)
        self._result = a**b
        return self._result

    # Comparisons
    async def __eq(self, other) -> bool:
        a, b = await _gather_check_and_materialize(self, other)
        return a == b

    async def __gt(self, other) -> bool:
        a, b = await _gather_check_and_materialize(self, other)
        return a > b

    async def __ge(self, other) -> bool:
        a, b = await _gather_check_and_materialize(self, other)
        return a >= b

    async def __lt(self, other) -> bool:
        a, b = await _gather_check_and_materialize(self, other)
        return a < b

    async def __le(self, other) -> bool:
        a, b = await _gather_check_and_materialize(self, other)
        return a <= b

    # not sure what to call these
    async def __contains(self, item: Any) -> bool:
        _self, _item = await _gather_check_and_materialize(self, item)
        return _item in _self

    # conversion
    # NOTE: We aren't allowed to return ASyncFutures here :(
    def __bool__(self) -> bool:
        return bool(_materialize(self))

    def __bytes__(self) -> bytes:
        return bytes(_materialize(self))

    def __str__(self) -> str:
        return str(_materialize(self))

    def __int__(self) -> int:
        return int(_materialize(self))

    def __float__(self) -> float:
        return float(_materialize(self))

    # WIP internals

    @property
    def __dependants__(self) -> Set["ASyncFuture"]:
        """
        Returns the set of dependants for this `ASyncFuture`, including nested dependants.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=42))
            >>> future2 = ASyncFuture(asyncio.sleep(1, result=10), dependencies=[future1])
            >>> dependants = future1.__dependants__
            >>> future2 in dependants
            True
        """
        dependants = set()
        for dep in self.__dependants:
            dependants.add(dep)
            dependants.union(dep.__dependants__)
        return dependants

    @property
    def __dependencies__(self) -> Set["ASyncFuture"]:
        """
        Returns the set of dependencies for this `ASyncFuture`, including nested dependencies.

        Example:
            >>> future1 = ASyncFuture(asyncio.sleep(1, result=42))
            >>> future2 = ASyncFuture(asyncio.sleep(1, result=10), dependencies=[future1])
            >>> dependencies = future2.__dependencies__
            >>> future1 in dependencies
            True
        """
        dependencies = set()
        for dep in self.__dependencies:
            dependencies.add(dep)
            dependencies.union(dep.__dependencies__)
        return dependencies

    def __sizeof__(self) -> int:
        if isinstance(self.__awaitable__, Coroutine):
            return sum(
                sys.getsizeof(v) for v in self.__awaitable__.cr_frame.f_locals.values()
            )
        elif isinstance(self.__awaitable__, asyncio.Future):
            raise NotImplementedError
        raise NotImplementedError


@final
class _ASyncFutureWrappedFn(Callable[P, ASyncFuture[T]]):
    """
    A callable class to wrap functions and return `ASyncFuture` objects.

    This class is used internally by the `future` decorator to wrap a function
    and return an `ASyncFuture` when the function is called. It allows the
    function to be executed asynchronously and its result to be awaited.

    Example:
        >>> def sync_fn():
        ...     return 42
        >>> wrapped_fn = _ASyncFutureWrappedFn(sync_fn)
        >>> future = wrapped_fn()
        >>> isinstance(future, ASyncFuture)
        True

    Note:
        This is not part of the public API. Use the `future` decorator instead.
    """

    __slots__ = "callable", "wrapped", "_callable_name"

    def __init__(
        self,
        callable: AnyFn[P, T] = None,
        **kwargs: Unpack[ModifierKwargs],
    ):
        from a_sync import a_sync

        if callable:
            self.callable = callable
            """The callable function."""

            self._callable_name = callable.__name__
            """The name of the callable function."""

            a_sync_callable = a_sync(callable, default="async", **kwargs)

            @wraps(callable)
            def future_wrap(*args: P.args, **kwargs: P.kwargs) -> "ASyncFuture[T]":
                return ASyncFuture(a_sync_callable(*args, **kwargs, sync=False))

            self.wrapped = future_wrap
            """The wrapped function returning ASyncFuture."""
        else:
            self.wrapped = partial(_ASyncFutureWrappedFn, **kwargs)

    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> ASyncFuture[T]:
        return self.wrapped(*args, **kwargs)

    def __repr__(self) -> str:
        return f"<{self.__class__.__name__} {self.callable}>"

    def __get__(
        self, instance: I, owner: Type[I]
    ) -> Union[Self, "_ASyncFutureInstanceMethod[I, P, T]"]:
        return self if owner is None else _ASyncFutureInstanceMethod(self, instance)


@final
class _ASyncFutureInstanceMethod(Generic[I, P, T]):
    # NOTE: probably could just replace this with functools.partial
    """
    A class to handle instance methods wrapped as `ASyncFuture`.

    This class is used internally to manage instance methods that are wrapped
    by `_ASyncFutureWrappedFn`. It ensures that the method is bound to the
    instance and returns an `ASyncFuture` when called.

    Example:
        >>> class MyClass:
        ...     @_ASyncFutureWrappedFn
        ...     def method(self):
        ...         return 42
        >>> instance = MyClass()
        >>> future = instance.method()
        >>> isinstance(future, ASyncFuture)
        True

    Note:
        This is not part of the public API. Use the `future` decorator instead.
    """

    __module__: str
    """The module name of the wrapper."""

    __name__: str
    """The name of the wrapper."""

    __qualname__: str
    """The qualified name of the wrapper."""

    __doc__: Optional[str]
    """The docstring of the wrapper."""

    __annotations__: Dict[str, Any]
    """The annotations of the wrapper."""

    __instance: I
    """The instance to which the method is bound."""

    __wrapper: _ASyncFutureWrappedFn[P, T]
    """The wrapper function."""

    def __init__(
        self,
        wrapper: _ASyncFutureWrappedFn[P, T],
        instance: I,
    ) -> None:  # sourcery skip: use-contextlib-suppress
        try:
            self.__module__ = wrapper.__module__
        except AttributeError:
            pass
        try:
            self.__name__ = wrapper.__name__
        except AttributeError:
            pass
        try:
            self.__qualname__ = wrapper.__qualname__
        except AttributeError:
            pass
        try:
            self.__doc__ = wrapper.__doc__
        except AttributeError:
            pass
        try:
            self.__annotations__ = wrapper.__annotations__
        except AttributeError:
            pass
        try:
            self.__dict__.update(wrapper.__dict__)
        except AttributeError:
            pass
        self.__instance = instance
        self.__wrapper = wrapper

    def __repr__(self) -> str:
        return f"<{self.__class__.__name__} for {self.__wrapper.callable} bound to {self.__instance}>"

    def __call__(self, /, *fn_args: P.args, **fn_kwargs: P.kwargs) -> T:
        return self.__wrapper(self.__instance, *fn_args, **fn_kwargs)


__all__ = ["future", "ASyncFuture"]
