diff --git a/README.md b/README.md index 13fa63e..711cce1 100644 --- a/README.md +++ b/README.md @@ -1,493 +1,27 @@ # Typer CLI -

- Run Typer scripts with completion, without having to create a package, using Typer CLI. -

-

- - Test - - - Coverage - - Package version - -

+⚠️ DEPRECATED ⚠️ -There is an optional utility tool called **Typer CLI**, additional to **Typer** itself. - -It's main feature is to provide ✨ completion ✨ in the Terminal for your own small programs built with **Typer**. - -...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` 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 📝. +Use [Typer](https://github.com/tiangolo/typer) instead of [Typer CLI](https://github.com/tiangolo/typer-cli). --- -**Documentation**: https://typer.tiangolo.com/typer-cli/ - -**Source Code for Typer CLI**: https://github.com/tiangolo/typer-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: - -```Python -import 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: - -
- -```console -$ typer my_script.py run - -Hello World -``` - -
- -But you never import anything from **Typer CLI** in your own scripts. - -## Usage - -### Install - -Install **Typer CLI**: - -
- -```console -$ python -m pip install typer-cli ----> 100% -Successfully installed typer-cli -``` - -
- -That creates a `typer` command you can call in your terminal, much like `python`, `git`, or `echo`. - -You can then install completion for it: - -
- -```console -$ typer --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`: - -```Python -from typing import Optional - -import 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**: - -
- -```console -$ python -m pip install typer ----> 100% -Successfully installed typer -``` - -
- -### Run with Python - -Then you could run your script with normal Python: - -
- -```console -$ 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. - -⛔️ But in your terminal, you won't get completion when hitting TAB for any of the subcommands or options, like `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` command you get after installing `typer-cli`: - -
- -```console -$ typer my_custom_script.py run hello - -Hello World! - -$ typer my_custom_script.py run hello --name Camila - -Hello Camila! - -$ typer my_custom_script.py run bye --name Camila - -Bye Camila -``` - -
- -* Instead of using `python` directly you use the `typer` command. -* After the name of the file, add the subcommand `run`. - -✔️ If you installed completion for **Typer CLI** (for the `typer` command) as described above, when you hit TAB you will have ✨ completion for everything ✨, including all the subcommands and options of your script, like `hello`, `bye`, and `--name` 🚀. - -## If main - -Because **Typer CLI** won't use the block with: - -```Python -if __name__ == "__main__": - app() -``` - -...you can also remove it if you are calling that script only with **Typer CLI** (using the `typer` 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: - -```Python -def main(name: str = "World"): - """ - Say hi to someone, by default to the World. - """ - print(f"Hello {name}") -``` - -Then you can call it with: - -
- -```console -$ typer main.py run --help -Usage: typer run [OPTIONS] +All the functionality in this repo for [`typer-cli`](https://github.com/tiangolo/typer-cli), has been integrated into [Typer](https://github.com/tiangolo/typer). - Say hi to someone, by default to the World. +The main repo, https://github.com/tiangolo/typer, publishes a PyPI package `typer-cli` (that used to be this repo), and that PyPI package does nothing other than depend on `typer`. -Options: - --name TEXT - --help Show this message and exit. +All the functionality has been integrated into `typer`. -$ typer main.py run --name Camila +Install instead `typer`: -Hello Camila +```bash +pip install typer ``` -
+That includes the `typer` command. -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: - -
- -```console -$ typer my_package.main run --help -Usage: typer run [OPTIONS] - -Options: - --name TEXT - --help Show this message and exit. - -$ typer 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 a `Typer()` object to run as the main app. -* `--func`: the name of the variable with a function that would be used with `typer.run()`. - -### Defaults - -When your run a script with the **Typer CLI** (the `typer` 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 using `typer.run()`). -* A **Typer** app in a variable with a name of `app`, `cli`, or `main`. -* The first **Typer** app available in the file, with any name. -* A function in a variable with a name of `main`, `cli`, or `app`. -* 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: - -```Python -import 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`. - -
- -```console -$ typer 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: - -
- -```console -$ typer 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**: - -```console -$ 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**: - -```console -$ 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**: - -```console -$ 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**: - -```console -$ 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**: - -```console -$ awesome-cli init [OPTIONS] -``` - -**Options**: - -* `--help`: Show this message and exit. - ---- +This repo is now deprecated and archived. 🤓 ## License -**Typer CLI**, the same as **Typer**, is licensed under the terms of the MIT license. +This project is licensed under the terms of the MIT license.