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

a_sync/a_sync/_descriptor.py

@@ -1,25 +1,55 @@
 """
-This module contains the ASyncDescriptor class, which is used to create sync/async methods
+This module contains the :class:`ASyncDescriptor` class, which is used to create dual-function sync/async methods
 and properties.
 
-It also includes utility methods for mapping operations across multiple instances.
+The :class:`ASyncDescriptor` class provides functionality for mapping operations across multiple instances
+and includes utility methods for common operations such as checking if all or any results are truthy, 
+and finding the minimum, maximum, or sum of results of the method or property mapped across multiple instances.
+
+See Also:
+    - :class:`~a_sync.a_sync.function.ASyncFunction`
+    - :class:`~a_sync.a_sync.method.ASyncMethodDescriptor`
 """
 
 import functools
 
 from a_sync._typing import *
 from a_sync.a_sync import decorator
-from a_sync.a_sync.function import ASyncFunction, ModifiedMixin, ModifierManager
+from a_sync.a_sync.function import ASyncFunction, ModifierManager, _ModifiedMixin
 
 if TYPE_CHECKING:
     from a_sync import TaskMapping
 
-class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
+
+class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
     """
-    A descriptor base class for asynchronous methods and properties.
+    A descriptor base class for dual-function ASync methods and properties.
 
     This class provides functionality for mapping operations across multiple instances
-    and includes utility methods for common operations.
+    and includes utility methods for common operations such as checking if all or any
+    results are truthy, and finding the minimum, maximum, or sum of results of the method
+    or property mapped across multiple instances.
+
+    Examples:
+        To create a dual-function method or property, subclass :class:`ASyncDescriptor` and implement
+        the desired functionality. You can then use the provided utility methods to perform operations
+        across multiple instances.
+
+        ```python
+        class MyDescriptor(ASyncDescriptor):
+            def __init__(self, func):
+                super().__init__(func)
+
+        class MyClass:
+            my_method = MyDescriptor(lambda x: x * 2)
+
+        instance = MyClass()
+        result = instance.my_method.map([1, 2, 3])
+        ```
+
+    See Also:
+        - :class:`~a_sync.a_sync.function.ASyncFunction`
+        - :class:`~a_sync.a_sync.method.ASyncMethodDescriptor`
     """
 
     __wrapped__: AnyFn[Concatenate[I, P], T]
@@ -28,13 +58,13 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
     __slots__ = "field_name", "_fget"
 
     def __init__(
-        self, 
-        _fget: AnyFn[Concatenate[I, P], T], 
-        field_name: Optional[str] = None, 
+        self,
+        _fget: AnyFn[Concatenate[I, P], T],
+        field_name: Optional[str] = None,
         **modifiers: ModifierKwargs,
     ) -> None:
         """
-        Initialize the {cls}.
+        Initialize the :class:`ASyncDescriptor`.
 
         Args:
             _fget: The function to be wrapped.
@@ -45,19 +75,21 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
             ValueError: If _fget is not callable.
         """
         if not callable(_fget):
-            raise ValueError(f'Unable to decorate {_fget}')
+            raise ValueError(f"Unable to decorate {_fget}")
         self.modifiers = ModifierManager(modifiers)
         if isinstance(_fget, ASyncFunction):
             self.modifiers.update(_fget.modifiers)
             self.__wrapped__ = _fget
         elif asyncio.iscoroutinefunction(_fget):
-            self.__wrapped__: AsyncUnboundMethod[I, P, T] = self.modifiers.apply_async_modifiers(_fget)
+            self.__wrapped__: AsyncUnboundMethod[I, P, T] = (
+                self.modifiers.apply_async_modifiers(_fget)
+            )
         else:
             self.__wrapped__ = _fget
 
         self.field_name = field_name or _fget.__name__
-        """The name of the field the {cls} is bound to."""
-        
+        """The name of the field the :class:`ASyncDescriptor` is bound to."""
+
         functools.update_wrapper(self, self.__wrapped__)
 
     def __repr__(self) -> str:
@@ -65,7 +97,7 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
 
     def __set_name__(self, owner, name):
         """
-        Set the field name when the {cls} is assigned to a class.
+        Set the field name when the :class:`ASyncDescriptor` is assigned to a class.
 
         Args:
             owner: The class owning this descriptor.
@@ -73,18 +105,32 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
         """
         self.field_name = name
 
