# 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)
- ✅ 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
## 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/29/9b/ce4b451e10191762a78460688a313a66da7d52563a48fc30c03678542025/poethepoet-0.25.1.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\n- \u2705 Straight forward [declaration of project tasks in your pyproject.toml](https://poethepoet.natn.io/tasks/index.html)\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\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.25.1",
"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": "84573cd6e7760ad059ddd74ac77732e3b7719922f7dfdf44db11302d960e12a8",
"md5": "ae2a1ca3db2dfbd718078d381c698583",
"sha256": "fee433f68424593bca6b357f0bf997d64edf42c7305c0d5d335bd570b8d2352b"
},
"downloads": -1,
"filename": "poethepoet-0.25.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ae2a1ca3db2dfbd718078d381c698583",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 66200,
"upload_time": "2024-04-13T18:39:07",
"upload_time_iso_8601": "2024-04-13T18:39:07.726112Z",
"url": "https://files.pythonhosted.org/packages/84/57/3cd6e7760ad059ddd74ac77732e3b7719922f7dfdf44db11302d960e12a8/poethepoet-0.25.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "299bce4b451e10191762a78460688a313a66da7d52563a48fc30c03678542025",
"md5": "46c16b33c6e54b8c46ec1bfb937fdf25",
"sha256": "98f4446533a4b2bdb08843e211f918b1f2e7f8baf6d1803ef78f64661ed62463"
},
"downloads": -1,
"filename": "poethepoet-0.25.1.tar.gz",
"has_sig": false,
"md5_digest": "46c16b33c6e54b8c46ec1bfb937fdf25",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 51313,
"upload_time": "2024-04-13T18:39:09",
"upload_time_iso_8601": "2024-04-13T18:39:09.848247Z",
"url": "https://files.pythonhosted.org/packages/29/9b/ce4b451e10191762a78460688a313a66da7d52563a48fc30c03678542025/poethepoet-0.25.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-13 18:39:09",
"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
