ez-a-sync 0.22.14__py3-none-any.whl → 0.22.16__py3-none-any.whl

a_sync/a_sync/method.py

@@ -16,7 +16,11 @@ from inspect import isawaitable
 from a_sync._typing import *
 from a_sync.a_sync import _helpers, _kwargs
 from a_sync.a_sync._descriptor import ASyncDescriptor
-from a_sync.a_sync.function import ASyncFunction, ASyncFunctionAsyncDefault, ASyncFunctionSyncDefault
+from a_sync.a_sync.function import (
+    ASyncFunction,
+    ASyncFunctionAsyncDefault,
+    ASyncFunctionSyncDefault,
+)
 
 if TYPE_CHECKING:
     from a_sync import TaskMapping
@@ -24,10 +28,37 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
+
 class ASyncMethodDescriptor(ASyncDescriptor[I, P, T]):
     """
-    This class provides the core functionality for creating :class:`ASyncBoundMethod` objects, 
-    which can be used to define methods that can be called both synchronously and asynchronously.
+    A descriptor for managing methods that can be called both synchronously and asynchronously.
+
+    This class provides the core functionality for binding methods to instances and determining
+    the execution mode ("sync" or "async") based on various conditions, such as the instance type,
+    the method's default setting, or specific flags passed during the method call.
+
+    The descriptor is responsible for creating an appropriate bound method when accessed,
+    which is the actual object that can be called in both synchronous and asynchronous contexts.
+    It can create different types of bound methods (`ASyncBoundMethodSyncDefault`,
+    `ASyncBoundMethodAsyncDefault`, or `ASyncBoundMethod`) based on the default mode or instance type.
+
+    It also manages cache handles for bound methods and prevents setting or deleting the descriptor.
+
+    Examples:
+        >>> class MyClass:
+        ...     @ASyncMethodDescriptor
+        ...     async def my_method(self):
+        ...         return "Hello, World!"
+        ...
+        >>> obj = MyClass()
+        >>> await obj.my_method()
+        'Hello, World!'
+        >>> obj.my_method(sync=True)
+        'Hello, World!'
+
+    See Also:
+        - :class:`ASyncBoundMethod`
+        - :class:`ASyncFunction`
     """
 
     __wrapped__: AnyFn[P, T]
@@ -42,18 +73,27 @@ class ASyncMethodDescriptor(ASyncDescriptor[I, P, T]):
             *args: Positional arguments.
             **kwargs: Keyword arguments.
 
-        Returns:
-            The result of the method call.
+        Examples:
+            >>> descriptor = ASyncMethodDescriptor(my_async_function)
+            >>> await descriptor(instance, arg1, arg2, kwarg1=value1)
         """
         # NOTE: This is only used by TaskMapping atm  # TODO: use it elsewhere
-        logger.debug("awaiting %s for instance: %s args: %s kwargs: %s", self, instance, args, kwargs)
+        logger.debug(
+            "awaiting %s for instance: %s args: %s kwargs: %s",
+            self,
+            instance,
+            args,
+            kwargs,
+        )
         return await self.__get__(instance, None)(*args, **kwargs)
 
     @overload
-    def __get__(self, instance: None, owner: Type[I]) -> Self:...
+    def __get__(self, instance: None, owner: Type[I]) -> Self: ...
     @overload
-    def __get__(self, instance: I, owner: Type[I]) -> "ASyncBoundMethod[I, P, T]":...
-    def __get__(self, instance: Optional[I], owner: Type[I]) -> Union[Self, "ASyncBoundMethod[I, P, T]"]:
+    def __get__(self, instance: I, owner: Type[I]) -> "ASyncBoundMethod[I, P, T]": ...
+    def __get__(
+        self, instance: Optional[I], owner: Type[I]
+    ) -> Union[Self, "ASyncBoundMethod[I, P, T]"]:
         """
         Get the bound method or the descriptor itself.
 
@@ -61,8 +101,9 @@ class ASyncMethodDescriptor(ASyncDescriptor[I, P, T]):
             instance: The instance to bind the method to, or None.
             owner: The owner class.
 
