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

a_sync/ENVIRONMENT_VARIABLES.py

@@ -4,10 +4,41 @@ envs = EnvVarFactory("EZASYNC")
 
 # We have some envs here to help you debug your custom class implementations
 
-# If you're only interested in debugging a specific class, set this to the class name
 DEBUG_CLASS_NAME = envs.create_env("DEBUG_CLASS_NAME", str, default="", verbose=False)
+"""str: The name of the class to debug.
+
+If you're only interested in debugging a specific class, set this to the class name.
+
+Examples:
+    To debug a class named `MyClass`, set the environment variable:
+    
+    .. code-block:: bash
+
+        export EZASYNC_DEBUG_CLASS_NAME=MyClass
+
+See Also:
+    :func:`DEBUG_MODE` for enabling debug mode on all classes.
+"""
 
-# Set this to enable debug mode on all classes
 DEBUG_MODE = envs.create_env(
-    "DEBUG_MODE", bool, default=DEBUG_CLASS_NAME, verbose=False
+    "DEBUG_MODE", bool, default=bool(DEBUG_CLASS_NAME), verbose=False
 )
+"""bool: Enables debug mode on all classes.
+
+Set this environment variable to `True` to enable debug mode on all classes. 
+If `DEBUG_CLASS_NAME` is set to a truthy value other than an empty string, 
+`DEBUG_MODE` will default to `True`.
+
+Examples:
+    To enable debug mode globally, set the environment variable:
+
+    .. code-block:: bash
+
+        export EZASYNC_DEBUG_MODE=True
+
+    If you have set `DEBUG_CLASS_NAME` to a specific class, `DEBUG_MODE` will 
+    automatically be `True` unless `DEBUG_CLASS_NAME` is an empty string.
+
+See Also:
+    :func:`DEBUG_CLASS_NAME` for debugging a specific class.
+"""

a_sync/__init__.py

@@ -8,17 +8,40 @@ that can operate in both synchronous and asynchronous contexts. Additionally, it
 such as queues and locks, with extra functionality.
 
 Modules and components included:
-- `aliases`, `exceptions`, `iter`, `task`: Core modules of the library.
-- `ASyncGenericBase`, `ASyncGenericSingleton`, `a_sync`: Base classes and decorators for dual-context execution.
-- `apply_semaphore`: Function to apply semaphores to coroutines.
-- `ASyncCachedPropertyDescriptor`, `ASyncPropertyDescriptor`, `cached_property`, `property`: Property descriptors for async properties.
-- `as_completed`, `create_task`, `gather`: Enhanced asyncio functions.
-- Executors: `AsyncThreadPoolExecutor`, `AsyncProcessPoolExecutor`, `PruningThreadPoolExecutor` for async execution.
-- Iterators: `ASyncFilter`, `ASyncSorter`, `ASyncIterable`, `ASyncIterator` for async iteration.
-- Utilities: `all`, `any`, `as_yielded` for async utilities.
+- :mod:`~aliases`, :mod:`~exceptions`, :mod:`~iter`, :mod:`~task`: Core modules of the library.
+- :class:`~ASyncGenericBase`, :class:`~ASyncGenericSingleton`, :func:`~a_sync`: Base classes and decorators for dual-context execution.
+- :class:`~ASyncCachedPropertyDescriptor`, :class:`~ASyncPropertyDescriptor`, `cached_property`, `property`: Property descriptors for async properties.
+- :func:`~as_completed`, :func:`~create_task`, :func:`~gather`: Enhanced asyncio functions.
+- Executors: :class:`~AsyncThreadPoolExecutor`, :class:`~AsyncProcessPoolExecutor`, :class:`~PruningThreadPoolExecutor` for async execution.
+- Iterators: :class:`~ASyncFilter`, :class:`~ASyncSorter`, :class:`~ASyncIterable`, :class:`~ASyncIterator` for async iteration.
+- Utilities: :func:`~all`, :func:`~any`, :func:`~as_yielded`, :func:`~exhaust_iterator`, :func:`~exhaust_iterators` for async utilities.
+- :func:`~apply_semaphore`: Function to apply semaphores to coroutines.
 
 Alias for backward compatibility:
-- `ASyncBase` is an alias for `ASyncGenericBase`, which will be removed eventually, probably in version 0.1.0.
+- :class:`~ASyncBase` is an alias for :class:`~ASyncGenericBase`, which will be removed eventually, probably in version 0.1.0.
+
+Examples:
+    Using the `@a_sync` decorator:
+    >>> from a_sync import a_sync
+    >>> @a_sync
+    ... async def my_function():
+    ...     return "Hello, World!"
+    >>> result = await my_function()
+    >>> print(result)
+
+    Using `ASyncGenericBase` for dual-context classes:
+    >>> from a_sync import ASyncGenericBase
+    >>> class MyClass(ASyncGenericBase):
+    ...     async def my_method(self):
+    ...         return "Hello from MyClass"
+    >>> obj = MyClass()
+    >>> result = await obj.my_method()
+    >>> print(result)
+
+See Also:
+    - :mod:`a_sync.a_sync`: Contains the core classes and decorators.
+    - :mod:`a_sync.asyncio`: Provides enhanced asyncio functions.
+    - :mod:`a_sync.primitives`: Includes modified versions of standard asyncio primitives.
 """
 
 from a_sync import aliases, exceptions, iter, task

a_sync/_smart.py

@@ -1,7 +1,8 @@
 """
 This module defines smart future and task utilities for the a_sync library.
 These utilities provide enhanced functionality for managing asynchronous tasks and futures,
