Typer, build great CLIs. Easy to code. Based on Python type hints.

Last update: Jan 02, 2023

Overview

Typer, build great CLIs. Easy to code. Based on Python type hints.

Documentation: https://typer.tiangolo.com

Source Code: https://github.com/tiangolo/typer

Typer is a library for building CLI applications that users will love using and developers will love creating. Based on Python 3.6+ type hints.

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.

FastAPI of CLIs

Typer is FastAPI's little sibling.

And it's intended to be the FastAPI of CLIs.

Requirements

Python 3.6+

Typer stands on the shoulders of a giant. Its only internal dependency is Click.

Installation

$ pip install typer
---> 100%
Successfully installed typer

Example

The absolute minimum

Create a file main.py with:

import typer


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


if __name__ == "__main__":
    typer.run(main)

Run it

Run your application:

// 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:
  --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.

// 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! 🎉

Note: auto-completion works when you create a Python package and run it with --install-completion or when you use Typer CLI.

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.

import 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

// Check the --help
$ 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

// 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: False]
  --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.

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.6+.

For example, for an int:

total: int

or for a bool flag:

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 Typer CLI.

For a more complete example including more features, see the Tutorial - User Guide.

Optional Dependencies

Typer uses Click internally. That's the only dependency.

But you can also install extras:

colorama: 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. wasabi, blessings.
shellingham: 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:

click-spinner: to show the user that you are loading data. A Click plug-in.
- There are several other Click plug-ins at click-contrib that you can explore.
tabulate: to automatically display tabular data nicely. Independent of Click or Typer.
tqdm: 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.

License

This project is licensed under the terms of the MIT license.

Comments

ImportError: cannot import name 'get_terminal_size' from 'click.termui'
First Check

[X] I added a very descriptive title to this issue.

[X] I used the GitHub search to find a similar issue and didn't find it.

[X] I searched the Typer documentation, with the integrated search.

[X] I already searched in Google "How to X in Typer" and didn't find any information.

[X] I already read and followed all the tutorial in the docs and didn't find an answer.

[X] I already checked if it is not related to Typer but to Click.

Commit to Help

[X] I commit to help with one of those options 👆

Example Code

import typer

Description

Install latest versions of typer (0.4.0) and click (8.1.0)

Run script with single line import typer