-        Returns:
-            The descriptor or bound method.
+        Examples:
+            >>> descriptor = ASyncMethodDescriptor(my_function)
+            >>> bound_method = descriptor.__get__(instance, MyClass)
         """
         if instance is None:
             return self
@@ -72,20 +113,42 @@ class ASyncMethodDescriptor(ASyncDescriptor[I, P, T]):
             bound._cache_handle.cancel()
         except KeyError:
             from a_sync.a_sync.abstract import ASyncABC
+
             if self.default == "sync":
-                bound = ASyncBoundMethodSyncDefault(instance, self.__wrapped__, self.__is_async_def__, **self.modifiers)
+                bound = ASyncBoundMethodSyncDefault(
+                    instance, self.__wrapped__, self.__is_async_def__, **self.modifiers
+                )
             elif self.default == "async":
-                bound = ASyncBoundMethodAsyncDefault(instance, self.__wrapped__, self.__is_async_def__, **self.modifiers)
+                bound = ASyncBoundMethodAsyncDefault(
+                    instance, self.__wrapped__, self.__is_async_def__, **self.modifiers
+                )
             elif isinstance(instance, ASyncABC):
                 try:
                     if instance.__a_sync_instance_should_await__:
-                        bound = ASyncBoundMethodSyncDefault(instance, self.__wrapped__, self.__is_async_def__, **self.modifiers)
+                        bound = ASyncBoundMethodSyncDefault(
+                            instance,
+                            self.__wrapped__,
+                            self.__is_async_def__,
+                            **self.modifiers,
+                        )
                     else:
-                        bound = ASyncBoundMethodAsyncDefault(instance, self.__wrapped__, self.__is_async_def__, **self.modifiers)
+                        bound = ASyncBoundMethodAsyncDefault(
+                            instance,
+                            self.__wrapped__,
+                            self.__is_async_def__,
+                            **self.modifiers,
+                        )
                 except AttributeError:
-                    bound = ASyncBoundMethod(instance, self.__wrapped__, self.__is_async_def__, **self.modifiers)
+                    bound = ASyncBoundMethod(
+                        instance,
+                        self.__wrapped__,
+                        self.__is_async_def__,
+                        **self.modifiers,
+                    )
             else:
-                bound = ASyncBoundMethod(instance, self.__wrapped__, self.__is_async_def__, **self.modifiers)
+                bound = ASyncBoundMethod(
+                    instance, self.__wrapped__, self.__is_async_def__, **self.modifiers
+                )
             instance.__dict__[self.field_name] = bound
             logger.debug("new bound method: %s", bound)
         # Handler for popping unused bound methods from bound method cache
@@ -101,9 +164,16 @@ class ASyncMethodDescriptor(ASyncDescriptor[I, P, T]):
             value: The value to set.
 
         Raises:
-            :class:`RuntimeError`: Always raised to prevent setting.
+            RuntimeError: Always raised to prevent setting.
+
+        Examples:
+            >>> descriptor = ASyncMethodDescriptor(my_function)
+            >>> descriptor.__set__(instance, value)
+            RuntimeError: cannot set field_name, descriptor is what you get. sorry.
         """
-        raise RuntimeError(f"cannot set {self.field_name}, {self} is what you get. sorry.")
+        raise RuntimeError(
+            f"cannot set {self.field_name}, {self} is what you get. sorry."
+        )
 
     def __delete__(self, instance):
         """
@@ -113,17 +183,26 @@ class ASyncMethodDescriptor(ASyncDescriptor[I, P, T]):
             instance: The instance.
 
         Raises:
-            :class:`RuntimeError`: Always raised to prevent deletion.
+            RuntimeError: Always raised to prevent deletion.
+
+        Examples:
+            >>> descriptor = ASyncMethodDescriptor(my_function)
+            >>> descriptor.__delete__(instance)
+            RuntimeError: cannot delete field_name, you're stuck with descriptor forever. sorry.
         """
-        raise RuntimeError(f"cannot delete {self.field_name}, you're stuck with {self} forever. sorry.")
+        raise RuntimeError(
+            f"cannot delete {self.field_name}, you're stuck with {self} forever. sorry."
+        )
 
     @functools.cached_property
     def __is_async_def__(self) -> bool:
         """
         Check if the wrapped function is a coroutine function.
 
-        Returns:
-            True if the wrapped function is a coroutine function, False otherwise.
+        Examples:
+            >>> descriptor = ASyncMethodDescriptor(my_function)
+            >>> descriptor.__is_async_def__
+            True
         """
         return asyncio.iscoroutinefunction(self.__wrapped__)
 
@@ -136,17 +215,44 @@ class ASyncMethodDescriptor(ASyncDescriptor[I, P, T]):
 
         Returns:
             A timer handle for cache management.
+
+        Examples:
+            >>> descriptor = ASyncMethodDescriptor(my_function)
+            >>> cache_handle = descriptor._get_cache_handle(instance)
         """
         # NOTE: use `instance.__dict__.pop` instead of `delattr` so we don't create a strong ref to `instance`
-        return asyncio.get_event_loop().call_later(300, instance.__dict__.pop, self.field_name)
+        return asyncio.get_event_loop().call_later(
+            300, instance.__dict__.pop, self.field_name
+        )
+
 
 @final
 class ASyncMethodDescriptorSyncDefault(ASyncMethodDescriptor[I, P, T]):
     """
     A descriptor for :class:`ASyncBoundMethodSyncDefault` objects.
 
