Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

✨ Richify, add integrations with Rich everywhere #419

Merged
merged 49 commits into from
Jul 12, 2022
Merged

✨ Richify, add integrations with Rich everywhere #419

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
49 commits
Select commit Hold shift + click to select a range
fcbfb66
✨ Add first version of rich_utils, from rich-click, refactored, updated
tiangolo Jul 8, 2022
0a02dea
✨ Use rich_utils in custom Click classes in Typer
tiangolo Jul 8, 2022
cde0aad
🐛 Fix type annotations in models
tiangolo Jul 9, 2022
e4b848d
♻️ Refactor Rich utils, remove unneeded, unsupported, untested configs
tiangolo Jul 9, 2022
c632eba
✨ Add support for config for rich_markdown_enable and rich_markup_enable
tiangolo Jul 9, 2022
c4bf617
♻️ Refactor flags for markup, make markdown and Rich markup exclusive
tiangolo Jul 9, 2022
624473e
✨ Add parameter rich_help_panel
tiangolo Jul 10, 2022
6d5ad22
♻️ Refactor and cleanup rich_utils
tiangolo Jul 10, 2022
c0bf289
✅ Update tests for compatibility with Rich
tiangolo Jul 10, 2022
e4aec72
✨ Add highlighting for negative options
tiangolo Jul 10, 2022
b0c8eb3
🐛 Fix exit code for explicit Exit exceptions with Rich support
tiangolo Jul 10, 2022
7071517
✅ Fix tests for rich support with negative options
tiangolo Jul 10, 2022
4de55ea
✅ Add tests for coverage
tiangolo Jul 10, 2022
04bc9b7
💄 Adjust Termy font size
tiangolo Jul 11, 2022
2f86921
♻️ Refactor typer.echo() to print(), anything worth using typer.echo(…
tiangolo Jul 11, 2022
501f3a9
📝 Update docs, show Rich output in console demos
tiangolo Jul 11, 2022
0e3f771
📝 Add/update sources for examples using Rich
tiangolo Jul 11, 2022
5ebafee
♻️ Update typer.echo to print in a missing example file
tiangolo Jul 11, 2022
22f5102
📝 Add docs for using Rich with Typer
tiangolo Jul 11, 2022
1b615f1
✅ Add new tests for Rich utils
tiangolo Jul 11, 2022
08578b1
💄 Tweak line height of terminals in docs, to better show Rich output
tiangolo Jul 12, 2022
ccc208b
🐛 Fix parameter name for rich_help_panel
tiangolo Jul 12, 2022
6220b9d
✨ Add rich_help_panel for commands
tiangolo Jul 12, 2022
ff0454f
🐛 Fix type annotations in params
tiangolo Jul 12, 2022
4100b93
✨ Add example sources for rich_help_panel
tiangolo Jul 12, 2022
dd7d60e
📝 Add docs for Rich docstrings and rich_help_panel
tiangolo Jul 12, 2022
2cc9e9a
✅ Add tests for rich_help_panel
tiangolo Jul 12, 2022
6ffd055
✨ Add source examples for deprecating commands
tiangolo Jul 12, 2022
7f6348a
📝 Add docs for deprecating commands
tiangolo Jul 12, 2022
538e4b6
✅ Add tests for deprecating commands
tiangolo Jul 12, 2022
00bdebf
✨ Upgrade rich_utils to show deprecated commands
tiangolo Jul 12, 2022
3a768fb
✅ Update test
tiangolo Jul 12, 2022
c432e3d
✨ Add support for Rich text in epilogue
tiangolo Jul 12, 2022
c0d6f62
✨ Add source example for epilog
tiangolo Jul 12, 2022
a86a658
📝 Add docs for help epilog
tiangolo Jul 12, 2022
c975765
✅ Add test for epilog
tiangolo Jul 12, 2022
691a4c9
♻️ Update compatibility with Click 7.x
tiangolo Jul 12, 2022
357fb60
🔇 Add mypy ignore for Click 7
tiangolo Jul 12, 2022
0321b1d
🐛 Fix stderr output
tiangolo Jul 12, 2022
b9c45f2
✅ Update tests for compatibility with Rich
tiangolo Jul 12, 2022
fd78454
🎨 Fix type annotation in rich_utils
tiangolo Jul 12, 2022
8f0eaf8
✅ Fix test with compatibility with Rich
tiangolo Jul 12, 2022
3dcf870
🔇 Disable colors in GITHUB_ACTIONS to try tests
tiangolo Jul 12, 2022
0481647
✅ Config terminal size for tests
tiangolo Jul 12, 2022
bd31ae7
✨ Add support for disabling custom tracebacks with an env var
tiangolo Jul 12, 2022
67d4d16
✅ Add tests for disabling traceback with an env var
tiangolo Jul 12, 2022
6c43a9d
👷 Add _TYPER_FORCE_DISABLE_TERMINAL env var to disable colors, takes …
tiangolo Jul 12, 2022
8230d2b
🎨 Cleanup rich_utils
tiangolo Jul 12, 2022
f5d2e47
👷 Trigger CI because Codecov is acting up again
tiangolo Jul 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
147 changes: 88 additions & 59 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
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
Open in desktop
Original file line number Diff line number Diff line change
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