Import fails due to method get_terminal_size having been removed in click 8.1.0 (https://github.com/pallets/click/pull/2130)

Traceback (most recent call last): File "test.py", line 1, in <module> import typer File "/.venv/lib/python3.8/site-packages/typer/__init__.py", line 12, in <module> from click.termui import get_terminal_size as get_terminal_size ImportError: cannot import name 'get_terminal_size' from 'click.termui' (/.venv/lib/python3.8/site-packages/click/termui.py)

Operating System

Linux

Operating System Details

Ubunutu 20.04

Typer Version

0.4.0

Python Version

Python 3.8.10

Additional Context

No response
question answered
opened by jmhummel 27
running typer cli command from python code

How can i trigger/run typer cli specific command from python code. I guess i need to emulate command line arguments some where but not sure. Can you please help on this?

Cli: python main.py goodbye --formal Camila

From Code: i want to run specific command based on my need. how do i pass command line arguments, some thing like: typer_app( "goodbye --formal Camila" )
question answered

opened by blnprasad 22

[FEATURE] Handling Mutliple Variable Length Arguments

I'm not familiar with the internals of typer and whether this is feasible, but it would be nice if it were possible to implement a command like the following:

from typing import Optional, List

import typer

app = typer.Typer()


@app.command()
def main(first_list: List[str], option: bool = False, second_list: List[str] = ()):
    print(first_list, second_list)

Where the expected behavior is:

$ python main.py a b c --option d e f
('a', 'b', 'c') ('d', 'e', 'f')
$ python main.py a b c d e f --option
('a', 'b', 'c', 'd', 'e', 'f') ()
$ python main.py a b c d e f
('a', 'b', 'c', 'd', 'e', 'f') ()

However the actual behavior in this case does not adhere to the above:

$ python main.py a b c --option d e f
('a', 'b', 'c', 'd', 'e', 'f') True ()

This can presently be achieved in argparse quite concisely:

import argparse

def main():
    cli = argparse.ArgumentParser()
    cli.add_argument(
        "first_list", nargs="*", type=str,
    )
    cli.add_argument(
        "--option", nargs="*", type=str, default=[],
    )
    args = cli.parse_args()
    print(args.first_list, args.option)

enhancement answered

opened by rmorshea 17

[QUESTION] Dependency Injection

First check

[X] I used the GitHub search to find a similar issue and didn't find it.
[X] I searched the Typer documentation, with the integrated search.
[X] I already searched in Google "How to X in Typer" and didn't find any information.
[X] I already searched in Google "How to X in Click" and didn't find any information.

First of all, thank you for your amazing tools, it helps my team and I to build great products !

Description

How can I inject a Database connection to a "cli function" ?

I was looking for a mecanism like Depends in FastAPI (https://fastapi.tiangolo.com/tutorial/dependencies/)

Additional context

I'm trying to create a cli which read files and insert them to a database but one of my subcommands is depending of a Database connection.

For the moment I've used:

save_app = typer.Typer()


def get_db():
    typer.echo("Initializing database")
    db = VerticaDB(
        host=conf.get_vertica_host(),
        port=conf.get_vertica_port(),
        user=conf.get_vertica_user(),
        password=conf.get_vertica_password(),
        database=conf.get_vertica_database()
    )
    return db


@save_app.command("save")
def ingest_snitch_file(
        path_to_log_file: Path = typer.Option(
            ...,
            exists=True,
            readable=True,
            envvar='PATH_TO_SNITCH_FILE'
        ),
        db=typer.Option(
            hidden=True,
            default=get_db()
        )
):
    """
    Ingest snitch files to Database
    """
    snitch = Snitch(
        db=db,
        path_to_snitch=path_to_log_file,
        table_schema=conf.get_vertica_table_schema(),
        table_name=conf.get_vertica_table_name()
    )
    snitch.insert_log_to_database()

question

opened by Leletir 17

✨ Richify, add integrations with Rich everywhere

✨ Richify, add integrations with Rich everywhere.

This started with a copy of https://github.com/ewels/rich-click, and started evolving from there with several refactors.

Rich is still an optional dependency, but when installed, it's used in several places.

This PR includes several things related to the new deep integration with Rich.

Use standard print

Now typer.echo() is no longer recommended, for the simplest cases, standard print() is recommended and documented.

And for more complex cases, Rich is recommended. Several places in the docs have been updated to recommend Rich, e.g. the whole section for "Printing and Colors".

Rich for --help

When Rich is installed, it's used to format all the output of --help commands.

New docs for deprecated

New docs for the deprecated parameter in commands, it includes special formatting and handling with Rich.

Rich Markup and Markdown

Rich Markup and Markdown can be enabled with a new parameter rich_markup_mode that can be None, "rich", "markdown".

Including a new section in the docs for it.

When using "rich" the content in help strings, epilog and docstrings is parsed with Rich Markup, when "markdown" is used, then it's parsed with Rich Markdown.

Help Panels

There's a new parameter rich_help_panel in typer.Typer(),app.add_typer(), app.command(), typer.Argument(), and typer.Option().

Setting it to a name will render that component in a Rich panel in the help from the --help option.

New docs for that in the sections about help for CLI arguments, CLI options, and commands.

Epilog docs

New docs for using the epilog, also rendered with Rich.

Tests

Updated tests and many new tests to keep 100% of test coverage with the new Rich utils and integrations.

opened by tiangolo 13
Default to add_completion == False in typer.run
First Check

[X] I added a very descriptive title to this issue.

[X] I used the GitHub search to find a similar issue and didn't find it.

[X] I searched the Typer documentation, with the integrated search.

[X] I already searched in Google "How to X in Typer" and didn't find any information.

[X] I already read and followed all the tutorial in the docs and didn't find an answer.

[X] I already checked if it is not related to Typer but to Click.

Commit to Help

[X] I commit to help with one of those options 👆

Example Code

from typing import Any, Callable import typer # Have typer.run() behave like: def run(function: Callable[..., Any], add_completion: bool = False) -> Any: app = typer.Typer(add_completion=add_completion) app.command()(function) app() def main(name: str) -> None: print(f"Hello, {name}!") if __name__ == "__main__": run(main) # defaults to suppressing completion installation options: # --install-completion [bash|zsh|fish|powershell|pwsh] # Install completion for the specified shell. # --show-completion [bash|zsh|fish|powershell|pwsh] # Show completion for the specified shell, to # copy it or customize the installation.

Description

I thought I'd introduce Typer via some small scripts where argparse is unwieldy. But having the autocompletion options in the command help scared the absolute crap out of a number of people: they assumed I was overengineering, that it would be complicated. Luckily you can suppress those, as I discovered by reading the source.

(Working to bring the folks I scared around, because typer is an essential quality of life improvement for anyone using Python for pretty much anything.)

Wanted Solution

I'd like to see:

add_completion default to False in typer.run. If you're doing the kind of program that warrants completion, you're probably using typer.Typer anyway.

Some really minimal, sketchy documentation of the full API. There are other gems in there, eg, one thing people really liked that also isn't documented is no_args_is_help. People love that for ops scripts. Makes them feel safe. Come to think of it, I wish I could pass that to typer.run as well...

I understand (1) is a big change and not do be taken lightly, and as I discovered in my description of (2) it brings up whether you should be able to pass other Typer options via run. But the first thing I did when I fired up typer for the first time is wonder, "can I suppress those completion options," searched the docs, and found nothing, so (2) would have solved my problem.

I looked at main.py and run is simple as could be, so I could certainly make a PR for (1) if it's wanted. The instructions for contributing documentation look straightforward enough so I could take a crack at (2). That's a little more intimidating given the high standard of the documentation, but I could at least do a first draft.

Wanted Code

# in mycmd.py typer.run(main) # python mycmd.py --help # # *no completion options*

Alternatives

Minimally documenting the typer.Typer API. There's already an issue about documenting add_completion: https://github.com/tiangolo/typer/issues/141, why not do all of 'em?

Operating System

macOS

Operating System Details

No response

Typer Version

0.4.1

Python Version

Python 3.10.2

Additional Context

No response
enhancement
opened by ajlive 13

[QUESTION] How to use Typer within Objects

Hello,

I already used Typer for a few short CLIs but now I'd like to use it for a bigger, object-oriented project. I thought I find a way to use it correctly, but I'm getting errors related to the "self" argument.

My code looks like this:

main_menu.py

class MainMenu:
    typer_app = typer.Typer()
    typer_app.add_typer(TournamentMenu.typer_app, name="tournament")

    def __init__(self):
        self.typer_app()
        self.tournament_handler = None
        self.print_menu()
        self.user_selection()

    def print_menu(self):
        number = typer.style("1. ", bold=True)
        typer.echo(number + "Tournois")

        number = typer.style("2. ", bold=True)
        typer.echo(number + "Gérer les joueurs")

    def user_selection(self):
        selection = typer.prompt("Entrez votre sélection: ")
        typer.echo("\n")

        if selection == "1":
            self.open_tournament_menu()
        else:
            self.user_selection()

    def open_tournament_menu(self):
        TournamentMenu()

tournament_menu.py

class TournamentMenu:
    typer_app = typer.Typer()

    def __init__(self):
        self.typer_app()
        self.print_menu()
        self.user_selection()

    def print_menu(self):
        number = typer.style("1. ", bold=True)
        typer.echo(number + "Commencer un nouveau tournoi")

        number = typer.style("2. ", bold=True)
        typer.echo(number + "Charger un tournoi")

    def user_selection(self):
        selection = typer.prompt("Entrez votre sélection: ")

        if selection == "1":
            self.create_new_tournament()
        else:
            self.user_selection()

    @typer_app.command("new")
    def create_new_tournament(self=None):
        NewTournamentMenu()

new_tournament_menu.py

class NewTournamentMenu:
    typer_app = typer.Typer()

    @typer_app.command()
    def __init__(self):
        self.typer_app()
        self.print_menu()
        self.user_selection()

    def print_menu(self):
        number = typer.style("1. ", bold=True)
        typer.echo(number + "Commencer un nouveau tournoi")

        number = typer.style("2. ", bold=True)
        typer.echo(number + "Charger un tournoi")

    def user_selection(self):
        selection = typer.prompt("Entrez votre sélection: ")

        if selection == "1":
            pass
        else:
            self.user_selection()

But for example with python main.py tournament newI'm getting:

Usage: dev.py [OPTIONS] SELF
Try 'dev.py --help' for help.

Error: Got unexpected extra argument (new)

So, is it possible to use typer in this kind of object oriented situation ? What am I missing ?

question

opened by PabloLec 13

Add click 8.1.0 support

Some deprecated code was removed in https://github.com/pallets/click/pull/2130 resulting in the failed import of get_terminal_size from click. Per the recommendation in Click's release notes, we can import from shutil instead.

get_terminal_size can probably be dropped from Typer's interface in the future since it's been dropped from Click's, but I'll leave that decision to a future PR. This change is backwards compatible.

See https://click.palletsprojects.com/en/8.1.x/changes/#version-8-1-0 Closes https://github.com/tiangolo/typer/issues/377

opened by madkinsz 12
⬆ [pre-commit.ci] pre-commit autoupdate
updates:

github.com/asottile/pyupgrade: v2.34.0 → v3.2.0

https://github.com/myint/autoflake → https://github.com/PyCQA/autoflake

github.com/PyCQA/autoflake: v1.4 → v1.7.7

github.com/psf/black: 22.3.0 → 22.10.0
opened by pre-commit-ci[bot] 10
[QUESTION] How to add short option "-h" to "--help" callback
First check

[x] I used the GitHub search to find a similar issue and didn't find it.

[x] I searched the Typer documentation, with the integrated search.

[x] I already searched in Google "How to X in Typer" and didn't find any information.

[x] I already searched in Google "How to X in Click" and didn't find any information.

Description

How can I add a short option "-h" to the existing "--help" callback?
question
opened by JeromeK13 10

[QUESTION] using python-rich with Typer

First check

[x] I used the GitHub search to find a similar issue and didn't find it.
[x] I searched the Typer documentation, with the integrated search.
[x] I already searched in Google "How to X in Typer" and didn't find any information.
[x] I already searched in Google "How to X in Click" and didn't find any information.

Description

How can I use python-rich with Typer ?

Eg.

from rich.console import Console

console = Console()

@app.command()
def version() -> None:
    """Show project Version."""
    # typer.secho(f"project Version: {__version__}", fg=typer.colors.BRIGHT_GREEN)

    console.print(f"project Version: {__version__}", style="bold green")

output:

project Version: 0.0.1

the problem that am facing is in test mode

runner = CliRunner()

def test_version_succeeds() -> None:
    """It exits with a status code of zero."""
    result = runner.invoke(app)
    assert result.exit_code == 0
    assert "project" in result.stdout

output:

FAILED tests/test_manage.py::test_version_succeeds - AssertionError: assert 'project' in ''

So is there a way to make them work together ?

question

opened by Mohamed-Kaizen 10

Support Python 3.10 optional union types

In Python 3.10+, recognise that SomeType | None is analogous to Optional[SomeType]. AFAIK, this shouldn't break anything pre-3.10 because it checks things via duck typing. Resolves #371.

Instead of:

from typing import Optional

app = typer.Typer()

@app.command()
def command(option: Optional[str] = None, test: Optional[int] = typer.Option(None)):
  ...

Allow:

app = typer.Typer()

@app.command()
def command(option: str | None = None, test: int | None = typer.Option(None)):
  ...

opened by potatoeggy 3

Accept environment variables named by convention when envvar is not set
First Check

[X] I added a very descriptive title to this issue.

[X] I used the GitHub search to find a similar issue and didn't find it.

[X] I searched the Typer documentation, with the integrated search.

[X] I already searched in Google "How to X in Typer" and didn't find any information.

[X] I already read and followed all the tutorial in the docs and didn't find an answer.

[X] I already checked if it is not related to Typer but to Click.

Commit to Help

[X] I commit to help with one of those options 👆

Example Code

import typer cli = typer.Typer() @cli.command() def configure(file: str = typer.Argument("", envvar="FILE")): print("Configure could be written more succintly if envvar=FILE is created by convention")

Description

We usually define arguments and options as environment variables. We tipically use a simple convention where param becomes PARAM and some_param becomes SOME_PARAM. That adds a bit of boilerplate to method definitions. I would like typer to accept environment variables that match argument and options names by conventions.

I can try to make a pull request if you find this behavior reasonable.

Wanted Solution

I would like that if envvar is not fullfilled in typer, it tries to get that environment variable by convention. I could try to make a pull request with this idea if you find it reasonable.

Wanted Code

import typer cli = typer.Typer() @cli.command() def configure(file: str)): print("Configure accepts FILE as envvar")

Alternatives

No response

Operating System

Linux

Operating System Details

No response

Typer Version

0.7.0

Python Version

Python 3.8.10

Additional Context

No response
enhancement
opened by jruizaranguren 4
Default value for optional multi-value argument
First Check

[X] I added a very descriptive title to this issue.

[X] I used the GitHub search to find a similar issue and didn't find it.

[X] I searched the Typer documentation, with the integrated search.

[X] I already searched in Google "How to X in Typer" and didn't find any information.

[X] I already read and followed all the tutorial in the docs and didn't find an answer.

[X] I already checked if it is not related to Typer but to Click.

Commit to Help

[X] I commit to help with one of those options 👆

Example Code

import typer def main(names: list[str] = typer.Argument(["Peter", "Paul", "Mary"])): for name in names: typer.echo(f"Hi, {name}") if __name__ == '__main__': typer.run(main)

Description

The provided example raises the following error:

Traceback (most recent call last): File "[...]\main.py", line 8, in <module> typer.run(main) TypeError: 'default' is not supported for nargs=-1.

Looking at the Click docs, my understanding is that nargs=-1 is used to denote Variadic arguments, i.e. multi-value arguments.

So if default is not supported for nargs=-1, is there any way to have default values for multi-value arguments in Typer?

Desired behaviour: the default values are used if no argument values are provided, with a help message that looks something like this:

Usage: main.py [OPTIONS] [NAMES]... Arguments: [NAMES]... [default: [Peter, Paul, Mary]] Options: --help Show this message and exit.

Operating System

Windows

Operating System Details

No response

Typer Version

0.7.0

Python Version

3.10.9

Additional Context

I believe this is related to #108, where the conclusion was to use None as default to achieve an optional multi-value argument. However, it would be useful if other default values were supported as well. But this might just be a limitation of Click?

Love the project ❤️
question
opened by mathiazom 0

How to display commands grouped by category when running using `--help` argument

First Check

[x] I added a very descriptive title to this issue.
[X] I used the GitHub search to find a similar issue and didn't find it.
[X] I searched the Typer documentation, with the integrated search.
[X] I already searched in Google "How to X in Typer" and didn't find any information.
[X] I already read and followed all the tutorial in the docs and didn't find an answer.
[X] I already checked if it is not related to Typer but to Click.

Commit to Help

[X] I commit to help with one of those options 👆

Example Code

import typer


# Troubleshooting and Debugging Commands:
def describe(foo: str):
    print(f"{foo}")


def logs(foo: str):
    print(f"{foo}")


def attach(foo: str):
    print(f"{foo}")


def _exec(foo: str):
    print(f"{foo}")


def port_forward(foo: str):
    print(f"{foo}")


def proxy(foo: str):
    print(f"{foo}")


def cp(foo: str):
    print(f"{foo}")


def auth(foo: str):
    print(f"{foo}")


def debug(foo: str):
    print(f"{foo}")


# Advanced Commands:
def diff(foo: str):
    print(f"{foo}")


def _apply(foo: str):
    print(f"{foo}")


def patch(foo: str):
    print(f"{foo}")


def replace(foo: str):
    print(f"{foo}")


def wait(foo: str):
    print(f"{foo}")


def kustomize(foo: str):
    print(f"{foo}")


# Settings Commands:
def label(foo: str):
    print(f"{foo}")


def annotate(foo: str):
    print(f"{foo}")


def completion(foo: str):
    print(f"{foo}")


def main():
    # console = Console()
    app = typer.Typer()

    # Troubleshooting and Debugging Commands
    app.command(short_help="Show details of a specific resource or group of resources")(
        describe
    )
    app.command(short_help="Print the logs for a container in a pod")(logs)
    app.command(short_help="Attach to a running container")(attach)
    app.command("exec", short_help="Execute a command in a container")(_exec)
    app.command(short_help="Forward one or more local ports to a pod")(port_forward)
    app.command(short_help="Run a proxy to the Kubernetes API server")(proxy)
    app.command(short_help="Copy files and directories to and from containers")(cp)
    app.command(short_help="Inspect authorization")(auth)
    app.command(
        short_help="Create debugging sessions for troubleshooting workloads and nodes"
    )(debug)

    # Advanced
    app.command(short_help="Diff the live version against a would-be applied version")(
        diff
    )
    app.command("apply", short_help="Apply a configuration to a resource by file name or stdin")(
        _apply
    )
    app.command(short_help="Update fields of a resource")(patch)
    app.command(short_help="Replace a resource by file name or stdin")(replace)
    app.command(
        short_help="Experimental: Wait for a specific condition on one or many resources"
    )(wait)
    app.command(short_help="Build a kustomization target from a directory or URL")(
        kustomize
    )

    # Settings
    app.command(short_help="Update the labels on a resource")(label)
    app.command(short_help="Update the annotations on a resource")(annotate)
    app.command(
        short_help="Output shell completion code for the specified shell (bash, zsh, fish, or powershell"
    )(completion)
    app()


if __name__ == "__main__":
    main()

Description

Hi, first of all let me tell you I've only been using typer for 20min and I love it, this is a really modern, powerful and very intuitive python package, so congrats about that :)

I've got a question:

I'm trying to figure out how to achieve a similar behaviour to kubectl --help cli in a way that if run python my_typer_cli.py --help I'd be able to see all my commands grouped by categories. How can I achieve a similar behaviour using typer?

Pasting the kubectl output:

$ kubectl --help
kubectl controls the Kubernetes cluster manager.

 Find more information at: https://kubernetes.io/docs/reference/kubectl/

Basic Commands (Beginner):
  create          Create a resource from a file or from stdin
  expose          Take a replication controller, service, deployment or pod and expose it as a new
Kubernetes service
  run             Run a particular image on the cluster
  set             Set specific features on objects

Basic Commands (Intermediate):
  explain         Get documentation for a resource
  get             Display one or many resources
  edit            Edit a resource on the server
  delete          Delete resources by file names, stdin, resources and names, or by resources and
label selector

Deploy Commands:
  rollout         Manage the rollout of a resource
  scale           Set a new size for a deployment, replica set, or replication controller
  autoscale       Auto-scale a deployment, replica set, stateful set, or replication controller

Cluster Management Commands:
  certificate     Modify certificate resources.
  cluster-info    Display cluster information
  top             Display resource (CPU/memory) usage
  cordon          Mark node as unschedulable
  uncordon        Mark node as schedulable
  drain           Drain node in preparation for maintenance
  taint           Update the taints on one or more nodes

Troubleshooting and Debugging Commands:
  describe        Show details of a specific resource or group of resources
  logs            Print the logs for a container in a pod
  attach          Attach to a running container
  exec            Execute a command in a container
  port-forward    Forward one or more local ports to a pod
  proxy           Run a proxy to the Kubernetes API server
  cp              Copy files and directories to and from containers
  auth            Inspect authorization
  debug           Create debugging sessions for troubleshooting workloads and nodes

Advanced Commands:
  diff            Diff the live version against a would-be applied version
  apply           Apply a configuration to a resource by file name or stdin
  patch           Update fields of a resource
  replace         Replace a resource by file name or stdin
  wait            Experimental: Wait for a specific condition on one or many resources
  kustomize       Build a kustomization target from a directory or URL.

Settings Commands:
  label           Update the labels on a resource
  annotate        Update the annotations on a resource
  completion      Output shell completion code for the specified shell (bash, zsh, fish, or
powershell)

Other Commands:
  alpha           Commands for features in alpha
  api-resources   Print the supported API resources on the server
  api-versions    Print the supported API versions on the server, in the form of "group/version"
  config          Modify kubeconfig files
  plugin          Provides utilities for interacting with plugins
  version         Print the client and server version information

Usage:
  kubectl [flags] [options]

Use "kubectl <command> --help" for more information about a given command.
Use "kubectl options" for a list of global command-line options (applies to all commands).

Operating System

Windows

Operating System Details

Windows 10 pro

Typer Version

0.7.0

Python Version

Python 3.10.1

Additional Context

No response

question

opened by brupelo 1

Add rich print using _get_rich_console

This feature allows using rich's print in typer context.

It uses the _get_rich_console to make it more aware of the terminal it sits in. For example, this can be useful if you want to set TERMINAL_WIDTH.

opened by feluelle 6

Releases(0.7.0)

0.7.0(Nov 5, 2022)
Features

✨ Make typer.run() not add completion scripts by default, it only makes sense in installed apps. Also update docs for handling autocompletion in CLI options. PR #488 by @tiangolo.

✨ Add support for Python 3.11, tests in CI and official marker. PR #487 by @tiangolo.

👷 Add CI for Python 3.10. PR #384 by @tiangolo.

Fixes

🎨 Fix type annotation of typer.run(). PR #284 by @yassu.

🎨 Fix type annotations for get_group. PR #430 by @tiangolo.

Docs

📝 Add note about how subcommands with function names using underscores are converted to dashes. PR #403 by @targhs.

📝 Fix typo in docs at docs/tutorial/commands/help.md. PR #466 by @fepegar.

✏ Fix link in docs to datetime.strptime(). PR #464 by @Kobu.

✏ Update first-steps.md, clarify distinction between parameter and argument. PR #176 by @mccarthysean.

✏ Fix broken plac link. PR #275 by @mgielda.

Internal

✅ Add extra tests just for coverage because monkeypatching with strange imports confuses coverage. PR #490 by @tiangolo.

🔧 Tweak pytest coverage. PR #485 by @tiangolo.

➕ Bring back pytest-cov because coverage can't detect pytest-xdist. PR #484 by @tiangolo.

⬆ Bump actions/upload-artifact from 2 to 3. PR #477 by @dependabot[bot].

⬆ Bump actions/checkout from 2 to 3. PR #478 by @dependabot[bot].

⬆ [pre-commit.ci] pre-commit autoupdate. PR #411 by @pre-commit-ci[bot].

⬆ Bump nwtgck/actions-netlify from 1.1.5 to 1.2.4. PR #479 by @dependabot[bot].

⬆ Bump tiangolo/issue-manager from 0.2.0 to 0.4.0. PR #481 by @dependabot[bot].

👷 Move from pytest-cov to coverage and Codecov to Smokeshow. PR #483 by @tiangolo.

➕ Add extra Material for MkDocs deps for docs. PR #482 by @tiangolo.

🔧 Update Dependabot config. PR #476 by @tiangolo.

Source code(tar.gz)
Source code(zip)
0.6.1(Jul 12, 2022)
Fixes

🐛 Fix setting FORCE_TERMINAL with colors 2. PR #424 by @tiangolo.

🐛 Fix setting FORCE_TERMINAL with colors. PR #423 by @tiangolo.

Source code(tar.gz)
Source code(zip)
0.6.0(Jul 12, 2022)
This release adds deep integrations with Rich. ✨

rich is an optional dependency, you can install it directly or it will be included when you install with:

$ pip install "typer[all]"

If Rich is available, it will be used to show the content from --help options, validation errors, and even errors in your app (exception tracebacks).

There are new options to group commands, CLI arguments, and CLI options, support for Rich Console Markup, and more! 🎉

Features

✨ Richify, add integrations with Rich everywhere. PR #419 by @tiangolo.

Recommend Rich as the main information displaying tool, new docs: Printing and Colors.

For most use cases not using Rich, use plain print() instead of typer.echo() in the docs, to simplify the concepts and avoid confusions. New docs: Printing and Colors - typer Echo.

Define help panels for CLI arguments, new docs: CLI Arguments with Help - CLI Argument help panels.

Define help panels for CLI options, new docs: CLI Options with Help - CLI Options help panels.

New docs for deprecating commands: Commands - Command Help - Deprecate a Command.

Support for Rich Markdown in docstrings, CLI parameters help, and epilog with the new parameter typer.Typer(rich_markup_mode="markdown"), new docs: Commands - Command Help - Rich Markdown and Markup.

Support for Rich Markup (different from Markdown) in docstrings, CLI parameters help, and epilog with the new parameter typer.Typer(rich_markup_mode="rich"), new docs: Commands - Command Help - Rich Markdown and Markup.

Define help panels for commands, new docs: Commands - Command Help - Help Panels.

New docs for setting an epilog, with support for Rich Markdown and Console Markup, new docs: Commands - Command Help - Epilog.

✨ Refactor and document handling pretty exceptions. PR #422 by @tiangolo.

Add support for customizing pretty short errors, new docs: Exceptions and Errors.

✨ Allow configuring pretty errors when creating the Typer instance. PR #416 by @tiangolo.

Docs

📝 Add docs for using Rich with Typer. PR #421 by @tiangolo.

Add new docs: Ask with Prompt - Prompt with Rich.

Add new docs to handle progress bars and spinners with Rich: Progress Par.

Internal

⬆️ Upgrade codecov GitHub Action. PR #420 by @tiangolo.

Source code(tar.gz)
Source code(zip)
0.5.0(Jul 6, 2022)
Features

✨ Add pretty error tracebacks for user errors and support for Rich. PR #412 by @tiangolo.

Docs

✏ Fix typo, "ASCII codes" to "ANSI escape sequences". PR #308 by @septatrix.

Source code(tar.gz)
Source code(zip)
0.4.2(Jul 2, 2022)
Fixes

🐛 Fix type conversion for List and Tuple and their internal types. PR #143 by @hellowhistler.

🐛 Fix context_settings for a Typer app with a single command. PR #210 by @daddycocoaman.

Docs

📝 Clarify testing documentation about checking stderr. PR #335 by @cgabard.

✏ Fix typo in docs for CLI Option autocompletion. PR #288 by @graue70.

🎨 Fix header format for "Standard Input" in docs/tutorial/printing.md. PR #386 by @briancohan.

✏ Fix typo in docs/tutorial/terminating.md. PR #382 by @kianmeng.

✏ Fix syntax typo in docs/tutorial/package.md. PR #333 by @ryanstreur.

✏ Fix typo, duplicated word in docs/tutorial/options/required.md.. PR #316 by @michaelriri.

✏ Fix minor typo in index.md. PR #274 by @RmStorm.

✏ Fix double "and" typo in first-steps tutorial. PR #225 by @softwarebloat.

🎨 Fix format in docs explaining datetime parameter type. PR #220 by @DiegoPiloni.

Internal

⬆ [pre-commit.ci] pre-commit autoupdate. PR #404 by @pre-commit-ci[bot].

👷 Fix Material for MkDocs install in CI. PR #395 by @tiangolo.

👷 Add pre-commit CI config. PR #394 by @tiangolo.

👷 Clear MkDocs Insiders cache. PR #393 by @tiangolo.

🔧 Add pre-commit config and formatting. PR #392 by @tiangolo.

👷 Disable installing MkDocs Insiders in forks. PR #391 by @tiangolo.

⬆️ Upgrade Codecov GitHub Action. PR #383 by @tiangolo.

Source code(tar.gz)
Source code(zip)
0.4.1(Mar 30, 2022)
Fixes

🐛 Fix import of get_terminal_size for Click 8.1.0 support and upgrade Black to fix CI. PR #380 by @tiangolo based on original PR #375 by @madkinsz.

Internal

📝 Add Jina's QA Bot to the docs to help people that want to ask quick questions. PR #368 by @tiangolo.

💚 Only test on push when on master, avoid duplicate CI runs from PRs. PR #358 by @tiangolo.

✨ Add support for previewing docs in PRs from forks and enable MkDocs Insiders. PR #357 by @tiangolo.

⬆️ Upgrade MkDocs Material, MDX-Include, and MkDocs structure. PR #356 by @tiangolo.

👷 Update publish GitHub action. PR #325 by @tiangolo.

Source code(tar.gz)
Source code(zip)
0.4.0(Aug 30, 2021)
Features

✨ Add support for Click 8 while keeping compatibility with Click 7. PR #317 by @tiangolo.

Internal

📝 Add Security policy. PR #324 by @tiangolo.

🔧 Add updated issue templates. PR #323 by @tiangolo.

👷 Enable tests for Python 3.9. PR #322 by @tiangolo.

👷 Add GitHub Action Latest Changes. PR #321 by @tiangolo.

👷 Update docs CI name. PR #320 by @tiangolo.

🔧 Add sponsors docs and badge. PR #319 by @tiangolo.

Source code(tar.gz)
Source code(zip)
0.3.2(Aug 16, 2020)
Features

Add support for mypy --strict. Original PR #147 by @victorphoenix3.

Docs

Update docs with new --help showing default values. PR #135 by @victorphoenix3.

Add Optional to docs for CLI Arguments and Options with a default of None. PR #131 by @rkbeatss.

Add valid date formats to docs. PR #122 by @IamCathal.

Internal

Report coverage in XML to support GitHub Actions. PR #146.

Update badges and remove Travis, now that GitHub Actions is the main CI. PR #145.

Source code(tar.gz)
Source code(zip)
0.3.1(Jul 19, 2020)
Add GitHub Actions, move from Travis. PR #144.

Pin dependencies. PR #138.

Add Dependabot. PR #136.

Upgrade Isort to version 5.x.x. PR #137.

Source code(tar.gz)
Source code(zip)
0.3.0(Jun 24, 2020)
Add support for help parameter in CLI arguments:

As help in CLI arguments is not supported by Click, there are two new internal classes (Click sub-classes) to support it:

typer.core.TyperArgument

typer.core.TyperCommand

This includes a new auto-generated help text section Arguments for CLI arguments, showing defaults, required arguments, etc.

It's also possible to disable it and keep the previous behavior, not showing automatic help for CLI arguments (Click's default) using the hidden parameter.

