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

a_sync/exceptions.py

@@ -15,27 +15,40 @@ class ASyncFlagException(ValueError):
     """
     Base exception class for flag-related errors in the a_sync library.
     """
-    @property
-    def viable_flags(self) -> Set[str]:
-        """
-        Returns the set of viable flags.
-        """
-        return VIABLE_FLAGS
+
+    viable_flags = VIABLE_FLAGS
+    """
+    The set of viable flags.
+
+    A-Sync uses 'flags' to indicate whether objects / fn calls will be sync or async.
+    You can use any of the provided flags, whichever makes most sense for your use case.
+    """
 
     def desc(self, target) -> str:
-        if target == 'kwargs':
+        """
+        Returns a description of the target for the flag error message.
+
+        Args:
+            target: The target object or string to describe.
+
+        Returns:
+            A string description of the target.
+        """
+        if target == "kwargs":
             return "flags present in 'kwargs'"
         else:
-            return f'flag attributes defined on {target}'
+            return f"flag attributes defined on {target}"
+
 
 class NoFlagsFound(ASyncFlagException):
     """
     Raised when no viable flags are found in the target.
     """
+
     def __init__(self, target, kwargs_keys=None):
         """
         Initializes the NoFlagsFound exception.
-        
+
         Args:
             target: The target object where flags were expected.
             kwargs_keys: Optional; keys in the kwargs if applicable.
@@ -47,14 +60,16 @@ class NoFlagsFound(ASyncFlagException):
         err += "\nThis is likely an issue with a custom subclass definition."
         super().__init__(err)
 
+
 class TooManyFlags(ASyncFlagException):
     """
     Raised when multiple flags are found, but only one was expected.
     """
+
     def __init__(self, target, present_flags):
         """
         Initializes the TooManyFlags exception.
-        
+
         Args:
             target: The target object where flags were found.
             present_flags: The flags that were found.
@@ -64,14 +79,16 @@ class TooManyFlags(ASyncFlagException):
         err += "This is likely an issue with a custom subclass definition."
         super().__init__(err)
 
+
 class InvalidFlag(ASyncFlagException):
     """
     Raised when an invalid flag is encountered.
     """
+
     def __init__(self, flag: Optional[str]):
         """
         Initializes the InvalidFlag exception.
-        
+
         Args:
             flag: The invalid flag.
         """
@@ -79,28 +96,32 @@ class InvalidFlag(ASyncFlagException):
         err += "\nThis code should not be reached and likely indicates an issue with a custom subclass definition."
         super().__init__(err)
 
+
 class InvalidFlagValue(ASyncFlagException):
     """
     Raised when a flag has an invalid value.
     """
+
     def __init__(self, flag: str, flag_value: Any):
         """
         Initializes the InvalidFlagValue exception.
-        
+
         Args:
             flag: The flag with an invalid value.
             flag_value: The invalid value of the flag.
         """
         super().__init__(f"'{flag}' should be boolean. You passed {flag_value}.")
 
+
 class FlagNotDefined(ASyncFlagException):
     """
     Raised when a flag is not defined on an object.
     """
+
     def __init__(self, obj: Type, flag: str):
         """
         Initializes the FlagNotDefined exception.
-        
+
         Args:
             obj: The object where the flag is not defined.
             flag: The undefined flag.
@@ -113,47 +134,62 @@ class ImproperFunctionType(ValueError):
     Raised when a function that should be sync is async or vice-versa.
     """
 
+
 class FunctionNotAsync(ImproperFunctionType):
     """
     Raised when a function expected to be async is not.
     """
+
     def __init__(self, fn):
         """
         Initializes the FunctionNotAsync exception.
-        
+
         Args:
             fn: The function that is not async.
         """
-        super().__init__(f"`coro_fn` must be a coroutine function defined with `async def`. You passed {fn}.")
+        super().__init__(
+            f"`coro_fn` must be a coroutine function defined with `async def`. You passed {fn}."
+        )
+
 
 class FunctionNotSync(ImproperFunctionType):
     """
     Raised when a function expected to be sync is not.
     """
+
     def __init__(self, fn):
         """
         Initializes the FunctionNotSync exception.
-        
+
         Args:
             fn: The function that is not sync.
         """
-        super().__init__(f"`func` must be a coroutine function defined with `def`. You passed {fn}.")
-        
+        super().__init__(
+            f"`func` must be a coroutine function defined with `def`. You passed {fn}."
+        )
+
+
 class ASyncRuntimeError(RuntimeError):