-    This class extends ASyncMethodDescriptor to provide a synchronous
-    default behavior for method calls.
+    This class extends :class:`ASyncMethodDescriptor` to provide a synchronous
+    default behavior for method calls. It specifically creates `ASyncBoundMethodSyncDefault`
+    instances, which are specialized versions of `ASyncBoundMethod` with synchronous default behavior.
+
+    Examples:
+        >>> class MyClass:
+        ...     @ASyncMethodDescriptorSyncDefault
+        ...     def my_method(self):
+        ...         return "Hello, World!"
+        ...
+        >>> obj = MyClass()
+        >>> obj.my_method()
+        'Hello, World!'
+        >>> coro = obj.my_method(sync=False)
+        >>> coro
+        <coroutine object MyClass.my_method at 0x7fb4f5fb49c0>
+        >>> await coro
+        'Hello, World!'
+
+    See Also:
+        - :class:`ASyncBoundMethodSyncDefault`
+        - :class:`ASyncFunctionSyncDefault`
     """
 
     default = "sync"
@@ -168,10 +274,18 @@ class ASyncMethodDescriptorSyncDefault(ASyncMethodDescriptor[I, P, T]):
     """Synchronous default version of the :meth:`~ASyncMethodDescriptor.sum` method."""
 
     @overload
-    def __get__(self, instance: None, owner: Type[I] = None) -> "ASyncMethodDescriptorSyncDefault[I, P, T]":...
+    def __get__(
+        self, instance: None, owner: Type[I] = None
+    ) -> "ASyncMethodDescriptorSyncDefault[I, P, T]": ...
     @overload
-    def __get__(self, instance: I, owner: Type[I] = None) -> "ASyncBoundMethodSyncDefault[I, P, T]":...
-    def __get__(self, instance: Optional[I], owner: Type[I] = None) -> "Union[ASyncMethodDescriptorSyncDefault, ASyncBoundMethodSyncDefault[I, P, T]]":
+    def __get__(
+        self, instance: I, owner: Type[I] = None
+    ) -> "ASyncBoundMethodSyncDefault[I, P, T]": ...
+    def __get__(
+        self, instance: Optional[I], owner: Type[I] = None
+    ) -> (
+        "Union[ASyncMethodDescriptorSyncDefault, ASyncBoundMethodSyncDefault[I, P, T]]"
+    ):
         """
         Get the bound method or the descriptor itself.
 
@@ -179,8 +293,9 @@ class ASyncMethodDescriptorSyncDefault(ASyncMethodDescriptor[I, P, T]):
             instance: The instance to bind the method to, or None.
             owner: The owner class.
 
-        Returns:
-            The descriptor or bound method with synchronous default.
+        Examples:
+            >>> descriptor = ASyncMethodDescriptorSyncDefault(my_function)
+            >>> bound_method = descriptor.__get__(instance, MyClass)
         """
         if instance is None:
             return self
@@ -189,20 +304,42 @@ class ASyncMethodDescriptorSyncDefault(ASyncMethodDescriptor[I, P, T]):
             # we will set a new one in the finally block
             bound._cache_handle.cancel()
         except KeyError:
-            bound = ASyncBoundMethodSyncDefault(instance, self.__wrapped__, self.__is_async_def__, **self.modifiers)
+            bound = ASyncBoundMethodSyncDefault(
+                instance, self.__wrapped__, self.__is_async_def__, **self.modifiers
+            )
             instance.__dict__[self.field_name] = bound
             logger.debug("new bound method: %s", bound)
         # Handler for popping unused bound methods from bound method cache
         bound._cache_handle = self._get_cache_handle(instance)
         return bound
 
+
 @final
 class ASyncMethodDescriptorAsyncDefault(ASyncMethodDescriptor[I, P, T]):
     """
     A descriptor for asynchronous methods with an asynchronous default.
 
-    This class extends ASyncMethodDescriptor to provide an asynchronous default
-    behavior for method calls.
+    This class extends :class:`ASyncMethodDescriptor` to provide an asynchronous default
+    behavior for method calls. It specifically creates `ASyncBoundMethodAsyncDefault`
+    instances, which are specialized versions of `ASyncBoundMethod` with asynchronous default behavior.
+
+    Examples:
+        >>> class MyClass:
+        ...     @ASyncMethodDescriptorAsyncDefault
+        ...     async def my_method(self):
+        ...         return "Hello, World!"
+        ...
+        >>> obj = MyClass()
+        >>> coro = obj.my_method()
+        >>> coro
+        <coroutine object MyClass.my_method at 0x7fb4f5fb49c0>
+        >>> await coro
+        >>> obj.my_method(sync=True)
+        'Hello, World!'
+
+    See Also:
+        - :class:`ASyncBoundMethodAsyncDefault`
+        - :class:`ASyncFunctionAsyncDefault`
     """
 
     default = "async"
@@ -213,21 +350,27 @@ class ASyncMethodDescriptorAsyncDefault(ASyncMethodDescriptor[I, P, T]):
 
     all: ASyncFunctionAsyncDefault[Concatenate[AnyIterable[I], P], bool]
     """Asynchronous default version of the :meth:`~ASyncMethodDescriptor.all` method."""
-    
+
     min: ASyncFunctionAsyncDefault[Concatenate[AnyIterable[I], P], T]
     """Asynchronous default version of the :meth:`~ASyncMethodDescriptor.min` method."""
-    
+
     max: ASyncFunctionAsyncDefault[Concatenate[AnyIterable[I], P], T]
     """Asynchronous default version of the :meth:`~ASyncMethodDescriptor.max` method."""
-    
+
     sum: ASyncFunctionAsyncDefault[Concatenate[AnyIterable[I], P], T]
     """Asynchronous default version of the :meth:`~ASyncMethodDescriptor.sum` method."""
 
     @overload
-    def __get__(self, instance: None, owner: Type[I]) -> "ASyncMethodDescriptorAsyncDefault[I, P, T]":...
+    def __get__(
+        self, instance: None, owner: Type[I]
+    ) -> "ASyncMethodDescriptorAsyncDefault[I, P, T]": ...
     @overload
-    def __get__(self, instance: I, owner: Type[I]) -> "ASyncBoundMethodAsyncDefault[I, P, T]":...
-    def __get__(self, instance: Optional[I], owner: Type[I]) -> "Union[ASyncMethodDescriptorAsyncDefault, ASyncBoundMethodAsyncDefault[I, P, T]]":
+    def __get__(
+        self, instance: I, owner: Type[I]
+    ) -> "ASyncBoundMethodAsyncDefault[I, P, T]": ...
+    def __get__(
+        self, instance: Optional[I], owner: Type[I]
+    ) -> "Union[ASyncMethodDescriptorAsyncDefault, ASyncBoundMethodAsyncDefault[I, P, T]]":
         """
         Get the bound method or the descriptor itself.
 