-    def map(self, *instances: AnyIterable[I], **bound_method_kwargs: P.kwargs) -> "TaskMapping[I, T]":
+    def map(
+        self, *instances: AnyIterable[I], **bound_method_kwargs: P.kwargs
+    ) -> "TaskMapping[I, T]":
         """
-        Create a TaskMapping for the given instances.
+        Create a :class:`TaskMapping` for the given instances.
 
         Args:
             *instances: Iterable of instances to map over.
             **bound_method_kwargs: Additional keyword arguments for the bound method.
 
         Returns:
-            A TaskMapping object.
+            A :class:`TaskMapping` object.
+
+        Examples:
+            class MyDescriptor(ASyncDescriptor):
+                def __init__(self, func):
+                    super().__init__(func)
+
+            class MyClass:
+                my_method = MyDescriptor(lambda x: x * 2)
+
+            instance = MyClass()
+            result = instance.my_method.map([1, 2, 3])
         """
         from a_sync.task import TaskMapping
+
         return TaskMapping(self, *instances, **bound_method_kwargs)
 
     @functools.cached_property
@@ -93,7 +139,18 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
         Create an :class:`~ASyncFunction` that checks if all results are truthy.
 
         Returns:
-            An ASyncFunction object.
+            An :class:`ASyncFunction` object.
+
+        Examples:
+            class MyDescriptor(ASyncDescriptor):
+                def __init__(self, func):
+                    super().__init__(func)
+
+            class MyClass:
+                my_method = MyDescriptor(lambda x: x > 0)
+
+            instance = MyClass()
+            result = await instance.my_method.all([1, 2, 3])
         """
         return decorator.a_sync(default=self.default)(self._all)
 
@@ -103,7 +160,18 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
         Create an :class:`~ASyncFunction` that checks if any result is truthy.
 
         Returns:
-            An ASyncFunction object.
+            An :class:`ASyncFunction` object.
+
+        Examples:
+            class MyDescriptor(ASyncDescriptor):
+                def __init__(self, func):
+                    super().__init__(func)
+
+            class MyClass:
+                my_method = MyDescriptor(lambda x: x > 0)
+
+            instance = MyClass()
+            result = await instance.my_method.any([-1, 0, 1])
         """
         return decorator.a_sync(default=self.default)(self._any)
 
@@ -113,7 +181,20 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
         Create an :class:`~ASyncFunction` that returns the minimum result.
 
         Returns:
-            An ASyncFunction object.
+            An :class:`ASyncFunction` object.
+
+        Examples:
+            ```python
+            class MyDescriptor(ASyncDescriptor):
+                def __init__(self, func):
+                    super().__init__(func)
+
+            class MyClass:
+                my_method = MyDescriptor(lambda x: x)
+
+            instance = MyClass()
+            result = await instance.my_method.min([3, 1, 2])
+            ```
         """
         return decorator.a_sync(default=self.default)(self._min)
 
@@ -123,7 +204,18 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
         Create an :class:`~ASyncFunction` that returns the maximum result.
 
         Returns:
-            An ASyncFunction object.
+            An :class:`ASyncFunction` object.
+
+        Examples:
+            class MyDescriptor(ASyncDescriptor):
+                def __init__(self, func):
+                    super().__init__(func)
+
+            class MyClass:
+                my_method = MyDescriptor(lambda x: x)
+
+            instance = MyClass()
+            result = await instance.my_method.max([3, 1, 2])
         """
         return decorator.a_sync(default=self.default)(self._max)
 
@@ -133,11 +225,30 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
         Create an :class:`~ASyncFunction` that returns the sum of results.
 
         Returns:
-            An ASyncFunction object.
+            An :class:`ASyncFunction` object.
+
+        Examples:
+            ```python
+            class MyDescriptor(ASyncDescriptor):
+                def __init__(self, func):
+                    super().__init__(func)
+
+            class MyClass:
+                my_method = MyDescriptor(lambda x: x)
+
+            instance = MyClass()
+            result = await instance.my_method.sum([1, 2, 3])
+            ```
         """
         return decorator.a_sync(default=self.default)(self._sum)
 
-    async def _all(self, *instances: AnyIterable[I], concurrency: Optional[int] = None, name: str = "", **kwargs: P.kwargs) -> bool:
+    async def _all(
+        self,
+        *instances: AnyIterable[I],
+        concurrency: Optional[int] = None,
+        name: str = "",
+        **kwargs: P.kwargs,
+    ) -> bool:
         """
         Check if all results are truthy.
 
@@ -149,10 +260,31 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
 
         Returns:
             A boolean indicating if all results are truthy.