+    """
+    Raised for runtime errors in asynchronous operations.
+    """
+
     def __init__(self, e: RuntimeError):
         """
         Initializes the ASyncRuntimeError exception.
-        
+
         Args:
             e: The original runtime error.
         """
         super().__init__(str(e))
 
+
 class SyncModeInAsyncContextError(ASyncRuntimeError):
     """
     Raised when synchronous code is used within an asynchronous context.
     """
-    def __init__(self, err: str = ''):
+
+    def __init__(self, err: str = ""):
         """
         Initializes the SyncModeInAsyncContextError exception.
         """
@@ -163,16 +199,18 @@ class SyncModeInAsyncContextError(ASyncRuntimeError):
             err += f"{VIABLE_FLAGS}"
         super().__init__(err)
 
+
 class MappingError(Exception):
     """
     Base class for errors related to :class:`~TaskMapping`.
     """
+
     _msg: str
 
-    def __init__(self, mapping: "TaskMapping", msg: str = ''):
+    def __init__(self, mapping: "TaskMapping", msg: str = ""):
         """
         Initializes the MappingError exception.
-        
+
         Args:
             mapping: The TaskMapping where the error occurred.
             msg: An optional message describing the error.
@@ -183,25 +221,42 @@ class MappingError(Exception):
         super().__init__(msg)
         self.mapping = mapping
 
+
 class MappingIsEmptyError(MappingError):
     """
     Raised when a TaskMapping is empty and an operation requires it to have items.
     """
+
     _msg = "TaskMapping does not contain anything to yield"
 
+
 class MappingNotEmptyError(MappingError):
     """
     Raised when a TaskMapping is not empty and an operation requires it to be empty.
     """
+
     _msg = "TaskMapping already contains some data. In order to use `map`, you need a fresh one"
 
+
 class PersistedTaskException(Exception):
+    """
+    Raised when an exception persists in an asyncio Task.
+    """
+
     def __init__(self, exc: E, task: asyncio.Task) -> None:
+        """
+        Initializes the PersistedTaskException exception.
+
+        Args:
+            exc: The exception that persisted.
+            task: The asyncio Task where the exception occurred.
+        """
         super().__init__(f"{exc.__class__.__name__}: {exc}", task)
         self.exception = exc
         self.task = task
 
+
 class EmptySequenceError(ValueError):
     """
-    Raised when an operation is attempted on an empty sequence but items are expected.
+    Raised when an operation is attempted on an empty sequence but items are required.
     """

a_sync/executor.py

@@ -1,13 +1,13 @@
 """
 With these executors, you can simply run sync functions in your executor with `await executor.run(fn, *args)`.
 
-`executor.submit(fn, *args)` will work the same as the concurrent.futures implementation, but will return an asyncio.Future instead of a concurrent.futures.Future
+`executor.submit(fn, *args)` will work the same as the concurrent.futures implementation, but will return an asyncio.Future instead of a concurrent.futures.Future.
 
 This module provides several executor classes:
-- _AsyncExecutorMixin: A mixin providing asynchronous run and submit methods.
+- _AsyncExecutorMixin: A mixin providing asynchronous run and submit methods, with support for synchronous mode.
 - AsyncProcessPoolExecutor: An async process pool executor.
 - AsyncThreadPoolExecutor: An async thread pool executor.
-- PruningThreadPoolExecutor: A thread pool executor that prunes inactive threads after a timeout.
+- PruningThreadPoolExecutor: A thread pool executor that prunes inactive threads after a timeout, ensuring at least one thread remains active.
 """
 
 import asyncio
@@ -27,42 +27,45 @@ TEN_MINUTES = 60 * 10
 
 Initializer = Callable[..., object]
 
+
 class _AsyncExecutorMixin(cf.Executor, _DebugDaemonMixin):
     """
     A mixin for Executors to provide asynchronous run and submit methods.
     """
+
     _max_workers: int
+
     _workers: str
+    """The type of workers used."""
+
     __slots__ = "_max_workers", "_initializer", "_initargs", "_broken", "_shutdown_lock"
 
-    async def run(self, fn: Callable[P, T], *args: P.args, **kwargs: P.kwargs) -> T:
+    async def run(self, fn: Callable[P, T], *args: P.args, **kwargs: P.kwargs):
         """
-        A shorthand way to call `await asyncio.get_event_loop().run_in_executor(this_executor, fn, *args)`
+        A shorthand way to call `await asyncio.get_event_loop().run_in_executor(this_executor, fn, *args)`.
         Doesn't `await this_executor.run(fn, *args)` look so much better?
