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

a_sync/ENVIRONMENT_VARIABLES.py

@@ -1,12 +1,44 @@
-
 from typed_envs import EnvVarFactory
 
 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) 
+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.
+"""
+
+DEBUG_MODE = envs.create_env(
+    "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.
 
-# Set this to enable debug mode on all classes
-DEBUG_MODE = envs.create_env("DEBUG_MODE", bool, default=DEBUG_CLASS_NAME, verbose=False)
+See Also:
+    :func:`DEBUG_CLASS_NAME` for debugging a specific class.
+"""

a_sync/__init__.py

@@ -1,8 +1,58 @@
+"""
+This module initializes the a_sync library by importing and organizing various components, utilities, and classes.
+It provides a convenient and unified interface for asynchronous programming with a focus on flexibility and efficiency.
+
+The `a_sync` library offers decorators and base classes to facilitate writing both synchronous and asynchronous code.
+It includes the `@a_sync()` decorator and the `ASyncGenericBase` class, which allow for creating functions and classes
+that can operate in both synchronous and asynchronous contexts. Additionally, it provides enhanced asyncio primitives,
+such as queues and locks, with extra functionality.
+
+Modules and components included:
+- :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:
+- :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
 from a_sync.a_sync import ASyncGenericBase, ASyncGenericSingleton, a_sync
 from a_sync.a_sync.modifiers.semaphores import apply_semaphore
-from a_sync.a_sync.property import ASyncCachedPropertyDescriptor, ASyncPropertyDescriptor, cached_property, property
+from a_sync.a_sync.property import (
+    ASyncCachedPropertyDescriptor,
+    ASyncPropertyDescriptor,
+    cached_property,
+    property,
+)
 from a_sync.asyncio import as_completed, create_task, gather
 from a_sync.executor import *
 from a_sync.executor import AsyncThreadPoolExecutor as ThreadPoolExecutor
@@ -29,16 +79,13 @@ __all__ = [
     "exceptions",
     "iter",
     "task",
-
     # builtins
     "sorted",
     "filter",
-
     # asyncio
     "create_task",
-    "gather", 
+    "gather",
     "as_completed",
-
     # functions
     "a_sync",
     "all",
@@ -47,33 +94,27 @@ __all__ = [
     "exhaust_iterator",
     "exhaust_iterators",
     "map",
-
     # classes
     "ASyncIterable",
     "ASyncIterator",
     "ASyncGenericSingleton",
-    "TaskMapping", 
-
+    "TaskMapping",
     # property
     "cached_property",
     "property",
     "ASyncPropertyDescriptor",
     "ASyncCachedPropertyDescriptor",
-
     # semaphores
     "Semaphore",
     "PrioritySemaphore",
     "ThreadsafeSemaphore",
-
     # queues
     "Queue",
     "ProcessingQueue",
     "SmartProcessingQueue",
-
     # locks
     "CounterLock",
     "Event",
-
     # executors
     "AsyncThreadPoolExecutor",
     "PruningThreadPoolExecutor",

a_sync/_smart.py

@@ -1,3 +1,9 @@
+"""
+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 a custom task factory for creating :class:`~SmartTask` instances and a shielding mechanism
+to protect tasks from cancellation.
+"""
 
 import asyncio
 import logging
@@ -17,11 +23,43 @@ _Key = Tuple[_Args, _Kwargs]
 
 logger = logging.getLogger(__name__)
 
+
 class _SmartFutureMixin(Generic[T]):
+    """
+    Mixin class that provides common functionality for smart futures and tasks.
+
+    This mixin provides methods for managing waiters and integrating with a smart processing queue.
+    """
+
     _queue: Optional["SmartProcessingQueue[Any, Any, T]"] = None
     _key: _Key
     _waiters: "weakref.WeakSet[SmartTask[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.
         self._asyncio_future_blocking = True
@@ -32,33 +70,86 @@ class _SmartFutureMixin(Generic[T]):
         if not self.done():
             raise RuntimeError("await wasn't used with future")
         return self.result()  # May raise too.
+
     @property
     def num_waiters(self: Union["SmartFuture", "SmartTask"]) -> int:
         # 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
             return 0
-        return sum(getattr(waiter, 'num_waiters', 1) or 1 for waiter in self._waiters)
-    def _waiter_done_cleanup_callback(self: Union["SmartFuture", "SmartTask"], waiter: "SmartTask") -> None:
-        "Removes the waiter from _waiters, and _queue._futs if applicable"
+        return sum(getattr(waiter, "num_waiters", 1) or 1 for waiter in self._waiters)
+
+    def _waiter_done_cleanup_callback(
+        self: Union["SmartFuture", "SmartTask"], waiter: "SmartTask"
+    ) -> None:
+        """
+        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)
+
     def _self_done_cleanup_callback(self: Union["SmartFuture", "SmartTask"]) -> None:
+        """
+        Callback to clean up waiters and remove the future from the queue when done.
+        """
         self._waiters.clear()
         if queue := self._queue:
             queue._futs.pop(self._key)
 
 
 class SmartFuture(_SmartFutureMixin[T], asyncio.Future):
