Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fastapi/typer
Typer, build great CLIs. Easy to code. Based on Python type hints.
https://github.com/fastapi/typer
cli click python python3 shell terminal typehints typer
Last synced: 20 days ago
JSON representation
Typer, build great CLIs. Easy to code. Based on Python type hints.
- Host: GitHub
- URL: https://github.com/fastapi/typer
- Owner: fastapi
- License: mit
- Created: 2019-12-24T12:24:11.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-08-09T22:20:31.000Z (3 months ago)
- Last Synced: 2024-08-11T20:10:58.204Z (3 months ago)
- Topics: cli, click, python, python3, shell, terminal, typehints, typer
- Language: Python
- Homepage: https://typer.tiangolo.com/
- Size: 1.21 MB
- Stars: 15,129
- Watchers: 78
- Forks: 644
- Open Issues: 213
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Citation: CITATION.cff
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-github-repos - fastapi/typer - Typer, build great CLIs. Easy to code. Based on Python type hints. (Python)
- jimsghstars - fastapi/typer - Typer, build great CLIs. Easy to code. Based on Python type hints. (Python)
- stars - fastapi/typer - Typer, build great CLIs. Easy to code. Based on Python type hints. (Python)
- stars - fastapi/typer - Typer, build great CLIs. Easy to code. Based on Python type hints. (Python)
README
Typer, build great CLIs. Easy to code. Based on Python type hints.
---
**Documentation**: https://typer.tiangolo.com
**Source Code**: https://github.com/fastapi/typer
---
Typer is a library for building CLI applications that users will **love using** and developers will **love creating**. Based on Python type hints.
It's also a command line tool to run scripts, automatically converting them to CLI applications.
The key features are:
* **Intuitive to write**: Great editor support. Completion 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.
* **Run scripts**: Typer includes a `typer` command/program that you can use to run scripts, automatically converting them to CLIs, even if they don't use Typer internally.
## FastAPI of CLIs
**Typer** is FastAPI's little sibling, it's the FastAPI of CLIs.
## Installation
Create and activate a virtual environment and then install **Typer**:
```console
$ pip install typer
---> 100%
Successfully installed typer rich shellingham
```
## Example
### The absolute minimum
* Create a file `main.py` with:
```Python
def main(name: str):
print(f"Hello {name}")
```
This script doesn't even use Typer internally. But you can use the `typer` command to run it as a CLI application.
### Run it
Run your application with the `typer` command:
```console
// Run your application
$ typer main.py run
// You get a nice error, you are missing NAME
Usage: typer [PATH_OR_MODULE] run [OPTIONS] NAME
Try 'typer [PATH_OR_MODULE] run --help' for help.
╭─ Error ───────────────────────────────────────────╮
│ Missing argument 'NAME'. │
╰───────────────────────────────────────────────────╯
// You get a --help for free
$ typer main.py run --help
Usage: typer [PATH_OR_MODULE] run [OPTIONS] NAME
Run the provided Typer app.
╭─ Arguments ───────────────────────────────────────╮
│ * name TEXT [default: None] [required] |
╰───────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────╮
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────╯
// Now pass the NAME argument
$ typer main.py run Camila
Hello Camila
// It works! 🎉
```
This is the simplest use case, not even using Typer internally, but it can already be quite useful for simple scripts.
**Note**: auto-completion works when you create a Python package and run it with `--install-completion` or when you use the `typer` command.
## Use Typer in your code
Now let's start using Typer in your own code, update `main.py` with:
```Python
import typer
def main(name: str):
print(f"Hello {name}")
if __name__ == "__main__":
typer.run(main)
```
Now you could run it with Python directly:
```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 TEXT [default: None] [required] |
╰───────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────╮
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────╯
// Now pass the NAME argument
$ python main.py Camila
Hello Camila
// It works! 🎉
```
**Note**: you can also call this same script with the `typer` command, but you don't need to.
## 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
app = typer.Typer()
@app.command()
def hello(name: str):
print(f"Hello {name}")
@app.command()
def goodbye(name: str, formal: bool = False):
if formal:
print(f"Goodbye Ms. {name}. Have a good day.")
else:
print(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
Check the new help:
```console
$ python main.py --help
Usage: main.py [OPTIONS] COMMAND [ARGS]...
╭─ Options ─────────────────────────────────────────╮
│ --install-completion Install completion │
│ for the current │
│ shell. │
│ --show-completion Show completion for │
│ the current shell, │
│ to copy it or │
│ customize the │
│ installation. │
│ --help Show this message │
│ and exit. │
╰───────────────────────────────────────────────────╯
╭─ Commands ────────────────────────────────────────╮
│ goodbye │
│ hello │
╰───────────────────────────────────────────────────╯
// When you create a package you get ✨ auto-completion ✨ for free, installed with --install-completion
// You have 2 subcommands (the 2 functions): goodbye and hello
```
Now check the help for the `hello` command:
```console
$ python main.py hello --help
Usage: main.py hello [OPTIONS] NAME
╭─ Arguments ───────────────────────────────────────╮
│ * name TEXT [default: None] [required] │
╰───────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────╮
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────╯
```
And now check the help for the `goodbye` command:
```console
$ python main.py goodbye --help
Usage: main.py goodbye [OPTIONS] NAME
╭─ Arguments ───────────────────────────────────────╮
│ * name TEXT [default: None] [required] │
╰───────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────╮
│ --formal --no-formal [default: no-formal] │
│ --help Show this message │
│ and exit. │
╰───────────────────────────────────────────────────╯
// Automatic --formal and --no-formal for the bool option 🎉
```
Now you can try out the new command line application:
```console
// 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.
```
### 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**.
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, PowerShell) when they install your package or when using the `typer` command.
For a more complete example including more features, see the Tutorial - User Guide.
## Dependencies
**Typer** stands on the shoulders of a giant. Its only internal required dependency is Click.
By default it also comes with extra standard dependencies:
* rich: to show nicely formatted errors automatically.
* shellingham: to automatically detect the current shell when installing completion.
* With `shellingham` you can just use `--install-completion`.
* Without `shellingham`, you have to pass the name of the shell to install completion for, e.g. `--install-completion bash`.
### `typer-slim`
If you don't want the extra standard optional dependencies, install `typer-slim` instead.
When you install with:
```bash
pip install typer
```
...it includes the same code and dependencies as:
```bash
pip install "typer-slim[standard]"
```
The `standard` extra dependencies are `rich` and `shellingham`.
**Note**: The `typer` command is only included in the `typer` package.
## License
This project is licensed under the terms of the MIT license.