Now show_default is True by default.

And now show_envvar is True by default.

So, default values and env vars are shown in the help text by default, without having to manually enable them, for both CLI arguments and CLI options.

New docs:

CLI Arguments Intro.

Optional CLI Arguments.

CLI Arguments with Default.

CLI Arguments with Help.

CLI Arguments with Environment Variables.

CLI Arguments: Other uses.

CLI arguments with tuples.

Lot's of tests for all the new examples in the new docs, keeping coverage at 100%.

PR #123.

Add docs for calling packages with python -m some_package using __main__.py: Building a Package: Support python -m. PR #121.

Add support for *args and **kwargs when calling the Typer app, just like in Click. PR #120 by @teymour-aldridge.

Fix typos in README and main docs #103 by @mrcartoonster.

Fix typo in docs. PR #98 by @mrcartoonster.

Fix typos and rewording in docs. PR #97 by @mrcartoonster.

Update GitHub Action issue-manager. PR #114.

Source code(tar.gz)
Source code(zip)
0.2.1(Apr 26, 2020)
Add support for forward references (types declared inside of strings). PR #93.

Source code(tar.gz)
Source code(zip)
0.2.0(Apr 26, 2020)
Add support for completion for commands/programs not available on startup.

This allows installing a Typer program/script in a virtual environment and still have completion globally installed.

