Skip to content

Commit

Permalink
✨ Richify, add integrations with Rich everywhere (#419)
Browse files Browse the repository at this point in the history
  • Loading branch information
@tiangolo
tiangolo committed Jul 12, 2022
1 parent 8212e73 commit 6208b5b
Show file tree
Hide file tree
Showing 250 changed files with 3,489 additions and 706 deletions.
147 changes: 88 additions & 59 deletions README.md
View file
Expand Up @@ -56,13 +56,15 @@ Python 3.6+
<div class="termy">

```console
$ pip install typer
$ pip install "typer[all]"
---> 100%
Successfully installed typer
```

</div>

**Note**: that will include <a href="https://rich.readthedocs.io/" class="external-link" target="_blank">Rich</a>. Rich is the recommended library to *display* information on the terminal, it is optional, but when installed, it's deeply integrated into **Typer** to display beautiful output.

## Example

### The absolute minimum
Expand All @@ -74,7 +76,7 @@ import typer


def main(name: str):
typer.echo(f"Hello {name}")
print(f"Hello {name}")


if __name__ == "__main__":
Expand All @@ -92,23 +94,33 @@ 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.
<font color="#F4BF75">Usage: </font>main.py [OPTIONS] NAME
<font color="#A5A5A1">Try </font><font color="#44919F">&apos;main.py </font><font color="#44919F"><b>--help</b></font><font color="#44919F">&apos;</font><font color="#A5A5A1"> for help.</font>
<font color="#F92672">╭─ Error ───────────────────────────────────────────╮</font>
<font color="#F92672">│</font> Missing argument &apos;NAME&apos;. <font color="#F92672">│</font>
<font color="#F92672">╰───────────────────────────────────────────────────╯</font>

Error: Missing argument 'NAME'.

// You get a --help for free
$ python main.py --help

Usage: main.py [OPTIONS] NAME

Arguments:
NAME [required]

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.
<b> </b><font color="#F4BF75"><b>Usage: </b></font><b>main.py [OPTIONS] NAME </b>
<b> </b>
<font color="#A5A5A1">╭─ Arguments ───────────────────────────────────────╮</font>
<font color="#A5A5A1">│ </font><font color="#F92672">*</font> name <font color="#F4BF75"><b>TEXT</b></font> [default: None] <font color="#A6194C">[required]</font> │
<font color="#A5A5A1">╰───────────────────────────────────────────────────╯</font>
<font color="#A5A5A1">╭─ Options ─────────────────────────────────────────╮</font>
<font color="#A5A5A1">│ </font><font color="#A1EFE4"><b>--install-completion</b></font> Install completion │
<font color="#A5A5A1">│ for the current │</font>
<font color="#A5A5A1">│ shell. │</font>
<font color="#A5A5A1">│ </font><font color="#A1EFE4"><b>--show-completion</b></font> Show completion for │
<font color="#A5A5A1">│ the current shell, │</font>
<font color="#A5A5A1">│ to copy it or │</font>
<font color="#A5A5A1">│ customize the │</font>
<font color="#A5A5A1">│ installation. │</font>
<font color="#A5A5A1">│ </font><font color="#A1EFE4"><b>--help</b></font> Show this message │
<font color="#A5A5A1">│ and exit. │</font>
<font color="#A5A5A1">╰───────────────────────────────────────────────────╯</font>

// When you create a package you get ✨ auto-completion ✨ for free, installed with --install-completion

Expand Down Expand Up @@ -144,15 +156,15 @@ app = typer.Typer()

@app.command()
def hello(name: str):
typer.echo(f"Hello {name}")
print(f"Hello {name}")


@app.command()
def goodbye(name: str, formal: bool = False):
if formal:
typer.echo(f"Goodbye Ms. {name}. Have a good day.")
print(f"Goodbye Ms. {name}. Have a good day.")
else:
typer.echo(f"Bye {name}!")
print(f"Bye {name}!")


if __name__ == "__main__":
Expand All @@ -168,53 +180,85 @@ And that will:

### Run the upgraded example

Check the new help:

<div class="termy">

```console
// Check the --help
$ python main.py --help

Usage: main.py [OPTIONS] COMMAND [ARGS]...
<b> </b><font color="#F4BF75"><b>Usage: </b></font><b>main.py [OPTIONS] COMMAND [ARGS]... </b>
<b> </b>
<font color="#A5A5A1">╭─ Options ─────────────────────────────────────────╮</font>
<font color="#A5A5A1">│ </font><font color="#A1EFE4"><b>--install-completion</b></font> Install completion │
<font color="#A5A5A1">│ for the current │</font>
<font color="#A5A5A1">│ shell. │</font>
<font color="#A5A5A1">│ </font><font color="#A1EFE4"><b>--show-completion</b></font> Show completion for │
<font color="#A5A5A1">│ the current shell, │</font>
<font color="#A5A5A1">│ to copy it or │</font>
<font color="#A5A5A1">│ customize the │</font>
<font color="#A5A5A1">│ installation. │</font>
<font color="#A5A5A1">│ </font><font color="#A1EFE4"><b>--help</b></font> Show this message │
<font color="#A5A5A1">│ and exit. │</font>
<font color="#A5A5A1">╰───────────────────────────────────────────────────╯</font>
<font color="#A5A5A1">╭─ Commands ────────────────────────────────────────╮</font>
<font color="#A5A5A1">│ </font><font color="#A1EFE4"><b>goodbye </b></font> │
<font color="#A5A5A1">│ </font><font color="#A1EFE4"><b>hello </b></font> │
<font color="#A5A5A1">╰───────────────────────────────────────────────────╯</font>

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.
// You have 2 subcommands (the 2 functions): goodbye and hello
```

Commands:
goodbye
hello
</div>

// You have 2 subcommands (the 2 functions): goodbye and hello
Now check the help for the `hello` command:

// Now get the --help for hello
<div class="termy">

```console
$ python main.py hello --help

Usage: main.py hello [OPTIONS] NAME
<b> </b><font color="#F4BF75"><b>Usage: </b></font><b>main.py hello [OPTIONS] NAME </b>
<b> </b>
<font color="#A5A5A1">╭─ Arguments ───────────────────────────────────────╮</font>
<font color="#A5A5A1">│ </font><font color="#F92672">*</font> name <font color="#F4BF75"><b>TEXT</b></font> [default: None] <font color="#A6194C">[required]</font> │
<font color="#A5A5A1">╰───────────────────────────────────────────────────╯</font>
<font color="#A5A5A1">╭─ Options ─────────────────────────────────────────╮</font>
<font color="#A5A5A1">│ </font><font color="#A1EFE4"><b>--help</b></font> Show this message and exit. │
<font color="#A5A5A1">╰───────────────────────────────────────────────────╯</font>
```

Arguments:
NAME [required]
</div>

Options:
--help Show this message and exit.
And now check the help for the `goodbye` command:

// And now get the --help for goodbye
<div class="termy">

```console
$ python main.py goodbye --help

Usage: main.py goodbye [OPTIONS] NAME
<b> </b><font color="#F4BF75"><b>Usage: </b></font><b>main.py goodbye [OPTIONS] NAME </b>
<b> </b>
<font color="#A5A5A1">╭─ Arguments ───────────────────────────────────────╮</font>
<font color="#A5A5A1">│ </font><font color="#F92672">*</font> name <font color="#F4BF75"><b>TEXT</b></font> [default: None] <font color="#A6194C">[required]</font> │
<font color="#A5A5A1">╰───────────────────────────────────────────────────╯</font>
<font color="#A5A5A1">╭─ Options ─────────────────────────────────────────╮</font>
<font color="#A5A5A1">│ </font><font color="#A1EFE4"><b>--formal</b></font> <font color="#AE81FF"><b>--no-formal</b></font> [default: no-formal] │
<font color="#A5A5A1">│ </font><font color="#A1EFE4"><b>--help</b></font> Show this message │
<font color="#A5A5A1">│ and exit. │</font>
<font color="#A5A5A1">╰───────────────────────────────────────────────────╯</font>

// Automatic --formal and --no-formal for the bool option 🎉
```

Arguments:
NAME [required]
</div>

Options:
--formal / --no-formal [default: False]
--help Show this message and exit.
Now you can try out the new command line application:

// Automatic --formal and --no-formal for the bool option 🎉
<div class="termy">

// And if you use it with the hello command
```console
// Use it with the hello command

$ python main.py hello Camila

Expand Down Expand Up @@ -271,27 +315,12 @@ Typer uses <a href="https://click.palletsprojects.com/" class="external-link" ta

But you can also install extras:

* <a href="https://rich.readthedocs.io/en/stable/index.html" class="external-link" target="_blank">Rich</a>: and Typer will show nicely formatted errors automatically.
* <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://rich.readthedocs.io/en/stable/index.html" class="external-link" target="_blank"><code>rich</code></a>: and Typer will show nicely formatted errors automatically.
* <a href="https://github.com/sarugaku/shellingham" class="external-link" target="_blank"><code>shellingham</code></a>: and Typer will 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`.

You can install `typer` with `colorama` and `shellingham` with `pip install typer[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()`.
* etc... you can re-use many of the great available tools for building CLIs.
You can install `typer` with `rich` and `shellingham` with `pip install typer[all]`.

## License

Expand Down
4 changes: 3 additions & 1 deletion docs/css/termynal.css
View file
Expand Up @@ -17,14 +17,16 @@
max-width: 100%;
background: var(--color-bg);
color: var(--color-text);
font-size: 18px;
/* font-size: 18px; */
font-size: 15px;
/* font-family: 'Fira Mono', Consolas, Menlo, Monaco, 'Courier New', Courier, monospace; */
font-family: 'Roboto Mono', 'Fira Mono', Consolas, Menlo, Monaco, 'Courier New', Courier, monospace;
border-radius: 4px;
padding: 75px 45px 35px;
position: relative;
-webkit-box-sizing: border-box;
box-sizing: border-box;
line-height: 1.2;
}

[data-termynal]:before {
Expand Down

0 comments on commit 6208b5b

Please sign in to comment.