-including task shielding and a custom task factory for creating SmartTask instances.
+including a custom task factory for creating :class:`~SmartTask` instances and a shielding mechanism
+to protect tasks from cancellation.
 """
 
 import asyncio
@@ -37,6 +38,27 @@ class _SmartFutureMixin(Generic[T]):
     def __await__(self: Union["SmartFuture", "SmartTask"]) -> Generator[Any, None, T]:
         """
         Await the smart future or task, handling waiters and logging.
+
+        Yields:
+            The result of the future or task.
+
+        Raises:
+            RuntimeError: If await wasn't used with future.
+
+        Example:
+            Awaiting a SmartFuture:
+
+            ```python
+            future = SmartFuture()
+            result = await future
+            ```
+
+            Awaiting a SmartTask:
+
+            ```python
+            task = SmartTask(coro=my_coroutine())
+            result = await task
+            ```
         """
         if self.done():
             return self.result()  # May raise too.
@@ -54,6 +76,12 @@ class _SmartFutureMixin(Generic[T]):
         # NOTE: we check .done() because the callback may not have ran yet and its very lightweight
         """
         Get the number of waiters currently awaiting the future or task.
+
+        Example:
+            ```python
+            future = SmartFuture()
+            print(future.num_waiters)
+            ```
         """
         if self.done():
             # if there are any waiters left, there won't be once the event loop runs once
@@ -67,6 +95,9 @@ class _SmartFutureMixin(Generic[T]):
         Callback to clean up waiters when a waiter task is done.
 
         Removes the waiter from _waiters, and _queue._futs if applicable
+
+        Args:
+            waiter: The waiter task to clean up.
         """
         if not self.done():
             self._waiters.remove(waiter)
@@ -84,8 +115,16 @@ class SmartFuture(_SmartFutureMixin[T], asyncio.Future):
     """
     A smart future that tracks waiters and integrates with a smart processing queue.
 
-    Inherits from both _SmartFutureMixin and asyncio.Future, providing additional functionality
+    Inherits from both :class:`_SmartFutureMixin` and :class:`asyncio.Future`, providing additional functionality
     for tracking waiters and integrating with a smart processing queue.
+
+    Example:
+        Creating and awaiting a SmartFuture:
+
+        ```python
+        future = SmartFuture()
+        await future
+        ```
     """
 
     _queue = None
@@ -105,6 +144,11 @@ class SmartFuture(_SmartFutureMixin[T], asyncio.Future):
             queue: Optional; a smart processing queue.
             key: Optional; a key identifying the future.
             loop: Optional; the event loop.
+
+        Example:
+            ```python
+            future = SmartFuture(queue=my_queue, key=my_key)
+            ```
         """
         super().__init__(loop=loop)
         if queue:
@@ -125,8 +169,12 @@ class SmartFuture(_SmartFutureMixin[T], asyncio.Future):
         Args:
             other: Another SmartFuture to compare with.
 
-        Returns:
-            True if self has more waiters than other.
+        Example:
+            ```python
+            future1 = SmartFuture()
+            future2 = SmartFuture()
+            print(future1 < future2)
+            ```
         """
         return self.num_waiters > other.num_waiters
 
@@ -138,7 +186,7 @@ def create_future(
     loop: Optional[asyncio.AbstractEventLoop] = None,
 ) -> SmartFuture[V]:
     """
-    Create a SmartFuture instance.
+    Create a :class:`~SmartFuture` instance.
 
     Args:
         queue: Optional; a smart processing queue.
@@ -147,6 +195,13 @@ def create_future(
 
     Returns:
         A SmartFuture instance.
+
+    Example:
+        Creating a SmartFuture using the factory function:
+
+        ```python
+        future = create_future(queue=my_queue, key=my_key)
+        ```
     """
     return SmartFuture(queue=queue, key=key, loop=loop or asyncio.get_event_loop())
 
