# Poe the Poet
<img alt="Poe the Poet" src="https://raw.githubusercontent.com/nat-n/poethepoet/main/docs/_static/poe_logo_x2000.png" height="200" width="200" align="left"/>
[](https://pypi.org/project/poethepoet/)
[](https://pypi.org/project/poethepoet/)
[](https://pypistats.org/packages/poethepoet)
[](https://github.com/nat-n/poethepoet/blob/doc/init-sphinx/LICENSE)
**A batteries included task runner that works well with [poetry](https://python-poetry.org/).**
**[📖 Read the documentation 📖](https://poethepoet.natn.io/)**
<br clear="both"/>
## Features
- ✅ Straight forward [declaration of project tasks in your pyproject.toml](https://poethepoet.natn.io/tasks/index.html) (or [poe_tasks.toml](https://poethepoet.natn.io/guides/without_poetry.html#usage-without-pyproject-toml))
- ✅ Tasks are run in poetry's virtualenv ([or another env](https://poethepoet.natn.io/index.html#usage-without-poetry) you specify)
- ✅ [Shell completion of task names](https://poethepoet.natn.io/installation.html#shell-completion) (and global options too for zsh)
- ✅ The poe CLI can be used standalone, or as a [plugin for poetry](https://poethepoet.natn.io/poetry_plugin.html)
- ✅ Tasks can be [commands](https://poethepoet.natn.io/tasks/task_types/cmd.html), [shell scripts](https://poethepoet.natn.io/tasks/task_types/shell.html), [python expressions](https://poethepoet.natn.io/tasks/task_types/expr.html), or references to [python functions](https://poethepoet.natn.io/tasks/task_types/script.html)
- ✅ Concise commands with extra arguments passed to the task `poe [options] task [task_args]`
- ✅ Easily [define CLI arguments](https://poethepoet.natn.io/guides/args_guide.html) for your tasks
- ✅ Tasks can specify and [reference environment variables](https://poethepoet.natn.io/tasks/task_types/cmd.html#ref-env-vars), even without a shell
- ✅ Tasks are [self documenting](https://poethepoet.natn.io/guides/help_guide.html), with optional help messages (just run `poe` with no arguments)
- ✅ Tasks can be composed into [sequences](https://poethepoet.natn.io/guides/composition_guide.html#composing-tasks-into-sequences) or [DAGs](https://poethepoet.natn.io/guides/composition_guide.html#composing-tasks-into-graphs)
- ✅ Works with [`.env` files](https://poethepoet.natn.io/tasks/options.html#loading-environment-variables-from-an-env-file)
- ✅ Can be [used as a library](https://poethepoet.natn.io/guides/library_guide.html) to embed in other tools
- ✅ Also works fine [without poetry](https://poethepoet.natn.io/guides/without_poetry.html)
## Quick start
1. Install the Poe the Poet via [pipx](https://pypa.github.io/pipx/) or [another method](https://poethepoet.natn.io/installation.html).
```sh
pipx install poethepoet
```
2. Define some tasks in your **pyproject.toml**
```toml
[tool.poe.tasks]
test = "pytest --cov=my_app" # a simple command task
serve.script = "my_app.service:run(debug=True)" # python script based task
tunnel.shell = "ssh -N -L 0.0.0.0:8080:$PROD:8080 $PROD &" # (posix) shell based task
```
3. Run your tasks via the CLI
```sh
$ poe test -v tests/unit # extra CLI arguments are appended to the underlying command
Poe => pytest --cov=my_app
...
```
If you're using poetry, then poe will automatically use CLI tools and libraries from your poetry managed virtualenv without you having to run `poetry run` or `poetry shell`
Poe can also be [used without poetry](https://poethepoet.natn.io/index.html#usage-without-poetry).
## Contributing
There's plenty to do, come say hi in the [discussions](https://github.com/nat-n/poethepoet/discussions) or [open an issue](https://github.com/nat-n/poethepoet/issues)! 👋
Also check out the [CONTRIBUTING guide](https://github.com/nat-n/poethepoet/blob/main/.github/CONTRIBUTING.rst) 🤓
## License
[MIT](https://github.com/nat-n/poethepoet/blob/main/LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/nat-n/poethepoet",
"name": "poethepoet",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "automation, tasks, task-runner, plugin, poetry, poe",
"author": "Nat Noordanus",
"author_email": "n@noordan.us",
"download_url": "https://files.pythonhosted.org/packages/dc/7a/7144e47128022146502e179e259b312335bc1465384025eee92d4c7e16b2/poethepoet-0.29.0.tar.gz",
"platform": null,
"description": "# Poe the Poet\n\n<img alt=\"Poe the Poet\" src=\"https://raw.githubusercontent.com/nat-n/poethepoet/main/docs/_static/poe_logo_x2000.png\" height=\"200\" width=\"200\" align=\"left\"/>\n\n[](https://pypi.org/project/poethepoet/)\n[](https://pypi.org/project/poethepoet/)\n[](https://pypistats.org/packages/poethepoet)\n[](https://github.com/nat-n/poethepoet/blob/doc/init-sphinx/LICENSE)\n\n**A batteries included task runner that works well with [poetry](https://python-poetry.org/).**\n\n**[\ud83d\udcd6 Read the documentation \ud83d\udcd6](https://poethepoet.natn.io/)**\n\n<br clear=\"both\"/>\n\n## Features\n\n- \u2705 Straight forward [declaration of project tasks in your pyproject.toml](https://poethepoet.natn.io/tasks/index.html) (or [poe_tasks.toml](https://poethepoet.natn.io/guides/without_poetry.html#usage-without-pyproject-toml))\n\n- \u2705 Tasks are run in poetry's virtualenv ([or another env](https://poethepoet.natn.io/index.html#usage-without-poetry) you specify)\n\n- \u2705 [Shell completion of task names](https://poethepoet.natn.io/installation.html#shell-completion) (and global options too for zsh)\n\n- \u2705 The poe CLI can be used standalone, or as a [plugin for poetry](https://poethepoet.natn.io/poetry_plugin.html)\n\n- \u2705 Tasks can be [commands](https://poethepoet.natn.io/tasks/task_types/cmd.html), [shell scripts](https://poethepoet.natn.io/tasks/task_types/shell.html), [python expressions](https://poethepoet.natn.io/tasks/task_types/expr.html), or references to [python functions](https://poethepoet.natn.io/tasks/task_types/script.html)\n\n- \u2705 Concise commands with extra arguments passed to the task `poe [options] task [task_args]`\n\n- \u2705 Easily [define CLI arguments](https://poethepoet.natn.io/guides/args_guide.html) for your tasks\n\n- \u2705 Tasks can specify and [reference environment variables](https://poethepoet.natn.io/tasks/task_types/cmd.html#ref-env-vars), even without a shell\n\n- \u2705 Tasks are [self documenting](https://poethepoet.natn.io/guides/help_guide.html), with optional help messages (just run `poe` with no arguments)\n\n- \u2705 Tasks can be composed into [sequences](https://poethepoet.natn.io/guides/composition_guide.html#composing-tasks-into-sequences) or [DAGs](https://poethepoet.natn.io/guides/composition_guide.html#composing-tasks-into-graphs)\n\n- \u2705 Works with [`.env` files](https://poethepoet.natn.io/tasks/options.html#loading-environment-variables-from-an-env-file)\n\n- \u2705 Can be [used as a library](https://poethepoet.natn.io/guides/library_guide.html) to embed in other tools\n\n- \u2705 Also works fine [without poetry](https://poethepoet.natn.io/guides/without_poetry.html)\n\n## Quick start\n\n1. Install the Poe the Poet via [pipx](https://pypa.github.io/pipx/) or [another method](https://poethepoet.natn.io/installation.html).\n\n ```sh\n pipx install poethepoet\n ```\n\n2. Define some tasks in your **pyproject.toml**\n\n ```toml\n [tool.poe.tasks]\n test = \"pytest --cov=my_app\" # a simple command task\n serve.script = \"my_app.service:run(debug=True)\" # python script based task\n tunnel.shell = \"ssh -N -L 0.0.0.0:8080:$PROD:8080 $PROD &\" # (posix) shell based task\n ```\n\n3. Run your tasks via the CLI\n\n ```sh\n $ poe test -v tests/unit # extra CLI arguments are appended to the underlying command\n Poe => pytest --cov=my_app\n ...\n ```\n\nIf you're using poetry, then poe will automatically use CLI tools and libraries from your poetry managed virtualenv without you having to run `poetry run` or `poetry shell`\n\nPoe can also be [used without poetry](https://poethepoet.natn.io/index.html#usage-without-poetry).\n\n## Contributing\n\nThere's plenty to do, come say hi in the [discussions](https://github.com/nat-n/poethepoet/discussions) or [open an issue](https://github.com/nat-n/poethepoet/issues)! \ud83d\udc4b\n\nAlso check out the [CONTRIBUTING guide](https://github.com/nat-n/poethepoet/blob/main/.github/CONTRIBUTING.rst) \ud83e\udd13\n\n\n## License\n\n[MIT](https://github.com/nat-n/poethepoet/blob/main/LICENSE)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A task runner that works well with poetry.",
"version": "0.29.0",
"project_urls": {
"Documentation": "https://poethepoet.natn.io/",
"Homepage": "https://github.com/nat-n/poethepoet",
"Repository": "https://github.com/nat-n/poethepoet"
},
"split_keywords": [
"automation",
" tasks",
" task-runner",
" plugin",
" poetry",
" poe"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b57d871be58cc970ab4c9a541d64b77b7454d150a409c3e48b53fc9eac7a8967",
"md5": "25172dcd26d44f01606fcbd94430aaf8",
"sha256": "f8dfe55006dcfb5cf31bcb1904e1262e1c642a4502fee3688cbf1bddfe5c7601"
},
"downloads": -1,
"filename": "poethepoet-0.29.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "25172dcd26d44f01606fcbd94430aaf8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 76069,
"upload_time": "2024-09-23T21:46:49",
"upload_time_iso_8601": "2024-09-23T21:46:49.770093Z",
"url": "https://files.pythonhosted.org/packages/b5/7d/871be58cc970ab4c9a541d64b77b7454d150a409c3e48b53fc9eac7a8967/poethepoet-0.29.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dc7a7144e47128022146502e179e259b312335bc1465384025eee92d4c7e16b2",
"md5": "c394c8e59da968596c3bcc33fc1b87fc",
"sha256": "676842302f2304a86b31ac56398dd672fae8471128d2086896393384dbafc095"
},
"downloads": -1,
"filename": "poethepoet-0.29.0.tar.gz",
"has_sig": false,
"md5_digest": "c394c8e59da968596c3bcc33fc1b87fc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 58619,
"upload_time": "2024-09-23T21:46:51",
"upload_time_iso_8601": "2024-09-23T21:46:51.322517Z",
"url": "https://files.pythonhosted.org/packages/dc/7a/7144e47128022146502e179e259b312335bc1465384025eee92d4c7e16b2/poethepoet-0.29.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-23 21:46:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nat-n",
"github_project": "poethepoet",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "poethepoet"
}
JSON