@@ -235,8 +378,9 @@ class ASyncMethodDescriptorAsyncDefault(ASyncMethodDescriptor[I, P, T]):
             instance: The instance to bind the method to, or None.
             owner: The owner class.
 
-        Returns:
-            The descriptor or bound method with asynchronous default.
+        Examples:
+            >>> descriptor = ASyncMethodDescriptorAsyncDefault(my_function)
+            >>> bound_method = descriptor.__get__(instance, MyClass)
         """
         if instance is None:
             return self
@@ -245,27 +389,52 @@ class ASyncMethodDescriptorAsyncDefault(ASyncMethodDescriptor[I, P, T]):
             # we will set a new one in the finally block
             bound._cache_handle.cancel()
         except KeyError:
-            bound = ASyncBoundMethodAsyncDefault(instance, self.__wrapped__, self.__is_async_def__, **self.modifiers)
+            bound = ASyncBoundMethodAsyncDefault(
+                instance, self.__wrapped__, self.__is_async_def__, **self.modifiers
+            )
             instance.__dict__[self.field_name] = bound
             logger.debug("new bound method: %s", bound)
         # Handler for popping unused bound methods from bound method cache
         bound._cache_handle = self._get_cache_handle(instance)
         return bound
 
+
 class ASyncBoundMethod(ASyncFunction[P, T], Generic[I, P, T]):
     """
     A bound method that can be called both synchronously and asynchronously.
 
     This class represents a method bound to an instance, which can be called
-    either synchronously or asynchronously based on various conditions.
+    either synchronously or asynchronously based on various conditions. It handles
+    caching of bound methods and includes logic for determining whether to await
+    the method call based on flags or default settings.
+
+    Examples:
+        >>> class MyClass:
+        ...     def __init__(self, value):
+        ...         self.value = value
+        ...
+        ...     @ASyncMethodDescriptor
+        ...     async def my_method(self):
+        ...         return self.value
+        ...
+        >>> obj = MyClass(42)
+        >>> await obj.my_method()
+        42
+        >>> obj.my_method(sync=True)
+        42
+
+    See Also:
+        - :class:`ASyncMethodDescriptor`
+        - :class:`ASyncFunction`
     """
+
     # NOTE: this is created by the Descriptor
 
     _cache_handle: asyncio.TimerHandle
-    "An asyncio handle used to pop the bound method from `instance.__dict__` 5 minutes after its last use."
+    """An asyncio handle used to pop the bound method from `instance.__dict__` 5 minutes after its last use."""
 
     __weakself__: "weakref.ref[I]"
-    "A weak reference to the instance the function is bound to."
+    """A weak reference to the instance the function is bound to."""
 
     __wrapped__: AnyFn[Concatenate[I, P], T]
     """The original unbound method that was wrapped."""
@@ -273,9 +442,9 @@ class ASyncBoundMethod(ASyncFunction[P, T], Generic[I, P, T]):
     __slots__ = "_is_async_def", "__weakself__"
 
     def __init__(
-        self, 
-        instance: I, 
-        unbound: AnyFn[Concatenate[I, P], T], 
+        self,
+        instance: I,
+        unbound: AnyFn[Concatenate[I, P], T],
         async_def: bool,
         **modifiers: Unpack[ModifierKwargs],
     ) -> None:
@@ -287,6 +456,18 @@ class ASyncBoundMethod(ASyncFunction[P, T], Generic[I, P, T]):
             unbound: The unbound function.
             async_def: Whether the original function is an async def.
             **modifiers: Additional modifiers for the function.
+
+        Examples:
+            >>> class MyClass:
+            ...     def __init__(self, value):
+            ...         self.value = value
+            ...
+            ...     @ASyncMethodDescriptor
+            ...     async def my_method(self):
+            ...         return self.value
+            ...
+            >>> obj = MyClass(42)
+            >>> bound_method = ASyncBoundMethod(obj, MyClass.my_method, True)
         """
         self.__weakself__ = weakref.ref(instance, self.__cancel_cache_handle)
         # First we unwrap the coro_fn and rewrap it so overriding flag kwargs are handled automagically.
