Typer CLI
Run Typer scripts with completion, without having to create a package, using Typer CLI.
There is an optional utility tool called Typer CLI, in addition to Typer itself.
It's main feature is to provide
... without you having to create a complete installable Python package.
It's probably most useful if you have a small custom Python script using Typer (maybe as part of some project), for some small tasks, and it's not complex/important enough to create a whole installable Python package for it (something to be installed with pip
).
In that case, you can install Typer CLI, and run your program with the typer-cloup
command in your Terminal, and it will provide completion for your script.
You can also use Typer CLI to generate Markdown documentation for your own Typer programs
Documentation: https://typer-cloup.netlify.app/typer-cloup-cli/
Source Code for Typer CLI: https://github.com/alexreg/typer-cloup-cli
Typer or Typer CLI
Typer is a library for building CLIs (Command Line Interface applications).
You use Typer in your Python scripts. Like in:
import typer_cloup as typer
def main():
typer.echo("Hello World")
if __name__ == "__main__":
typer.run(main)
Typer CLI is a command line application to run simple programs created with Typer, with completion in your terminal
You use Typer CLI in your terminal, to run your scripts (as an alternative to calling python
directly). Like in:
$ typer-cloup my_script.py run
Hello World
But you never import anything from Typer CLI in your own scripts.
Usage
Install
Install Typer CLI:
$ pip install typer-cloup-cli
---> 100%
Successfully installed typer-cloup-cli
That creates a typer-cloup
command you can call in your terminal, much like python
, git
, or echo
.
You can then install completion for it:
$ typer-cloup --install-completion
zsh completion installed in /home/user/.bashrc.
Completion will take effect once you restart the terminal.
Sample script
Let's say you have a script that uses Typer in my_custom_script.py
:
from typing import Optional
import typer_cloup as typer
app = typer.Typer()
@app.command()
def hello(name: Optional[str] = None):
if name:
typer.echo(f"Hello {name}")
else:
typer.echo("Hello World!")
@app.command()
def bye(name: Optional[str] = None):
if name:
typer.echo(f"Bye {name}")
else:
typer.echo("Goodbye!")
if __name__ == "__main__":
app()
For it to work, you would also install Typer:
$ pip install typer
---> 100%
Successfully installed typer
Run with Python
Then you could run your script with normal Python:
$ python my_custom_script.py hello
Hello World!
$ python my_custom_script.py hello --name Camila
Hello Camila!
$ python my_custom_script.py bye --name Camila
Bye Camila
There's nothing wrong with using Python directly to run it. And, in fact, if some other code or program uses your script, that would probably be the best way to do it.
hello
, bye
, and --name
.
Run with Typer CLI
Here's where Typer CLI is useful.
You can also run the same script with the typer-cloup
command you get after installing typer-cloup-cli
:
$ typer-cloup my_custom_script.py run hello
Hello World!
$ typer-cloup my_custom_script.py run hello --name Camila
Hello Camila!
$ typer-cloup my_custom_script.py run bye --name Camila
Bye Camila
- Instead of using
python
directly you use thetyper-cloup
command. - After the name of the file, add the subcommand
run
.
typer-cloup
command) as described above, when you hit TAB you will have hello
, bye
, and --name
If main
Because Typer CLI won't use the block with:
if __name__ == "__main__":
app()
... you can also remove it if you are calling that script only with Typer CLI (using the typer-cloup
command).
Run other files
Typer CLI can run any script with Typer, but the script doesn't even have to use Typer at all.
Typer CLI could even run a file with a function that could be used with typer.run()
, even if the script doesn't use typer.run()
or anything else.
For example, a file main.py
like this will still work:
def main(name: str = "World"):
"""
Say hi to someone, by default to the World.
"""
print(f"Hello {name}")
Then you can call it with:
$ typer-cloup main.py run --help
Usage: typer-cloup run [OPTIONS]
Say hi to someone, by default to the World.
Options:
--name TEXT
--help Show this message and exit.
$ typer-cloup main.py run --name Camila
Hello Camila
And it will also have completion for things like the --name
CLI Option.
Run a package or module
Instead of a file path you can pass a module (possibly in a package) to import.
For example:
$ typer-cloup my_package.main run --help
Usage: typer-cloup run [OPTIONS]
Options:
--name TEXT
--help Show this message and exit.
$ typer-cloup my_package.main run --name Camila
Hello Camila
Options
You can specify one of the following CLI options:
-
--app
: the name of the variable with aTyper()
object to run as the main app. -
--func
: the name of the variable with a function that would be used withtyper.run()
.
Defaults
When your run a script with the Typer CLI (the typer-cloup
command) it will use the app from the following priority:
- An app object from the
--app
CLI Option. - A function to convert to a Typer app from
--func
CLI Option (like when usingtyper.run()
). - A Typer app in a variable with a name of
app
,cli
, ormain
. - The first Typer app available in the file, with any name.
- A function in a variable with a name of
main
,cli
, orapp
. - The first function in the file, with any name.
Generate docs
Typer CLI can also generate Markdown documentation for your Typer application.
Sample script with docs
For example, you could have a script like:
import typer_cloup as typer
app = typer.Typer(help="Awesome CLI user manager.")
@app.command()
def create(username: str):
"""
Create a new user with USERNAME.
"""
typer.echo(f"Creating user: {username}")
@app.command()
def delete(
username: str,
force: bool = typer.Option(
...,
prompt="Are you sure you want to delete the user?",
help="Force deletion without confirmation.",
),
):
"""
Delete a user with USERNAME.
If --force is not used, will ask for confirmation.
"""
if force:
typer.echo(f"Deleting user: {username}")
else:
typer.echo("Operation cancelled")
@app.command()
def delete_all(
force: bool = typer.Option(
...,
prompt="Are you sure you want to delete ALL users?",
help="Force deletion without confirmation.",
)
):
"""
Delete ALL users in the database.
If --force is not used, will ask for confirmation.
"""
if force:
typer.echo("Deleting all users")
else:
typer.echo("Operation cancelled")
@app.command()
def init():
"""
Initialize the users database.
"""
typer.echo("Initializing user database")
if __name__ == "__main__":
app()
Generate docs with Typer CLI
Then you could generate docs for it with Typer CLI.
You can use the subcommand utils
.
And then the subcommand docs
.
$ typer-cloup some_script.py utils docs
Options:
-
--name TEXT
: The name of the CLI program to use in docs. -
--output FILE
: An output file to write docs to, like README.md.
For example:
$ typer-cloup my_package.main utils docs --name awesome-cli --output README.md
Docs saved to: README.md
Sample docs output
For example, for the previous script, the generated docs would look like:
awesome-cli
Awesome CLI user manager.
Usage:
$ awesome-cli [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:
-
create
: Create a new user with USERNAME. -
delete
: Delete a user with USERNAME. -
delete-all
: Delete ALL users in the database. -
init
: Initialize the users database.
awesome-cli create
Create a new user with USERNAME.
Usage:
$ awesome-cli create [OPTIONS] USERNAME
Options:
-
--help
: Show this message and exit.
awesome-cli delete
Delete a user with USERNAME.
If --force is not used, will ask for confirmation.
Usage:
$ awesome-cli delete [OPTIONS] USERNAME
Options:
-
--force / --no-force
: Force deletion without confirmation. [required] -
--help
: Show this message and exit.
awesome-cli delete-all
Delete ALL users in the database.
If --force is not used, will ask for confirmation.
Usage:
$ awesome-cli delete-all [OPTIONS]
Options:
-
--force / --no-force
: Force deletion without confirmation. [required] -
--help
: Show this message and exit.
awesome-cli init
Initialize the users database.
Usage:
$ awesome-cli init [OPTIONS]
Options:
-
--help
: Show this message and exit.
License
Typer CLI, the same as Typer, is licensed under the terms of the MIT license.