PR #92.

Add note about typer.echo() and print() for colors in Windows. PR #89.

Upgrade Mkdocs-Material version, update contributing guide style. PR #90.

Source code(tar.gz)
Source code(zip)
0.1.1(Mar 29, 2020)
Fix completion evaluation for Bash and Zsh when the program is not installed/found. PR #83.

Fix completion script for Fish. PR #82.

Fix shell installation for Bash to ~/.bashrc and update Windows development docs. PR #81.

Update coverage badge. PR #78.

Source code(tar.gz)
Source code(zip)
0.1.0(Mar 19, 2020)
Fix coverage instructions. PR #72.

Add docs for Building a Package. PR #71.

Add docs for Using Click (with Typer). PR #70.

Add support for type-based callbacks and autocompletion functions, extra tests and docs:

Extra tests, raising coverage to 100%.

New docs: Printing and Colors: "Standard Output" and "Standard Error".

New docs: Password CLI Option and Confirmation Prompt.

Support for callbacks based on type annotations. New docs: CLI Option Callback and Context.

New docs: Version CLI Option, is_eager.

Support for autocompletion functions based on type annotations. New docs: CLI Option autocompletion.

New docs: Commands: Using the Context.

New docs: Testing.

PR #68.

Fix Zsh completion install script. PR #69.

