ez-a-sync 0.33.4__cp313-cp313-musllinux_1_2_i686.whl

a_sync/a_sync/function.pyx

@@ -0,0 +1,1381 @@
+import asyncio
+import inspect
+import sys
+import typing
+from logging import getLogger
+from libc.stdint cimport uintptr_t
+
+import async_lru
+import async_property
+from typing_extensions import Unpack
+
+from a_sync._typing import AnyFn, AnyIterable, CoroFn, DefaultMode, MaybeCoro, ModifierKwargs, P, SyncFn, T
+from a_sync.a_sync._kwargs cimport get_flag_name, is_sync
+from a_sync.a_sync._helpers cimport _asyncify, _await
+from a_sync.a_sync.flags cimport VIABLE_FLAGS
+from a_sync.a_sync.modifiers cimport ModifierManager
+from a_sync.functools cimport update_wrapper, wraps
+
+if typing.TYPE_CHECKING:
+    from a_sync import TaskMapping
+    from a_sync.a_sync.method import (
+        ASyncBoundMethod,
+        ASyncBoundMethodAsyncDefault,
+        ASyncBoundMethodSyncDefault,
+    )
+
+else:
+    # due to circ import issues we will populate this later
+    TaskMapping = None
+
+
+ctypedef object object_id
+
+
+# cdef asyncio
+cdef object iscoroutinefunction = asyncio.iscoroutinefunction
+del asyncio
+
+# cdef inspect
+cdef object getargspec
+if sys.version_info < (3, 11):
+    getargspec = inspect.getargspec
+else:
+    # getargspec was deprecated in python 3.11
+    getargspec = inspect.getfullargspec
+cdef object isasyncgenfunction = inspect.isasyncgenfunction
+cdef object isgeneratorfunction = inspect.isgeneratorfunction
+del inspect
+
+# cdef logging
+cdef public object logger = getLogger(__name__)
+cdef object _logger_debug = logger.debug
+
+# cdef typing
+cdef object TYPE_CHECKING = typing.TYPE_CHECKING
+cdef object Any = typing.Any
+cdef object Callable = typing.Callable
+cdef object Coroutine = typing.Coroutine
+cdef object Generic = typing.Generic
+cdef object Literal = typing.Literal
+cdef object Optional = typing.Optional
+cdef object overload = typing.overload
+
+
+# cdef async_lru
+cdef object _LRUCacheWrapper = async_lru._LRUCacheWrapper
+
+# cdef async_property
+cdef object AsyncPropertyDescriptor = async_property.base.AsyncPropertyDescriptor
+cdef object AsyncCachedPropertyDescriptor = async_property.cached.AsyncCachedPropertyDescriptor
+
+
+cdef class _ModifiedMixin:
+    """
+    A mixin class for internal use that provides functionality for applying modifiers to functions.
+
+    This class is used as a base for :class:`~ASyncFunction` and its variants, such as
+    `ASyncFunctionAsyncDefault` and `ASyncFunctionSyncDefault`, to handle the application
+    of async and sync modifiers to functions. Modifiers can alter the behavior of functions,
+    such as converting sync functions to async, applying caching, or rate limiting.
+
+    See Also:
+        - :class:`~ASyncFunction`
+        - :class:`~ModifierManager`
+    """
+
+    @property
+    def default(self) -> DefaultMode:
+        """
+        Gets the default execution mode (sync, async, or None) for the function.
+
+        Returns:
+            The default execution mode.
+
+        See Also:
+            - :attr:`ModifierManager.default`
+        """
+        return self.get_default()
+
+    cdef inline object _asyncify(self, func: SyncFn[P, T]):
+        """
+        Converts a synchronous function to an asynchronous one and applies async modifiers.
+
+        Args:
+            func: The synchronous function to be converted.
+
+        Returns:
+            The asynchronous version of the function with applied modifiers.
+
+        See Also:
+            - :meth:`ModifierManager.apply_async_modifiers`
+        """
+        return self.modifiers.apply_async_modifiers(_asyncify(func, self.modifiers.executor))
+    
+    cdef inline object get_await(self):
+        """
+        Applies sync modifiers to the _helpers._await function and caches it.
+
+        Returns:
+            The modified _await function.
+
+        See Also:
+            - :meth:`ModifierManager.apply_sync_modifiers`
+        """
+        awaiter = self.__await
+        if awaiter is None:
+            awaiter = self.modifiers.apply_sync_modifiers(_await)
+            self.__await = awaiter
+        return awaiter
+    
+    cdef inline str get_default(self):
+        cdef str default = self.__default
+        if default is None:
+            default = self.modifiers.get_default()
+            self.__default = default
+        return default
+
+
+
+cdef void _validate_wrapped_fn(fn: Callable):
+    """Ensures 'fn' is an appropriate function for wrapping with a_sync.
+
+    Args:
+        fn: The function to validate.
+
+    Raises:
+        TypeError: If the input is not callable.
+        RuntimeError: If the function has arguments with names that conflict with viable flags.
+
+    See Also:
+        - :func:`_check_not_genfunc`
+    """
+    typ = type(fn)
+    if typ is _function_type:
+        _check_not_genfunc_cached(fn)
+        _validate_argspec_cached(fn)
+        return
+    if issubclass(typ, (AsyncPropertyDescriptor, AsyncCachedPropertyDescriptor)):
+        return  # These are always valid
+    elif issubclass(typ, _LRUCacheWrapper):
+        fn = fn.__wrapped__
+        if type(fn) is _function_type:
+            _check_not_genfunc_cached(fn)
+            _validate_argspec_cached(fn)
+            return
+    elif not callable(fn):
+        raise TypeError(f"Input is not callable. Unable to decorate {fn}")
+    _check_not_genfunc(fn)
+    _validate_argspec(fn)
+
+cdef object _function_type = type(getLogger)
+
+cdef set[object_id] _argspec_validated = set()
+
+cdef inline void _validate_argspec_cached(fn: Callable):
+    cdef object_id fid = id(fn)
+    if fid not in _argspec_validated:
+        _validate_argspec(fn)
+        _argspec_validated.add(fid)
+
+cdef inline void _validate_argspec(fn: Callable):
+    cdef tuple[str, ...] fn_args
+    cdef object fn_code
+    
+    try:
+        fn_code = fn.__code__  # May fail for built-ins or special callables
+        fn_args = fn_code.co_varnames[:fn_code.co_argcount]
+    except:
+        try:
+            argspec = getargspec(fn)
+        except TypeError:
+            warn = logger.warning
+            warn(f"inspect.{getargspec.__name__} does not support {fn}")
+            warn("we will allow you to proceed but cannot guarantee things will work")
+            warn("hopefully you know what you're doing...")
+            return
+        else:
+            # python argspec is already a tuple but mypyc compiled functions
+            # return a list which me must coerce to tuple.
+            fn_args = tuple(argspec[0])
+    
+    for flag in fn_args:
+        if flag in VIABLE_FLAGS:
+            raise RuntimeError(
+                f"{fn} must not have any arguments with the following names: {VIABLE_FLAGS}"
+            )
+
+    
+cdef class _ASyncFunction(_ModifiedMixin):
+    """
+    A callable wrapper object that can be executed both synchronously and asynchronously.
+
+    This class wraps a function or coroutine function, allowing it to be called in both
+    synchronous and asynchronous contexts. It provides a flexible interface for handling
+    different execution modes and applying various modifiers to the function's behavior.
+
+    The class supports various modifiers that can alter the behavior of the function,
+    such as caching, rate limiting, and execution in specific contexts (e.g., thread pools).
+
+    Note:
+        The logic for determining whether to execute the function synchronously or asynchronously
+        is handled by the `self.fn` property, which checks for flags in the `kwargs` and defers
+        to the default execution mode if no flags are specified.
+
+    Example:
+        async def my_coroutine(x: int) -> str:
+            return str(x)
+
+        func = ASyncFunction(my_coroutine)
+
+        # Synchronous call
+        result = func(5, sync=True)  # returns "5"
+
+        # Asynchronous call
+        result = await func(5)  # returns "5"
+
+    See Also:
+        - :class:`_ModifiedMixin`
+        - :class:`ModifierManager`
+    """
+
+    def __init__(
+        self,
+        fn: AnyFn[P, T],
+        _skip_validate: bint = False,
+        **modifiers: Unpack[ModifierKwargs],
+    ) -> None:
+        """
+        Initializes an ASyncFunction instance.
+
+        Args:
+            fn: The function to wrap.
+            _skip_validate: For internal use only. Skips validation of the wrapped function when its already been validated once before.
+            **modifiers: Keyword arguments for function modifiers.
+
+        See Also:
+            - :func:`_validate_wrapped_fn`
+            - :class:`ModifierManager`
+        """
+        if not _skip_validate:
+            _validate_wrapped_fn(fn)
+
+        self.modifiers = ModifierManager(modifiers)
+        """A :class:`~ModifierManager` instance managing function modifiers."""
+
+        self._fn = None
+        """The wrapped callable that will be called. This will be populated the first time it is needed."""
+
+        self.__wrapped__ = fn
+        """The original function that was wrapped."""
+
+        self.__sync_default_cached = False
+        self.__async_def_cached = False
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> MaybeCoro[T]:
+        """
+        Calls the wrapped function either synchronously or asynchronously.
+
+        This method determines whether to execute the wrapped function synchronously
+        or asynchronously based on the default mode and any provided flags. The
+        decision logic is encapsulated within the `self.fn` property, which uses
+        the `_run_sync` method to decide the execution mode.
+
+        Note:
+            The `self.fn` property is responsible for selecting the appropriate
+            execution path (sync or async) by leveraging the `_run_sync` method.
+
+        Args:
+            *args: Positional arguments to pass to the wrapped function.
+            **kwargs: Keyword arguments to pass to the wrapped function.
+
+        Raises:
+            Exception: Any exception that may be raised by the wrapped function.
+
+        See Also:
+            - :attr:`default`
+            - :meth:`_run_sync`
+        """
+        fn = self.get_fn()
+        _logger_debug(
+            "calling %s fn: %s with args: %s kwargs: %s", self, fn, args, kwargs
+        )
+        return fn(*args, **kwargs)
+
+    def __repr__(self) -> str:
+        return "<{} {}.{} at {}>".format(
+            self.__class__.__name__, self.__module__, self.__name__, hex(id(self))
+        )
+
+    @property
+    def fn(self):
+        # NOTE type hint doesnt work in py3.8 or py3.9, debug later
+        #  -> Union[SyncFn[[CoroFn[P, T]], MaybeAwaitable[T]], SyncFn[[SyncFn[P, T]], MaybeAwaitable[T]]]:
+        """
+        Returns the final wrapped version of :attr:`ASyncFunction.__wrapped__` decorated with all of the a_sync goodness.
+
+        Returns:
+            The final wrapped function.
+
+        See Also:
+            - :meth:`_async_wrap`
+            - :meth:`_sync_wrap`
+        """
+        return self.get_fn()
+
+    cdef object get_fn(self):
+        fn = self._fn
+        if fn is None:
+            fn = self._async_wrap if self.is_async_def() else self._sync_wrap
+            self._fn = fn
+        return fn
+
+    if sys.version_info >= (3, 11) or TYPE_CHECKING:
+        # we can specify P.args in python>=3.11 but in lower versions it causes a crash. Everything should still type check correctly on all versions.
+        def map(
+            self,
+            *iterables: AnyIterable[P.args],
+            concurrency: Optional[int] = None,
+            task_name: str = "",
+            **function_kwargs: P.kwargs,
+        ) -> "TaskMapping[P, T]":
+            """
+            Creates a TaskMapping for the wrapped function with the given iterables.
+
+            Args:
+                *iterables: Iterable objects to be used as arguments for the function.
+                concurrency: Optional maximum number of concurrent tasks.
+                task_name: Optional name for the tasks.
+                **function_kwargs: Additional keyword arguments to pass to the function.
+
+            Returns:
+                A TaskMapping object for managing concurrent execution.
+
+            See Also:
+                - :class:`TaskMapping`
+            """
+            if TaskMapping is None:
+                _import_TaskMapping()
+
+            return TaskMapping(
+                self,
+                *iterables,
+                concurrency=concurrency,
+                name=task_name,
+                **function_kwargs,
+            )
+
+        async def any(
+            self,
+            *iterables: AnyIterable[P.args],
+            concurrency: Optional[int] = None,
+            task_name: str = "",
+            **function_kwargs: P.kwargs,
+        ) -> bint:
+            """
+            Checks if any result of the function applied to the iterables is truthy.
+
+            Args:
+                *iterables: Iterable objects to be used as arguments for the function.
+                concurrency: Optional maximum number of concurrent tasks.
+                task_name: Optional name for the tasks.
+                **function_kwargs: Additional keyword arguments to pass to the function.
+
+            Returns:
+                True if any result is truthy, otherwise False.
+
+            See Also:
+                - :meth:`map`
+            """
+            return await self.map(
+                *iterables,
+                concurrency=concurrency,
+                task_name=task_name,
+                **function_kwargs,
+            ).any(pop=True, sync=False)
+
+        async def all(
+            self,
+            *iterables: AnyIterable[P.args],
+            concurrency: Optional[int] = None,
+            task_name: str = "",
+            **function_kwargs: P.kwargs,
+        ) -> bint:
+            """
+            Checks if all results of the function applied to the iterables are truthy.
+
+            Args:
+                *iterables: Iterable objects to be used as arguments for the function.
+                concurrency: Optional maximum number of concurrent tasks.
+                task_name: Optional name for the tasks.
+                **function_kwargs: Additional keyword arguments to pass to the function.
+
+            Returns:
+                True if all results are truthy, otherwise False.
+
+            See Also:
+                - :meth:`map`
+            """
+            return await self.map(
+                *iterables,
+                concurrency=concurrency,
+                task_name=task_name,
+                **function_kwargs,
+            ).all(pop=True, sync=False)
+
+        async def min(
+            self,
+            *iterables: AnyIterable[P.args],
+            concurrency: Optional[int] = None,
+            task_name: str = "",
+            **function_kwargs: P.kwargs,
+        ) -> T:
+            """
+            Finds the minimum result of the function applied to the iterables.
+
+            Args:
+                *iterables: Iterable objects to be used as arguments for the function.
+                concurrency: Optional maximum number of concurrent tasks.
+                task_name: Optional name for the tasks.
+                **function_kwargs: Additional keyword arguments to pass to the function.
+
+            Returns:
+                The minimum result.
+
+            See Also:
+                - :meth:`map`
+            """
+            return await self.map(
+                *iterables,
+                concurrency=concurrency,
+                task_name=task_name,
+                **function_kwargs,
+            ).min(pop=True, sync=False)
+
+        async def max(
+            self,
+            *iterables: AnyIterable[P.args],
+            concurrency: Optional[int] = None,
+            task_name: str = "",
+            **function_kwargs: P.kwargs,
+        ) -> T:
+            """
+            Finds the maximum result of the function applied to the iterables.
+
+            Args:
+                *iterables: Iterable objects to be used as arguments for the function.
+                concurrency: Optional maximum number of concurrent tasks.
+                task_name: Optional name for the tasks.
+                **function_kwargs: Additional keyword arguments to pass to the function.
+
+            Returns:
+                The maximum result.
+
+            See Also:
+                - :meth:`map`
+            """
+            return await self.map(
+                *iterables,
+                concurrency=concurrency,
+                task_name=task_name,
+                **function_kwargs,
+            ).max(pop=True, sync=False)
+
+        async def sum(
+            self,
+            *iterables: AnyIterable[P.args],
+            concurrency: Optional[int] = None,
+            task_name: str = "",
+            **function_kwargs: P.kwargs,
+        ) -> T:
+            """
+            Calculates the sum of the results of the function applied to the iterables.
+
+            Args:
+                *iterables: Iterable objects to be used as arguments for the function.
+                concurrency: Optional maximum number of concurrent tasks.
+                task_name: Optional name for the tasks.
+                **function_kwargs: Additional keyword arguments to pass to the function.
+
+            Returns:
+                The sum of the results.
+
+            See Also:
+                - :meth:`map`
+            """
+            return await self.map(
+                *iterables,
+                concurrency=concurrency,
+                task_name=task_name,
+                **function_kwargs,
+            ).sum(pop=True, sync=False)
+
+    else:
+
+        def map(
+            self,
+            *iterables: AnyIterable[Any],
+            concurrency: Optional[int] = None,
+            task_name: str = "",
+            **function_kwargs: P.kwargs,
+        ) -> "TaskMapping[P, T]":
+            """
+            Creates a TaskMapping for the wrapped function with the given iterables.
+
+            Args:
+                *iterables: Iterable objects to be used as arguments for the function.
+                concurrency: Optional maximum number of concurrent tasks.
+                task_name: Optional name for the tasks.
+                **function_kwargs: Additional keyword arguments to pass to the function.
+
+            Returns:
+                A TaskMapping object for managing concurrent execution.
+
+            See Also:
+                - :class:`TaskMapping`
+            """
+            if TaskMapping is None:
+                _import_TaskMapping()
+
+            return TaskMapping(
+                self,
+                *iterables,
+                concurrency=concurrency,
+                name=task_name,
+                **function_kwargs,
+            )
+
+        async def any(
+            self,
+            *iterables: AnyIterable[Any],
+            concurrency: Optional[int] = None,
+            task_name: str = "",
+            **function_kwargs: P.kwargs,
+        ) -> bint:
+            """
+            Checks if any result of the function applied to the iterables is truthy.
+
+            Args:
+                *iterables: Iterable objects to be used as arguments for the function.
+                concurrency: Optional maximum number of concurrent tasks.
+                task_name: Optional name for the tasks.
+                **function_kwargs: Additional keyword arguments to pass to the function.
+
+            Returns:
+                True if any result is truthy, otherwise False.
+
+            See Also:
+                - :meth:`map`
+            """
+            return await self.map(
+                *iterables,
+                concurrency=concurrency,
+                task_name=task_name,
+                **function_kwargs,
+            ).any(pop=True, sync=False)
+
+        async def all(
+            self,
+            *iterables: AnyIterable[Any],
+            concurrency: Optional[int] = None,
+            task_name: str = "",
+            **function_kwargs: P.kwargs,
+        ) -> bint:
+            """
+            Checks if all results of the function applied to the iterables are truthy.
+
+            Args:
+                *iterables: Iterable objects to be used as arguments for the function.
+                concurrency: Optional maximum number of concurrent tasks.
+                task_name: Optional name for the tasks.
+                **function_kwargs: Additional keyword arguments to pass to the function.
+
+            Returns:
+                True if all results are truthy, otherwise False.
+
+            See Also:
+                - :meth:`map`
+            """
+            return await self.map(
+                *iterables,
+                concurrency=concurrency,
+                task_name=task_name,
+                **function_kwargs,
+            ).all(pop=True, sync=False)
+
+        async def min(
+            self,
+            *iterables: AnyIterable[Any],
+            concurrency: Optional[int] = None,
+            task_name: str = "",
+            **function_kwargs: P.kwargs,
+        ) -> T:
+            """
+            Finds the minimum result of the function applied to the iterables.
+
+            Args:
+                *iterables: Iterable objects to be used as arguments for the function.
+                concurrency: Optional maximum number of concurrent tasks.
+                task_name: Optional name for the tasks.
+                **function_kwargs: Additional keyword arguments to pass to the function.
+
+            Returns:
+                The minimum result.
+
+            See Also:
+                - :meth:`map`
+            """
+            return await self.map(
+                *iterables,
+                concurrency=concurrency,
+                task_name=task_name,
+                **function_kwargs,
+            ).min(pop=True, sync=False)
+
+        async def max(
+            self,
+            *iterables: AnyIterable[Any],
+            concurrency: Optional[int] = None,
+            task_name: str = "",
+            **function_kwargs: P.kwargs,
+        ) -> T:
+            """
+            Finds the maximum result of the function applied to the iterables.
+
+            Args:
+                *iterables: Iterable objects to be used as arguments for the function.
+                concurrency: Optional maximum number of concurrent tasks.
+                task_name: Optional name for the tasks.
+                **function_kwargs: Additional keyword arguments to pass to the function.
+
+            Returns:
+                The maximum result.
+
+            See Also:
+                - :meth:`map`
+            """
+            return await self.map(
+                *iterables,
+                concurrency=concurrency,
+                task_name=task_name,
+                **function_kwargs,
+            ).max(pop=True, sync=False)
+
+        async def sum(
+            self,
+            *iterables: AnyIterable[Any],
+            concurrency: Optional[int] = None,
+            task_name: str = "",
+            **function_kwargs: P.kwargs,
+        ) -> T:
+            """
+            Calculates the sum of the results of the function applied to the iterables.
+
+            Args:
+                *iterables: Iterable objects to be used as arguments for the function.
+                concurrency: Optional maximum number of concurrent tasks.
+                task_name: Optional name for the tasks.
+                **function_kwargs: Additional keyword arguments to pass to the function.
+
+            Returns:
+                The sum of the results.
+
+            See Also:
+                - :meth:`map`
+            """
+            return await self.map(
+                *iterables,
+                concurrency=concurrency,
+                task_name=task_name,
+                **function_kwargs,
+            ).sum(pop=True, sync=False)
+
+    @property
+    def _asyncified(self) -> CoroFn[P, T]:
+        """
+        Converts the wrapped function to an asynchronous function and applies both sync and async modifiers.
+
+        Raises:
+            TypeError: If the wrapped function is already asynchronous.
+
+        Returns:
+            The asynchronous version of the wrapped function.
+
+        See Also:
+            - :meth:`_asyncify`
+        """
+        asyncified = self.__asyncified
+        if asyncified is None:
+            if self.is_async_def():
+                raise TypeError(
+                    f"Can only be applied to sync functions, not {self.__wrapped__}"
+                )
+            
+            asyncified = self.__asyncified = self._asyncify(self._modified_fn)
+        return asyncified
+
+    @property
+    def _modified_fn(self) -> AnyFn[P, T]:
+        """
+        Applies modifiers to the wrapped function.
+
+        If the wrapped function is an asynchronous function, this method applies async modifiers.
+        If the wrapped function is a synchronous function, this method applies sync modifiers.
+
+        Returns:
+            The modified function.
+
+        See Also:
+            - :meth:`ModifierManager.apply_async_modifiers`
+            - :meth:`ModifierManager.apply_sync_modifiers`
+        """
+        modified_fn = self.__modified_fn
+        if modified_fn is None:
+            
+            # recursively unwrap ASync objects to get to the original wrapped callable
+            wrapped = self.__wrapped__
+            while isinstance(wrapped, _ASyncFunction):
+                wrapped = wrapped.__wrapped__
+                
+            if self.is_async_def():
+                modified_fn = self.__modified_fn = self.modifiers.apply_async_modifiers(wrapped)
+            else:
+                modified_fn = self.__modified_fn = self.modifiers.apply_sync_modifiers(wrapped)
+                
+        return modified_fn
+
+    @property
+    def _async_wrap(self):  # -> SyncFn[[CoroFn[P, T]], MaybeAwaitable[T]]:
+        """
+        The final wrapper if the wrapped function is an asynchronous function.
+
+        This method applies the appropriate modifiers and determines whether to await the result.
+
+        Returns:
+            The wrapped function with async handling.
+
+        See Also:
+            - :meth:`_run_sync`
+            - :meth:`_await`
+        """
+        async_wrap = self.__async_wrap
+        if async_wrap is None:
+
+            modified_fn = self._modified_fn
+            await_helper = self.get_await()
+
+            @wraps(modified_fn)
+            def async_wrap(*args: P.args, **kwargs: P.kwargs) -> MaybeAwaitable[T]:  # type: ignore [name-defined]
+                # sourcery skip: assign-if-exp
+                # we dont want this so profiler outputs are more useful
+
+                # Must take place before coro is created, we're popping a kwarg.
+                should_await = self._run_sync(kwargs)
+                coro = modified_fn(*args, **kwargs)
+                if should_await:
+                    return await_helper(coro)
+                else:
+                    return coro
+        
+            self.__async_wrap = async_wrap
+
+        return async_wrap
+
+    @property
+    def _sync_wrap(self):  # -> SyncFn[[SyncFn[P, T]], MaybeAwaitable[T]]:
+        """
+        The final wrapper if the wrapped function is a synchronous function.
+
+        This method applies the appropriate modifiers and determines whether to run the function synchronously or asynchronously.
+
+        Returns:
+            The wrapped function with sync handling.
+
+        See Also:
+            - :meth:`_run_sync`
+            - :meth:`_asyncified`
+        """
+        sync_wrap = self.__sync_wrap
+        if sync_wrap is None:
+
+            modified_fn = self._modified_fn
+            asyncified = self._asyncified
+
+            @wraps(modified_fn)
+            def sync_wrap(*args: P.args, **kwargs: P.kwargs) -> MaybeAwaitable[T]:  # type: ignore [name-defined]
+                if self._run_sync(kwargs):
+                    return modified_fn(*args, **kwargs)
+                return asyncified(*args, **kwargs)
+            
+            self.__sync_wrap = sync_wrap
+
+        return sync_wrap
+
+    cpdef bint is_async_def(self):
+        """
+        Checks if the wrapped function is an asynchronous function.
+
+        Returns:
+            True if the function is asynchronous, otherwise False.
+
+        See Also:
+            - :func:`asyncio.iscoroutinefunction`
+        """
+        if self.__async_def_cached:
+            return self.__async_def
+        cdef bint async_def
+
+        # recursively unwrap ASync callables to get the original wrapped fn
+        wrapped = self.__wrapped__
+        while isinstance(wrapped, _ASyncFunction):
+            wrapped = wrapped.__wrapped__
+            
+        async_def = self.__async_def = iscoroutinefunction(wrapped)
+        self.__async_def_cached = True
+        return async_def
+
+    cpdef bint is_sync_default(self):
+        """
+        Determines the default execution mode (sync or async) for the function.
+
+        If the user did not specify a default, this method defers to the function's
+        definition (sync vs async def).
+
+        Returns:
+            True if the default is sync, False if async.
+
+        See Also:
+            - :attr:`default`
+        """
+        if self.__sync_default_cached:
+            return self.__sync_default
+
+        cdef str default = self.get_default()
+        cdef bint sync_default = (
+            True
+            if default == "sync"
+            else False if default == "async" else not self.is_async_def()
+        )
+        self.__sync_default = sync_default
+        self.__sync_default_cached = True
+        return sync_default
+
+    cdef inline bint _run_sync(self, dict kwargs):
+        """
+        Determines whether to run the function synchronously or asynchronously.
+    
+        This method checks for a flag in the kwargs and defers to it if present.
+        If no flag is specified, it defers to the default execution mode.
+    
+        Args:
+            kwargs: The keyword arguments passed to the function.
+    
+        Returns:
+            True if the function should run synchronously, otherwise False.
+    
+        See Also:
+            - :func:`_kwargs.get_flag_name`
+        """
+        cdef str flag = get_flag_name(kwargs)
+        if flag:
+            # If a flag was specified in the kwargs, we will defer to it.
+            return is_sync(flag, kwargs, pop_flag=True)
+        else:
+            # No flag specified in the kwargs, we will defer to 'default'.
+            return self.is_sync_default()
+
+
+class ASyncFunction(_ASyncFunction, Generic[P, T]):
+
+    @overload
+    def __init__(self, fn: CoroFn[P, T], **modifiers: Unpack[ModifierKwargs]) -> None:
+        """
+        Initializes an ASyncFunction instance for a coroutine function.
+
+        Args:
+            fn: The coroutine function to wrap.
+            **modifiers: Keyword arguments for function modifiers.
+
+        Example:
+            async def my_coroutine(x: int) -> str:
+                return str(x)
+
+            func = ASyncFunction(my_coroutine, cache_type='memory')
+        """
+
+    @overload
+    def __init__(self, fn: SyncFn[P, T], **modifiers: Unpack[ModifierKwargs]) -> None:
+        """
+        Initializes an ASyncFunction instance for a synchronous function.
+
+        Args:
+            fn: The synchronous function to wrap.
+            **modifiers: Keyword arguments for function modifiers.
+
+        Example:
+            def my_function(x: int) -> str:
+                return str(x)
+
+            func = ASyncFunction(my_function, runs_per_minute=60)
+        """
+    
+    def __init__(
+        self,
+        fn: AnyFn[P, T],
+        _skip_validate: bint = False,
+        **modifiers: Unpack[ModifierKwargs],
+    ) -> None:
+        _ASyncFunction.__init__(self, fn, _skip_validate=_skip_validate, **modifiers)
+        update_wrapper(self, fn)
+        if self.__doc__ is None:
+            self.__doc__ = f"Since `{self.__name__}` is an {self.__docstring_append__}"
+        else:
+            self.__doc__ += (
+                f"\n\nSince `{self.__name__}` is an {self.__docstring_append__}"
+            )
+    
+    __docstring_append__ = ":class:`~a_sync.a_sync.function.ASyncFunction`, you can optionally pass either a `sync` or `asynchronous` kwarg with a boolean value."
+
+    @overload
+    def __call__(self, *args: P.args, sync: Literal[True], **kwargs: P.kwargs) -> T:
+        """
+        Calls the wrapped function synchronously.
+
+        Args:
+            *args: Positional arguments to pass to the wrapped function.
+            sync: Must be True to indicate synchronous execution.
+            **kwargs: Keyword arguments to pass to the wrapped function.
+
+        Example:
+            result = func(5, sync=True)
+        """
+
+    @overload
+    def __call__(
+        self, *args: P.args, sync: Literal[False], **kwargs: P.kwargs
+    ) -> Coroutine[Any, Any, T]:
+        """
+        Calls the wrapped function asynchronously.
+
+        Args:
+            *args: Positional arguments to pass to the wrapped function.
+            sync: Must be False to indicate asynchronous execution.
+            **kwargs: Keyword arguments to pass to the wrapped function.
+
+        Example:
+            result = await func(5, sync=False)
+        """
+
+    @overload
+    def __call__(
+        self, *args: P.args, asynchronous: Literal[False], **kwargs: P.kwargs
+    ) -> T:
+        """
+        Calls the wrapped function synchronously.
+
+        Args:
+            *args: Positional arguments to pass to the wrapped function.
+            asynchronous: Must be False to indicate synchronous execution.
+            **kwargs: Keyword arguments to pass to the wrapped function.
+
+        Example:
+            result = func(5, asynchronous=False)
+        """
+
+    @overload
+    def __call__(
+        self, *args: P.args, asynchronous: Literal[True], **kwargs: P.kwargs
+    ) -> Coroutine[Any, Any, T]:
+        """
+        Calls the wrapped function asynchronously.
+
+        Args:
+            *args: Positional arguments to pass to the wrapped function.
+            asynchronous: Must be True to indicate asynchronous execution.
+            **kwargs: Keyword arguments to pass to the wrapped function.
+
+        Example:
+            result = await func(5, asynchronous=True)
+        """
+
+    @overload
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> MaybeCoro[T]:
+        """
+        Calls the wrapped function using the default execution mode.
+
+        Args:
+            *args: Positional arguments to pass to the wrapped function.
+            **kwargs: Keyword arguments to pass to the wrapped function.
+
+        Example:
+            result = func(5)
+        """
+
+
+if sys.version_info < (3, 10):
+    _inherit = ASyncFunction[AnyFn[P, T], ASyncFunction[P, T]]
+else:
+    _inherit = ASyncFunction[[AnyFn[P, T]], ASyncFunction[P, T]]
+
+
+cdef class ASyncDecorator(_ModifiedMixin):
+    def __cinit__(self, **modifiers: Unpack[ModifierKwargs]) -> None:
+        """
+        Initializes an ASyncDecorator instance by validating the inputs.
+
+        Args:
+            **modifiers: Keyword arguments for function modifiers.
+
+        Raises:
+            ValueError: If 'default' is not 'sync', 'async', or None.
+
+        See Also:
+            - :class:`ModifierManager`
+        """
+        if modifiers.get("default", object) not in ("sync", "async", None):
+            if "default" not in modifiers:
+                raise ValueError("you must pass a value for `default`")
+            raise ValueError(
+                f"'default' must be either 'sync', 'async', or None. You passed {modifiers['default']}."
+            )
+        self.modifiers = ModifierManager(modifiers)
+
+    @overload
+    def __call__(self, func: AnyFn[Concatenate[B, P], T]) -> "ASyncBoundMethod[B, P, T]":  # type: ignore [override]
+        """
+        Decorates a bound method with async or sync behavior based on the default modifier.
+
+        Args:
+            func: The bound method to decorate.
+
+        Returns:
+            An ASyncBoundMethod instance with the appropriate default behavior.
+
+        See Also:
+            - :class:`ASyncBoundMethod`
+        """
+
+    @overload
+    def __call__(self, func: AnyFn[P, T]) -> ASyncFunction[P, T]:  # type: ignore [override]
+        """
+        Decorates a function with async or sync behavior based on the default modifier.
+
+        Args:
+            func: The function to decorate.
+
+        Returns:
+            An ASyncFunction instance with the appropriate default behavior.
+
+        See Also:
+            - :class:`ASyncFunction`
+        """
+
+    def __call__(self, func: AnyFn[P, T]) -> ASyncFunction[P, T]:  # type: ignore [override]
+        """
+        Decorates a function with async or sync behavior based on the default modifier.
+
+        Args:
+            func: The function to decorate.
+
+        Returns:
+            An ASyncFunction instance with the appropriate default behavior.
+
+        See Also:
+            - :class:`ASyncFunction`
+        """
+        cdef str default = self.get_default()
+        if default == "async":
+            return ASyncFunctionAsyncDefault(func, **self.modifiers._modifiers)
+        elif default == "sync":
+            return ASyncFunctionSyncDefault(func, **self.modifiers._modifiers)
+        elif iscoroutinefunction(func):
+            return ASyncFunctionAsyncDefault(func, **self.modifiers._modifiers)
+        else:
+            return ASyncFunctionSyncDefault(func, **self.modifiers._modifiers)
+
+
+cdef set[uintptr_t] _is_genfunc_cache = set()
+
+cdef void _check_not_genfunc_cached(func: Callable):
+    cdef uintptr_t fid = id(func)
+    if fid not in _is_genfunc_cache:
+        _check_not_genfunc(func)
+        _is_genfunc_cache.add(fid)
+
+cdef void _check_not_genfunc(func: Callable):
+    """Raises an error if the function is a generator or async generator.
+
+    Args:
+        func: The function to check.
+
+    Raises:
+        ValueError: If the function is a generator or async generator.
+
+    See Also:
+        - :func:`inspect.isasyncgenfunction`
+        - :func:`inspect.isgeneratorfunction`
+    """
+    if isasyncgenfunction(func) or isgeneratorfunction(func):
+        raise ValueError("unable to decorate generator functions with this decorator")
+
+
+# Mypy helper classes
+
+
+class ASyncFunctionSyncDefault(ASyncFunction[P, T]):
+    """A specialized :class:`~ASyncFunction` that defaults to synchronous execution.
+
+    This class is used when the :func:`~a_sync` decorator is applied with `default='sync'`.
+    It provides type hints to indicate that the default call behavior is synchronous and
+    supports IDE type checking for most use cases.
+
+    The wrapped function can still be called asynchronously by passing `sync=False`
+    or `asynchronous=True` as a keyword argument.
+
+    Example:
+        @a_sync(default='sync')
+        async def my_function(x: int) -> str:
+            return str(x)
+
+        # Synchronous call (default behavior)
+        result = my_function(5)  # returns "5"
+
+        # Asynchronous call
+        result = await my_function(5, sync=False)  # returns "5"
+    """
+
+    @overload
+    def __call__(self, *args: P.args, sync: Literal[True], **kwargs: P.kwargs) -> T:
+        # TODO write specific docs for this overload
+        ...
+
+    @overload
+    def __call__(
+        self, *args: P.args, sync: Literal[False], **kwargs: P.kwargs
+    ) -> Coroutine[Any, Any, T]:
+        # TODO write specific docs for this overload
+        ...
+
+    @overload
+    def __call__(
+        self, *args: P.args, asynchronous: Literal[False], **kwargs: P.kwargs
+    ) -> T:
+        # TODO write specific docs for this overload
+        ...
+
+    @overload
+    def __call__(
+        self, *args: P.args, asynchronous: Literal[True], **kwargs: P.kwargs
+    ) -> Coroutine[Any, Any, T]:
+        # TODO write specific docs for this overload
+        ...
+
+    @overload
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> T:
+        # TODO write specific docs for this overload
+        ...
+
+    def __call__(_ASyncFunction self, *args: P.args, **kwargs: P.kwargs) -> MaybeCoro[T]:
+        """Calls the wrapped function, defaulting to synchronous execution.
+
+        This method overrides the base :meth:`ASyncFunction.__call__` to provide a synchronous
+        default behavior.
+
+        Args:
+            *args: Positional arguments to pass to the wrapped function.
+            **kwargs: Keyword arguments to pass to the wrapped function.
+
+        Raises:
+            Exception: Any exception that may be raised by the wrapped function.
+
+        Returns:
+            The result of the function call.
+
+        See Also:
+            - :meth:`ASyncFunction.__call__`
+        """
+        return self.get_fn()(*args, **kwargs)
+
+    __docstring_append__ = ":class:`~a_sync.a_sync.function.ASyncFunctionSyncDefault`, you can optionally pass `sync=False` or `asynchronous=True` to force it to return a coroutine. Without either kwarg, it will run synchronously."
+
+
+class ASyncFunctionAsyncDefault(ASyncFunction[P, T]):
+    """
+    A specialized :class:`~ASyncFunction` that defaults to asynchronous execution.
+
+    This class is used when the :func:`~a_sync` decorator is applied with `default='async'`.
+    It provides type hints to indicate that the default call behavior is asynchronous
+    and supports IDE type checking for most use cases.
+
+    The wrapped function can still be called synchronously by passing `sync=True`
+    or `asynchronous=False` as a keyword argument.
+
+    Example:
+        @a_sync(default='async')
+        async def my_function(x: int) -> str:
+            return str(x)
+
+        # Asynchronous call (default behavior)
+        result = await my_function(5)  # returns "5"
+
+        # Synchronous call
+        result = my_function(5, sync=True)  # returns "5"
+    """
+
+    @overload
+    def __call__(self, *args: P.args, sync: Literal[True], **kwargs: P.kwargs) -> T:
+        # TODO write specific docs for this overload
+        ...
+
+    @overload
+    def __call__(
+        self, *args: P.args, sync: Literal[False], **kwargs: P.kwargs
+    ) -> Coroutine[Any, Any, T]:
+        # TODO write specific docs for this overload
+        ...
+
+    @overload
+    def __call__(
+        self, *args: P.args, asynchronous: Literal[False], **kwargs: P.kwargs
+    ) -> T:
+        # TODO write specific docs for this overload
+        ...
+
+    @overload
+    def __call__(
+        self, *args: P.args, asynchronous: Literal[True], **kwargs: P.kwargs
+    ) -> Coroutine[Any, Any, T]:
+        # TODO write specific docs for this overload
+        ...
+
+    @overload
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> Coroutine[Any, Any, T]: ...
+    def __call__(_ASyncFunction self, *args: P.args, **kwargs: P.kwargs) -> MaybeCoro[T]:
+        """Calls the wrapped function, defaulting to asynchronous execution.
+
+        This method overrides the base :meth:`ASyncFunction.__call__` to provide an asynchronous
+        default behavior.
+
+        Args:
+            *args: Positional arguments to pass to the wrapped function.
+            **kwargs: Keyword arguments to pass to the wrapped function.
+
+        Raises:
+            Exception: Any exception that may be raised by the wrapped function.
+
+        Returns:
+            The result of the function call.
+
+        See Also:
+            - :meth:`ASyncFunction.__call__`
+        """
+        return self.get_fn()(*args, **kwargs)
+
+    __docstring_append__ = ":class:`~a_sync.a_sync.function.ASyncFunctionAsyncDefault`, you can optionally pass `sync=True` or `asynchronous=False` to force it to run synchronously and return a value. Without either kwarg, it will return a coroutine for you to await."
+
+
+cdef class ASyncDecoratorSyncDefault(ASyncDecorator):
+    @overload
+    def __call__(self, func: AnyFn[Concatenate[B, P], T]) -> "ASyncBoundMethodSyncDefault[P, T]":  # type: ignore [override]
+        """
+        Decorates a bound method with synchronous default behavior.
+
+        Args:
+            func: The bound method to decorate.
+
+        Returns:
+            An ASyncBoundMethodSyncDefault instance with synchronous default behavior.
+
+        See Also:
+            - :class:`ASyncBoundMethodSyncDefault`
+        """
+
+    @overload
+    def __call__(self, func: AnyBoundMethod[P, T]) -> ASyncFunctionSyncDefault[P, T]:  # type: ignore [override]
+        """
+        Decorates a bound method with synchronous default behavior.
+
+        Args:
+            func: The bound method to decorate.
+
+        Returns:
+            An ASyncFunctionSyncDefault instance with synchronous default behavior.
+
+        See Also:
+            - :class:`ASyncFunctionSyncDefault`
+        """
+
+    @overload
+    def __call__(self, func: AnyFn[P, T]) -> ASyncFunctionSyncDefault[P, T]:  # type: ignore [override]
+        """
+        Decorates a function with synchronous default behavior.
+
+        Args:
+            func: The function to decorate.
+
+        Returns:
+            An ASyncFunctionSyncDefault instance with synchronous default behavior.
+
+        See Also:
+            - :class:`ASyncFunctionSyncDefault`
+        """
+
+    def __call__(self, func: AnyFn[P, T]) -> ASyncFunctionSyncDefault[P, T]:
+        # TODO write specific docs for this implementation
+        return ASyncFunctionSyncDefault(func, **self.modifiers._modifiers)
+
+
+cdef class ASyncDecoratorAsyncDefault(ASyncDecorator):
+    @overload
+    def __call__(self, func: AnyFn[Concatenate[B, P], T]) -> "ASyncBoundMethodAsyncDefault[P, T]":  # type: ignore [override]
+        """
+        Decorates a bound method with asynchronous default behavior.
+
+        Args:
+            func: The bound method to decorate.
+
+        Returns:
+            An ASyncBoundMethodAsyncDefault instance with asynchronous default behavior.
+
+        See Also:
+            - :class:`ASyncBoundMethodAsyncDefault`
+        """
+
+    @overload
+    def __call__(self, func: AnyBoundMethod[P, T]) -> ASyncFunctionAsyncDefault[P, T]:  # type: ignore [override]
+        """
+        Decorates a bound method with asynchronous default behavior.
+
+        Args:
+            func: The bound method to decorate.
+
+        Returns:
+            An ASyncFunctionAsyncDefault instance with asynchronous default behavior.
+
+        See Also:
+            - :class:`ASyncFunctionAsyncDefault`
+        """
+
+    @overload
+    def __call__(self, func: AnyFn[P, T]) -> ASyncFunctionAsyncDefault[P, T]:  # type: ignore [override]
+        """
+        Decorates a function with asynchronous default behavior.
+
+        Args:
+            func: The function to decorate.
+
+        Returns:
+            An ASyncFunctionAsyncDefault instance with asynchronous default behavior.
+
+        See Also:
+            - :class:`ASyncFunctionAsyncDefault`
+        """
+
+    def __call__(self, func: AnyFn[P, T]) -> ASyncFunctionAsyncDefault[P, T]:
+        # TODO write specific docs for this implementation
+        return ASyncFunctionAsyncDefault(func, **self.modifiers._modifiers)
+
+
+cdef inline void _import_TaskMapping():
+    global TaskMapping
+    from a_sync import TaskMapping