@@ -295,15 +476,17 @@ class ASyncBoundMethod(ASyncFunction[P, T], Generic[I, P, T]):
             unbound = unbound.__wrapped__
         ASyncFunction.__init__(self, unbound, **modifiers)
         self._is_async_def = async_def
-        "True if `self.__wrapped__` is a coroutine function, False otherwise."
+        """True if `self.__wrapped__` is a coroutine function, False otherwise."""
         functools.update_wrapper(self, unbound)
 
     def __repr__(self) -> str:
         """
         Return a string representation of the bound method.
 
-        Returns:
-            A string representation of the bound method.
+        Examples:
+            >>> bound_method = ASyncBoundMethod(instance, my_function, True)
+            >>> repr(bound_method)
+            '<ASyncBoundMethod for function module.ClassName.method_name bound to instance>'
         """
         try:
             instance_type = type(self.__self__)
@@ -312,15 +495,21 @@ class ASyncBoundMethod(ASyncFunction[P, T], Generic[I, P, T]):
             return f"<{self.__class__.__name__} for function COLLECTED.COLLECTED.{self.__name__} bound to {self.__weakself__}>"
 
     @overload
-    def __call__(self, *args: P.args, sync: Literal[True], **kwargs: P.kwargs) -> T:...
+    def __call__(self, *args: P.args, sync: Literal[True], **kwargs: P.kwargs) -> T: ...
     @overload
-    def __call__(self, *args: P.args, sync: Literal[False], **kwargs: P.kwargs) -> Coroutine[Any, Any, T]:...
+    def __call__(
+        self, *args: P.args, sync: Literal[False], **kwargs: P.kwargs
+    ) -> Coroutine[Any, Any, T]: ...
     @overload
-    def __call__(self, *args: P.args, asynchronous: Literal[False], **kwargs: P.kwargs) -> T:...
+    def __call__(
+        self, *args: P.args, asynchronous: Literal[False], **kwargs: P.kwargs
+    ) -> T: ...
     @overload
-    def __call__(self, *args: P.args, asynchronous: Literal[True], **kwargs: P.kwargs) -> Coroutine[Any, Any, T]:...
+    def __call__(
+        self, *args: P.args, asynchronous: Literal[True], **kwargs: P.kwargs
+    ) -> Coroutine[Any, Any, T]: ...
     @overload
-    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> MaybeCoro[T]:...
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> MaybeCoro[T]: ...
     def __call__(self, *args: P.args, **kwargs: P.kwargs) -> MaybeCoro[T]:
         """
         Call the bound method.
@@ -332,8 +521,10 @@ class ASyncBoundMethod(ASyncFunction[P, T], Generic[I, P, T]):
             *args: Positional arguments.
             **kwargs: Keyword arguments.
 
-        Returns:
-            The result of the method call, which may be a coroutine.
+        Examples:
+            >>> bound_method = ASyncBoundMethod(instance, my_function, True)
+            >>> await bound_method(arg1, arg2, kwarg1=value1)
+            >>> bound_method(arg1, arg2, kwarg1=value1, sync=True)
         """
         logger.debug("calling %s with args: %s kwargs: %s", self, args, kwargs)
         # This could either be a coroutine or a return value from an awaited coroutine,
@@ -345,9 +536,13 @@ class ASyncBoundMethod(ASyncFunction[P, T], Generic[I, P, T]):
             pass
         elif self._should_await(kwargs):
             # The awaitable was not awaited, so now we need to check the flag as defined on 'self' and await if appropriate.
-            logger.debug("awaiting %s for %s args: %s kwargs: %s", coro, self, args, kwargs)
+            logger.debug(
+                "awaiting %s for %s args: %s kwargs: %s", coro, self, args, kwargs
+            )
             retval = _helpers._await(coro)
-        logger.debug("returning %s for %s args: %s kwargs: %s", retval, self, args, kwargs)
+        logger.debug(
+            "returning %s for %s args: %s kwargs: %s", retval, self, args, kwargs
+        )
         return retval  # type: ignore [call-overload, return-value]
 
     @property
@@ -355,11 +550,13 @@ class ASyncBoundMethod(ASyncFunction[P, T], Generic[I, P, T]):
         """
         Get the instance the method is bound to.
 
-        Returns:
-            The instance the method is bound to.
-
         Raises:
-            :class:`ReferenceError`: If the instance has been garbage collected.
+            ReferenceError: If the instance has been garbage collected.
+
+        Examples:
+            >>> bound_method = ASyncBoundMethod(instance, my_function, True)
+            >>> bound_method.__self__
+            <MyClass instance>
         """
         instance = self.__weakself__()
         if instance is not None:
@@ -371,13 +568,22 @@ class ASyncBoundMethod(ASyncFunction[P, T], Generic[I, P, T]):
         """
         Check if the method is bound to an ASyncABC instance.
 
-        Returns:
-            True if bound to an ASyncABC instance, False otherwise.
+        Examples:
+            >>> bound_method = ASyncBoundMethod(instance, my_function, True)
+            >>> bound_method.__bound_to_a_sync_instance__
+            True
         """
         from a_sync.a_sync.abstract import ASyncABC