Fix typo in progressbar example. PR #63 by @ValentinCalomme.

Source code(tar.gz)
Source code(zip)
0.0.11(Mar 16, 2020)
Re-implement completion system:

Remove optional dependency click-completion (with its sub-dependencies, like Jinja).

Add optional dependency shellingham to auto detect shell to install (it was used by click-completion).

Completion now doesn't require a third party library.

If shellingham is not installed/added as a dependency, --install-completion and --show-completion take a value with the name of the shell.

Fix support for user provided completion in CLI Parameters.

Fix completion for files in Bash, Zsh, and Fish.

Add support for modern versions of PowerShell, 5, 6, and 7 (e.g. in Windows 10).

Add support for pwsh (PowerShell Core).

PowerShell support includes help strings for commands and CLI Parameters.

Several bug fixes.

Tests for the completion logic/code.

Tested in all the shells in Linux and Windows.

PR #66.

Fix format in docs with highlighted lines. PR #65.

Add docs about Typer CLI - completion for small scripts. PR #64.

Add docs about Alternatives, Inspiration and Comparisons. PR #62.

Add Development - Contributing Guide. PR #61.

Source code(tar.gz)
Source code(zip)
0.0.10(Mar 10, 2020)
Add support for Click version 7.1.1. PR #60.

Source code(tar.gz)
Source code(zip)
0.0.9(Mar 8, 2020)
Add support for PEP 561, to allow mypy to type check applications built with Typer. PR #58.

