<p align="center">
<a href="https://typer-cloup.netlify.app"><img src="https://typer-cloup.netlify.app/img/logo-margin/logo-margin-vector.svg" alt="Typer"></a>
</p>
<p align="center">
<em>Typer, build great CLIs. Easy to code. Based on Python type hints.</em>
</p>
<p align="center">
<a href="https://github.com/alexreg/typer-cloup/actions?query=workflow%3ATest" target="_blank">
<img src="https://github.com/alexreg/typer-cloup/workflows/Test/badge.svg" alt="Test">
</a>
<a href="https://github.com/alexreg/typer-cloup/actions?query=workflow%3APublish" target="_blank">
<img src="https://github.com/alexreg/typer-cloup/workflows/Publish/badge.svg" alt="Publish">
</a>
<a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/alexreg/typer-cloup" target="_blank">
<img src="https://coverage-badge.samuelcolvin.workers.dev/alexreg/typer-cloup.svg" alt="Coverage">
<a href="https://pypi.org/project/typer-cloup" target="_blank">
<img src="https://img.shields.io/pypi/v/typer-cloup?color=%2334D058&label=pypi%20package" alt="Package version">
</a>
</p>
---
**Documentation**: <a href="https://typer-cloup.netlify.app" target="_blank">https://typer-cloup.netlify.app</a>
**Source Code**: <a href="https://github.com/alexreg/typer-cloup" target="_blank">https://github.com/alexreg/typer-cloup</a>
---
**NOTE**: This project is a fork of <a href="https://github.com/tiangolo/typer" class="external-link" target="_blank">the original Typer project</a>, building upon <a href="https://github.com/janLuke/cloup" class="external-link" target="_blank">Cloup</a> rather than <a href="https://click.palletsprojects.com/" class="external-link" target="_blank">Click</a> (of which Cloup is an extension). `typer-cloup` is largely but not entirely backward compatible with `typer` 0.4.2, and also includes some changes to `typer` made since then.
Typer is a library for building <abbr title="command-line interface, programs executed from a terminal">CLI</abbr> applications that users will **love using** and developers will **love creating**. Based on Python 3.7+ type hints.
The key features are:
* **Intuitive to write**: Great editor support. <abbr title="also known as auto-complete, autocompletion, IntelliSense">Completion</abbr> everywhere. Less time debugging. Designed to be easy to use and learn. Less time reading docs.
* **Easy to use**: It's easy to use for the final users. Automatic help, and automatic completion for all shells.
* **Short**: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs.
* **Start simple**: The simplest example adds only 2 lines of code to your app: **1 import, 1 function call**.
* **Grow large**: Grow in complexity as much as you want, create arbitrarily complex trees of commands and groups of subcommands, with options and arguments.
## FastAPI of CLIs
<a href="https://fastapi.tiangolo.com" target="_blank"><img src="https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png" style="width: 20%;"></a>
**Typer** is <a href="https://fastapi.tiangolo.com" class="external-link" target="_blank">FastAPI</a>'s little sibling.
And it's intended to be the FastAPI of CLIs.
## Requirements
Python 3.7+
**Typer** stands on the shoulders of a giant. Its only internal dependency is <a href="https://github.com/janLuke/cloup" class="external-link" target="_blank">Cloup</a>, which is itself based on <a href="https://click.palletsprojects.com/" class="external-link" target="_blank">Click</a>.
## Installation
<div class="termy">
```console
$ pip install typer-cloup
---> 100%
Successfully installed typer-cloup
```
</div>
## Example
### The absolute minimum
* Create a file `main.py` with:
```Python
import typer_cloup as typer
def main(name: str):
typer.echo(f"Hello {name}")
if __name__ == "__main__":
typer.run(main)
```
### Run it
Run your application:
<div class="termy">
```console
// Run your application
$ python main.py
// You get a nice error, you are missing NAME
Usage: main.py [OPTIONS] NAME
Try "main.py --help" for help.
Error: Missing argument 'NAME'.
// You get a --help for free
$ python main.py --help
Usage: main.py [OPTIONS] NAME
Arguments:
NAME [required]
Options:
--help Show this message and exit.
// When you create a package you get ✨ auto-completion ✨ for free, installed with --install-completion
// Now pass the NAME argument
$ python main.py Camila
Hello Camila
// It works! 🎉
```
</div>
**Note**: auto-completion works when you create a Python package and run it with `--install-completion` or when you use <a href="https://typer-cloup.netlify.app/typer-cloup-cli/" class="internal-link" target="_blank">Typer CLI</a>.
## Example upgrade
This was the simplest example possible.
Now let's see one a bit more complex.
### An example with two subcommands
Modify the file `main.py`.
Create a `typer.Typer()` app, and create two subcommands with their parameters.
```Python hl_lines="3 6 11 20"
import typer_cloup as typer
app = typer.Typer()
@app.command()
def hello(name: str):
typer.echo(f"Hello {name}")
@app.command()
def goodbye(name: str, formal: bool = False):
if formal:
typer.echo(f"Goodbye Ms. {name}. Have a good day.")
else:
typer.echo(f"Bye {name}!")
if __name__ == "__main__":
app()
```
And that will:
* Explicitly create a `typer.Typer` app.
* The previous `typer.run` actually creates one implicitly for you.
* Add two subcommands with `@app.command()`.
* Execute the `app()` itself, as if it was a function (instead of `typer.run`).
### Run the upgraded example
<div class="termy">
```console
// Check the --help
$ python main.py --help
Usage: main.py [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
Commands:
goodbye
hello
// You have 2 subcommands (the 2 functions): goodbye and hello
// Now get the --help for hello
$ python main.py hello --help
Usage: main.py hello [OPTIONS] NAME
Arguments:
NAME [required]
Options:
--help Show this message and exit.
// And now get the --help for goodbye
$ python main.py goodbye --help
Usage: main.py goodbye [OPTIONS] NAME
Arguments:
NAME [required]
Options:
--formal / --no-formal [default: no-formal]
--help Show this message and exit.
// Automatic --formal and --no-formal for the bool option 🎉
// And if you use it with the hello command
$ python main.py hello Camila
Hello Camila
// And with the goodbye command
$ python main.py goodbye Camila
Bye Camila!
// And with --formal
$ python main.py goodbye --formal Camila
Goodbye Ms. Camila. Have a good day.
```
</div>
### Recap
In summary, you declare **once** the types of parameters (*CLI arguments* and *CLI options*) as function parameters.
You do that with standard modern Python types.
You don't have to learn a new syntax, the methods or classes of a specific library, etc.
Just standard **Python 3.7+**.
For example, for an `int`:
```Python
total: int
```
or for a `bool` flag:
```Python
force: bool
```
And similarly for **files**, **paths**, **enums** (choices), etc. And there are tools to create **groups of subcommands**, add metadata, extra **validation**, etc.
**You get**: great editor support, including **completion** and **type checks** everywhere.
**Your users get**: automatic **`--help`**, **auto-completion** in their terminal (Bash, Zsh, Fish) when they install your package or when using <a href="https://typer-cloup.netlify.app/typer-cloup-cli/" class="internal-link" target="_blank">Typer CLI</a>.
For a more complete example including more features, see the <a href="https://typer-cloup.netlify.app/tutorial/">Tutorial - User Guide</a>.
## Optional Dependencies
Typer uses <a href="https://github.com/janLuke/cloup" class="external-link" target="_blank">Cloup</a> internally, which is based on <a href="https://click.palletsprojects.com/" class="external-link" target="_blank">Click</a>. That's the only dependency.
But you can also install extras:
* <a href="https://pypi.org/project/colorama/" class="external-link" target="_blank"><code>colorama</code></a>: and Click will automatically use it to make sure your terminal's colors always work correctly, even in Windows.
* Then you can use any tool you want to output your terminal's colors in all the systems, including the integrated `typer.style()` and `typer.secho()` (provided by Click).
* Or any other tool, e.g. <a href="https://pypi.org/project/wasabi/" class="external-link" target="_blank"><code>wasabi</code></a>, <a href="https://github.com/erikrose/blessings" class="external-link" target="_blank"><code>blessings</code></a>.
* <a href="https://pypi.org/project/docstring_parser/" class="external-link" target="_blank"><code>docstring_parser</code></a>: and Typer will automatically use it to parse help text for parameters from docstrings of functions.
You can install `typer-cloup` with all optional dependencies by running `pip install typer-cloup[all]`.
## Other tools and plug-ins
Click has many plug-ins available that you can use. And there are many tools that help with command-line applications that you can use as well, even if they are not related to Typer or Click.
For example:
* <a href="https://github.com/click-contrib/click-spinner" class="external-link" target="_blank"><code>click-spinner</code></a>: to show the user that you are loading data. A Click plug-in.
* There are several other Click plug-ins at <a href="https://github.com/click-contrib" class="external-link" target="_blank">click-contrib</a> that you can explore.
* <a href="https://pypi.org/project/tabulate/" class="external-link" target="_blank"><code>tabulate</code></a>: to automatically display tabular data nicely. Independent of Click or Typer.
* <a href="https://github.com/tqdm/tqdm" class="external-link" target="_blank"><code>tqdm</code></a>: a fast, extensible progress bar, alternative to Typer's own `typer.progressbar()`.
## License
This project is licensed under the terms of the MIT license.
Raw data
{
"_id": null,
"home_page": null,
"name": "typer-cloup",
"maintainer": null,
"docs_url": null,
"requires_python": ">= 3.7",
"maintainer_email": "Alexander Regueiro <alex@noldorin.com>",
"keywords": "cli,click,cloup,shell,terminal,typer,typehints",
"author": null,
"author_email": "Sebasti\u00e1n Ram\u00edrez <tiangolo@gmail.com>, Alexander Regueiro <alex@noldorin.com>",
"download_url": "https://files.pythonhosted.org/packages/d5/13/d44f9eb2a3cd3e69266f36d30b18a7ad2438a3f8e380ec13c4e87d416c28/typer-cloup-0.11.0.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <a href=\"https://typer-cloup.netlify.app\"><img src=\"https://typer-cloup.netlify.app/img/logo-margin/logo-margin-vector.svg\" alt=\"Typer\"></a>\n</p>\n<p align=\"center\">\n <em>Typer, build great CLIs. Easy to code. Based on Python type hints.</em>\n</p>\n<p align=\"center\">\n <a href=\"https://github.com/alexreg/typer-cloup/actions?query=workflow%3ATest\" target=\"_blank\">\n <img src=\"https://github.com/alexreg/typer-cloup/workflows/Test/badge.svg\" alt=\"Test\">\n </a>\n <a href=\"https://github.com/alexreg/typer-cloup/actions?query=workflow%3APublish\" target=\"_blank\">\n <img src=\"https://github.com/alexreg/typer-cloup/workflows/Publish/badge.svg\" alt=\"Publish\">\n </a>\n <a href=\"https://coverage-badge.samuelcolvin.workers.dev/redirect/alexreg/typer-cloup\" target=\"_blank\">\n <img src=\"https://coverage-badge.samuelcolvin.workers.dev/alexreg/typer-cloup.svg\" alt=\"Coverage\">\n <a href=\"https://pypi.org/project/typer-cloup\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/v/typer-cloup?color=%2334D058&label=pypi%20package\" alt=\"Package version\">\n </a>\n</p>\n\n---\n\n**Documentation**: <a href=\"https://typer-cloup.netlify.app\" target=\"_blank\">https://typer-cloup.netlify.app</a>\n\n**Source Code**: <a href=\"https://github.com/alexreg/typer-cloup\" target=\"_blank\">https://github.com/alexreg/typer-cloup</a>\n\n---\n\n**NOTE**: This project is a fork of <a href=\"https://github.com/tiangolo/typer\" class=\"external-link\" target=\"_blank\">the original Typer project</a>, building upon <a href=\"https://github.com/janLuke/cloup\" class=\"external-link\" target=\"_blank\">Cloup</a> rather than <a href=\"https://click.palletsprojects.com/\" class=\"external-link\" target=\"_blank\">Click</a> (of which Cloup is an extension). `typer-cloup` is largely but not entirely backward compatible with `typer` 0.4.2, and also includes some changes to `typer` made since then.\n\nTyper is a library for building <abbr title=\"command-line interface, programs executed from a terminal\">CLI</abbr> applications that users will **love using** and developers will **love creating**. Based on Python 3.7+ type hints.\n\nThe key features are:\n\n* **Intuitive to write**: Great editor support. <abbr title=\"also known as auto-complete, autocompletion, IntelliSense\">Completion</abbr> everywhere. Less time debugging. Designed to be easy to use and learn. Less time reading docs.\n* **Easy to use**: It's easy to use for the final users. Automatic help, and automatic completion for all shells.\n* **Short**: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs.\n* **Start simple**: The simplest example adds only 2 lines of code to your app: **1 import, 1 function call**.\n* **Grow large**: Grow in complexity as much as you want, create arbitrarily complex trees of commands and groups of subcommands, with options and arguments.\n\n## FastAPI of CLIs\n\n<a href=\"https://fastapi.tiangolo.com\" target=\"_blank\"><img src=\"https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png\" style=\"width: 20%;\"></a>\n\n**Typer** is <a href=\"https://fastapi.tiangolo.com\" class=\"external-link\" target=\"_blank\">FastAPI</a>'s little sibling.\n\nAnd it's intended to be the FastAPI of CLIs.\n\n## Requirements\n\nPython 3.7+\n\n**Typer** stands on the shoulders of a giant. Its only internal dependency is <a href=\"https://github.com/janLuke/cloup\" class=\"external-link\" target=\"_blank\">Cloup</a>, which is itself based on <a href=\"https://click.palletsprojects.com/\" class=\"external-link\" target=\"_blank\">Click</a>.\n\n## Installation\n\n<div class=\"termy\">\n\n```console\n$ pip install typer-cloup\n---> 100%\nSuccessfully installed typer-cloup\n```\n\n</div>\n\n## Example\n\n### The absolute minimum\n\n* Create a file `main.py` with:\n\n```Python\nimport typer_cloup as typer\n\n\ndef main(name: str):\n typer.echo(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n typer.run(main)\n```\n\n### Run it\n\nRun your application:\n\n<div class=\"termy\">\n\n```console\n// Run your application\n$ python main.py\n\n// You get a nice error, you are missing NAME\nUsage: main.py [OPTIONS] NAME\nTry \"main.py --help\" for help.\n\nError: Missing argument 'NAME'.\n\n// You get a --help for free\n$ python main.py --help\n\nUsage: main.py [OPTIONS] NAME\n\nArguments:\n NAME [required]\n\nOptions:\n --help Show this message and exit.\n\n// When you create a package you get \u2728 auto-completion \u2728 for free, installed with --install-completion\n\n// Now pass the NAME argument\n$ python main.py Camila\n\nHello Camila\n\n// It works! \ud83c\udf89\n```\n\n</div>\n\n**Note**: auto-completion works when you create a Python package and run it with `--install-completion` or when you use <a href=\"https://typer-cloup.netlify.app/typer-cloup-cli/\" class=\"internal-link\" target=\"_blank\">Typer CLI</a>.\n\n## Example upgrade\n\nThis was the simplest example possible.\n\nNow let's see one a bit more complex.\n\n### An example with two subcommands\n\nModify the file `main.py`.\n\nCreate a `typer.Typer()` app, and create two subcommands with their parameters.\n\n```Python hl_lines=\"3 6 11 20\"\nimport typer_cloup as typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef hello(name: str):\n typer.echo(f\"Hello {name}\")\n\n\n@app.command()\ndef goodbye(name: str, formal: bool = False):\n if formal:\n typer.echo(f\"Goodbye Ms. {name}. Have a good day.\")\n else:\n typer.echo(f\"Bye {name}!\")\n\n\nif __name__ == \"__main__\":\n app()\n```\n\nAnd that will:\n\n* Explicitly create a `typer.Typer` app.\n * The previous `typer.run` actually creates one implicitly for you.\n* Add two subcommands with `@app.command()`.\n* Execute the `app()` itself, as if it was a function (instead of `typer.run`).\n\n### Run the upgraded example\n\n<div class=\"termy\">\n\n```console\n// Check the --help\n$ python main.py --help\n\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n goodbye\n hello\n\n// You have 2 subcommands (the 2 functions): goodbye and hello\n\n// Now get the --help for hello\n\n$ python main.py hello --help\n\nUsage: main.py hello [OPTIONS] NAME\n\nArguments:\n NAME [required]\n\nOptions:\n --help Show this message and exit.\n\n// And now get the --help for goodbye\n\n$ python main.py goodbye --help\n\nUsage: main.py goodbye [OPTIONS] NAME\n\nArguments:\n NAME [required]\n\nOptions:\n --formal / --no-formal [default: no-formal]\n --help Show this message and exit.\n\n// Automatic --formal and --no-formal for the bool option \ud83c\udf89\n\n// And if you use it with the hello command\n\n$ python main.py hello Camila\n\nHello Camila\n\n// And with the goodbye command\n\n$ python main.py goodbye Camila\n\nBye Camila!\n\n// And with --formal\n\n$ python main.py goodbye --formal Camila\n\nGoodbye Ms. Camila. Have a good day.\n```\n\n</div>\n\n### Recap\n\nIn summary, you declare **once** the types of parameters (*CLI arguments* and *CLI options*) as function parameters.\n\nYou do that with standard modern Python types.\n\nYou don't have to learn a new syntax, the methods or classes of a specific library, etc.\n\nJust standard **Python 3.7+**.\n\nFor example, for an `int`:\n\n```Python\ntotal: int\n```\n\nor for a `bool` flag:\n\n```Python\nforce: bool\n```\n\nAnd similarly for **files**, **paths**, **enums** (choices), etc. And there are tools to create **groups of subcommands**, add metadata, extra **validation**, etc.\n\n**You get**: great editor support, including **completion** and **type checks** everywhere.\n\n**Your users get**: automatic **`--help`**, **auto-completion** in their terminal (Bash, Zsh, Fish) when they install your package or when using <a href=\"https://typer-cloup.netlify.app/typer-cloup-cli/\" class=\"internal-link\" target=\"_blank\">Typer CLI</a>.\n\nFor a more complete example including more features, see the <a href=\"https://typer-cloup.netlify.app/tutorial/\">Tutorial - User Guide</a>.\n\n## Optional Dependencies\n\nTyper uses <a href=\"https://github.com/janLuke/cloup\" class=\"external-link\" target=\"_blank\">Cloup</a> internally, which is based on <a href=\"https://click.palletsprojects.com/\" class=\"external-link\" target=\"_blank\">Click</a>. That's the only dependency.\n\nBut you can also install extras:\n\n* <a href=\"https://pypi.org/project/colorama/\" class=\"external-link\" target=\"_blank\"><code>colorama</code></a>: and Click will automatically use it to make sure your terminal's colors always work correctly, even in Windows.\n * Then you can use any tool you want to output your terminal's colors in all the systems, including the integrated `typer.style()` and `typer.secho()` (provided by Click).\n * Or any other tool, e.g. <a href=\"https://pypi.org/project/wasabi/\" class=\"external-link\" target=\"_blank\"><code>wasabi</code></a>, <a href=\"https://github.com/erikrose/blessings\" class=\"external-link\" target=\"_blank\"><code>blessings</code></a>.\n* <a href=\"https://pypi.org/project/docstring_parser/\" class=\"external-link\" target=\"_blank\"><code>docstring_parser</code></a>: and Typer will automatically use it to parse help text for parameters from docstrings of functions.\n\nYou can install `typer-cloup` with all optional dependencies by running `pip install typer-cloup[all]`.\n\n## Other tools and plug-ins\n\nClick has many plug-ins available that you can use. And there are many tools that help with command-line applications that you can use as well, even if they are not related to Typer or Click.\n\nFor example:\n\n* <a href=\"https://github.com/click-contrib/click-spinner\" class=\"external-link\" target=\"_blank\"><code>click-spinner</code></a>: to show the user that you are loading data. A Click plug-in.\n * There are several other Click plug-ins at <a href=\"https://github.com/click-contrib\" class=\"external-link\" target=\"_blank\">click-contrib</a> that you can explore.\n* <a href=\"https://pypi.org/project/tabulate/\" class=\"external-link\" target=\"_blank\"><code>tabulate</code></a>: to automatically display tabular data nicely. Independent of Click or Typer.\n* <a href=\"https://github.com/tqdm/tqdm\" class=\"external-link\" target=\"_blank\"><code>tqdm</code></a>: a fast, extensible progress bar, alternative to Typer's own `typer.progressbar()`.\n\n## License\n\nThis project is licensed under the terms of the MIT license.\n",
"bugtrack_url": null,
"license": null,
"summary": "Typer, build great CLIs. Easy to code. Based on Python type hints.",
"version": "0.11.0",
"split_keywords": [
"cli",
"click",
"cloup",
"shell",
"terminal",
"typer",
"typehints"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "40cf7ba1e52f96de4630a6458b7979b59220bdd03e20249ca0b8edac34d18470",
"md5": "4048cff64719ab9b0a4c7d1336e3a616",
"sha256": "75d80b5354d16dc88ad39b613974a97bb3102cb2add78267046f12811d3561f1"
},
"downloads": -1,
"filename": "typer_cloup-0.11.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4048cff64719ab9b0a4c7d1336e3a616",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">= 3.7",
"size": 26034,
"upload_time": "2023-01-25T04:33:46",
"upload_time_iso_8601": "2023-01-25T04:33:46.500017Z",
"url": "https://files.pythonhosted.org/packages/40/cf/7ba1e52f96de4630a6458b7979b59220bdd03e20249ca0b8edac34d18470/typer_cloup-0.11.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d513d44f9eb2a3cd3e69266f36d30b18a7ad2438a3f8e380ec13c4e87d416c28",
"md5": "bd4bbfdf69bc3b7dedea20e92ca3e689",
"sha256": "3a9f59e1c702026844316b744f959cfee5ea9db108f12810831bcd3673200596"
},
"downloads": -1,
"filename": "typer-cloup-0.11.0.tar.gz",
"has_sig": false,
"md5_digest": "bd4bbfdf69bc3b7dedea20e92ca3e689",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">= 3.7",
"size": 226576,
"upload_time": "2023-01-25T04:33:48",
"upload_time_iso_8601": "2023-01-25T04:33:48.571463Z",
"url": "https://files.pythonhosted.org/packages/d5/13/d44f9eb2a3cd3e69266f36d30b18a7ad2438a3f8e380ec13c4e87d416c28/typer-cloup-0.11.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-25 04:33:48",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "typer-cloup"
}
JSON