-        
+
         Oh, and you can also use kwargs!
 
         Args:
-            fn (Callable[P, T]): The function to run.
+            fn: The function to run.
             *args: Positional arguments for the function.
             **kwargs: Keyword arguments for the function.
-
-        Returns:
-            T: The result of the function.
         """
-        return fn(*args, **kwargs) if self.sync_mode else await self.submit(fn, *args, **kwargs)
+        return (
+            fn(*args, **kwargs)
+            if self.sync_mode
+            else await self.submit(fn, *args, **kwargs)
+        )
 
     def submit(self, fn: Callable[P, T], *args: P.args, **kwargs: P.kwargs) -> "asyncio.Future[T]":  # type: ignore [override]
         """
         Submits a job to the executor and returns an asyncio.Future that can be awaited for the result without blocking.
 
         Args:
-            fn (Callable[P, T]): The function to submit.
+            fn: The function to submit.
             *args: Positional arguments for the function.
             **kwargs: Keyword arguments for the function.
-
-        Returns:
-            asyncio.Future[T]: The future representing the result of the function.
         """
         if self.sync_mode:
             fut = asyncio.get_event_loop().create_future()
@@ -86,9 +89,6 @@ class _AsyncExecutorMixin(cf.Executor, _DebugDaemonMixin):
     def sync_mode(self) -> bool:
         """
         Indicates if the executor is in synchronous mode (max_workers == 0).
-
-        Returns:
-            bool: True if in synchronous mode, False otherwise.
         """
         return self._max_workers == 0
 
@@ -96,9 +96,6 @@ class _AsyncExecutorMixin(cf.Executor, _DebugDaemonMixin):
     def worker_count_current(self) -> int:
         """
         Returns the current number of workers.
-
-        Returns:
-            int: The current number of workers.
         """
         return len(getattr(self, f"_{self._workers}"))
 
@@ -107,14 +104,14 @@ class _AsyncExecutorMixin(cf.Executor, _DebugDaemonMixin):
         Runs until manually cancelled by the finished work item.
 
         Args:
-            fut (asyncio.Future): The future being debugged.
+            fut: The future being debugged.
             fn: The function being executed.
             *args: Positional arguments for the function.
             **kwargs: Keyword arguments for the function.
         """
         # TODO: make prettier strings for other types
         if type(fn).__name__ == "function":
-            fnid = getattr(fn, '__qualname__', fn.__name__)
+            fnid = getattr(fn, "__qualname__", fn.__name__)
             if fn.__module__:
                 fnid = f"{fn.__module__}.{fnid}"
         else:
@@ -125,27 +122,44 @@ class _AsyncExecutorMixin(cf.Executor, _DebugDaemonMixin):
             msg = f"{msg[:-1]} {', '.join(f'{k}={v}' for k, v in kwargs.items())})"
         else:
             msg = f"{msg[:-2]})"
-        
+
         while not fut.done():
             await asyncio.sleep(15)
             if not fut.done():
                 self.logger.debug(msg, self, fnid)
-    
+
+
 # Process
 
+
 class AsyncProcessPoolExecutor(_AsyncExecutorMixin, cf.ProcessPoolExecutor):
     """
     An async process pool executor that allows use of kwargs.
+
+    Attributes:
+        _workers:
     """
+
     _workers = "processes"
-    __slots__ = ("_mp_context", "_processes", "_pending_work_items", "_call_queue", "_result_queue",
-                 "_queue_management_thread", "_queue_count", "_shutdown_thread", "_work_ids",
-                 "_queue_management_thread_wakeup")
+    """The type of workers used, set to "processes"."""
+
+    __slots__ = (
+        "_mp_context",
+        "_processes",
+        "_pending_work_items",
+        "_call_queue",
+        "_result_queue",
+        "_queue_management_thread",
+        "_queue_count",
+        "_shutdown_thread",
+        "_work_ids",
+        "_queue_management_thread_wakeup",
+    )
 
     def __init__(
-        self, 
-        max_workers: Optional[int] = None, 
-        mp_context: Optional[multiprocessing.context.BaseContext] = None, 
+        self,
+        max_workers: Optional[int] = None,
+        mp_context: Optional[multiprocessing.context.BaseContext] = None,
         initializer: Optional[Initializer] = None,
         initargs: Tuple[Any, ...] = (),
     ) -> None:
