📝 Update docs with references to --install-completion
This commit is contained in:
Sebastián Ramírez
GitHub
commit
9b44a9fda3
4 changed files with 54 additions and 23 deletions
22
README.md
22
README.md
|
|
@ -34,7 +34,7 @@ The key features are:
|
|||
* **Easy to use**: It's easy to use for the final users. Automatic help commands, and (optional) 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 sub-commands, with options and arguments.
|
||||
* **Grow large**: Grow in complexity as much as you want, create arbitrarily complex trees of commands and groups subcommands, with options and arguments.
|
||||
|
||||
## Requirements
|
||||
|
||||
|
|
@ -94,7 +94,11 @@ $ python main.py --help
|
|||
Usage: main.py [OPTIONS] NAME
|
||||
|
||||
Options:
|
||||
--help Show this message and exit.
|
||||
--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.
|
||||
|
||||
// You get a ✨ auto completion ✨ for free, installed with --install-completion
|
||||
|
||||
// Now pass the NAME argument
|
||||
$ python main.py Camila
|
||||
|
|
@ -112,11 +116,11 @@ This was the simplest example possible.
|
|||
|
||||
Now let's see one a bit more complex.
|
||||
|
||||
### An example with two sub-commands
|
||||
### An example with two subcommands
|
||||
|
||||
Modify the file `main.py`.
|
||||
|
||||
Create a `typer.Typer()` app, and create two sub-commands with their parameters.
|
||||
Create a `typer.Typer()` app, and create two subcommands with their parameters.
|
||||
|
||||
```Python hl_lines="3 6 11 20"
|
||||
import typer
|
||||
|
|
@ -145,7 +149,7 @@ And that will:
|
|||
|
||||
* Explicitly create a `typer.Typer` app.
|
||||
* The previous `typer.run` actually creates one implicitly for you.
|
||||
* Add two sub-commands with `@app.command()`.
|
||||
* Add two subcommands with `@app.command()`.
|
||||
* Execute the `app()` itself, as if it was a function (instead of `typer.run`).
|
||||
|
||||
### Run the upgraded example
|
||||
|
|
@ -159,13 +163,15 @@ $ python main.py --help
|
|||
Usage: main.py [OPTIONS] COMMAND [ARGS]...
|
||||
|
||||
Options:
|
||||
--help Show this message and exit.
|
||||
--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
|
||||
|
||||
// You have 2 sub-commands (the 2 functions): goodbye and hello
|
||||
// You have 2 subcommands (the 2 functions): goodbye and hello
|
||||
|
||||
// Now get the --help for hello
|
||||
|
||||
|
|
@ -231,7 +237,7 @@ or for a `bool` flag:
|
|||
force: bool
|
||||
```
|
||||
|
||||
And similarly for **files**, **paths**, **enums** (choices), etc. And there are tools to create **groups of sub-commands**, add metadata, extra **validation**, etc.
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -43,15 +43,18 @@ But by default, it all **"just works"**.
|
|||
The resulting CLI apps created with **Typer** have the nice features of many "pro" command line programs you probably already love.
|
||||
|
||||
* Automatic help commands and options.
|
||||
* Automatic command and sub-command structure handling (you will see more about sub-commands in the Tutorial - User Guide).
|
||||
* Automatic autocompletion for the CLI app in all operating systems, in all the shells (Bash, Zsh, Fish, PowerShell), so that the final user of your app can just hit <kbd>TAB</kbd> and get the options of sub-commands. *
|
||||
* Automatic command and subcommand structure handling (you will see more about subcommands in the Tutorial - User Guide).
|
||||
* Automatic autocompletion for the CLI app in all operating systems, in all the shells (Bash, Zsh, Fish, PowerShell), so that the final user of your app can just hit <kbd>TAB</kbd> and get the available options or subcommands. *
|
||||
|
||||
!!! note "* Autocompletion"
|
||||
For the autocompletion to work on all shells you also need to add the dependency `click-completion`.
|
||||
|
||||
Just that. And **Typer** does the rest.
|
||||
|
||||
If **Typer** detects `click-completion` installed, it will automatically create a command to install completion for the user's shell.
|
||||
If **Typer** detects `click-completion` installed, it will automatically create 2 *CLI options*:
|
||||
|
||||
* `--install-completion`: Install completion for the current shell.
|
||||
* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
|
||||
|
||||
Then you can tell the user to run that command and the rest will just work.
|
||||
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ The key features are:
|
|||
* **Easy to use**: It's easy to use for the final users. Automatic help commands, and (optional) 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 sub-commands, with options and arguments.
|
||||
* **Grow large**: Grow in complexity as much as you want, create arbitrarily complex trees of commands and groups subcommands, with options and arguments.
|
||||
|
||||
## Requirements
|
||||
|
||||
|
|
@ -94,7 +94,11 @@ $ python main.py --help
|
|||
Usage: main.py [OPTIONS] NAME
|
||||
|
||||
Options:
|
||||
--help Show this message and exit.
|
||||
--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.
|
||||
|
||||
// You get a ✨ auto completion ✨ for free, installed with --install-completion
|
||||
|
||||
// Now pass the NAME argument
|
||||
$ python main.py Camila
|
||||
|
|
@ -112,11 +116,11 @@ This was the simplest example possible.
|
|||
|
||||
Now let's see one a bit more complex.
|
||||
|
||||
### An example with two sub-commands
|
||||
### An example with two subcommands
|
||||
|
||||
Modify the file `main.py`.
|
||||
|
||||
Create a `typer.Typer()` app, and create two sub-commands with their parameters.
|
||||
Create a `typer.Typer()` app, and create two subcommands with their parameters.
|
||||
|
||||
```Python hl_lines="3 6 11 20"
|
||||
import typer
|
||||
|
|
@ -145,7 +149,7 @@ And that will:
|
|||
|
||||
* Explicitly create a `typer.Typer` app.
|
||||
* The previous `typer.run` actually creates one implicitly for you.
|
||||
* Add two sub-commands with `@app.command()`.
|
||||
* Add two subcommands with `@app.command()`.
|
||||
* Execute the `app()` itself, as if it was a function (instead of `typer.run`).
|
||||
|
||||
### Run the upgraded example
|
||||
|
|
@ -159,13 +163,15 @@ $ python main.py --help
|
|||
Usage: main.py [OPTIONS] COMMAND [ARGS]...
|
||||
|
||||
Options:
|
||||
--help Show this message and exit.
|
||||
--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
|
||||
|
||||
// You have 2 sub-commands (the 2 functions): goodbye and hello
|
||||
// You have 2 subcommands (the 2 functions): goodbye and hello
|
||||
|
||||
// Now get the --help for hello
|
||||
|
||||
|
|
@ -231,7 +237,7 @@ or for a `bool` flag:
|
|||
force: bool
|
||||
```
|
||||
|
||||
And similarly for **files**, **paths**, **enums** (choices), etc. And there are tools to create **groups of sub-commands**, add metadata, extra **validation**, etc.
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -37,14 +37,24 @@ All the code blocks can be copied and used directly (they are tested Python file
|
|||
|
||||
To run any of the examples, copy the code to a file `main.py`, and run it:
|
||||
|
||||
```bash
|
||||
python main.py
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ python main.py
|
||||
|
||||
✨ The magic happens here ✨
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
It is **HIGHLY encouraged** that you write or copy the code, edit it and run it locally.
|
||||
|
||||
Using it in your editor is what really shows you the benefits of Typer, seeing how little code you have to write, all the type checks, autocompletion, etc.
|
||||
|
||||
And running the examples is what will really help you understand what is going on.
|
||||
|
||||
You can learn a lot more by running some examples and playing around with them than by reading all the docs here.
|
||||
|
||||
---
|
||||
|
||||
## Install Typer
|
||||
|
|
@ -53,8 +63,14 @@ The first step is to install Typer.
|
|||
|
||||
For the tutorial, you might want to install it with all the optional dependencies and features:
|
||||
|
||||
```bash
|
||||
pip install typer[all]
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ pip install typer[all]
|
||||
---> 100%
|
||||
Successfully installed typer click colorama click-completion
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
...that also includes `colorama` and `click-completion`.
|
||||
|
|
|
|||
Loading…
Reference in a new issue