Default to add_completion == False in typer.run

[ajlive]

First Check

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

Commit to Help

• 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:

1. 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.
2. 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: #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

[wassafshahzad]

Is this issue up for grabs ?

[ajlive]

I don't know...no response from a maintainer

[Dr-ZeeD]

I think adding documentation would be fine, but changing the default to False when you get completion for free is weird in my opinion. Even if your coworkers thought it was weird, a simple "you get it for free from the CLI framework" should suffice, shouldn't it?

[ajlive]

You don't really get completion for free: it requires installation, which raises questions, or installing the typer command. Completion seems like something you'd expect for a more heavyweight CLI app, not for a script. I think if you introduce Typer as "here's a CLI framework we should use for production apps" then free completion is definitely a plus. But if your coworkers have the good instinct to reject a dependency covered by the standard library, starting by demonstrating Typer as a scripting tool, where completion is not expected, is effective.

The reason why I think changing the default for run might not be a big deal is that it seems unlikely to me that there are many people out there installing completion for a script that uses typer.run(main). Surely in most cases where completion would be wanted the CLI is being started with app(), and if someone really wants completion for a small script they'll use the typer command.

[Dr-ZeeD]

What I meant by for free: without me interfering on the Python level. I tend to forget that putting stuff into your configuration files like .profile is a hurdle for people, so I see where you're coming from.

So far my experience when showing this to co-workers was maybe just a different one. They never knew how they could add completions to their scripts, it had never crossed their minds. But as soon as they saw the help message their interest was piqued, they opened up the documentation and were pleasantly surprised.

Maybe the field I'm in also "ticks" a bit differently, as we basically live on the command line.

[ajlive]

Maybe the field I'm in also "ticks" a bit differently, as we basically live on the command line.

Hmm, yeah, good point. I guess there's not one right answer here in terms of behavior, so the existing behavior and any possible changes will always be a compromise for somebody.

[gregersn]

Considering how typer is supposed to be a very easy and smooth way to add argument parsing, etc, to scripts, it does seem like a hurdle to have to disable this extra information.
If understand how it is meant as to be "for free", but the fact is that when you write small scripts, that are not meant to be used a lot, you probably don't want to have completion, etc, installed.

Wanting to add completion feels a lot more like a decision you are making, as opposed to have two extra long lines, added to the script help without having thought about it.
And also, I really don't like it when there are more things happening than what I have asked for.

Adding this extra bit is, in a way a bit intrusive, IMO.

[i30817]

The only thing that bothers me about completion is how in recent updates the 'default' completion targets started appearing in the left side -install-completion [bash|zsh|fish|powershell|pwsh].

This leads to rightwards drift, which almost always lead to the option line being 'by itself' which leads to a 'race to the edges leaving a very awkward empty space in the middle unnecessarily.

A cosmetic issue, sure, but i think it matters for a library like this. I do not like the options like this.

[i30817]

Also in these options i'd like to pass them with typer.run

I use that strategy instead of 'app' a lot because i want two different scripts in the same file, and it's just neater if you don't have to interact with click.

[ajlive]

Just want to say I'm happy to put up a PR for any decision that comes out of this discussion.

[carderne]

This has been fixed by #488, released in typer==0.7.0.

[ajlive]

Thank you!

[tiangolo]

Thanks for the discussion everyone! ☕

And thanks for coming back to close the issue. 🍰