@@ -153,10 +167,10 @@ class AsyncProcessPoolExecutor(_AsyncExecutorMixin, cf.ProcessPoolExecutor):
         Initializes the AsyncProcessPoolExecutor.
 
         Args:
-            max_workers (Optional[int], optional): The maximum number of workers. Defaults to None.
-            mp_context (Optional[multiprocessing.context.BaseContext], optional): The multiprocessing context. Defaults to None.
-            initializer (Optional[Initializer], optional): An initializer callable. Defaults to None.
-            initargs (Tuple[Any, ...], optional): Arguments for the initializer. Defaults to ().
+            max_workers: The maximum number of workers. Defaults to None.
+            mp_context: The multiprocessing context. Defaults to None.
+            initializer: An initializer callable. Defaults to None.
+            initargs: Arguments for the initializer. Defaults to ().
         """
         if max_workers == 0:
             super().__init__(1, mp_context, initializer, initargs)
@@ -164,19 +178,30 @@ class AsyncProcessPoolExecutor(_AsyncExecutorMixin, cf.ProcessPoolExecutor):
         else:
             super().__init__(max_workers, mp_context, initializer, initargs)
 
+
 # Thread
 
+
 class AsyncThreadPoolExecutor(_AsyncExecutorMixin, cf.ThreadPoolExecutor):
     """
     An async thread pool executor that allows use of kwargs.
     """
+
     _workers = "threads"
-    __slots__ = "_work_queue", "_idle_semaphore", "_threads", "_shutdown", "_thread_name_prefix"
+    """The type of workers used, set to "threads"."""
+
+    __slots__ = (
+        "_work_queue",
+        "_idle_semaphore",
+        "_threads",
+        "_shutdown",
+        "_thread_name_prefix",
+    )
 
     def __init__(
-        self, 
-        max_workers: Optional[int] = None, 
-        thread_name_prefix: str = '', 
+        self,
+        max_workers: Optional[int] = None,
+        thread_name_prefix: str = "",
         initializer: Optional[Initializer] = None,
         initargs: Tuple[Any, ...] = (),
     ) -> None:
@@ -184,24 +209,28 @@ class AsyncThreadPoolExecutor(_AsyncExecutorMixin, cf.ThreadPoolExecutor):
         Initializes the AsyncThreadPoolExecutor.
 
         Args:
-            max_workers (Optional[int], optional): The maximum number of workers. Defaults to None.
-            thread_name_prefix (str, optional): Prefix for thread names. Defaults to ''.
-            initializer (Optional[Initializer], optional): An initializer callable. Defaults to None.
-            initargs (Tuple[Any, ...], optional): Arguments for the initializer. Defaults to ().
+            max_workers: The maximum number of workers. Defaults to None.
+            thread_name_prefix: Prefix for thread names. Defaults to ''.
+            initializer: An initializer callable. Defaults to None.
+            initargs: Arguments for the initializer. Defaults to ().
         """
         if max_workers == 0:
             super().__init__(1, thread_name_prefix, initializer, initargs)
             self._max_workers = 0
         else:
             super().__init__(max_workers, thread_name_prefix, initializer, initargs)
-    
+
+
 # For backward-compatibility
 ProcessPoolExecutor = AsyncProcessPoolExecutor
 ThreadPoolExecutor = AsyncThreadPoolExecutor
 
 # Pruning thread pool
 