+
         return isinstance(self.__self__, ASyncABC)
 
-    def map(self, *iterables: AnyIterable[I], concurrency: Optional[int] = None, task_name: str = "", **kwargs: P.kwargs) -> "TaskMapping[I, T]":
+    def map(
+        self,
+        *iterables: AnyIterable[I],
+        concurrency: Optional[int] = None,
+        task_name: str = "",
+        **kwargs: P.kwargs,
+    ) -> "TaskMapping[I, T]":
         """
         Create a TaskMapping for this method.
 
@@ -389,11 +595,25 @@ class ASyncBoundMethod(ASyncFunction[P, T], Generic[I, P, T]):
 
         Returns:
             A TaskMapping instance for this method.
+
+        Examples:
+            >>> bound_method = ASyncBoundMethod(instance, my_function, True)
+            >>> task_mapping = bound_method.map(iterable1, iterable2, concurrency=5)
+            TODO briefly include how someone would then use task_mapping
         """
         from a_sync import TaskMapping
-        return TaskMapping(self, *iterables, concurrency=concurrency, name=task_name, **kwargs)
 
-    async def any(self, *iterables: AnyIterable[I], concurrency: Optional[int] = None, task_name: str = "", **kwargs: P.kwargs) -> bool:
+        return TaskMapping(
+            self, *iterables, concurrency=concurrency, name=task_name, **kwargs
+        )
+
+    async def any(
+        self,
+        *iterables: AnyIterable[I],
+        concurrency: Optional[int] = None,
+        task_name: str = "",
+        **kwargs: P.kwargs,
+    ) -> bool:
         """
         Check if any of the results are truthy.
 
@@ -403,12 +623,21 @@ class ASyncBoundMethod(ASyncFunction[P, T], Generic[I, P, T]):
             task_name: Optional name for the task.
             **kwargs: Additional keyword arguments.
 
-        Returns:
-            True if any result is truthy, False otherwise.
+        Examples:
+            >>> bound_method = ASyncBoundMethod(instance, my_function, True)
+            >>> result = await bound_method.any(iterable1, iterable2)
         """
-        return await self.map(*iterables, concurrency=concurrency, task_name=task_name, **kwargs).any(pop=True, sync=False)
+        return await self.map(
+            *iterables, concurrency=concurrency, task_name=task_name, **kwargs
+        ).any(pop=True, sync=False)
 
-    async def all(self, *iterables: AnyIterable[I], concurrency: Optional[int] = None, task_name: str = "", **kwargs: P.kwargs) -> bool:
+    async def all(
+        self,
+        *iterables: AnyIterable[I],
+        concurrency: Optional[int] = None,
+        task_name: str = "",
+        **kwargs: P.kwargs,
+    ) -> bool:
         """
         Check if all of the results are truthy.
 
@@ -418,12 +647,21 @@ class ASyncBoundMethod(ASyncFunction[P, T], Generic[I, P, T]):
             task_name: Optional name for the task.
             **kwargs: Additional keyword arguments.
 
-        Returns:
-            True if all results are truthy, False otherwise.
+        Examples:
+            >>> bound_method = ASyncBoundMethod(instance, my_function, True)
+            >>> result = await bound_method.all(iterable1, iterable2)
         """
-        return await self.map(*iterables, concurrency=concurrency, task_name=task_name, **kwargs).all(pop=True, sync=False)
+        return await self.map(
+            *iterables, concurrency=concurrency, task_name=task_name, **kwargs
+        ).all(pop=True, sync=False)
 
-    async def min(self, *iterables: AnyIterable[I], concurrency: Optional[int] = None, task_name: str = "", **kwargs: P.kwargs) -> T:
+    async def min(
+        self,
+        *iterables: AnyIterable[I],
+        concurrency: Optional[int] = None,
+        task_name: str = "",
+        **kwargs: P.kwargs,
+    ) -> T:
         """
         Find the minimum result.
 
@@ -433,12 +671,21 @@ class ASyncBoundMethod(ASyncFunction[P, T], Generic[I, P, T]):
             task_name: Optional name for the task.
             **kwargs: Additional keyword arguments.
 
-        Returns:
-            The minimum result.
+        Examples:
+            >>> bound_method = ASyncBoundMethod(instance, my_function, True)
+            >>> result = await bound_method.min(iterable1, iterable2)
         """
-        return await self.map(*iterables, concurrency=concurrency, task_name=task_name, **kwargs).min(pop=True, sync=False)
+        return await self.map(
+            *iterables, concurrency=concurrency, task_name=task_name, **kwargs
+        ).min(pop=True, sync=False)
 