-        """
-        return await self.map(*instances, concurrency=concurrency, name=name, **kwargs).all(pop=True, sync=False)
 
-    async def _any(self, *instances: AnyIterable[I], concurrency: Optional[int] = None, name: str = "", **kwargs: P.kwargs) -> bool:
+        Examples:
+            ```python
+            class MyDescriptor(ASyncDescriptor):
+                def __init__(self, func):
+                    super().__init__(func)
+
+            class MyClass:
+                my_method = MyDescriptor(lambda x: x > 0)
+
+            instance = MyClass()
+            result = await instance.my_method._all([1, 2, 3])
+            ```
+        """
+        return await self.map(
+            *instances, concurrency=concurrency, name=name, **kwargs
+        ).all(pop=True, sync=False)
+
+    async def _any(
+        self,
+        *instances: AnyIterable[I],
+        concurrency: Optional[int] = None,
+        name: str = "",
+        **kwargs: P.kwargs,
+    ) -> bool:
         """
         Check if any result is truthy.
 
@@ -164,10 +296,31 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
 
         Returns:
             A boolean indicating if any result is truthy.
-        """
-        return await self.map(*instances, concurrency=concurrency, name=name, **kwargs).any(pop=True, sync=False)
 
-    async def _min(self, *instances: AnyIterable[I], concurrency: Optional[int] = None, name: str = "", **kwargs: P.kwargs) -> T:
+        Examples:
+            ```python
+            class MyDescriptor(ASyncDescriptor):
+                def __init__(self, func):
+                    super().__init__(func)
+
+            class MyClass:
+                my_method = MyDescriptor(lambda x: x > 0)
+
+            instance = MyClass()
+            result = await instance.my_method._any([-1, 0, 1])
+            ```
+        """
+        return await self.map(
+            *instances, concurrency=concurrency, name=name, **kwargs
+        ).any(pop=True, sync=False)
+
+    async def _min(
+        self,
+        *instances: AnyIterable[I],
+        concurrency: Optional[int] = None,
+        name: str = "",
+        **kwargs: P.kwargs,
+    ) -> T:
         """
         Find the minimum result.
 
@@ -179,10 +332,31 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
 
         Returns:
             The minimum result.
-        """
-        return await self.map(*instances, concurrency=concurrency, name=name, **kwargs).min(pop=True, sync=False)
 
-    async def _max(self, *instances: AnyIterable[I], concurrency: Optional[int] = None, name: str = "", **kwargs: P.kwargs) -> T:
+        Examples:
+            ```python
+            class MyDescriptor(ASyncDescriptor):
+                def __init__(self, func):
+                    super().__init__(func)
+
+            class MyClass:
+                my_method = MyDescriptor(lambda x: x)
+
+            instance = MyClass()
+            result = await instance.my_method._min([3, 1, 2])
+            ```
+        """
+        return await self.map(
+            *instances, concurrency=concurrency, name=name, **kwargs
+        ).min(pop=True, sync=False)
+
+    async def _max(
+        self,
+        *instances: AnyIterable[I],
+        concurrency: Optional[int] = None,
+        name: str = "",
+        **kwargs: P.kwargs,
+    ) -> T:
         """
         Find the maximum result.
 
@@ -194,10 +368,31 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
 
         Returns:
             The maximum result.
-        """
-        return await self.map(*instances, concurrency=concurrency, name=name, **kwargs).max(pop=True, sync=False)
 
-    async def _sum(self, *instances: AnyIterable[I], concurrency: Optional[int] = None, name: str = "", **kwargs: P.kwargs) -> T:
+        Examples:
+            ```python
+            class MyDescriptor(ASyncDescriptor):
+                def __init__(self, func):
+                    super().__init__(func)
+
+            class MyClass:
+                my_method = MyDescriptor(lambda x: x)
+
+            instance = MyClass()
+            result = await instance.my_method._max([3, 1, 2])
+            ```
+        """
+        return await self.map(
+            *instances, concurrency=concurrency, name=name, **kwargs
+        ).max(pop=True, sync=False)
+
+    async def _sum(
+        self,
+        *instances: AnyIterable[I],
+        concurrency: Optional[int] = None,
+        name: str = "",
+        **kwargs: P.kwargs,
+    ) -> T:
         """
         Calculate the sum of results.
 
@@ -209,11 +404,26 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
 
         Returns:
             The sum of the results.