@@ -155,8 +210,16 @@ class SmartTask(_SmartFutureMixin[T], asyncio.Task):
     """
     A smart task that tracks waiters and integrates with a smart processing queue.
 
-    Inherits from both _SmartFutureMixin and asyncio.Task, providing additional functionality
+    Inherits from both :class:`_SmartFutureMixin` and :class:`asyncio.Task`, providing additional functionality
     for tracking waiters and integrating with a smart processing queue.
+
+    Example:
+        Creating and awaiting a SmartTask:
+
+        ```python
+        task = SmartTask(coro=my_coroutine())
+        await task
+        ```
     """
 
     def __init__(
@@ -173,6 +236,11 @@ class SmartTask(_SmartFutureMixin[T], asyncio.Task):
             coro: The coroutine to run in the task.
             loop: Optional; the event loop.
             name: Optional; the name of the task.
+
+        Example:
+            ```python
+            task = SmartTask(coro=my_coroutine(), name="my_task")
+            ```
         """
         super().__init__(coro, loop=loop, name=name)
         self._waiters: Set["asyncio.Task[T]"] = set()
@@ -193,6 +261,17 @@ def smart_task_factory(
 
     Returns:
         A SmartTask instance running the provided coroutine.
+
+    Example:
+        Using the smart task factory to create a SmartTask:
+
+        ```python
+        loop = asyncio.get_event_loop()
+        task = smart_task_factory(loop, my_coroutine())
+        ```
+
+    See Also:
+        - :func:`set_smart_task_factory`
     """
     return SmartTask(coro, loop=loop)
 
@@ -203,6 +282,16 @@ def set_smart_task_factory(loop: asyncio.AbstractEventLoop = None) -> None:
 
     Args:
         loop: Optional; the event loop. If None, the current event loop is used.
+
+    Example:
+        Setting the smart task factory for the current event loop:
+
+        ```python
+        set_smart_task_factory()
+        ```
+
+    See Also:
+        - :func:`smart_task_factory`
     """
     if loop is None:
         loop = a_sync.asyncio.get_event_loop()
@@ -241,6 +330,16 @@ def shield(
     Args:
         arg: The awaitable to shield from cancellation.
         loop: Optional; the event loop. Deprecated since Python 3.8.
+
+    Example:
+        Using shield to protect a coroutine from cancellation:
+
+        ```python
+        result = await shield(my_coroutine())
+        ```
+
+    See Also:
+        - :func:`asyncio.shield`
     """
     if loop is not None:
         warnings.warn(

a_sync/_typing.py

@@ -1,7 +1,60 @@
 """
-This module provides type definitions and type-related utilities for the a_sync library.
-It includes various type aliases, protocols, and TypedDicts used throughout the library
-to enhance type checking and provide better IDE support.
+This module provides type definitions and type-related utilities for the `a_sync` library.
+
+It includes various type aliases and protocols used throughout the library to enhance type checking and provide better IDE support.
+
+Examples:
+    The following examples demonstrate how to use some of the type aliases and protocols defined in this module.
+
+    Example of a function that can return either an awaitable or a direct value:
+
+    ```python
+    from a_sync._typing import MaybeAwaitable
+    from typing import Awaitable
+
+    async def process_data(data: MaybeAwaitable[int]) -> int:
+        if isinstance(data, Awaitable):
+            return await data
+        return data
+
+    # Usage
+    import asyncio
+
+    async def main():
+        result = await process_data(asyncio.sleep(1, result=42))
+        print(result)  # Output: 42
+
+        result = await process_data(42)
+        print(result)  # Output: 42
+
+    asyncio.run(main())
+    ```
+
+    Example of defining a coroutine function type:
+
+    ```python
+    from a_sync._typing import CoroFn
+
+    async def async_function(x: int) -> str:
+        return str(x)
+
+    coro_fn: CoroFn[[int], str] = async_function
+    ```
+
+    Example of defining a synchronous function type:
+
+    ```python
+    from a_sync._typing import SyncFn
+
+    def sync_function(x: int) -> str:
+        return str(x)
+
+    sync_fn: SyncFn[[int], str] = sync_function
+    ```
+
+See Also:
+    - :mod:`typing`
+    - :mod:`asyncio`
 """
 
 import asyncio

a_sync/a_sync/_descriptor.py

@@ -1,8 +1,14 @@
 """
-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
@@ -23,6 +29,27 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
     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]
@@ -37,7 +64,7 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
         **modifiers: ModifierKwargs,
     ) -> None:
         """
-        Initialize the {cls}.
+        Initialize the :class:`ASyncDescriptor`.
 
         Args:
             _fget: The function to be wrapped.
@@ -61,7 +88,7 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
             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__)
 
@@ -70,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.
@@ -82,14 +109,25 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
         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
 
@@ -101,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)
 
@@ -111,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)
 
@@ -121,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)
 
@@ -131,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)
 
@@ -141,7 +225,20 @@ 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)
 
@@ -163,6 +260,19 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
 
         Returns:
             A boolean indicating if all results are truthy.
+
+        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
@@ -186,6 +296,19 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
 
         Returns:
             A boolean indicating if any result is truthy.
+
+        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
@@ -209,6 +332,19 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
 
         Returns:
             The minimum result.
+
+        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
@@ -232,6 +368,19 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
 
         Returns:
             The maximum result.
+
+        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
@@ -255,6 +404,19 @@ 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