-    async def max(self, *iterables: AnyIterable[I], concurrency: Optional[int] = None, task_name: str = "", **kwargs: P.kwargs) -> T:
+    async def max(
+        self,
+        *iterables: AnyIterable[I],
+        concurrency: Optional[int] = None,
+        task_name: str = "",
+        **kwargs: P.kwargs,
+    ) -> T:
         """
         Find the maximum result.
 
@@ -448,12 +695,21 @@ class ASyncBoundMethod(ASyncFunction[P, T], Generic[I, P, T]):
             task_name: Optional name for the task.
             **kwargs: Additional keyword arguments.
 
-        Returns:
-            The maximum result.
+        Examples:
+            >>> bound_method = ASyncBoundMethod(instance, my_function, True)
+            >>> result = await bound_method.max(iterable1, iterable2)
         """
-        return await self.map(*iterables, concurrency=concurrency, task_name=task_name, **kwargs).max(pop=True, sync=False)
+        return await self.map(
+            *iterables, concurrency=concurrency, task_name=task_name, **kwargs
+        ).max(pop=True, sync=False)
 
-    async def sum(self, *iterables: AnyIterable[I], concurrency: Optional[int] = None, task_name: str = "", **kwargs: P.kwargs) -> T:
+    async def sum(
+        self,
+        *iterables: AnyIterable[I],
+        concurrency: Optional[int] = None,
+        task_name: str = "",
+        **kwargs: P.kwargs,
+    ) -> T:
         """
         Calculate the sum of the results.
 
@@ -463,10 +719,13 @@ class ASyncBoundMethod(ASyncFunction[P, T], Generic[I, P, T]):
             task_name: Optional name for the task.
             **kwargs: Additional keyword arguments.
 
-        Returns:
-            The sum of the results.
+        Examples:
+            >>> bound_method = ASyncBoundMethod(instance, my_function, True)
+            >>> result = await bound_method.sum(iterable1, iterable2)
         """
-        return await self.map(*iterables, concurrency=concurrency, task_name=task_name, **kwargs).sum(pop=True, sync=False)
+        return await self.map(
+            *iterables, concurrency=concurrency, task_name=task_name, **kwargs
+        ).sum(pop=True, sync=False)
 
     def _should_await(self, kwargs: dict) -> bool:
         """
@@ -475,8 +734,9 @@ class ASyncBoundMethod(ASyncFunction[P, T], Generic[I, P, T]):
         Args:
             kwargs: Keyword arguments passed to the method.
 
-        Returns:
-            True if the method should be awaited, False otherwise.
+        Examples:
+            >>> bound_method = ASyncBoundMethod(instance, my_function, True)
+            >>> should_await = bound_method._should_await(kwargs)
         """
         if flag := _kwargs.get_flag_name(kwargs):
             return _kwargs.is_sync(flag, kwargs, pop_flag=True)  # type: ignore [arg-type]
@@ -493,6 +753,10 @@ class ASyncBoundMethod(ASyncFunction[P, T], Generic[I, P, T]):
 
         Args:
             instance: The instance associated with the cache handle.
+
+        Examples:
+            >>> bound_method = ASyncBoundMethod(instance, my_function, True)
+            >>> bound_method.__cancel_cache_handle(instance)
         """
         cache_handle: asyncio.TimerHandle = self._cache_handle
         cache_handle.cancel()
@@ -501,9 +765,33 @@ class ASyncBoundMethod(ASyncFunction[P, T], Generic[I, P, T]):
 class ASyncBoundMethodSyncDefault(ASyncBoundMethod[I, P, T]):
     """
     A bound method with synchronous default behavior.
+
+    This class is a specialized version of :class:`ASyncBoundMethod` that defaults to synchronous execution.
+    It overrides the `__call__` method to enforce synchronous default behavior.
+
+    Examples:
+        >>> class MyClass:
+        ...     def __init__(self, value):
+        ...         self.value = value
+        ...
+        ...     @ASyncMethodDescriptorSyncDefault
+        ...     def my_method(self):
+        ...         return self.value
+        ...
+        >>> obj = MyClass(42)
+        >>> obj.my_method()
+        42
+        >>> await obj.my_method(sync=False)
+        42
+
+    See Also:
+        - :class:`ASyncBoundMethod`
+        - :class:`ASyncMethodDescriptorSyncDefault`
     """
 
-    def __get__(self, instance: Optional[I], owner: Type[I]) -> ASyncFunctionSyncDefault[P, T]:
+    def __get__(
+        self, instance: Optional[I], owner: Type[I]
+    ) -> ASyncFunctionSyncDefault[P, T]:
         """
         Get the bound method or descriptor.
 
@@ -511,21 +799,28 @@ class ASyncBoundMethodSyncDefault(ASyncBoundMethod[I, P, T]):
             instance: The instance to bind the method to, or None.
             owner: The owner class.
 
