| Name | trogon JSON |
| Version |
0.6.0
JSON |
| download |
| home_page | https://github.com/Textualize/trogon |
| Summary | Automatically generate a Textual TUI for your Click CLI |
| upload_time | 2024-10-02 13:38:12 |
| maintainer | None |
| docs_url | None |
| author | Darren Burns |
| requires_python | <4.0.0,>=3.8.1 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center">
<img src="https://github.com/Textualize/trogon/assets/554369/f4751783-c322-4143-a6c1-d8c564d4e38f" alt="A picture of a trogon (bird) sitting on a laptop" width="300" align="center">
</p>
[](https://discord.gg/Enf6Z3qhVr)
# Trogon
Auto-generate friendly terminal user interfaces for command line apps.
<details>
<summary> 🎬 Video demonstration </summary>
A quick tour of a Trogon app applied to [sqlite-utils](https://github.com/simonw/sqlite-utils).
https://github.com/Textualize/trogon/assets/554369/c9e5dabb-5624-45cb-8612-f6ecfde70362
</details>
Trogon works with the popular [Click](https://click.palletsprojects.com/) library for Python, but will support other libraries and languages in the future.
## How it works
Trogon inspects your (command line) app and extracts a *schema* which describes the options / switches / help etc.
It then uses that information to build a [Textual](https://github.com/textualize/textual) UI you can use to edit and run the command.
Ultimately we would like to formalize this schema and a protocol to extract or expose it from apps.
This which would allow Trogon to build TUIs for any CLI app, regardless of how it was built.
If you are familiar with Swagger, think Swagger for CLIs.
## Screenshots
<table>
<tr>
<td>
<img width="100%" alt="Screenshot 2023-05-20 at 12 07 31" src="https://github.com/Textualize/trogon/assets/554369/009cf3f2-f0c4-464b-bd74-60e303864443">
</td>
<td>
<img width="100%" alt="Screenshot 2023-05-20 at 12 08 21" src="https://github.com/Textualize/trogon/assets/554369/b1039ee6-4ba6-4123-b0dd-aa7b2341672f">
</td>
</tr>
<tr>
<td>
<img width="100%" alt="Screenshot 2023-05-20 at 12 08 53" src="https://github.com/Textualize/trogon/assets/554369/c0a42277-e946-4bef-b0d0-3fa87e4ab55b">
</td>
<td>
<img width="100%" alt="Screenshot 2023-05-20 at 12 09 47" src="https://github.com/Textualize/trogon/assets/554369/55477f6c-e6b8-49b6-85c1-b01bee006c8e">
</td>
</tr>
</table>
## Why?
Command line apps reward repeated use, but they lack in *discoverability*.
If you don't use a CLI app frequently, or there are too many options to commit to memory, a Trogon TUI interface can help you (re)discover options and switches.
## What does the name mean?
This project started life as a [Textual](https://github.com/Textualize/textual) experiment, which we have been giving birds' names to.
A [Trogon](https://www.willmcgugan.com/blog/photography/post/costa-rica-trip-report-2017/#bird) is a beautiful bird I was lucky enough to photograph in 2017.
See also [Frogmouth](https://github.com/Textualize/frogmouth), a Markdown browser for the terminal.
## Roadmap
Trogon is usable now. It is only 2 lines (!) of code to add to an existing project.
It is still in an early stage of development, and we have lots of improvements planned for it.
## Installing
Trogon may be installed with PyPI.
```bash
pip install trogon
```
## Quickstart
### Click
1. Import `from trogon import tui`
2. Add the `@tui` decorator above your click app, e.g.
```python
from trogon import tui
@tui()
@click.group(...)
def cli():
...
```
3. Your click app will have a new `tui` command available.
### Typer
1. Import `from trogon.typer import init_tui`
2. Pass your Typer CLI app into the `init_tui` function, e.g.
```python
cli = typer.Typer(...)
init_tui(cli)
```
3. Your Typer app will have a new `tui` command available.
See also the `examples` folder for two example apps.
## Custom command name and custom help
By default the command added will be called `tui` and the help text for it will be `Open Textual TUI.`
You can customize one or both of these using the `command=` and `help=` parameters:
```python
@tui(command="ui", help="Open terminal UI")
@click.group(...)
def cli():
...
```
## Follow this project
If this app interests you, you may want to join the Textual [Discord server](https://discord.gg/Enf6Z3qhVr) where you can talk to Textual developers / community.
Raw data
{
"_id": null,
"home_page": "https://github.com/Textualize/trogon",
"name": "trogon",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.8.1",
"maintainer_email": null,
"keywords": null,
"author": "Darren Burns",
"author_email": "darrenb900@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/cf/ae/7367acac2194a215b092ba3fccde3b558272702110b8bb9bea164ab4ac42/trogon-0.6.0.tar.gz",
"platform": null,
"description": "\n<p align=\"center\">\n <img src=\"https://github.com/Textualize/trogon/assets/554369/f4751783-c322-4143-a6c1-d8c564d4e38f\" alt=\"A picture of a trogon (bird) sitting on a laptop\" width=\"300\" align=\"center\">\n</p>\n \n[](https://discord.gg/Enf6Z3qhVr)\n\n\n# Trogon\n\nAuto-generate friendly terminal user interfaces for command line apps.\n\n\n<details> \n <summary> \ud83c\udfac Video demonstration </summary>\n\n \n \nA quick tour of a Trogon app applied to [sqlite-utils](https://github.com/simonw/sqlite-utils).\n\nhttps://github.com/Textualize/trogon/assets/554369/c9e5dabb-5624-45cb-8612-f6ecfde70362\n\n</details>\n\n\nTrogon works with the popular [Click](https://click.palletsprojects.com/) library for Python, but will support other libraries and languages in the future.\n\n## How it works\n\nTrogon inspects your (command line) app and extracts a *schema* which describes the options / switches / help etc.\nIt then uses that information to build a [Textual](https://github.com/textualize/textual) UI you can use to edit and run the command. \n\nUltimately we would like to formalize this schema and a protocol to extract or expose it from apps.\nThis which would allow Trogon to build TUIs for any CLI app, regardless of how it was built.\nIf you are familiar with Swagger, think Swagger for CLIs.\n\n## Screenshots\n\n<table>\n\n<tr>\n<td>\n<img width=\"100%\" alt=\"Screenshot 2023-05-20 at 12 07 31\" src=\"https://github.com/Textualize/trogon/assets/554369/009cf3f2-f0c4-464b-bd74-60e303864443\">\n</td>\n\n<td>\n<img width=\"100%\" alt=\"Screenshot 2023-05-20 at 12 08 21\" src=\"https://github.com/Textualize/trogon/assets/554369/b1039ee6-4ba6-4123-b0dd-aa7b2341672f\">\n</td>\n</tr>\n\n<tr>\n\n<td>\n<img width=\"100%\" alt=\"Screenshot 2023-05-20 at 12 08 53\" src=\"https://github.com/Textualize/trogon/assets/554369/c0a42277-e946-4bef-b0d0-3fa87e4ab55b\">\n</td>\n\n<td>\n<img width=\"100%\" alt=\"Screenshot 2023-05-20 at 12 09 47\" src=\"https://github.com/Textualize/trogon/assets/554369/55477f6c-e6b8-49b6-85c1-b01bee006c8e\">\n</td>\n\n</tr>\n\n</table>\n\n## Why?\n\nCommand line apps reward repeated use, but they lack in *discoverability*.\nIf you don't use a CLI app frequently, or there are too many options to commit to memory, a Trogon TUI interface can help you (re)discover options and switches.\n\n## What does the name mean?\n\nThis project started life as a [Textual](https://github.com/Textualize/textual) experiment, which we have been giving birds' names to.\nA [Trogon](https://www.willmcgugan.com/blog/photography/post/costa-rica-trip-report-2017/#bird) is a beautiful bird I was lucky enough to photograph in 2017.\n\nSee also [Frogmouth](https://github.com/Textualize/frogmouth), a Markdown browser for the terminal.\n\n## Roadmap\n\nTrogon is usable now. It is only 2 lines (!) of code to add to an existing project.\n\nIt is still in an early stage of development, and we have lots of improvements planned for it.\n\n## Installing\n\nTrogon may be installed with PyPI.\n\n```bash\npip install trogon\n```\n\n## Quickstart\n\n### Click\n1. Import `from trogon import tui`\n2. Add the `@tui` decorator above your click app, e.g.\n ```python\n from trogon import tui\n \n @tui()\n @click.group(...)\n def cli():\n ...\n ```\n3. Your click app will have a new `tui` command available.\n\n### Typer\n1. Import `from trogon.typer import init_tui`\n2. Pass your Typer CLI app into the `init_tui` function, e.g.\n ```python\n cli = typer.Typer(...)\n init_tui(cli)\n ```\n3. Your Typer app will have a new `tui` command available.\n\nSee also the `examples` folder for two example apps.\n\n## Custom command name and custom help\n\nBy default the command added will be called `tui` and the help text for it will be `Open Textual TUI.`\n\nYou can customize one or both of these using the `command=` and `help=` parameters:\n\n```python\n@tui(command=\"ui\", help=\"Open terminal UI\")\n@click.group(...)\ndef cli():\n ...\n```\n\n## Follow this project\n\nIf this app interests you, you may want to join the Textual [Discord server](https://discord.gg/Enf6Z3qhVr) where you can talk to Textual developers / community.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Automatically generate a Textual TUI for your Click CLI",
"version": "0.6.0",
"project_urls": {
"Homepage": "https://github.com/Textualize/trogon"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "973033035d5796a3b8b9624997fec7545e3febd2268c7b48df38a715a95cb5e4",
"md5": "32f924c22740f7a88966bd774637e6b2",
"sha256": "fb5b6c25acd7a0eaba8d2cd32a57f1d80c26413cea737dad7a4eebcda56060e0"
},
"downloads": -1,
"filename": "trogon-0.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "32f924c22740f7a88966bd774637e6b2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.8.1",
"size": 26077,
"upload_time": "2024-10-02T13:38:11",
"upload_time_iso_8601": "2024-10-02T13:38:11.090149Z",
"url": "https://files.pythonhosted.org/packages/97/30/33035d5796a3b8b9624997fec7545e3febd2268c7b48df38a715a95cb5e4/trogon-0.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cfae7367acac2194a215b092ba3fccde3b558272702110b8bb9bea164ab4ac42",
"md5": "58f8b25d86d951a52e0a9f807b500f07",
"sha256": "fd1abfeb7b15d79d6e6cfc9e724aad2a2728812e4713a744d975f133e7ec73a4"
},
"downloads": -1,
"filename": "trogon-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "58f8b25d86d951a52e0a9f807b500f07",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.8.1",
"size": 22902,
"upload_time": "2024-10-02T13:38:12",
"upload_time_iso_8601": "2024-10-02T13:38:12.511071Z",
"url": "https://files.pythonhosted.org/packages/cf/ae/7367acac2194a215b092ba3fccde3b558272702110b8bb9bea164ab4ac42/trogon-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-02 13:38:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Textualize",
"github_project": "trogon",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "trogon"
}
