diff --git a/README.md b/README.md index 7b8134e..bbbb9ce 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ The key features are: Python 3.6+ -Typer stands on the shoulders of a giant. Its only internal dependency is Click. +Typer stands on the shoulders of a giant. Its only internal dependency is Click. ## Installation @@ -247,14 +247,14 @@ For a more complete example including more features, see the Click internally. That's the only dependency. +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. +* 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. -* click-completion: and Typer will automatically configure it to provide completion for all the shells, including installation commands. + * Or any other tool, e.g. wasabi, blessings. +* click-completion: and Typer will automatically configure it to provide completion for all the shells, including installation commands. You can install `typer` with `colorama` and `click-completion` with `pip install typer[all]`. @@ -264,9 +264,9 @@ Click has many plug-ins available that you can use. And there are many tools tha 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. +* 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. * etc... you can re-use many of the great available tools for building CLIs. ## License diff --git a/docs/css/custom.css b/docs/css/custom.css index b9d77de..735128c 100644 --- a/docs/css/custom.css +++ b/docs/css/custom.css @@ -7,3 +7,7 @@ .termy [data-termynal] { white-space: pre-wrap; } + +a.external-link::after { + content: " [↪]"; +} diff --git a/docs/features.md b/docs/features.md index c3bdb34..08139cf 100644 --- a/docs/features.md +++ b/docs/features.md @@ -20,11 +20,11 @@ You will rarely need to come back to the docs. Here's how your editor might help you: -* in Visual Studio Code: +* in Visual Studio Code: ![editor support](img/vscode-completion.png) -* in PyCharm: +* in PyCharm: ![editor support](img/pycharm-completion.png) @@ -60,7 +60,7 @@ The resulting CLI apps created with **Typer** have the nice features of many "pr ## The power of Click -Click is one of the most popular tools for building CLIs in Python. +Click is one of the most popular tools for building CLIs in Python. **Typer** is based on it, so you get all its benefits, plug-ins, robustness, etc. diff --git a/docs/help-typer.md b/docs/help-typer.md index 0565918..379acde 100644 --- a/docs/help-typer.md +++ b/docs/help-typer.md @@ -10,13 +10,13 @@ And there are several ways to get help too. ## Star **Typer** in GitHub -You can "star" Typer in GitHub (clicking the star button at the top right): https://github.com/tiangolo/typer. +You can "star" Typer in GitHub (clicking the star button at the top right): https://github.com/tiangolo/typer. By adding a star, other users will be able to find it more easily and see that it has been already useful for others. ## Watch the GitHub repository for releases -You can "watch" Typer in GitHub (clicking the "watch" button at the top right): https://github.com/tiangolo/typer. +You can "watch" Typer in GitHub (clicking the "watch" button at the top right): https://github.com/tiangolo/typer. There you can select "Releases only". @@ -24,28 +24,28 @@ Doing it, you will receive notifications (in your email) whenever there's a new ## Connect with the author -You can connect with me (Sebastián Ramírez / `tiangolo`), the author. +You can connect with me (Sebastián Ramírez / `tiangolo`), the author. You can: -* Follow me on **GitHub**. +* Follow me on **GitHub**. * See other Open Source projects I have created that could help you. * Follow me to see when I create a new Open Source project. -* Follow me on **Twitter**. +* Follow me on **Twitter**. * Tell me how you use Typer (I love to hear that). * Ask questions. -* Connect with me on **Linkedin**. +* Connect with me on **Linkedin**. * Talk to me. * Endorse me or recommend me :) * Read what I write (or follow me): * Read other ideas, articles and tools I have created. * Follow me to see when I publish something new. - * On **Dev.to**. - * On **Medium**. + * On **Dev.to**. + * On **Medium**. ## Tweet about **Typer** -Tweet about **Typer** and let me and others know why you like it. +Tweet about **Typer** and let me and others know why you like it. ## Let me know how are you using **Typer** @@ -53,18 +53,18 @@ I love to hear about how **Typer** is being used, what have you liked in it, in You can let me know: -* On **Twitter**. -* On **Linkedin**. -* On **Dev.to**. -* On **Medium**. +* On **Twitter**. +* On **Linkedin**. +* On **Dev.to**. +* On **Medium**. ## Help others with issues in GitHub -You can see existing issues and try and help others. +You can see existing issues and try and help others. ## Watch the GitHub repository -You can "watch" Typer in GitHub (clicking the "watch" button at the top right): https://github.com/tiangolo/typer. +You can "watch" Typer in GitHub (clicking the "watch" button at the top right): https://github.com/tiangolo/typer. If you select "Watching" instead of "Releases only", you will receive notifications when someone creates a new issue. @@ -72,7 +72,7 @@ Then you can try and help them solving those issues. ## Create issues -You can create a new issue in the GitHub repository, for example to: +You can create a new issue in the GitHub repository, for example to: * Report a bug/issue. * Suggest a new feature. @@ -80,7 +80,7 @@ You can create a Pull Request, for example: +You can create a Pull Request, for example: * To fix a typo you found on the documentation. * To propose new documentation sections. diff --git a/docs/index.md b/docs/index.md index 7b8134e..bbbb9ce 100644 --- a/docs/index.md +++ b/docs/index.md @@ -40,7 +40,7 @@ The key features are: Python 3.6+ -Typer stands on the shoulders of a giant. Its only internal dependency is Click. +Typer stands on the shoulders of a giant. Its only internal dependency is Click. ## Installation @@ -247,14 +247,14 @@ For a more complete example including more features, see the Click internally. That's the only dependency. +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. +* 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. -* click-completion: and Typer will automatically configure it to provide completion for all the shells, including installation commands. + * Or any other tool, e.g. wasabi, blessings. +* click-completion: and Typer will automatically configure it to provide completion for all the shells, including installation commands. You can install `typer` with `colorama` and `click-completion` with `pip install typer[all]`. @@ -264,9 +264,9 @@ Click has many plug-ins available that you can use. And there are many tools tha 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. +* 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. * etc... you can re-use many of the great available tools for building CLIs. ## License diff --git a/docs/tutorial/app-dir.md b/docs/tutorial/app-dir.md index d6e0dca..472c0dd 100644 --- a/docs/tutorial/app-dir.md +++ b/docs/tutorial/app-dir.md @@ -32,7 +32,7 @@ If the first element is a `Path` object the next ones (after the `/`) can be `st And it will create a new `Path` object from that. -If you want a quick guide on using `Path()` you can check this post on Real Python or this post by Trey Hunner. +If you want a quick guide on using `Path()` you can check this post on Real Python or this post by Trey Hunner. In the code above, we are also explicitly declaring `config_path` as having type `Path` to help the editor provide completion and type checks: diff --git a/docs/tutorial/arguments.md b/docs/tutorial/arguments.md index 8915ed9..c9c1940 100644 --- a/docs/tutorial/arguments.md +++ b/docs/tutorial/arguments.md @@ -35,7 +35,7 @@ __init__.py test_tutorial ### An alternative *CLI argument* declaration -In the First Steps you saw how to add a *CLI argument*: +In the First Steps you saw how to add a *CLI argument*: ```Python hl_lines="4" {!./src/first_steps/tutorial002.py!} @@ -70,7 +70,7 @@ As we no longer have the Python function default value (or its absence) to tell To make it *required*, we pass `...` as the first function argument passed to `typer.Argument(...)`. !!! info - If you hadn't seen that `...` before: it is a a special single value, it is part of Python and is called "Ellipsis". + If you hadn't seen that `...` before: it is a a special single value, it is part of Python and is called "Ellipsis". All we did there achieves the same thing as before, a **required** *CLI argument*: @@ -191,7 +191,7 @@ For that reason, Typer (actually Click underneath) doesn't attempt to automatica And you should document them as part of the CLI app documentation, normally in a docstring. -Check the last example from the First Steps: +Check the last example from the First Steps: ```Python hl_lines="5 6 7 8 9" {!./src/first_steps/tutorial006.py!} diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md index 984f5e0..084f68a 100644 --- a/docs/tutorial/index.md +++ b/docs/tutorial/index.md @@ -2,7 +2,7 @@ If you need a refreshed about how to use Python type hints, check the first part of FastAPI's Python types intro. -You can also check the mypy cheat sheet. +You can also check the mypy cheat sheet. In short (very short), you can declare a function with parameters like: diff --git a/docs/tutorial/multiple-values/options-with-multiple-values.md b/docs/tutorial/multiple-values/options-with-multiple-values.md index dcbec85..f340f65 100644 --- a/docs/tutorial/multiple-values/options-with-multiple-values.md +++ b/docs/tutorial/multiple-values/options-with-multiple-values.md @@ -51,7 +51,7 @@ is_wizard = user[2] !!! tip Notice that the default is a tuple with `(None, None, None)`. - You cannot simply use `None` here as the default because Click doesn't support it. + You cannot simply use `None` here as the default because Click doesn't support it. ## Check it diff --git a/docs/tutorial/options/name.md b/docs/tutorial/options/name.md index 3e61137..fb5c413 100644 --- a/docs/tutorial/options/name.md +++ b/docs/tutorial/options/name.md @@ -33,7 +33,7 @@ You can pass the *CLI option* name that you want to have in the next positional Here you are passing the string `"--name"` as the second positional argument to `typer.Option()`. !!! info - "Positional" means that it's not a function argument with a keyword name. + "Positional" means that it's not a function argument with a keyword name. For example `show_default=True` is a keyword argument. "`show_default`" is the keyword. diff --git a/docs/tutorial/options/required.md b/docs/tutorial/options/required.md index 39d52ab..48e5f93 100644 --- a/docs/tutorial/options/required.md +++ b/docs/tutorial/options/required.md @@ -10,7 +10,7 @@ But if you really want, you can change that. To make a *CLI option* required, pass `...` to `typer.Option()`. !!! info - If you hadn't seen that `...` before: it is a a special single value, it is part of Python and is called "Ellipsis". + If you hadn't seen that `...` before: it is a a special single value, it is part of Python and is called "Ellipsis". That will tell **Typer** that it's still a *CLI option*, but it doesn't have a default value, and it's required. diff --git a/docs/tutorial/parameter-types/datetime.md b/docs/tutorial/parameter-types/datetime.md index 104c43e..418ddef 100644 --- a/docs/tutorial/parameter-types/datetime.md +++ b/docs/tutorial/parameter-types/datetime.md @@ -1,4 +1,4 @@ -You can specify a *CLI parameter* as a Python `datetime`. +You can specify a *CLI parameter* as a Python `datetime`. Your function will receive a standard Python `datetime` object, and again, your editor will give you completion, etc. @@ -42,7 +42,7 @@ Error: Invalid value for "[%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d %H:%M:%S]": inval You can also customize the formats received for the `datetime` with the `formats` parameter. -`formats` receives a list of strings with the date formats that would be passed to datetime.strptime(). +`formats` receives a list of strings with the date formats that would be passed to datetime.strptime(). For example, let's imagine that you want to accept an ISO formatted datetime, but for some strange reason, you also want to accept a format with: diff --git a/docs/tutorial/parameter-types/enum.md b/docs/tutorial/parameter-types/enum.md index 08b518a..d2089a2 100644 --- a/docs/tutorial/parameter-types/enum.md +++ b/docs/tutorial/parameter-types/enum.md @@ -1,4 +1,4 @@ -To define a *CLI parameter* that can take a value from a predefined set of values you can use a standard Python `enum.Enum`: +To define a *CLI parameter* that can take a value from a predefined set of values you can use a standard Python `enum.Enum`: ```Python hl_lines="1 6 7 8 9 12 13" {!./src/parameter_types/enum/tutorial001.py!} diff --git a/docs/tutorial/parameter-types/file.md b/docs/tutorial/parameter-types/file.md index 43cbc74..d923883 100644 --- a/docs/tutorial/parameter-types/file.md +++ b/docs/tutorial/parameter-types/file.md @@ -5,7 +5,7 @@ Apart from `Path` *CLI parameters* you can also declare some types of "files". You can read and write data with `Path` the same way. -The difference is that these types will give you a Python file-like object instead of a Python Path. +The difference is that these types will give you a Python file-like object instead of a Python Path. A "file-like object" is the same type of object returned by `open()` as in: @@ -168,7 +168,7 @@ $ ls ./binary.dat You can use several configuration parameters for these types (classes) in `typer.Option()` and `typer.Argument()`: -* `mode`: controls the "mode" to open the file with. +* `mode`: controls the "mode" to open the file with. * It's automatically set for you by using the classes above. * Read more about it below. * `encoding`: to force a specific encoding, e.g. `"utf-8"`. @@ -178,7 +178,7 @@ You can use several configuration parameters for these types (classes) in `typer ## Advanced `mode` -By default, **Typer** will configure the `mode` for you: +By default, **Typer** will configure the `mode` for you: * `typer.FileText`: `mode="r"`, to read text. * `typer.FileTextWrite`: `mode="w"`, to write text. diff --git a/docs/tutorial/parameter-types/index.md b/docs/tutorial/parameter-types/index.md index 3e00f28..bf1a661 100644 --- a/docs/tutorial/parameter-types/index.md +++ b/docs/tutorial/parameter-types/index.md @@ -62,4 +62,4 @@ See more about specific types and validations in the next sections... !!! info "Technical Details" - All the types you will see in the next sections are handled underneath by Click's Parameter Types. + All the types you will see in the next sections are handled underneath by Click's Parameter Types. diff --git a/docs/tutorial/parameter-types/path.md b/docs/tutorial/parameter-types/path.md index 8ca2bea..799e6fd 100644 --- a/docs/tutorial/parameter-types/path.md +++ b/docs/tutorial/parameter-types/path.md @@ -1,4 +1,4 @@ -You can declare a *CLI parameter* to be a standard Python `pathlib.Path`. +You can declare a *CLI parameter* to be a standard Python `pathlib.Path`. This is what you would do for directory paths, file paths, etc: @@ -55,7 +55,7 @@ You can perform several validations for `Path` *CLI parameters*: It will not expand a tilde-prefix (something with `~`, like `~/Documents/`), as this is supposed to be done by the shell only. !!! tip - All these parameters come directly from Click. + All these parameters come directly from Click. For example: diff --git a/docs/tutorial/parameter-types/uuid.md b/docs/tutorial/parameter-types/uuid.md index 4632994..dcb97f5 100644 --- a/docs/tutorial/parameter-types/uuid.md +++ b/docs/tutorial/parameter-types/uuid.md @@ -1,5 +1,5 @@ !!! info - A UUID is a "Universally Unique Identifier". + A UUID is a "Universally Unique Identifier". It's a standard format for identifiers, like passport numbers, but for anything, not just people in countries. @@ -23,7 +23,7 @@ You can declare a *CLI parameter* as a UUID: {!./src/parameter_types/uuid/tutorial001.py!} ``` -Your Python code will receive a standard Python `UUID` object with all its attributes and methods, and as you are annotating your function parameter with that type, you will have type checks, autocompletion in your editor, etc. +Your Python code will receive a standard Python `UUID` object with all its attributes and methods, and as you are annotating your function parameter with that type, you will have type checks, autocompletion in your editor, etc. Check it: diff --git a/docs/tutorial/printing.md b/docs/tutorial/printing.md index b8247e0..e616323 100644 --- a/docs/tutorial/printing.md +++ b/docs/tutorial/printing.md @@ -7,7 +7,7 @@ You can use `typer.echo()` to print to the screen: The reason to use `typer.echo()` instead of just `print()` is that it applies some error corrections in case the terminal is misconfigured, and it will properly output color if it's supported. !!! info - `typer.echo()` comes directly from Click, you can read more about it in Click's docs. + `typer.echo()` comes directly from Click, you can read more about it in Click's docs. Check it: @@ -24,7 +24,7 @@ Hello World ## Color !!! info - For colors to work correctly on Windows you need to also install `colorama`. + For colors to work correctly on Windows you need to also install `colorama`. You don't need to call `colorama.init()`. Typer (actually Click) will handle it underneath. @@ -65,7 +65,7 @@ You can pass these function arguments to `typer.style()`: * `reset`: by default a reset-all code is added at the end of the string which means that styles do not carry over. This can be disabled to compose styles. !!! info - You can read more about it in Click's docs about `style()` + You can read more about it in Click's docs about `style()` ## `typer.secho()` - style and print diff --git a/docs/tutorial/progressbar.md b/docs/tutorial/progressbar.md index af72989..7afc61f 100644 --- a/docs/tutorial/progressbar.md +++ b/docs/tutorial/progressbar.md @@ -84,7 +84,7 @@ Processed 100 user IDs. ### About the function with `yield` -If you hadn't seen something like that `yield` above, that's a "generator". +If you hadn't seen something like that `yield` above, that's a "generator". You can iterate over that function with a `for` and at each iteration it will give you the value at `yield`. diff --git a/docs/tutorial/prompt.md b/docs/tutorial/prompt.md index bb18a72..56c5846 100644 --- a/docs/tutorial/prompt.md +++ b/docs/tutorial/prompt.md @@ -1,4 +1,4 @@ -When you need to ask the user for info interactively you should normally use *CLI Option*s with Prompt, because they allow using the CLI program in a non-interactive way (for example, a Bash script could use it). +When you need to ask the user for info interactively you should normally use *CLI Option*s with Prompt, because they allow using the CLI program in a non-interactive way (for example, a Bash script could use it). But if you absolutely need to ask for interactive information without using a *CLI option*, you can use `typer.prompt()`: @@ -22,7 +22,7 @@ Hello Camila ## Confirm -There's also an alternative to ask for confirmation. Again, if possible, you should use a *CLI Option* with a confirmation prompt: +There's also an alternative to ask for confirmation. Again, if possible, you should use a *CLI Option* with a confirmation prompt: ```Python hl_lines="5" {!./src/prompt/tutorial002.py!} diff --git a/docs/tutorial/subcommands/callback-override.md b/docs/tutorial/subcommands/callback-override.md index 060e3ab..3c8c788 100644 --- a/docs/tutorial/subcommands/callback-override.md +++ b/docs/tutorial/subcommands/callback-override.md @@ -51,7 +51,7 @@ Creating user: Camila If a callback was added when creating the `typer.Typer()` app, it's possible to override it with a new one using `@app.callback()`. -This is the same information you saw on the section about Commands - Typer Callback, and it applies the same for sub-Typer apps: +This is the same information you saw on the section about Commands - Typer Callback, and it applies the same for sub-Typer apps: ```Python hl_lines="6 7 10 14 15 16" {!./src/subcommands/callback_override/tutorial003.py!} diff --git a/docs/tutorial/subcommands/index.md b/docs/tutorial/subcommands/index.md index 7e399bf..f1b6fb0 100644 --- a/docs/tutorial/subcommands/index.md +++ b/docs/tutorial/subcommands/index.md @@ -1,4 +1,4 @@ -You read before how to create a program with Commands. +You read before how to create a program with Commands. Now we'll see how to create a *CLI program* with commands that have their own subcommands. Also known as command groups.