-        Returns:
-            The bound method with synchronous default behavior.
+        Examples:
+            >>> descriptor = ASyncMethodDescriptorSyncDefault(my_function)
+            >>> bound_method = descriptor.__get__(instance, MyClass)
         """
         return ASyncBoundMethod.__get__(self, instance, owner)
 
     @overload
-    def __call__(self, *args: P.args, sync: Literal[True], **kwargs: P.kwargs) -> T:...
+    def __call__(self, *args: P.args, sync: Literal[True], **kwargs: P.kwargs) -> T: ...
     @overload
-    def __call__(self, *args: P.args, sync: Literal[False], **kwargs: P.kwargs) -> Coroutine[Any, Any, T]:...
+    def __call__(
+        self, *args: P.args, sync: Literal[False], **kwargs: P.kwargs
+    ) -> Coroutine[Any, Any, T]: ...
     @overload
-    def __call__(self, *args: P.args, asynchronous: Literal[False], **kwargs: P.kwargs) -> T:...
+    def __call__(
+        self, *args: P.args, asynchronous: Literal[False], **kwargs: P.kwargs
+    ) -> T: ...
     @overload
-    def __call__(self, *args: P.args, asynchronous: Literal[True], **kwargs: P.kwargs) -> Coroutine[Any, Any, T]:...
+    def __call__(
+        self, *args: P.args, asynchronous: Literal[True], **kwargs: P.kwargs
+    ) -> Coroutine[Any, Any, T]: ...
     @overload
-    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> T:...
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> T: ...
     def __call__(self, *args: P.args, **kwargs: P.kwargs) -> T:
         """
         Call the bound method with synchronous default behavior.
@@ -534,14 +829,38 @@ class ASyncBoundMethodSyncDefault(ASyncBoundMethod[I, P, T]):
             *args: Positional arguments.
             **kwargs: Keyword arguments.
 
-        Returns:
-            The result of the method call.
+        Examples:
+            >>> bound_method = ASyncBoundMethodSyncDefault(instance, my_function, True)
+            >>> bound_method(arg1, arg2, kwarg1=value1)
         """
         return ASyncBoundMethod.__call__(self, *args, **kwargs)
 
+
 class ASyncBoundMethodAsyncDefault(ASyncBoundMethod[I, P, T]):
     """
     A bound method with asynchronous default behavior.
+
+    This class is a specialized version of :class:`ASyncBoundMethod` that defaults to asynchronous execution.
+    It overrides the `__call__` method to enforce asynchronous default behavior.
+
+    Examples:
+        >>> class MyClass:
+        ...     def __init__(self, value):
+        ...         self.value = value
+        ...
+        ...     @ASyncMethodDescriptorAsyncDefault
+        ...     async def my_method(self):
+        ...         return self.value
+        ...
+        >>> obj = MyClass(42)
+        >>> await obj.my_method()
+        42
+        >>> obj.my_method(sync=True)
+        42
+
+    See Also:
+        - :class:`ASyncBoundMethod`
+        - :class:`ASyncMethodDescriptorAsyncDefault`
     """
 
     def __get__(self, instance: I, owner: Type[I]) -> ASyncFunctionAsyncDefault[P, T]:
@@ -552,21 +871,28 @@ class ASyncBoundMethodAsyncDefault(ASyncBoundMethod[I, P, T]):
             instance: The instance to bind the method to.
             owner: The owner class.
 
-        Returns:
-            The bound method with asynchronous default behavior.
+        Examples:
+            >>> descriptor = ASyncMethodDescriptorAsyncDefault(my_function)
+            >>> bound_method = descriptor.__get__(instance, MyClass)
         """
         return ASyncBoundMethod.__get__(self, instance, owner)
 
     @overload
-    def __call__(self, *args: P.args, sync: Literal[True], **kwargs: P.kwargs) -> T:...
+    def __call__(self, *args: P.args, sync: Literal[True], **kwargs: P.kwargs) -> T: ...
     @overload
-    def __call__(self, *args: P.args, sync: Literal[False], **kwargs: P.kwargs) -> Coroutine[Any, Any, T]:...
+    def __call__(
+        self, *args: P.args, sync: Literal[False], **kwargs: P.kwargs
+    ) -> Coroutine[Any, Any, T]: ...
     @overload
-    def __call__(self, *args: P.args, asynchronous: Literal[False], **kwargs: P.kwargs) -> T:...
+    def __call__(
+        self, *args: P.args, asynchronous: Literal[False], **kwargs: P.kwargs
+    ) -> T: ...
     @overload
-    def __call__(self, *args: P.args, asynchronous: Literal[True], **kwargs: P.kwargs) -> Coroutine[Any, Any, T]:...
+    def __call__(
+        self, *args: P.args, asynchronous: Literal[True], **kwargs: P.kwargs
+    ) -> Coroutine[Any, Any, T]: ...
     @overload
-    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> Coroutine[Any, Any, T]:...
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> Coroutine[Any, Any, T]: ...
     def __call__(self, *args: P.args, **kwargs: P.kwargs) -> Coroutine[Any, Any, T]:
         """
         Call the bound method with asynchronous default behavior.
@@ -575,7 +901,8 @@ class ASyncBoundMethodAsyncDefault(ASyncBoundMethod[I, P, T]):
             *args: Positional arguments.
             **kwargs: Keyword arguments.
 
-        Returns:
-            A coroutine representing the asynchronous method call.
+        Examples:
+            >>> bound_method = ASyncBoundMethodAsyncDefault(instance, my_function, True)
+            >>> await bound_method(arg1, arg2, kwarg1=value1)
         """
         return ASyncBoundMethod.__call__(self, *args, **kwargs)