Upgrade deploy docs to Netlify GitHub action. PR #57.

Add support for Mermaid JS for visualizations. PR #56.

Update CI to run docs deployment in GitHub actions. PR #50.

Update format for internal links. PR #38.

Tweak external links' format. PR #36.

Source code(tar.gz)
Source code(zip)
0.0.8(Jan 5, 2020)
Update docs and add latest changes to MkDocs/website. PR #33.

Add extra tests for edge cases that don't belong in docs' examples. PR #32.

Add docs for CLI Parameters with Multiple Values. Includes tests for all the examples and bug fixes. PR #31.

Add docs for extra CLI parameter types: CLI Parameter Types: Number and CLI Parameter Types: Boolean CLI Options. PR #30.

Extend docs for Commands, add Commands: Typer Callback and Commands: One or Multiple. This includes tests for all the examples and bug fixes. PR #29.

Add docs for SubCommands - Command Groups. This includes tests for all the examples and bug fixes. PR #28.

Remove unneeded code for argument handling. PR #26.

Add docs for Launching Applications. PR #25.

Add docs for getting the CLI Application Directory. PR #24.

Add docs for Progress Bars. PR #23.

Add docs for Asking with Interactive Prompts. PR #22.

Update docs for path CLI option. PR #21.

Add colors module and docs for Printing and Colors and for Terminating, including tests. PR #20.