+    """
+    A smart future that tracks waiters and integrates with a smart processing queue.
+
+    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
     _key = None
+
     def __init__(
-        self, 
-        *, 
-        queue: Optional["SmartProcessingQueue[Any, Any, T]"], 
-        key: Optional[_Key] = None, 
+        self,
+        *,
+        queue: Optional["SmartProcessingQueue[Any, Any, T]"],
+        key: Optional[_Key] = None,
         loop: Optional[asyncio.AbstractEventLoop] = None,
     ) -> None:
+        """
+        Initialize the SmartFuture with an optional queue and key.
+
+        Args:
+            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:
             self._queue = weakref.proxy(queue)
@@ -66,63 +157,150 @@ class SmartFuture(_SmartFutureMixin[T], asyncio.Future):
             self._key = key
         self._waiters = weakref.WeakSet()
         self.add_done_callback(SmartFuture._self_done_cleanup_callback)
+
     def __repr__(self):
         return f"<{type(self).__name__} key={self._key} waiters={self.num_waiters} {self._state}>"
+
     def __lt__(self, other: "SmartFuture[T]") -> bool:
-        """heap considers lower values as higher priority so a future with more waiters will be 'less than' a future with less waiters."""
-        #other = other_ref()
-        #if other is None:
-        #    # garbage collected refs should always process first so they can be popped from the queue
-        #    return False
+        """
+        Compare the number of waiters to determine priority in a heap.
+        Lower values indicate higher priority, so more waiters means 'less than'.
+
+        Args:
+            other: Another SmartFuture to compare with.
+
+        Example:
+            ```python
+            future1 = SmartFuture()
+            future2 = SmartFuture()
+            print(future1 < future2)
+            ```
+        """
         return self.num_waiters > other.num_waiters
 
+
 def create_future(
     *,
-    queue: Optional["SmartProcessingQueue"] = None, 
-    key: Optional[_Key] = None, 
+    queue: Optional["SmartProcessingQueue"] = None,
+    key: Optional[_Key] = None,
     loop: Optional[asyncio.AbstractEventLoop] = None,
 ) -> SmartFuture[V]:
+    """
+    Create a :class:`~SmartFuture` instance.
+
+    Args:
+        queue: Optional; a smart processing queue.
+        key: Optional; a key identifying the future.
+        loop: Optional; the event loop.
+
+    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())
 
+
 class SmartTask(_SmartFutureMixin[T], asyncio.Task):
+    """
+    A smart task that tracks waiters and integrates with a smart processing queue.
+
+    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__(
-        self, 
-        coro: Awaitable[T], 
-        *, 
-        loop: Optional[asyncio.AbstractEventLoop] = None, 
+        self,
+        coro: Awaitable[T],
+        *,
+        loop: Optional[asyncio.AbstractEventLoop] = None,
         name: Optional[str] = None,
     ) -> None:
+        """
+        Initialize the SmartTask with a coroutine and optional event loop.
+
+        Args:
+            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()
         self.add_done_callback(SmartTask._self_done_cleanup_callback)
 
-def smart_task_factory(loop: asyncio.AbstractEventLoop, coro: Awaitable[T]) -> SmartTask[T]:
+
+def smart_task_factory(
+    loop: asyncio.AbstractEventLoop, coro: Awaitable[T]
+) -> SmartTask[T]:
     """
     Task factory function that an event loop calls to create new tasks.
-     
+
     This factory function utilizes ez-a-sync's custom :class:`~SmartTask` implementation.
-    
+
     Args:
         loop: The event loop.
         coro: The coroutine to run in the task.
-        
+
     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)
 
+
 def set_smart_task_factory(loop: asyncio.AbstractEventLoop = None) -> None:
     """
     Set the event loop's task factory to :func:`~smart_task_factory` so all tasks will be SmartTask instances.
-    
+
     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()
     loop.set_task_factory(smart_task_factory)
 
-def shield(arg: Awaitable[T], *, loop: Optional[asyncio.AbstractEventLoop] = None) -> SmartFuture[T]:
+
+def shield(
+    arg: Awaitable[T], *, loop: Optional[asyncio.AbstractEventLoop] = None
+) -> SmartFuture[T]:
     """
     Wait for a future, shielding it from cancellation.
 
@@ -148,11 +326,28 @@ def shield(arg: Awaitable[T], *, loop: Optional[asyncio.AbstractEventLoop] = Non
             res = await shield(something())
         except CancelledError:
             res = None
+
+    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("The loop argument is deprecated since Python 3.8, "
-                      "and scheduled for removal in Python 3.10.",
-                      DeprecationWarning, stacklevel=2)
+        warnings.warn(
+            "The loop argument is deprecated since Python 3.8, "
+            "and scheduled for removal in Python 3.10.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
     inner = asyncio.ensure_future(arg, loop=loop)
     if inner.done():
         # Shortcut.
@@ -162,6 +357,7 @@ def shield(arg: Awaitable[T], *, loop: Optional[asyncio.AbstractEventLoop] = Non
     # special handling to connect SmartFutures to SmartTasks if enabled
     if (waiters := getattr(inner, "_waiters", None)) is not None:
         waiters.add(outer)
+
     def _inner_done_callback(inner):
         if outer.cancelled():
             if not inner.cancelled():
@@ -187,4 +383,11 @@ def shield(arg: Awaitable[T], *, loop: Optional[asyncio.AbstractEventLoop] = Non
     return outer
 
 
-__all__ = ["create_future", "shield", "SmartFuture", "SmartTask", "smart_task_factory", "set_smart_task_factory"]
+__all__ = [
+    "create_future",
+    "shield",
+    "SmartFuture",
+    "SmartTask",
+    "smart_task_factory",
+    "set_smart_task_factory",
+]