-def _worker(executor_reference, work_queue, initializer, initargs, timeout):  # NOTE: NEW 'timeout'
+
+def _worker(
+    executor_reference, work_queue, initializer, initargs, timeout
+):  # NOTE: NEW 'timeout'
     """
     Worker function for the PruningThreadPoolExecutor.
 
@@ -216,22 +245,21 @@ def _worker(executor_reference, work_queue, initializer, initargs, timeout):  #
         try:
             initializer(*initargs)
         except BaseException:
-            _base.LOGGER.critical('Exception in initializer:', exc_info=True)
+            _base.LOGGER.critical("Exception in initializer:", exc_info=True)
             executor = executor_reference()
             if executor is not None:
                 executor._initializer_failed()
             return
-        
+
     try:
         while True:
             try:  # NOTE: NEW
-                work_item = work_queue.get(block=True, 
-                                           timeout=timeout)  # NOTE: NEW
+                work_item = work_queue.get(block=True, timeout=timeout)  # NOTE: NEW
             except queue.Empty:  # NOTE: NEW
                 # Its been 'timeout' seconds and there are no new work items.  # NOTE: NEW
                 # Let's suicide the thread.  # NOTE: NEW
                 executor = executor_reference()  # NOTE: NEW
-                
+
                 with executor._adjusting_lock:  # NOTE: NEW
                     # NOTE: We keep a minimum of one thread active to prevent locks
                     if len(executor) > 1:  # NOTE: NEW
@@ -240,9 +268,9 @@ def _worker(executor_reference, work_queue, initializer, initargs, timeout):  #
                         thread._threads_queues.pop(t)  # NOTE: NEW
                         # Let the executor know we have one less idle thread available
                         executor._idle_semaphore.acquire(blocking=False)  # NOTE: NEW
-                        return  # NOTE: NEW 
+                        return  # NOTE: NEW
                 continue
-                
+
             if work_item is not None:
                 work_item.run()
                 # Delete references to object. See issue16284
@@ -269,34 +297,48 @@ def _worker(executor_reference, work_queue, initializer, initargs, timeout):  #
                 return
             del executor
     except BaseException:
-        _base.LOGGER.critical('Exception in worker', exc_info=True)
+        _base.LOGGER.critical("Exception in worker", exc_info=True)
+
 
 class PruningThreadPoolExecutor(AsyncThreadPoolExecutor):
     """
     This `AsyncThreadPoolExecutor` implementation prunes inactive threads after 'timeout' seconds without a work item.
     Pruned threads will be automatically recreated as needed for future workloads. Up to 'max_threads' can be active at any one time.
+    A minimum of one thread will remain active to prevent locks.
     """
+
     __slots__ = "_timeout", "_adjusting_lock"
 
-    def __init__(self, max_workers=None, thread_name_prefix='',
-                 initializer=None, initargs=(), timeout=TEN_MINUTES):
+    def __init__(
+        self,
+        max_workers=None,
+        thread_name_prefix="",
+        initializer=None,
+        initargs=(),
+        timeout=TEN_MINUTES,
+    ):
         """
         Initializes the PruningThreadPoolExecutor.
 
         Args:
-            max_workers (Optional[int], optional): The maximum number of workers. Defaults to None.
-            thread_name_prefix (str, optional): Prefix for thread names. Defaults to ''.
-            initializer (Optional[Initializer], optional): An initializer callable. Defaults to None.
-            initargs (Tuple[Any, ...], optional): Arguments for the initializer. Defaults to ().
-            timeout (int, optional): Timeout duration for pruning inactive threads. Defaults to TEN_MINUTES.
+            max_workers: The maximum number of workers. Defaults to None.
+            thread_name_prefix: Prefix for thread names. Defaults to ''.
+            initializer: An initializer callable. Defaults to None.
+            initargs: Arguments for the initializer. Defaults to ().
+            timeout: Timeout duration for pruning inactive threads. Defaults to TEN_MINUTES.
         """
-        self._timeout=timeout
+
+        self._timeout = timeout
+        """Timeout duration for pruning inactive threads."""
+
         self._adjusting_lock = threading.Lock()
+        """Lock used to adjust the number of threads."""
+
         super().__init__(max_workers, thread_name_prefix, initializer, initargs)
-    
+
     def __len__(self) -> int:
         return len(self._threads)
-        
+
     def _adjust_thread_count(self):
         """
         Adjusts the number of threads based on workload and idle threads.
@@ -313,19 +355,24 @@ class PruningThreadPoolExecutor(AsyncThreadPoolExecutor):
 
             num_threads = len(self._threads)
             if num_threads < self._max_workers:
-                thread_name = '%s_%d' % (self._thread_name_prefix or self,
-                                         num_threads)
-                t = threading.Thread(name=thread_name, target=_worker,
-                                     args=(weakref.ref(self, weakref_cb),
-                                           self._work_queue,
-                                           self._initializer,
-                                           self._initargs,
-                                           self._timeout))
+                thread_name = "%s_%d" % (self._thread_name_prefix or self, num_threads)
+                t = threading.Thread(
+                    name=thread_name,
+                    target=_worker,
+                    args=(
+                        weakref.ref(self, weakref_cb),
+                        self._work_queue,
+                        self._initializer,
+                        self._initargs,
+                        self._timeout,
+                    ),
+                )
                 t.daemon = True
                 t.start()
                 self._threads.add(t)
                 thread._threads_queues[t] = self._work_queue
 
+
 executor = PruningThreadPoolExecutor(128)
 
 __all__ = [