+
+        Examples:
+            ```python
+            class MyDescriptor(ASyncDescriptor):
+                def __init__(self, func):
+                    super().__init__(func)
+
+            class MyClass:
+                my_method = MyDescriptor(lambda x: x)
+
+            instance = MyClass()
+            result = await instance.my_method._sum([1, 2, 3])
+            ```
         """
-        return await self.map(*instances, concurrency=concurrency, name=name, **kwargs).sum(pop=True, sync=False)
+        return await self.map(
+            *instances, concurrency=concurrency, name=name, **kwargs
+        ).sum(pop=True, sync=False)
 
     def __init_subclass__(cls) -> None:
         for attr in cls.__dict__.values():
             if attr.__doc__ and "{cls}" in attr.__doc__:
                 attr.__doc__ = attr.__doc__.replace("{cls}", f":class:`{cls.__name__}`")
-        return super().__init_subclass__()
+        return super().__init_subclass__()

a_sync/a_sync/_flags.py

@@ -2,27 +2,71 @@
 This module provides functionality for handling synchronous and asynchronous flags
 in the ez-a-sync library.
 
-ez-a-sync uses 'flags' to indicate whether objects / function calls will be sync or async.
+ez-a-sync uses 'flags' to indicate whether objects or function calls will be synchronous or asynchronous.
 
-You can use any of the provided flags, whichever makes most sense for your use case.
+You can use any of the provided flags, whichever makes the most sense for your use case.
+
+AFFIRMATIVE_FLAGS: Set of flags indicating synchronous behavior. Currently includes "sync".
+
+NEGATIVE_FLAGS: Set of flags indicating asynchronous behavior. Currently includes "asynchronous".
+
+VIABLE_FLAGS: Set of all valid flags, combining both synchronous and asynchronous indicators.
+
+Functions:
+    - negate_if_necessary: Negates the flag value if necessary based on the flag type.
+    - validate_flag_value: Validates that the flag value is a boolean.
 """
 
 from typing import Any
 
 from a_sync import exceptions
 
-AFFIRMATIVE_FLAGS = {'sync'}
-"""Set of flags indicating synchronous behavior."""
+AFFIRMATIVE_FLAGS = {"sync"}
+"""Set of flags indicating synchronous behavior.
+
+Examples:
+    >>> 'sync' in AFFIRMATIVE_FLAGS
+    True
+
+    >>> 'async' in AFFIRMATIVE_FLAGS
+    False
+"""
+
+NEGATIVE_FLAGS = {"asynchronous"}
+"""Set of flags indicating asynchronous behavior.
 
-NEGATIVE_FLAGS = {'asynchronous'}
-"""Set of flags indicating asynchronous behavior."""
+Examples:
+    >>> 'asynchronous' in NEGATIVE_FLAGS
+    True
+
+    >>> 'sync' in NEGATIVE_FLAGS
+    False
+"""
 
 VIABLE_FLAGS = AFFIRMATIVE_FLAGS | NEGATIVE_FLAGS
-"""Set of all valid flags."""
+"""Set of all valid flags, combining both synchronous and asynchronous indicators.
+
+A-Sync uses 'flags' to indicate whether objects or function calls will be sync or async.
+You can use any of the provided flags, whichever makes most sense for your use case.
+
+Examples:
+    >>> 'sync' in VIABLE_FLAGS
+    True
+
+    >>> 'asynchronous' in VIABLE_FLAGS
+    True
+
+    >>> 'invalid' in VIABLE_FLAGS
+    False
+"""
+
 
 def negate_if_necessary(flag: str, flag_value: bool) -> bool:
     """Negate the flag value if necessary based on the flag type.
 
+    This function checks if the provided flag is in the set of affirmative or negative flags
+    and negates the flag value accordingly. If the flag is not recognized, it raises an exception.
+
     Args:
         flag: The flag to check.
         flag_value: The value of the flag.
@@ -31,7 +75,17 @@ def negate_if_necessary(flag: str, flag_value: bool) -> bool:
         The potentially negated flag value.
 
     Raises:
-        :class:`exceptions.InvalidFlag`: If the flag is not recognized.
+        exceptions.InvalidFlag: If the flag is not recognized.
+
+    Examples:
+        >>> negate_if_necessary('sync', True)
+        True
+
+        >>> negate_if_necessary('asynchronous', True)
+        False
+
+    See Also:
+        - :func:`validate_flag_value`: Validates that the flag value is a boolean.
     """
     validate_flag_value(flag, flag_value)
     if flag in AFFIRMATIVE_FLAGS:
@@ -40,10 +94,13 @@ def negate_if_necessary(flag: str, flag_value: bool) -> bool:
         return bool(not flag_value)
     raise exceptions.InvalidFlag(flag)
 
