[//]: # (This file is part of asyncio-taskpool.)
[//]: # (asyncio-taskpool is free software: you can redistribute it and/or modify it under the terms of)
[//]: # (version 3.0 of the GNU Lesser General Public License as published by the Free Software Foundation.)
[//]: # (asyncio-taskpool is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;)
[//]: # (without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.)
[//]: # (See the GNU Lesser General Public License for more details.)
[//]: # (You should have received a copy of the GNU Lesser General Public License along with asyncio-taskpool.)
[//]: # (If not, see <https://www.gnu.org/licenses/>.)
# asyncio-taskpool
[![GitHub last commit][github-last-commit-img]][github-last-commit]
![Lines of code][gist-cloc-code-img]
![Lines of comments][gist-cloc-comments-img]
![Test coverage][gist-test-coverage-img]
[![License: LGPL v3.0][lgpl3-img]][lgpl3]
[![PyPI version][pypi-latest-version-img]][pypi-latest-version]
**Dynamically manage pools of asyncio tasks**
Full documentation available at [RtD](https://asyncio-taskpool.readthedocs.io/en/latest).
---
## Contents
- [Contents](#contents)
- [Summary](#summary)
- [Usage](#usage)
- [Installation](#installation)
- [Dependencies](#dependencies)
- [Testing](#testing)
- [License](#license)
## Summary
A **task pool** is an object with a simple interface for aggregating and dynamically managing asynchronous tasks.
With an interface that is intentionally similar to the [`multiprocessing.Pool`](https://docs.python.org/3/library/multiprocessing.html#module-multiprocessing.pool) class from the standard library, the `TaskPool` provides you such methods as `apply`, `map`, and `starmap` to execute coroutines concurrently as [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#task-object) objects. There is no limitation imposed on what kind of tasks can be run or in what combination, when new ones can be added, or when they can be cancelled.
For a more streamlined use-case, the `SimpleTaskPool` provides an even more intuitive and simple interface at the cost of flexibility.
If you need control over a task pool at runtime, you can launch an asynchronous `ControlServer` to be able to interface with the pool from an outside process or via a network, and stop/start tasks within the pool as you wish.
## Usage
Generally speaking, a task is added to a pool by providing it with a coroutine function reference as well as the arguments for that function. Here is what that could look like in the most simplified form:
```python
from asyncio_taskpool import SimpleTaskPool
...
async def work(_foo, _bar): ...
async def main():
pool = SimpleTaskPool(work, args=('xyz', 420))
pool.start(5)
...
pool.stop(3)
...
await pool.gather_and_close()
```
Since one of the main goals of `asyncio-taskpool` is to be able to start/stop tasks dynamically or "on-the-fly", _most_ of the associated methods are non-blocking _most_ of the time. A notable exception is the `gather_and_close` method for awaiting the return of all tasks in the pool. (It is essentially a glorified wrapper around the [`asyncio.gather`](https://docs.python.org/3/library/asyncio-task.html#asyncio.gather) function.)
For working and fully documented demo scripts see [USAGE.md](usage/USAGE.md).
## Installation
```shell
pip install asyncio-taskpool
```
## Dependencies
Python Version 3.8+, tested on Linux
## Testing
Install [`coverage`](https://coverage.readthedocs.io/en/latest/) with `pip`, then execute the [`./coverage.sh`](coverage.sh) shell script to run all unit tests and save the coverage report.
## License
`asyncio-taskpool` is licensed under the **GNU LGPL version 3.0** specifically.
The full license texts for the [GNU GPLv3.0](COPYING) and the [GNU LGPLv3.0](COPYING.LESSER) are included in this repository. If not, see https://www.gnu.org/licenses/.
---
© 2022 Daniil Fajnberg
[github-last-commit]: https://github.com/daniil-berg/asyncio-taskpool/commits
[github-last-commit-img]: https://img.shields.io/github/last-commit/daniil-berg/asyncio-taskpool?label=Last%20commit&logo=git&
[gist-cloc-code-img]: https://img.shields.io/endpoint?logo=python&color=blue&url=https://gist.githubusercontent.com/daniil-berg/3f8240a976e8781a765d9c74a583dcda/raw/cloc-code.json
[gist-cloc-comments-img]: https://img.shields.io/endpoint?logo=sharp&color=lightgrey&url=https://gist.githubusercontent.com/daniil-berg/3f8240a976e8781a765d9c74a583dcda/raw/cloc-comments.json
[gist-test-coverage-img]: https://img.shields.io/endpoint?logo=pytest&color=blue&url=https://gist.githubusercontent.com/daniil-berg/3f8240a976e8781a765d9c74a583dcda/raw/test-coverage.json
[lgpl3]: https://www.gnu.org/licenses/lgpl-3.0
[lgpl3-img]: https://img.shields.io/badge/License-LGPL_v3.0-darkgreen.svg?logo=gnu
[pypi-latest-version-img]: https://img.shields.io/pypi/v/asyncio-taskpool?color=teal&logo=pypi
[pypi-latest-version]: https://pypi.org/project/asyncio-taskpool/
Raw data
{
"_id": null,
"home_page": "https://git.fajnberg.de/daniil/asyncio-taskpool",
"name": "asyncio-taskpool",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "asyncio,concurrency,tasks,coroutines,asynchronous,server",
"author": "Daniil Fajnberg",
"author_email": "mail@daniil.fajnberg.de",
"download_url": "https://files.pythonhosted.org/packages/e4/dd/685b428a9aa89ee08d279eebbd26b28d524b7bffd1b14c3611997c3694c7/asyncio-taskpool-1.1.4.tar.gz",
"platform": null,
"description": "[//]: # (This file is part of asyncio-taskpool.)\n\n[//]: # (asyncio-taskpool is free software: you can redistribute it and/or modify it under the terms of)\n[//]: # (version 3.0 of the GNU Lesser General Public License as published by the Free Software Foundation.)\n\n[//]: # (asyncio-taskpool is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;)\n[//]: # (without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.)\n[//]: # (See the GNU Lesser General Public License for more details.)\n\n[//]: # (You should have received a copy of the GNU Lesser General Public License along with asyncio-taskpool.)\n[//]: # (If not, see <https://www.gnu.org/licenses/>.)\n\n# asyncio-taskpool\n\n[![GitHub last commit][github-last-commit-img]][github-last-commit]\n![Lines of code][gist-cloc-code-img]\n![Lines of comments][gist-cloc-comments-img]\n![Test coverage][gist-test-coverage-img]\n[![License: LGPL v3.0][lgpl3-img]][lgpl3]\n[![PyPI version][pypi-latest-version-img]][pypi-latest-version]\n\n**Dynamically manage pools of asyncio tasks**\n\nFull documentation available at [RtD](https://asyncio-taskpool.readthedocs.io/en/latest).\n\n---\n\n## Contents\n- [Contents](#contents)\n- [Summary](#summary)\n- [Usage](#usage)\n- [Installation](#installation)\n- [Dependencies](#dependencies)\n- [Testing](#testing)\n- [License](#license)\n\n## Summary\n\nA **task pool** is an object with a simple interface for aggregating and dynamically managing asynchronous tasks.\n\nWith an interface that is intentionally similar to the [`multiprocessing.Pool`](https://docs.python.org/3/library/multiprocessing.html#module-multiprocessing.pool) class from the standard library, the `TaskPool` provides you such methods as `apply`, `map`, and `starmap` to execute coroutines concurrently as [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#task-object) objects. There is no limitation imposed on what kind of tasks can be run or in what combination, when new ones can be added, or when they can be cancelled.\n\nFor a more streamlined use-case, the `SimpleTaskPool` provides an even more intuitive and simple interface at the cost of flexibility.\n\nIf you need control over a task pool at runtime, you can launch an asynchronous `ControlServer` to be able to interface with the pool from an outside process or via a network, and stop/start tasks within the pool as you wish.\n\n## Usage\n\nGenerally speaking, a task is added to a pool by providing it with a coroutine function reference as well as the arguments for that function. Here is what that could look like in the most simplified form:\n\n```python\nfrom asyncio_taskpool import SimpleTaskPool\n...\nasync def work(_foo, _bar): ...\n\nasync def main():\n pool = SimpleTaskPool(work, args=('xyz', 420))\n pool.start(5)\n ...\n pool.stop(3)\n ...\n await pool.gather_and_close()\n```\n\nSince one of the main goals of `asyncio-taskpool` is to be able to start/stop tasks dynamically or \"on-the-fly\", _most_ of the associated methods are non-blocking _most_ of the time. A notable exception is the `gather_and_close` method for awaiting the return of all tasks in the pool. (It is essentially a glorified wrapper around the [`asyncio.gather`](https://docs.python.org/3/library/asyncio-task.html#asyncio.gather) function.)\n\nFor working and fully documented demo scripts see [USAGE.md](usage/USAGE.md).\n\n## Installation\n\n```shell\npip install asyncio-taskpool\n```\n\n## Dependencies\n\nPython Version 3.8+, tested on Linux\n\n## Testing\n\nInstall [`coverage`](https://coverage.readthedocs.io/en/latest/) with `pip`, then execute the [`./coverage.sh`](coverage.sh) shell script to run all unit tests and save the coverage report.\n\n## License\n\n`asyncio-taskpool` is licensed under the **GNU LGPL version 3.0** specifically.\n\nThe full license texts for the [GNU GPLv3.0](COPYING) and the [GNU LGPLv3.0](COPYING.LESSER) are included in this repository. If not, see https://www.gnu.org/licenses/.\n\n---\n\n\u00a9 2022 Daniil Fajnberg\n\n[github-last-commit]: https://github.com/daniil-berg/asyncio-taskpool/commits\n[github-last-commit-img]: https://img.shields.io/github/last-commit/daniil-berg/asyncio-taskpool?label=Last%20commit&logo=git&\n[gist-cloc-code-img]: https://img.shields.io/endpoint?logo=python&color=blue&url=https://gist.githubusercontent.com/daniil-berg/3f8240a976e8781a765d9c74a583dcda/raw/cloc-code.json\n[gist-cloc-comments-img]: https://img.shields.io/endpoint?logo=sharp&color=lightgrey&url=https://gist.githubusercontent.com/daniil-berg/3f8240a976e8781a765d9c74a583dcda/raw/cloc-comments.json\n[gist-test-coverage-img]: https://img.shields.io/endpoint?logo=pytest&color=blue&url=https://gist.githubusercontent.com/daniil-berg/3f8240a976e8781a765d9c74a583dcda/raw/test-coverage.json\n[lgpl3]: https://www.gnu.org/licenses/lgpl-3.0\n[lgpl3-img]: https://img.shields.io/badge/License-LGPL_v3.0-darkgreen.svg?logo=gnu\n[pypi-latest-version-img]: https://img.shields.io/pypi/v/asyncio-taskpool?color=teal&logo=pypi\n[pypi-latest-version]: https://pypi.org/project/asyncio-taskpool/\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Dynamically manage pools of asyncio tasks",
"version": "1.1.4",
"project_urls": {
"Bug Tracker": "https://github.com/daniil-berg/asyncio-taskpool/issues",
"Homepage": "https://git.fajnberg.de/daniil/asyncio-taskpool"
},
"split_keywords": [
"asyncio",
"concurrency",
"tasks",
"coroutines",
"asynchronous",
"server"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3e7f8b7cc0f92a98ca30f617588362cf2b81414d9fc5dd65dd6ed6fedc883d4a",
"md5": "545e0582f369a317a3ed9146d093c8d9",
"sha256": "57251f8d3c101c7dd5740aa92c8449f770e4ab6a009d1f55ff9259b9af1f1962"
},
"downloads": -1,
"filename": "asyncio_taskpool-1.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "545e0582f369a317a3ed9146d093c8d9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 52809,
"upload_time": "2022-05-08T13:27:30",
"upload_time_iso_8601": "2022-05-08T13:27:30.957023Z",
"url": "https://files.pythonhosted.org/packages/3e/7f/8b7cc0f92a98ca30f617588362cf2b81414d9fc5dd65dd6ed6fedc883d4a/asyncio_taskpool-1.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e4dd685b428a9aa89ee08d279eebbd26b28d524b7bffd1b14c3611997c3694c7",
"md5": "c1d35208169d6559ec8e6cee038e4822",
"sha256": "61fe2ec61979e01b145e1246c4d28412e264d2e699283f543c4ab0e7e671146e"
},
"downloads": -1,
"filename": "asyncio-taskpool-1.1.4.tar.gz",
"has_sig": false,
"md5_digest": "c1d35208169d6559ec8e6cee038e4822",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 43932,
"upload_time": "2022-05-08T13:27:32",
"upload_time_iso_8601": "2022-05-08T13:27:32.843092Z",
"url": "https://files.pythonhosted.org/packages/e4/dd/685b428a9aa89ee08d279eebbd26b28d524b7bffd1b14c3611997c3694c7/asyncio-taskpool-1.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-05-08 13:27:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "daniil-berg",
"github_project": "asyncio-taskpool",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "asyncio-taskpool"
}
JSON