Refactor docs to make each individual page/section "bite-sized" / small. Add docs for CLI option names. Update typer.Argument() to remove invalid positional param_decls. PR #19.

Source code(tar.gz)
Source code(zip)
0.0.7(Dec 31, 2019)
Add docs for CLI parameter types. Includes tests and file classes refactor. PR #17.

Add tests for completion. PR #15 and #16.

Source code(tar.gz)
Source code(zip)
0.0.6(Dec 30, 2019)
Add docs for Commands. Includes a bug fix for handling default values set in typer.Typer() parameters. PR #14.

Add docs for CLI Arguments. PR #13.

Add docs for CLI Options. PR #12.

Source code(tar.gz)
Source code(zip)
0.0.5(Dec 28, 2019)
Clean exports from Typer. Remove unneeded components from Click and add needed Exit exception. PR #11.

Fix and document extracting help from a functions' docstring First Steps: Document your CLI app. PR #10.

Update references to --install-completion and --show-completion in docs. PR #9.

Fix testing utilities, add tests for First Steps examples. PR #8.

Add auto completion options by default when click-completion is installed: --install-completion and --show-completion. PR #7.

Update Termynal to have fixed sizes, add "fast" button, and use it in First Steps. PR #6.

Add custom automatic Termynal for docs. PR #5.

