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

a_sync/ENVIRONMENT_VARIABLES.py

@@ -1,4 +1,3 @@
-
 from typed_envs import EnvVarFactory
 
 envs = EnvVarFactory("EZASYNC")
@@ -6,7 +5,9 @@ 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)
 
 # 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 = envs.create_env(
+    "DEBUG_MODE", bool, default=DEBUG_CLASS_NAME, verbose=False
+)

a_sync/__init__.py

@@ -1,8 +1,35 @@
+"""
+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:
+- `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.
+
+Alias for backward compatibility:
+- `ASyncBase` is an alias for `ASyncGenericBase`, which will be removed eventually, probably in version 0.1.0.
+"""
 
 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 +56,13 @@ __all__ = [
     "exceptions",
     "iter",
     "task",
-
     # builtins
     "sorted",
     "filter",
-
     # asyncio
     "create_task",
-    "gather", 
+    "gather",
     "as_completed",
-
     # functions
     "a_sync",
     "all",
@@ -47,33 +71,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,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.
+"""
 
 import asyncio
 import logging
@@ -17,11 +22,22 @@ _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.
+        """
         if self.done():
             return self.result()  # May raise too.
         self._asyncio_future_blocking = True
@@ -32,33 +48,64 @@ 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.
+        """
         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
+        """
         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 _SmartFutureMixin and asyncio.Future, providing additional functionality
+    for tracking waiters and integrating with a smart processing queue.
+    """
+
     _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.
+        """
         super().__init__(loop=loop)
         if queue:
             self._queue = weakref.proxy(queue)
@@ -66,55 +113,94 @@ 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.
+
+        Returns:
+            True if self has more waiters than other.
+        """
         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 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.
+    """
     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 _SmartFutureMixin and asyncio.Task, providing additional functionality
+    for tracking waiters and integrating with a smart processing queue.
+    """
+
     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.
+        """
         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.
     """
     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.
     """
@@ -122,7 +208,10 @@ def set_smart_task_factory(loop: asyncio.AbstractEventLoop = None) -> 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 +237,18 @@ 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.
     """
     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 +258,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 +284,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",
+]

a_sync/_typing.py

@@ -7,16 +7,47 @@ to enhance type checking and provide better IDE support.
 import asyncio
 from concurrent.futures._base import Executor
 from decimal import Decimal
-from typing import (TYPE_CHECKING, Any, AsyncGenerator, AsyncIterable, AsyncIterator, 
-                    Awaitable, Callable, Coroutine, DefaultDict, Deque, Dict, Generator, 
-                    Generic, ItemsView, Iterable, Iterator, KeysView, List, Literal,
-                    Mapping, NoReturn, Optional, Protocol, Set, Tuple, Type, TypedDict,
-                    TypeVar, Union, ValuesView, final, overload, runtime_checkable)
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    AsyncGenerator,
+    AsyncIterable,
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    Coroutine,
+    DefaultDict,
+    Deque,
+    Dict,
+    Generator,
+    Generic,
+    ItemsView,
+    Iterable,
+    Iterator,
+    KeysView,
+    List,
+    Literal,
+    Mapping,
+    NoReturn,
+    Optional,
+    Protocol,
+    Set,
+    Tuple,
+    Type,
+    TypedDict,
+    TypeVar,
+    Union,
+    ValuesView,
+    final,
+    overload,
+    runtime_checkable,
+)
 
 from typing_extensions import Concatenate, ParamSpec, Self, Unpack
 
 if TYPE_CHECKING:
     from a_sync import ASyncGenericBase
+
     B = TypeVar("B", bound=ASyncGenericBase)
 else:
     B = TypeVar("B")
@@ -27,7 +58,7 @@ V = TypeVar("V")
 I = TypeVar("I")
 """A :class:`TypeVar` that is used to represent instances of a common class."""
 
-E = TypeVar('E', bound=Exception)
+E = TypeVar("E", bound=Exception)
 TYPE = TypeVar("TYPE", bound=Type)
 
 P = ParamSpec("P")
@@ -51,6 +82,7 @@ SyncFn = Callable[P, T]
 AnyFn = Union[CoroFn[P, T], SyncFn[P, T]]
 "Type alias for any function, whether synchronous or asynchronous."
 
+
 class CoroBoundMethod(Protocol[I, P, T]):
     """
     Protocol for coroutine bound methods.
@@ -59,13 +91,15 @@ class CoroBoundMethod(Protocol[I, P, T]):
         class MyClass:
             async def my_method(self, x: int) -> str:
                 return str(x)
-        
+
         instance = MyClass()
         bound_method: CoroBoundMethod[MyClass, [int], str] = instance.my_method
     """
+
     __self__: I
     __call__: Callable[P, Awaitable[T]]
 
+
 class SyncBoundMethod(Protocol[I, P, T]):
     """
     Protocol for synchronous bound methods.
@@ -74,36 +108,43 @@ class SyncBoundMethod(Protocol[I, P, T]):
         class MyClass:
             def my_method(self, x: int) -> str:
                 return str(x)
-        
+
         instance = MyClass()
         bound_method: SyncBoundMethod[MyClass, [int], str] = instance.my_method
     """
+
     __self__: I
     __call__: Callable[P, T]
 
+
 AnyBoundMethod = Union[CoroBoundMethod[Any, P, T], SyncBoundMethod[Any, P, T]]
 "Type alias for any bound method, whether synchronous or asynchronous."
 
+
 @runtime_checkable
 class AsyncUnboundMethod(Protocol[I, P, T]):
     """
     Protocol for unbound asynchronous methods.
-    
+
     An unbound method is a method that hasn't been bound to an instance of a class yet.
     It's essentially the function object itself, before it's accessed through an instance.
     """
+
     __get__: Callable[[I, Type], CoroBoundMethod[I, P, T]]
 
+
 @runtime_checkable
 class SyncUnboundMethod(Protocol[I, P, T]):
     """
     Protocol for unbound synchronous methods.
-    
+
     An unbound method is a method that hasn't been bound to an instance of a class yet.
     It's essentially the function object itself, before it's accessed through an instance.
     """
+
     __get__: Callable[[I, Type], SyncBoundMethod[I, P, T]]
 
+
 AnyUnboundMethod = Union[AsyncUnboundMethod[I, P, T], SyncUnboundMethod[I, P, T]]
 "Type alias for any unbound method, whether synchronous or asynchronous."
 
@@ -122,19 +163,21 @@ AsyncDecorator = Callable[[CoroFn[P, T]], CoroFn[P, T]]
 AsyncDecoratorOrCoroFn = Union[AsyncDecorator[P, T], CoroFn[P, T]]
 "Type alias for either an asynchronous decorator or a coroutine function."
 
-DefaultMode = Literal['sync', 'async', None]
+DefaultMode = Literal["sync", "async", None]
 "Type alias for default modes of operation."
 
-CacheType = Literal['memory', None]
+CacheType = Literal["memory", None]
 "Type alias for cache types."
 
 SemaphoreSpec = Optional[Union[asyncio.Semaphore, int]]
 "Type alias for semaphore specifications."
 
+
 class ModifierKwargs(TypedDict, total=False):
     """
     TypedDict for keyword arguments that modify the behavior of asynchronous operations.
     """
+
     default: DefaultMode
     cache_type: CacheType
     cache_typed: bool
@@ -145,6 +188,7 @@ class ModifierKwargs(TypedDict, total=False):
     # sync modifiers
     executor: Executor
 
+
 AnyIterable = Union[AsyncIterable[K], Iterable[K]]
 "Type alias for any iterable, whether synchronous or asynchronous."
 

a_sync/a_sync/__init__.py

@@ -1,13 +1,38 @@
+"""
+This module enables developers to write both synchronous and asynchronous code without having to write redundant code. 
+
+The two main objects you should use are
+    - a decorator `@a_sync()`
+    - a base class `ASyncGenericBase` which can be used to create classes that can be utilized in both synchronous and asynchronous contexts.
+
+The rest of the objects are exposed for type checking only, you should not make use of them otherwise.
+"""
+
+# TODO: double check on these before adding them to docs
+# - two decorators @:class:`property` and @:class:`cached_property` for the creation of dual-function properties and cached properties, respectively.
 
 from a_sync.a_sync.base import ASyncGenericBase
 from a_sync.a_sync.decorator import a_sync
-from a_sync.a_sync.function import ASyncFunction, ASyncFunctionAsyncDefault, ASyncFunctionSyncDefault
+from a_sync.a_sync.function import (
+    ASyncFunction,
+    ASyncFunctionAsyncDefault,
+    ASyncFunctionSyncDefault,
+)
 from a_sync.a_sync.modifiers.semaphores import apply_semaphore
+
 # NOTE: Some of these we purposely import without including in __all__. Do not remove.
-from a_sync.a_sync.property import (ASyncCachedPropertyDescriptor, ASyncCachedPropertyDescriptorAsyncDefault,
-                                    ASyncCachedPropertyDescriptorSyncDefault, ASyncPropertyDescriptor, 
-                                    ASyncPropertyDescriptorAsyncDefault, ASyncPropertyDescriptorSyncDefault, 
-                                    HiddenMethod, HiddenMethodDescriptor, cached_property, property)
+from a_sync.a_sync.property import (
+    ASyncCachedPropertyDescriptor,
+    ASyncCachedPropertyDescriptorAsyncDefault,
+    ASyncCachedPropertyDescriptorSyncDefault,
+    ASyncPropertyDescriptor,
+    ASyncPropertyDescriptorAsyncDefault,
+    ASyncPropertyDescriptorSyncDefault,
+    HiddenMethod,
+    HiddenMethodDescriptor,
+    cached_property,
+    property,
+)
 from a_sync.a_sync.singleton import ASyncGenericSingleton
 
 
@@ -15,14 +40,14 @@ __all__ = [
     # entrypoints
     "a_sync",
     "ASyncGenericBase",
-
-    # classes
-    "ASyncFunction",
-
+    # maybe entrypoints (?)
+    # TODO: double check how I intended for these to be used
     "property",
     "cached_property",
+    # classes exposed for type hinting only
+    "ASyncFunction",
     "ASyncPropertyDescriptor",
     "ASyncCachedPropertyDescriptor",
     "HiddenMethod",
     "HiddenMethodDescriptor",
-]
+]