+
 def validate_flag_value(flag: str, flag_value: Any) -> bool:
     """
     Validate that the flag value is a boolean.
 
+    This function ensures that the provided flag value is of type boolean. If not, it raises an exception.
+
     Args:
         flag: The flag being validated.
         flag_value: The value to validate.
@@ -52,7 +109,19 @@ def validate_flag_value(flag: str, flag_value: Any) -> bool:
         The validated flag value.
 
     Raises:
-        :class:`exceptions.InvalidFlagValue`: If the flag value is not a boolean.
+        exceptions.InvalidFlagValue: If the flag value is not a boolean.
+
+    Examples:
+        >>> validate_flag_value('sync', True)
+        True
+
+        >>> validate_flag_value('asynchronous', 'yes')
+        Traceback (most recent call last):
+        ...
+        exceptions.InvalidFlagValue: Invalid flag value for 'asynchronous': 'yes'
+
+    See Also:
+        - :func:`negate_if_necessary`: Negates the flag value if necessary based on the flag type.
     """
     if not isinstance(flag_value, bool):
         raise exceptions.InvalidFlagValue(flag, flag_value)

a_sync/a_sync/_helpers.py

@@ -17,13 +17,21 @@ def _await(awaitable: Awaitable[T]) -> T:
     Await an awaitable object in a synchronous context.
 
     Args:
-        awaitable: The awaitable object to be awaited.
-
-    Returns:
-        The result of the awaitable.
+        awaitable (Awaitable[T]): The awaitable object to be awaited.
 
     Raises:
-        :class:`exceptions.SyncModeInAsyncContextError`: If the event loop is already running.
+        exceptions.SyncModeInAsyncContextError: If the event loop is already running.
+
+    Examples:
+        >>> async def example_coroutine():
+        ...     return 42
+        ...
+        >>> result = _await(example_coroutine())
+        >>> print(result)
+        42
+
+    See Also:
+        - :func:`asyncio.run`: For running the main entry point of an asyncio program.
     """
     try:
         return a_sync.asyncio.get_event_loop().run_until_complete(awaitable)
@@ -32,27 +40,52 @@ def _await(awaitable: Awaitable[T]) -> T:
             raise exceptions.SyncModeInAsyncContextError from None
         raise
 
+
 def _asyncify(func: SyncFn[P, T], executor: Executor) -> CoroFn[P, T]:  # type: ignore [misc]
     """
-    Convert a synchronous function to a coroutine function.
+    Convert a synchronous function to a coroutine function using an executor.
 
-    Args:
-        func: The synchronous function to be converted.
-        executor: The executor to run the synchronous function.
+    This function submits the synchronous function to the provided executor and wraps
+    the resulting future in a coroutine function. This allows the synchronous function
+    to be executed asynchronously.
+
+    Note:
+        The function `_asyncify` uses `asyncio.futures.wrap_future` to wrap the future
+        returned by the executor, specifying the event loop with `a_sync.asyncio.get_event_loop()`.
+        Ensure that your environment supports this usage or adjust the import if necessary.
 
-    Returns:
-        A coroutine function wrapping the input function.
+    Args:
+        func (SyncFn[P, T]): The synchronous function to be converted.
+        executor (Executor): The executor used to run the synchronous function.
 
     Raises:
-        :class:`exceptions.FunctionNotSync`: If the input function is already asynchronous.
+        exceptions.FunctionNotSync: If the input function is a coroutine function or an instance of :class:`~a_sync.a_sync.function.ASyncFunction`.
+
+    Examples:
+        >>> from concurrent.futures import ThreadPoolExecutor
+        >>> def sync_function(x):
+        ...     return x * 2
+        ...
+        >>> executor = ThreadPoolExecutor()
+        >>> async_function = _asyncify(sync_function, executor)
+        >>> result = await async_function(3)
+        >>> print(result)
+        6
+
+    See Also:
+        - :class:`concurrent.futures.Executor`: For managing pools of threads or processes.
+        - :func:`asyncio.to_thread`: For running blocking code in a separate thread.
     """
     from a_sync.a_sync.function import ASyncFunction
+
     if asyncio.iscoroutinefunction(func) or isinstance(func, ASyncFunction):
         raise exceptions.FunctionNotSync(func)
+
     @functools.wraps(func)
     async def _asyncify_wrap(*args: P.args, **kwargs: P.kwargs) -> T:
         return await asyncio.futures.wrap_future(
-            executor.submit(func, *args, **kwargs), 
+            executor.submit(func, *args, **kwargs),
             loop=a_sync.asyncio.get_event_loop(),
         )
+
     return _asyncify_wrap