Source code(tar.gz)
Source code(zip)
0.0.4(Dec 24, 2019)
Update short descriptions and assets.

Docs rewording and fix typos. PR #1 by @mariacamilagl.

Source code(tar.gz)
Source code(zip)
0.0.3(Dec 24, 2019)
Fix group creation without name.

Source code(tar.gz)
Source code(zip)
0.0.2(Dec 24, 2019)
Add initial version of code, docs, etc.

Source code(tar.gz)
Source code(zip)

Typer, build great CLIs. Easy to code. Based on Python type hints.

Related tags

Overview

FastAPI of CLIs

Requirements

Installation

Example

The absolute minimum

Run it

Example upgrade

An example with two subcommands

Run the upgraded example

Recap

Optional Dependencies

Other tools and plug-ins

License

Comments

First Check

Commit to Help

Example Code

Description

Operating System

Operating System Details

Typer Version

Python Version

Additional Context

First check

Description

Additional context

Use standard print

Rich for --help

New docs for deprecated

Rich Markup and Markdown

Help Panels

Epilog docs

Tests

First Check

Commit to Help

Example Code

Description

Wanted Solution

Wanted Code

Alternatives

Operating System

Operating System Details

Typer Version

Python Version

Additional Context

First check

Description

First check

Description

First Check

Commit to Help

Example Code

Description

Wanted Solution

Wanted Code

Alternatives

Operating System

Operating System Details

Typer Version

Python Version

Additional Context

First Check

Commit to Help

Example Code

Description

Operating System

Operating System Details

Typer Version

Python Version

Additional Context

First Check

Commit to Help

Example Code

Description

Operating System

Operating System Details

Typer Version

Use standard `print`

Rich for `--help`

New docs for `deprecated`