flexexecutor 0.0.8__tar.gz → 0.0.10__tar.gz

flexexecutor-0.0.10/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.1
+Name: flexexecutor
+Version: 0.0.10
+Summary: Executors for both async and sync functions and automatically scales the number of workers
+Home-page: https://github.com/leavers/flexexecutor
+Author: leavers
+Author-Email: Leavers <leavers930@gmail.com>
+License: MIT
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Project-URL: Homepage, https://github.com/leavers/flexexecutor
+Project-URL: Documentation, https://github.com/leavers/flexexecutor/blob/main/README.md
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Flexexecutor
+
+[![Testing](https://github.com/leavers/flexexecutor/workflows/Test%20Suite/badge.svg)](https://github.com/leavers/flexexecutor/actions)
+[![Package version](https://img.shields.io/pypi/v/flexexecutor.svg)](https://pypi.org/project/flexexecutor/)
+[![Python](https://img.shields.io/pypi/pyversions/flexexecutor.svg)](https://pypi.org/project/flexexecutor/)
+
+Flexexecutor provides executors that can automatically scale the number of workers up
+and down.
+
+## Overview
+
+Flexexecutor implements several subclasses of `concurrent.futures.Executor`.
+Like the built-in `ThreadPoolExecutor` and `ProcessPoolExecutor`,
+they create multiple workers to execute tasks concurrently.
+Additionally, it can shut down idle workers to save resources. These subclasses are:
+
+- `ThreadPoolExecutor` - thread concurrency, same name as the built-in class and can
+  be a in-place replacement.
+- `AsyncPoolExecutor` - coroutine concurrency. Note that in flexexecutor's
+  implementation, all coroutines are executed in a dedicated worker thread.
+- `ProcessPoolExecutor` - flexexecutor directly imports the built-in implementation as it
+  already has scaling capabilities.
+
+## Features
+
+- Supports various concurrency modes: threads, processes and coroutines.
+- Automatically shut down idle workers to save resources.
+- Single file design, keeps the code clean and easy for hackers to directly take away
+  and add more features.
+
+## Installation
+
+Flexexecutor is available on [PyPI](https://pypi.org/project/flexexecutor/):
+
+```shell
+pip install flexexecutor
+```
+
+## Usage
+
+### ThreadPoolExecutor
+
+```python
+from flexexecutor import ThreadPoolExecutor
+
+
+def task(i):
+    import time
+
+    print(f"task {i} started")
+    time.sleep(1)
+
+if __name__ == "__main__":
+    with ThreadPoolExecutor(
+        # 1024 is the default value of max_workers, since workers are closed if they are
+        # idle for some time, you can set it to a big value to get better short-term
+        # performance.
+        max_workers=1024,
+        # Timeout for idle workers.
+        idle_timeout=60.0,
+        # These parameters are given for compatibility with the built-in
+        # `ThreadPoolExecutor`, I don't use them very often, do you?
+        thread_name_prefix="Task",
+        initializer=None,
+        initargs=(),
+    ) as executor:
+        for i in range(1024):
+            executor.submit(task, i)
+```
+
+### AsyncPoolExecutor
+
+```python
+from flexexecutor import AsyncPoolExecutor
+
+
+async def task(i):
+    import asyncio
+
+    print(f"task {i} started")
+    await asyncio.sleep(1)
+
+if __name__ == "__main__":
+    # AsyncPoolExecutor behaves just like ThreadPoolExecutor except it only accepts
+    # coroutine functions.
+    with AsyncPoolExecutor(
+        # Default value of max_workers is huge, if you don't like it, set it smaller.
+        max_workers=1024,
+        # Idle timeout for the working thread.
+        idle_timeout=60.0,
+        # These parameters are given for compatibility with the built-in
+        # `ThreadPoolExecutor`, I don't use them very often, do you?
+        thread_name_prefix="Task",
+        initializer=None,
+        initargs=(),
+    ) as executor:
+        for i in range(1024):
+            executor.submit(task, i)
+```
+
+### ProcessPoolExecutor
+
+`ProcessPoolExecutor` in flexexecutor is just the same as the built-in
+`concurrent.futures.ProcessPoolExecutor`, we just import it directly for convenience.

flexexecutor-0.0.10/README.md

@@ -0,0 +1,104 @@
+# Flexexecutor
+
+[![Testing](https://github.com/leavers/flexexecutor/workflows/Test%20Suite/badge.svg)](https://github.com/leavers/flexexecutor/actions)
+[![Package version](https://img.shields.io/pypi/v/flexexecutor.svg)](https://pypi.org/project/flexexecutor/)
+[![Python](https://img.shields.io/pypi/pyversions/flexexecutor.svg)](https://pypi.org/project/flexexecutor/)
+
+Flexexecutor provides executors that can automatically scale the number of workers up
+and down.
+
+## Overview
+
+Flexexecutor implements several subclasses of `concurrent.futures.Executor`.
+Like the built-in `ThreadPoolExecutor` and `ProcessPoolExecutor`,
+they create multiple workers to execute tasks concurrently.
+Additionally, it can shut down idle workers to save resources. These subclasses are:
+
+- `ThreadPoolExecutor` - thread concurrency, same name as the built-in class and can
+  be a in-place replacement.
+- `AsyncPoolExecutor` - coroutine concurrency. Note that in flexexecutor's
+  implementation, all coroutines are executed in a dedicated worker thread.
+- `ProcessPoolExecutor` - flexexecutor directly imports the built-in implementation as it
+  already has scaling capabilities.
+
+## Features
+
+- Supports various concurrency modes: threads, processes and coroutines.
+- Automatically shut down idle workers to save resources.
+- Single file design, keeps the code clean and easy for hackers to directly take away
+  and add more features.
+
+## Installation
+
+Flexexecutor is available on [PyPI](https://pypi.org/project/flexexecutor/):
+
+```shell
+pip install flexexecutor
+```
+
+## Usage
+
+### ThreadPoolExecutor
+
+```python
+from flexexecutor import ThreadPoolExecutor
+
+
+def task(i):
+    import time
+
+    print(f"task {i} started")
+    time.sleep(1)
+
+if __name__ == "__main__":
+    with ThreadPoolExecutor(
+        # 1024 is the default value of max_workers, since workers are closed if they are
+        # idle for some time, you can set it to a big value to get better short-term
+        # performance.
+        max_workers=1024,
+        # Timeout for idle workers.
+        idle_timeout=60.0,
+        # These parameters are given for compatibility with the built-in
+        # `ThreadPoolExecutor`, I don't use them very often, do you?
+        thread_name_prefix="Task",
+        initializer=None,
+        initargs=(),
+    ) as executor:
+        for i in range(1024):
+            executor.submit(task, i)
+```
+
+### AsyncPoolExecutor
+
+```python
+from flexexecutor import AsyncPoolExecutor
+
+
+async def task(i):
+    import asyncio
+
+    print(f"task {i} started")
+    await asyncio.sleep(1)
+
+if __name__ == "__main__":
+    # AsyncPoolExecutor behaves just like ThreadPoolExecutor except it only accepts
+    # coroutine functions.
+    with AsyncPoolExecutor(
+        # Default value of max_workers is huge, if you don't like it, set it smaller.
+        max_workers=1024,
+        # Idle timeout for the working thread.
+        idle_timeout=60.0,
+        # These parameters are given for compatibility with the built-in
+        # `ThreadPoolExecutor`, I don't use them very often, do you?
+        thread_name_prefix="Task",
+        initializer=None,
+        initargs=(),
+    ) as executor:
+        for i in range(1024):
+            executor.submit(task, i)
+```
+
+### ProcessPoolExecutor
+
+`ProcessPoolExecutor` in flexexecutor is just the same as the built-in
+`concurrent.futures.ProcessPoolExecutor`, we just import it directly for convenience.

{flexexecutor-0.0.8 → flexexecutor-0.0.10}/flexexecutor.py

@@ -1,8 +1,17 @@
+"""
+Flexexecutor provides executors that can automatically scale the number of
+workers up and down.
+
+Copyright (c) 2020-2024, Leavers.
+License: MIT
+"""
+
 import asyncio
 import atexit
 import itertools
-from concurrent.futures import ProcessPoolExecutor, _base
-from concurrent.futures import thread as _thread
+from concurrent.futures import Future, ProcessPoolExecutor, _base
+from concurrent.futures.thread import BrokenThreadPool, _WorkItem
+from concurrent.futures.thread import ThreadPoolExecutor as _ThreadPoolExecutor
 from inspect import iscoroutinefunction
 from queue import Empty
 from threading import Event, Lock, Thread
@@ -12,11 +21,13 @@ from weakref import WeakKeyDictionary, ref
 __all__ = (
     "__version__",
     "AsyncPoolExecutor",
+    "BrokenThreadPool",
+    "Future",
     "ProcessPoolExecutor",
     "ThreadPoolExecutor",
 )
 
-__version__ = "0.0.8"
+__version__ = "0.0.10"
 
 _threads_queues = WeakKeyDictionary()  # type: ignore
 _shutdown = False
@@ -44,17 +55,16 @@ def _worker(executor_ref, work_queue, initializer, initargs, idle_timeout):
         except BaseException:
             _base.LOGGER.critical("Exception in initializer:", exc_info=True)
             executor = executor_ref()
-            if executor is not None:
+            if executor is not None:  # pragma: no cover
                 executor._initializer_failed()
             return
 
-    idle_tick = monotonic()
+    idle_tick = -1.0
     try:
         while True:
-            if idle_timeout >= 0 and monotonic() - idle_tick > idle_timeout:
-                executor = executor_ref()
-                if executor is not None:
-                    executor._idle_semaphore.acquire(timeout=0)
+            if idle_tick == -1.0:
+                idle_tick = monotonic()
+            elif idle_timeout >= 0 and monotonic() - idle_tick > idle_timeout:
                 break
             try:
                 work_item = work_queue.get(block=True, timeout=0.1)
@@ -70,32 +80,80 @@ def _worker(executor_ref, work_queue, initializer, initargs, idle_timeout):
                 del executor
                 idle_tick = monotonic()
                 continue
-            executor = executor_ref()
-            if _thread._shutdown or executor is None or executor._shutdown:
-                if executor is not None:
-                    executor._shutdown = True
+            break  # pragma: no cover
+    finally:
+        executor = executor_ref()
+        if executor is None:
+            work_queue.put(None)
+        else:
+            executor._idle_semaphore.acquire(timeout=0)
+            if _shutdown or executor._shutdown:
+                executor._shutdown = True
                 work_queue.put(None)
-                return
-            del executor
-    except BaseException:
-        _base.LOGGER.critical("Exception in worker", exc_info=True)
+        del executor
 
 
-class ThreadPoolExecutor(_thread.ThreadPoolExecutor):
+class ThreadPoolExecutor(_ThreadPoolExecutor):
     def __init__(
         self,
-        max_workers=None,
+        max_workers=1024,
         thread_name_prefix="",
         initializer=None,
         initargs=(),
         idle_timeout=60.0,
     ):
+        """Initializes a new ThreadPoolExecutor instance.
+
+        :type max_workers: int, optional
+        :param max_workers: The maximum number of workers to create. Defaults to 1024.
+
+        :type thread_name_prefix: str, optional
+        :param thread_name_prefix: An optional name prefix to give our threads.
+
+        :type initializer: callable, optional
+        :param initializer: A callable used to initialize worker threads.
+
+        :type initargs: tuple, optional
+        :parm initargs: A tuple of arguments to pass to the initializer.
+
+        :type idle_timeout: float, optional
+        :param idle_timeout: The maximum amount of time (in seconds) that a worker
+            thread can remain idle before it is terminated. If set to None or negative
+            value, workers will never be terminated. Defaults to 60 seconds.
+        """
+        if max_workers is None:
+            max_workers = 1024
         super().__init__(max_workers, thread_name_prefix, initializer, initargs)
         if idle_timeout is None or idle_timeout < 0:
             self._idle_timeout = -1
         else:
             self._idle_timeout = max(0.1, idle_timeout)
 
+    def submit(self, fn, /, *args, **kwargs):
+        if iscoroutinefunction(fn):
+            raise TypeError("fn must not be a coroutine function")
+
+        with self._shutdown_lock, _global_shutdown_lock:
+            if self._broken:
+                raise BrokenThreadPool(self._broken)
+
+            if self._shutdown:
+                raise RuntimeError("cannot schedule new futures after shutdown")
+            if _shutdown:
+                # coverage didn't realize that _shutdown is set, add no cover here
+                raise RuntimeError(  # pragma: no cover
+                    "cannot schedule new futures after interpreter shutdown"
+                )
+
+            f = Future()  # type: ignore
+            w = _WorkItem(f, fn, args, kwargs)
+
+            self._work_queue.put(w)
+            self._adjust_thread_count()
+            return f
+
+    submit.__doc__ = _base.Executor.submit.__doc__
+
     def _adjust_thread_count(self):
         if self._idle_semaphore.acquire(timeout=0):
             return
@@ -125,9 +183,10 @@ class ThreadPoolExecutor(_thread.ThreadPoolExecutor):
             _threads_queues[t] = self._work_queue
 
 
-class _AsyncWorkItem(_thread._WorkItem):
+class _AsyncWorkItem(_WorkItem):
     async def run(self):
         if not self.future.set_running_or_notify_cancel():
+            print("cancelled")
             return
 
         try:
@@ -156,7 +215,7 @@ async def _async_worker(
             initializer(*initargs)
         except BaseException:
             _base.LOGGER.critical("Exception in initializer:", exc_info=True)
-            if executor is not None:
+            if executor is not None:  # pragma: no cover
                 executor._running.set()
                 executor._initializer_failed()
             return
@@ -169,43 +228,40 @@ async def _async_worker(
     try:
         while True:
             if idle_timeout >= 0 and monotonic() - idle_tick > idle_timeout:
-                executor = executor_ref()
-                if executor is not None:
-                    executor._idle_semaphore.acquire(timeout=0)
                 break
-            try:
-                work_item = work_queue.get(block=True, timeout=0.1)
-            except Empty:
-                pass
-            if work_item is not None:
-                task = loop.create_task(work_item.run())
-                curr_tasks.add(task)
-                await asleep(0)  # ugly but working
-                del work_item
-
-                finished_tasks = [t for t in curr_tasks if t.done()]
-                for t in finished_tasks:
-                    curr_tasks.remove(t)
-                if curr_tasks:
-                    idle_tick = monotonic()
-                continue
-
-            executor = executor_ref()
-            if _thread._shutdown or executor is None or executor._shutdown:
-                if executor is not None:
-                    executor._shutdown = True
-                work_queue.put(None)
-
-                for t in curr_tasks:
-                    await t
-                return
-            del executor
-    except BaseException:
-        _base.LOGGER.critical("Exception in worker", exc_info=True)
+            if len(curr_tasks) < max_workers:
+                try:
+                    work_item = work_queue.get(block=True, timeout=0.1)
+                    if work_item is not None:
+                        task = loop.create_task(work_item.run())
+                        curr_tasks.add(task)
+                        await asleep(0)
+                        del work_item
+                    else:
+                        break
+                except Empty:
+                    pass
+            await asleep(0)
+            finished_tasks = [t for t in curr_tasks if t.done()]
+            for t in finished_tasks:
+                curr_tasks.remove(t)
+            if curr_tasks:
+                idle_tick = monotonic()
     finally:
+        while curr_tasks:
+            await asleep(0)
+            finished_tasks = [t for t in curr_tasks if t.done()]
+            for t in finished_tasks:
+                curr_tasks.remove(t)
         executor = executor_ref()
-        if executor is not None:
+        if executor is None:
+            work_queue.put(None)
+        else:
             executor._running.clear()
+            if _shutdown or executor._shutdown:
+                executor._shutdown = True
+                work_queue.put(None)
+        del executor
 
 
 class AsyncWorker(Thread):
@@ -241,7 +297,7 @@ class AsyncWorker(Thread):
         )
 
 
-class AsyncPoolExecutor(_thread.ThreadPoolExecutor):
+class AsyncPoolExecutor(ThreadPoolExecutor):
     _counter = itertools.count().__next__
 
     def __init__(
@@ -252,6 +308,25 @@ class AsyncPoolExecutor(_thread.ThreadPoolExecutor):
         initargs=(),
         idle_timeout=60.0,
     ):
+        """Initializes a new AsyncPoolExecutor instance.
+
+        :type max_workers: int, optional
+        :param max_workers: The maximum number of workers to create. Defaults to 261244.
+
+        :type thread_name_prefix: str, optional
+        :param thread_name_prefix: An optional name prefix to give our threads.
+
+        :type initializer: callable, optional
+        :param initializer: A callable used to initialize worker threads.
+
+        :type initargs: tuple, optional
+        :parm initargs: A tuple of arguments to pass to the initializer.
+
+        :type idle_timeout: float, optional
+        :param idle_timeout: The maximum amount of time (in seconds) that a worker
+            thread can remain idle before it is terminated. If set to None or negative
+            value, workers will never be terminated. Defaults to 60 seconds.
+        """
         if max_workers is None:
             max_workers = 262144
         if not thread_name_prefix:
@@ -269,16 +344,17 @@ class AsyncPoolExecutor(_thread.ThreadPoolExecutor):
             raise TypeError("fn must be a coroutine function")
         with self._shutdown_lock, _global_shutdown_lock:
             if self._broken:
-                raise _thread.BrokenThreadPool(self._broken)
+                raise BrokenThreadPool(self._broken)
 
             if self._shutdown:
                 raise RuntimeError("cannot schedule new futures after shutdown")
-            if _thread._shutdown:
-                raise RuntimeError(
+            if _shutdown:
+                # coverage didn't realize that _shutdown is set, add no cover here
+                raise RuntimeError(  # pragma: no cover
                     "cannot schedule new futures after interpreter shutdown"
                 )
 
-            f = _base.Future()  # type: ignore
+            f = Future()  # type: ignore
             w = _AsyncWorkItem(f, fn, args, kwargs)
 
             self._work_queue.put(w)

flexexecutor-0.0.10/pyproject.toml

@@ -0,0 +1,107 @@
+[project]
+name = "flexexecutor"
+description = "Executors for both async and sync functions and automatically scales the number of workers"
+authors = [
+    { name = "leavers" },
+    { name = "Leavers", email = "leavers930@gmail.com" },
+]
+classifiers = [
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
+requires-python = ">=3.8"
+readme = "README.md"
+dependencies = []
+dynamic = []
+version = "0.0.10"
+
+[project.license]
+text = "MIT"
+
+[project.urls]
+homepage = "https://github.com/leavers/flexexecutor"
+documentation = "https://github.com/leavers/flexexecutor/blob/main/README.md"
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[tool.pdm]
+distribution = true
+
+[tool.pdm.build]
+includes = [
+    "flexexecutor.py",
+]
+excludes = [
+    "tests",
+]
+
+[tool.pdm.version]
+source = "file"
+path = "flexexecutor.py"
+
+[tool.pdm.dev-dependencies]
+dev = [
+    "autoflake>=2.3.1",
+    "coverage[toml]>=7.6.1",
+    "mypy>=1.11.1",
+    "nox>=2024.4.15",
+    "pytest>=8.3.2",
+    "pytest-asyncio>=0.23.8",
+    "pytest-cov>=5.0.0",
+    "pytest-mock>=3.14.0",
+    "pytest-timeout>=2.3.1",
+    "ruoml>=0.11.0",
+    "ruff>=0.6.1",
+]
+
+[tool.autoflake]
+in-place = true
+recursive = true
+remove-all-unused-imports = true
+ignore-init-module-imports = true
+remove-duplicate-keys = true
+remove-unused-variables = true
+
+[tool.coverage.run]
+branch = true
+source = [
+    "flexexecutor.py",
+]
+parallel = true
+
+[tool.coverage.html]
+directory = "coverage_html_report"
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+]
+
+[tool.ruff]
+line-length = 88
+
+[tool.mypy]
+check_untyped_defs = true
+follow_imports = "error"
+ignore_missing_imports = true
+show_error_codes = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "strict"

flexexecutor-0.0.8/.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,17 +0,0 @@
-## Expected Behavior
-
-
-## Actual Behavior
-
-
-## Steps to Reproduce the Problem
-
-  1.
-  1.
-  1.
-
-## Specifications
-
-  - Version:
-  - Platform:
-  - Subsystem:

flexexecutor-0.0.8/.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,14 +0,0 @@
-## Feature Request
-
-**Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I have an issue when [...]
-
-**Describe the solution you'd like**
-A clear and concise description of what you want to happen. Add any considered drawbacks.
-
-**Describe alternatives you've considered**
-A clear and concise description of any alternative solutions or features you've considered.
-
-**Teachability, Documentation, Adoption, Migration Strategy**
-If you can, explain how users will be able to use this and possibly write out a version the docs.
-Maybe a screenshot or design?