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

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,62 @@ 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!
+
+        In synchronous mode, the function is executed directly in the current thread.
+        In asynchronous mode, the function is submitted to the executor and awaited.
 
         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.
+        Examples:
+            >>> async def example():
+            >>>     result = await executor.run(some_function, arg1, arg2, kwarg1=value1)
+            >>>     print(result)
+
+        See Also:
+            - :meth:`submit` for submitting functions to the executor.
         """
-        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.
+        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.
+        Examples:
+            >>> future = executor.submit(some_function, arg1, arg2, kwarg1=value1)
+            >>> result = await future
+            >>> print(result)
+
+        See Also:
+            - :meth:`run` for running functions with the executor.
         """
         if self.sync_mode:
             fut = asyncio.get_event_loop().create_future()
@@ -87,8 +107,9 @@ class _AsyncExecutorMixin(cf.Executor, _DebugDaemonMixin):
         """
         Indicates if the executor is in synchronous mode (max_workers == 0).
 
-        Returns:
-            bool: True if in synchronous mode, False otherwise.
+        Examples:
+            >>> if executor.sync_mode:
+            >>>     print("Executor is in synchronous mode.")
         """
         return self._max_workers == 0
 
@@ -97,8 +118,8 @@ class _AsyncExecutorMixin(cf.Executor, _DebugDaemonMixin):
         """
         Returns the current number of workers.
 
-        Returns:
-            int: The current number of workers.
+        Examples:
+            >>> print(f"Current worker count: {executor.worker_count_current}")
         """
         return len(getattr(self, f"_{self._workers}"))
 
@@ -107,14 +128,17 @@ 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.
+
+        See Also:
+            - :meth:`_start_debug_daemon` to start the debug daemon.
         """
         # 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 +149,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 +194,15 @@ 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 ().
+
+        Examples:
+            >>> executor = AsyncProcessPoolExecutor(max_workers=4)
+            >>> future = executor.submit(some_function, arg1, arg2)
+            >>> result = await future
         """
         if max_workers == 0:
             super().__init__(1, mp_context, initializer, initargs)
@@ -164,19 +210,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 +241,33 @@ 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 ().
+
+        Examples:
+            >>> executor = AsyncThreadPoolExecutor(max_workers=10, thread_name_prefix="MyThread")
+            >>> future = executor.submit(some_function, arg1, arg2)
+            >>> result = await future
         """
         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.
 
@@ -211,27 +277,29 @@ def _worker(executor_reference, work_queue, initializer, initargs, timeout):  #
         initializer: The initializer function.
         initargs: Arguments for the initializer.
         timeout: Timeout duration for pruning inactive threads.
+
+    See Also:
+        - :class:`PruningThreadPoolExecutor` for more details on thread pruning.
     """
     if initializer is not None:
         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 +308,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,37 +337,59 @@ 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.
+
+        Examples:
+            >>> executor = PruningThreadPoolExecutor(max_workers=5, timeout=300)
+            >>> future = executor.submit(some_function, arg1, arg2)
+            >>> result = await future
         """
-        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.
+
+        See Also:
+            - :func:`_worker` for the worker function that handles thread pruning.
         """
         with self._adjusting_lock:
             # if idle threads are available, don't spin new threads
@@ -313,19 +403,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__ = [