\n\n```console\n// You could create an env var MY_NAME with\n$ export MY_NAME=\"Wade Wilson\"\n\n// Then you could use it with other programs, like\n$ echo \"Hello $MY_NAME\"\n\nHello Wade Wilson\n```\n\n
\n\n////\n\n//// tab | Windows PowerShell\n\n\n\n```console\n// Create an env var MY_NAME\n$ $Env:MY_NAME = \"Wade Wilson\"\n\n// Use it with other programs, like\n$ echo \"Hello $Env:MY_NAME\"\n\nHello Wade Wilson\n```\n\n
\n\n////\n\n## Read env vars in Python\n\nYou could also create environment variables **outside** of Python, in the terminal (or with any other method), and then **read them in Python**.\n\nFor example you could have a file `main.py` with:\n\n```Python hl_lines=\"3\"\nimport os\n\nname = os.getenv(\"MY_NAME\", \"World\")\nprint(f\"Hello {name} from Python\")\n```\n\n/// tip\n\nThe second argument to \n\n```console\n// Here we don't set the env var yet\n$ python main.py\n\n// As we didn't set the env var, we get the default value\n\nHello World from Python\n\n// But if we create an environment variable first\n$ export MY_NAME=\"Wade Wilson\"\n\n// And then call the program again\n$ python main.py\n\n// Now it can read the environment variable\n\nHello Wade Wilson from Python\n```\n\n
\n\n////\n\n//// tab | Windows PowerShell\n\n\n\n```console\n// Here we don't set the env var yet\n$ python main.py\n\n// As we didn't set the env var, we get the default value\n\nHello World from Python\n\n// But if we create an environment variable first\n$ $Env:MY_NAME = \"Wade Wilson\"\n\n// And then call the program again\n$ python main.py\n\n// Now it can read the environment variable\n\nHello Wade Wilson from Python\n```\n\n
\n\n////\n\nAs environment variables can be set outside of the code, but can be read by the code, and don't have to be stored (committed to `git`) with the rest of the files, it's common to use them for configurations or **settings**.\n\nYou can also create an environment variable only for a **specific program invocation**, that is only available to that program, and only for its duration.\n\nTo do that, create it right before the program itself, on the same line:\n\n\n\n```console\n// Create an env var MY_NAME in line for this program call\n$ MY_NAME=\"Wade Wilson\" python main.py\n\n// Now it can read the environment variable\n\nHello Wade Wilson from Python\n\n// The env var no longer exists afterwards\n$ python main.py\n\nHello World from Python\n```\n\n
\n\n/// tip\n\nYou can read more about it at \n\n```console\n$ pip install typer\n---> 100%\nSuccessfully installed typer rich shellingham\n```\n\n
\n\n## Example\n\n### The absolute minimum\n\n* Create a file `main.py` with:\n\n```Python\ndef main(name: str):\n print(f\"Hello {name}\")\n```\n\nThis script doesn't even use Typer internally. But you can use the `typer` command to run it as a CLI application.\n\n### Run it\n\nRun your application with the `typer` command:\n\n\n\n```console\n// Run your application\n$ typer main.py run\n\n// You get a nice error, you are missing NAME\nUsage: typer [PATH_OR_MODULE] run [OPTIONS] NAME\nTry 'typer [PATH_OR_MODULE] run --help' for help.\nโญโ Error โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ Missing argument 'NAME'. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n\n\n// You get a --help for free\n$ typer main.py run --help\n\nUsage: typer [PATH_OR_MODULE] run [OPTIONS] NAME\n\nRun the provided Typer app.\n\nโญโ Arguments โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ * name TEXT [default: None] [required] |\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --help Show this message and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n\n// Now pass the NAME argument\n$ typer main.py run Camila\n\nHello Camila\n\n// It works! ๐\n```\n\n
\n\nThis is the simplest use case, not even using Typer internally, but it can already be quite useful for simple scripts.\n\n**Note**: auto-completion works when you create a Python package and run it with `--install-completion` or when you use the `typer` command.\n\n## Use Typer in your code\n\nNow let's start using Typer in your own code, update `main.py` with:\n\n```Python\nimport typer\n\n\ndef main(name: str):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n typer.run(main)\n```\n\nNow you could run it with Python directly:\n\n\n\n```console\n// Run your application\n$ python main.py\n\n// You get a nice error, you are missing NAME\nUsage: main.py [OPTIONS] NAME\nTry 'main.py --help' for help.\nโญโ Error โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ Missing argument 'NAME'. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n\n\n// You get a --help for free\n$ python main.py --help\n\nUsage: main.py [OPTIONS] NAME\n\nโญโ Arguments โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ * name TEXT [default: None] [required] |\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --help Show this message and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n\n// Now pass the NAME argument\n$ python main.py Camila\n\nHello Camila\n\n// It works! ๐\n```\n\n
\n\n**Note**: you can also call this same script with the `typer` command, but you don't need to.\n\n## Example upgrade\n\nThis was the simplest example possible.\n\nNow let's see one a bit more complex.\n\n### An example with two subcommands\n\nModify the file `main.py`.\n\nCreate a `typer.Typer()` app, and create two subcommands with their parameters.\n\n```Python hl_lines=\"3 6 11 20\"\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef hello(name: str):\n print(f\"Hello {name}\")\n\n\n@app.command()\ndef goodbye(name: str, formal: bool = False):\n if formal:\n print(f\"Goodbye Ms. {name}. Have a good day.\")\n else:\n print(f\"Bye {name}!\")\n\n\nif __name__ == \"__main__\":\n app()\n```\n\nAnd that will:\n\n* Explicitly create a `typer.Typer` app.\n * The previous `typer.run` actually creates one implicitly for you.\n* Add two subcommands with `@app.command()`.\n* Execute the `app()` itself, as if it was a function (instead of `typer.run`).\n\n### Run the upgraded example\n\nCheck the new help:\n\n\n\n```console\n$ python main.py --help\n\n Usage: main.py [OPTIONS] COMMAND [ARGS]...\n\nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --install-completion Install completion โ\nโ for the current โ\nโ shell. โ\nโ --show-completion Show completion for โ\nโ the current shell, โ\nโ to copy it or โ\nโ customize the โ\nโ installation. โ\nโ --help Show this message โ\nโ and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Commands โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ goodbye โ\nโ hello โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n\n// When you create a package you get โจ auto-completion โจ for free, installed with --install-completion\n\n// You have 2 subcommands (the 2 functions): goodbye and hello\n```\n\n
\n\nNow check the help for the `hello` command:\n\n\n\n```console\n$ python main.py hello --help\n\n Usage: main.py hello [OPTIONS] NAME\n\nโญโ Arguments โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ * name TEXT [default: None] [required] โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --help Show this message and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n```\n\n
\n\nAnd now check the help for the `goodbye` command:\n\n\n\n```console\n$ python main.py goodbye --help\n\n Usage: main.py goodbye [OPTIONS] NAME\n\nโญโ Arguments โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ * name TEXT [default: None] [required] โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --formal --no-formal [default: no-formal] โ\nโ --help Show this message โ\nโ and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n\n// Automatic --formal and --no-formal for the bool option ๐\n```\n\n
\n\nNow you can try out the new command line application:\n\n\n\n```console\n// Use it with the hello command\n\n$ python main.py hello Camila\n\nHello Camila\n\n// And with the goodbye command\n\n$ python main.py goodbye Camila\n\nBye Camila!\n\n// And with --formal\n\n$ python main.py goodbye --formal Camila\n\nGoodbye Ms. Camila. Have a good day.\n```\n\n
\n\n**Note**: If your app only has one command, by default the command name is **omitted** in usage: `python main.py Camila`. However, when there are multiple commands, you must **explicitly include the command name**: `python main.py hello Camila`. See [One or Multiple Commands](https://typer.tiangolo.com/tutorial/commands/one-or-multiple/) for more details.\n\n### Recap\n\nIn summary, you declare **once** the types of parameters (*CLI arguments* and *CLI options*) as function parameters.\n\nYou do that with standard modern Python types.\n\nYou don't have to learn a new syntax, the methods or classes of a specific library, etc.\n\nJust standard **Python**.\n\nFor example, for an `int`:\n\n```Python\ntotal: int\n```\n\nor for a `bool` flag:\n\n```Python\nforce: bool\n```\n\nAnd similarly for **files**, **paths**, **enums** (choices), etc. And there are tools to create **groups of subcommands**, add metadata, extra **validation**, etc.\n\n**You get**: great editor support, including **completion** and **type checks** everywhere.\n\n**Your users get**: automatic **`--help`**, **auto-completion** in their terminal (Bash, Zsh, Fish, PowerShell) when they install your package or when using the `typer` command.\n\nFor a more complete example including more features, see the \n * @version 0.0.1\n * @license MIT\n */\n\n'use strict';\n\n/** Generate a terminal widget. */\nclass Termynal {\n /**\n * Construct the widget's settings.\n * @param {(string|Node)=} container - Query selector or container element.\n * @param {Object=} options - Custom settings.\n * @param {string} options.prefix - Prefix to use for data attributes.\n * @param {number} options.startDelay - Delay before animation, in ms.\n * @param {number} options.typeDelay - Delay between each typed character, in ms.\n * @param {number} options.lineDelay - Delay between each line, in ms.\n * @param {number} options.progressLength - Number of characters displayed as progress bar.\n * @param {string} options.progressChar โ Character to use for progress bar, defaults to โ.\n\t * @param {number} options.progressPercent - Max percent of progress.\n * @param {string} options.cursor โ Character to use for cursor, defaults to โ.\n * @param {Object[]} lineData - Dynamically loaded line data objects.\n * @param {boolean} options.noInit - Don't initialise the animation.\n */\n constructor(container = '#termynal', options = {}) {\n this.container = (typeof container === 'string') ? document.querySelector(container) : container;\n this.pfx = `data-${options.prefix || 'ty'}`;\n this.originalStartDelay = this.startDelay = options.startDelay\n || parseFloat(this.container.getAttribute(`${this.pfx}-startDelay`)) || 600;\n this.originalTypeDelay = this.typeDelay = options.typeDelay\n || parseFloat(this.container.getAttribute(`${this.pfx}-typeDelay`)) || 90;\n this.originalLineDelay = this.lineDelay = options.lineDelay\n || parseFloat(this.container.getAttribute(`${this.pfx}-lineDelay`)) || 1500;\n this.progressLength = options.progressLength\n || parseFloat(this.container.getAttribute(`${this.pfx}-progressLength`)) || 40;\n this.progressChar = options.progressChar\n || this.container.getAttribute(`${this.pfx}-progressChar`) || 'โ';\n\t\tthis.progressPercent = options.progressPercent\n || parseFloat(this.container.getAttribute(`${this.pfx}-progressPercent`)) || 100;\n this.cursor = options.cursor\n || this.container.getAttribute(`${this.pfx}-cursor`) || 'โ';\n this.lineData = this.lineDataToElements(options.lineData || []);\n this.loadLines()\n if (!options.noInit) this.init()\n }\n\n loadLines() {\n // Load all the lines and create the container so that the size is fixed\n // Otherwise it would be changing and the user viewport would be constantly\n // moving as she/he scrolls\n const finish = this.generateFinish()\n finish.style.visibility = 'hidden'\n this.container.appendChild(finish)\n // Appends dynamically loaded lines to existing line elements.\n this.lines = [...this.container.querySelectorAll(`[${this.pfx}]`)].concat(this.lineData);\n for (let line of this.lines) {\n line.style.visibility = 'hidden'\n this.container.appendChild(line)\n }\n const restart = this.generateRestart()\n restart.style.visibility = 'hidden'\n this.container.appendChild(restart)\n this.container.setAttribute('data-termynal', '');\n }\n\n /**\n * Initialise the widget, get lines, clear container and start animation.\n */\n init() {\n /**\n * Calculates width and height of Termynal container.\n * If container is empty and lines are dynamically loaded, defaults to browser `auto` or CSS.\n */\n const containerStyle = getComputedStyle(this.container);\n this.container.style.width = containerStyle.width !== '0px' ?\n containerStyle.width : undefined;\n this.container.style.minHeight = containerStyle.height !== '0px' ?\n containerStyle.height : undefined;\n\n this.container.setAttribute('data-termynal', '');\n this.container.innerHTML = '';\n for (let line of this.lines) {\n line.style.visibility = 'visible'\n }\n this.start();\n }\n\n /**\n * Start the animation and rener the lines depending on their data attributes.\n */\n async start() {\n this.addFinish()\n await this._wait(this.startDelay);\n\n for (let line of this.lines) {\n const type = line.getAttribute(this.pfx);\n const delay = line.getAttribute(`${this.pfx}-delay`) || this.lineDelay;\n\n if (type == 'input') {\n line.setAttribute(`${this.pfx}-cursor`, this.cursor);\n await this.type(line);\n await this._wait(delay);\n }\n\n else if (type == 'progress') {\n await this.progress(line);\n await this._wait(delay);\n }\n\n else {\n this.container.appendChild(line);\n await this._wait(delay);\n }\n\n line.removeAttribute(`${this.pfx}-cursor`);\n }\n this.addRestart()\n this.finishElement.style.visibility = 'hidden'\n this.lineDelay = this.originalLineDelay\n this.typeDelay = this.originalTypeDelay\n this.startDelay = this.originalStartDelay\n }\n\n generateRestart() {\n const restart = document.createElement('a')\n restart.onclick = (e) => {\n e.preventDefault()\n this.container.innerHTML = ''\n this.init()\n }\n restart.href = '#'\n restart.setAttribute('data-terminal-control', '')\n restart.innerHTML = \"restart โป\"\n return restart\n }\n\n generateFinish() {\n const finish = document.createElement('a')\n finish.onclick = (e) => {\n e.preventDefault()\n this.lineDelay = 0\n this.typeDelay = 0\n this.startDelay = 0\n }\n finish.href = '#'\n finish.setAttribute('data-terminal-control', '')\n finish.innerHTML = \"fast โ\"\n this.finishElement = finish\n return finish\n }\n\n addRestart() {\n const restart = this.generateRestart()\n this.container.appendChild(restart)\n }\n\n addFinish() {\n const finish = this.generateFinish()\n this.container.appendChild(finish)\n }\n\n /**\n * Animate a typed line.\n * @param {Node} line - The line element to render.\n */\n async type(line) {\n const chars = [...line.textContent];\n line.textContent = '';\n this.container.appendChild(line);\n\n for (let char of chars) {\n const delay = line.getAttribute(`${this.pfx}-typeDelay`) || this.typeDelay;\n await this._wait(delay);\n line.textContent += char;\n }\n }\n\n /**\n * Animate a progress bar.\n * @param {Node} line - The line element to render.\n */\n async progress(line) {\n const progressLength = line.getAttribute(`${this.pfx}-progressLength`)\n || this.progressLength;\n const progressChar = line.getAttribute(`${this.pfx}-progressChar`)\n || this.progressChar;\n const chars = progressChar.repeat(progressLength);\n\t\tconst progressPercent = line.getAttribute(`${this.pfx}-progressPercent`)\n\t\t\t|| this.progressPercent;\n line.textContent = '';\n this.container.appendChild(line);\n\n for (let i = 1; i < chars.length + 1; i++) {\n await this._wait(this.typeDelay);\n const percent = Math.round(i / chars.length * 100);\n line.textContent = `${chars.slice(0, i)} ${percent}%`;\n\t\t\tif (percent>progressPercent) {\n\t\t\t\tbreak;\n\t\t\t}\n }\n }\n\n /**\n * Helper function for animation delays, called with `await`.\n * @param {number} time - Timeout, in ms.\n */\n _wait(time) {\n return new Promise(resolve => setTimeout(resolve, time));\n }\n\n /**\n * Converts line data objects into line elements.\n *\n * @param {Object[]} lineData - Dynamically loaded lines.\n * @param {Object} line - Line data object.\n * @returns {Element[]} - Array of line elements.\n */\n lineDataToElements(lineData) {\n return lineData.map(line => {\n let div = document.createElement('div');\n div.innerHTML = `${line.value || ''}`;\n\n return div.firstElementChild;\n });\n }\n\n /**\n * Helper function for generating attributes string.\n *\n * @param {Object} line - Line data object.\n * @returns {string} - String of attributes.\n */\n _attributes(line) {\n let attrs = '';\n for (let prop in line) {\n // Custom add class\n if (prop === 'class') {\n attrs += ` class=${line[prop]} `\n continue\n }\n if (prop === 'type') {\n attrs += `${this.pfx}=\"${line[prop]}\" `\n } else if (prop !== 'value') {\n attrs += `${this.pfx}-${prop}=\"${line[prop]}\" `\n }\n }\n return attrs;\n }\n}\n\n/**\n* HTML API: If current script has container(s) specified, initialise Termynal.\n*/\nif (document.currentScript.hasAttribute('data-termynal-container')) {\n const containers = document.currentScript.getAttribute('data-termynal-container');\n containers.split('|')\n .forEach(container => new Termynal(container))\n}\n"
},
{
"path": "docs/management-tasks.md",
"content": "# Repository Management Tasks\n\nThese are the tasks that can be performed to manage the Typer repository by [team members](./management.md#team){.internal-link target=_blank}.\n\n/// tip\n\nThis section is useful only to a handful of people, team members with permissions to manage the repository. You can probably skip it. ๐\n\n///\n\n...so, you are a [team member of Typer](./management.md#team){.internal-link target=_blank}? Wow, you are so cool! ๐\n\nYou can help with everything on [Help Typer - Get Help](./help-typer.md){.internal-link target=_blank} the same ways as external contributors. But additionally, there are some tasks that only you (as part of the team) can perform.\n\nHere are the general instructions for the tasks you can perform.\n\nThanks a lot for your help. ๐\n\n## Be Nice\n\nFirst of all, be nice. ๐\n\nYou probably are super nice if you were added to the team, but it's worth mentioning it. ๐ค\n\n### When Things are Difficult\n\nWhen things are great, everything is easier, so that doesn't need much instructions. But when things are difficult, here are some guidelines.\n\nTry to find the good side. In general, if people are not being unfriendly, try to thank their effort and interest, even if you disagree with the main subject (discussion, PR), just thank them for being interested in the project, or for having dedicated some time to try to do something.\n\nIt's difficult to convey emotion in text, use emojis to help. ๐
\n\nIn discussions and PRs, in many cases, people bring their frustration and show it without filter, in many cases exaggerating, complaining, being entitled, etc. That's really not nice, and when it happens, it lowers our priority to solve their problems. But still, try to breath, and be gentle with your answers.\n\nTry to avoid using bitter sarcasm or potentially passive-aggressive comments. If something is wrong, it's better to be direct (try to be gentle) than sarcastic.\n\nTry to be as specific and objective as possible, avoid generalizations.\n\nFor conversations that are more difficult, for example to reject a PR, you can ask me (@tiangolo) to handle it directly.\n\n## Edit PR Titles\n\n* Edit the PR title to start with an emoji from gitmoji.\n * Use the emoji character, not the GitHub code. So, use `๐` instead of `:bug:`. This is so that it shows up correctly outside of GitHub, for example in the release notes.\n* Start the title with a verb. For example `Add`, `Refactor`, `Fix`, etc. This way the title will say the action that the PR does. Like `Add support for teleporting`, instead of `Teleporting wasn't working, so this PR fixes it`.\n* Edit the text of the PR title to start in \"imperative\", like giving an order. So, instead of `Adding support for teleporting` use `Add support for teleporting`.\n* Try to make the title descriptive about what it achieves. If it's a feature, try to describe it, for example `Add support for teleporting` instead of `Create TeleportAdapter class`.\n* Do not finish the title with a period (`.`).\n\nOnce the PR is merged, a GitHub Action (latest-changes) will use the PR title to update the latest changes automatically.\n\nSo, having a nice PR title will not only look nice in GitHub, but also in the release notes. ๐\n\n## Add Labels to PRs\n\nThe same GitHub Action latest-changes uses one label in the PR to decide the section in the release notes to put this PR in.\n\nMake sure you use a supported label from the latest-changes list of labels:\n\n* `breaking`: Breaking Changes\n * Existing code will break if they update the version without changing their code. This rarely happens, so this label is not frequently used.\n* `security`: Security Fixes\n * This is for security fixes, like vulnerabilities. It would almost never be used.\n* `feature`: Features\n * New features, adding support for things that didn't exist before.\n* `bug`: Fixes\n * Something that was supported didn't work, and this fixes it. There are many PRs that claim to be bug fixes because the user is doing something in an unexpected way that is not supported, but they considered it what should be supported by default. Many of these are actually features or refactors. But in some cases there's an actual bug.\n* `refactor`: Refactors\n * This is normally for changes to the internal code that don't change the behavior. Normally it improves maintainability, or enables future features, etc.\n* `upgrade`: Upgrades\n * This is for upgrades to direct dependencies from the project, or extra optional dependencies, normally in `pyproject.toml`. So, things that would affect final users, they would end up receiving the upgrade in their code base once they update. But this is not for upgrades to internal dependencies used for development, testing, docs, etc. Those internal dependencies or GitHub Action versions should be marked as `internal`, not `upgrade`.\n* `docs`: Docs\n * Changes in docs. This includes updating the docs, fixing typos. But it doesn't include changes to translations.\n * You can normally quickly detect it by going to the \"Files changed\" tab in the PR and checking if the updated file(s) starts with `docs/en/docs`. The original version of the docs is always in English, so in `docs/en/docs`.\n* `internal`: Internal\n * Use this for changes that only affect how the repo is managed. For example upgrades to internal dependencies, changes in GitHub Actions or scripts, etc.\n\n/// tip\n\nSome tools like Dependabot, will add some labels, like `dependencies`, but have in mind that this label is not used by the `latest-changes` GitHub Action, so it won't be used in the release notes. Please make sure one of the labels above is added.\n\n///\n\n## Review PRs\n\n* If a PR doesn't explain what it does or why, if it seems like it could be useful, ask for more information. Otherwise, feel free to close it.\n\n* If a PR seems to be spam, meaningless, only to change statistics (to appear as \"contributor\") or similar, you can simply mark it as `invalid`, and it will be automatically closed.\n\n* If a PR seems to be AI generated, and seems like reviewing it would take more time from you than the time it took to write the prompt, mark it as `maybe-ai`, and it will be automatically closed.\n\n* A PR should have a specific use case that it is solving.\n\n* If the PR is for a feature, it should have docs.\n * Unless it's a feature we want to discourage, like support for a corner case that we don't want users to use.\n* The docs should include a source example file, not write Python directly in Markdown.\n* If the source example(s) file can have different syntax for different Python versions, there should be different versions of the file, and they should be shown in tabs in the docs.\n* There should be tests testing the source example.\n* Before the PR is applied, the new tests should fail.\n* After applying the PR, the new tests should pass.\n* Coverage should stay at 100%.\n* If you see the PR makes sense, or we discussed it and considered it should be accepted, you can add commits on top of the PR to tweak it, to add docs, tests, format, refactor, remove extra files, etc.\n* Feel free to comment in the PR to ask for more information, to suggest changes, etc.\n* Once you think the PR is ready, move it in the internal GitHub project for me to review it.\n\n## Dependabot PRs\n\nDependabot will create PRs to update dependencies for several things, and those PRs all look similar, but some are way more delicate than others.\n\n* If the PR is for a direct dependency, so, Dependabot is modifying `pyproject.toml` in the main dependencies, **don't merge it**. ๐ฑ Let me check it first. There's a good chance that some additional tweaks or updates are needed.\n* If the PR updates one of the internal dependencies, for example the group `dev` in `pyproject.toml`, or GitHub Action versions, if the tests are passing, the release notes (shown in a summary in the PR) don't show any obvious potential breaking change, you can merge it. ๐\n\n## Mark GitHub Discussions Answers\n\nWhen a question in GitHub Discussions has been answered, mark the answer by clicking \"Mark as answer\".\n\nYou can filter discussions by `Questions` that are `Unanswered`.\n"
},
{
"path": "docs/management.md",
"content": "# Repository Management\n\nHere's a short description of how the Typer repository is managed and maintained.\n\n## Owner\n\nI, @tiangolo, am the creator and owner of the Typer repository. ๐ค\n\nI normally give the final review to each PR before merging them. I make the final decisions on the project, I'm the BDFL. ๐
\n\n## Team\n\nThere's a team of people that help manage and maintain the project. ๐\n\nThey have different levels of permissions and [specific instructions](./management-tasks.md){.internal-link target=_blank}.\n\nSome of the tasks they can perform include:\n\n* Adding labels to PRs.\n* Editing PR titles.\n* Adding commits on top of PRs to tweak them.\n* Mark answers in GitHub Discussions questions, etc.\n* Merge some specific types of PRs.\n\nJoining the team is by invitation only, and I could update or remove permissions, instructions, or membership.\n\n### Team Members\n\nThis is the current list of team members. ๐\n\n\n{% for user in members[\"members\"] %}\n\n
\n{% endfor %}\n\n
\n\n```console\n$ python main.py\n\nConfig file doesn't exist yet\n```\n\n
\n\n## About `Path`\n\nIf you hadn't seen something like that:\n\n```Python\nPath(app_dir) / \"config.json\"\n```\n\nA `Path` object can be used with `/` and it will convert it to the separator for the current system (`/` for Unix systems and `\\` for Windows).\n\nIf the first element is a `Path` object the next ones (after the `/`) can be `str`.\n\nAnd it will create a new `Path` object from that.\n\nIf you want a quick guide on using `Path()` you can check this post on Real Python or this post by Trey Hunner.\n\nIn the code above, we are also explicitly declaring `config_path` as having type `Path` to help the editor provide completion and type checks:\n\n```Python\nconfig_path: Path = Path(app_dir) / \"config.json\"\n```\n\nOtherwise it could think it's a sub-type (a `PurePath`) and stop providing completion for some methods.\n"
},
{
"path": "docs/tutorial/arguments/default.md",
"content": "# CLI Arguments with Default\n\nWe can also use the same `typer.Argument()` to set a default value.\n\nThat way the *CLI argument* will be optional *and also* have a default value.\n\n## An optional *CLI argument* with a default\n\nWe can also use `typer.Argument()` to make a *CLI argument* have a default value other than `None`:\n\n{* docs_src/arguments/default/tutorial001_an_py310.py hl[9] *}\n\n/// tip\n\nBecause now the value will be a `str` passed by the user or the default value of `\"Wade Wilson\"` which is also a `str`, we know the value will never be `None`, so we don't have to (and shouldn't) use `Optional[str]`.\n\nHave in mind that the `Optional[something]` tells Python that a value \"could be `None`\". But the use of `Optional` doesn't affect Typer in any way, e.g. it doesn't tell Typer if a value is required or not.\n\n///\n\nCheck it:\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\n// Notice the [default: Wade Wilson] โจ\nUsage: main.py [OPTIONS] [NAME]\n\nArguments:\n [NAME] [default: Wade Wilson]\n\nOptions:\n --help Show this message and exit.\n\n// With no optional CLI argument\n$ python main.py\n\nHello Wade Wilson\n\n// With one CLI argument\n$ python main.py Camila\n\nHello Camila\n```\n\n
\n\n## Dynamic default value\n\nAnd we can even make the default value be dynamically generated by passing a function as the `default_factory` argument:\n\n{* docs_src/arguments/default/tutorial002_an_py310.py hl[9:10,14] *}\n\nIn this case, we created the function `get_name` that will just return a random `str` each time.\n\nAnd we pass it as the first function argument to `typer.Argument()`.\n\n/// tip\n\nThe word \"factory\" in `default_factory` is just a fancy way of saying \"function that will create the default value\".\n\n///\n\nCheck it:\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\nUsage: main.py [OPTIONS] [NAME]\n\nArguments:\n [NAME] [default: (dynamic)]\n\nOptions:\n --help Show this message and exit.\n\n// Try it several times, it will use a random default each time\n$ python main.py\n\nHello Deadpool\n\n$ python main.py\n\nHello Hiro\n\n$ python main.py\n\nHello Rick\n\n// Now pass a value for the CLI argument\n$ python main.py Camila\n\nHello Camila\n```\n\n
\n"
},
{
"path": "docs/tutorial/arguments/envvar.md",
"content": "# CLI Arguments with Environment Variables\n\nYou can also configure a *CLI argument* to read a value from an environment variable if it is not provided in the command line as a *CLI argument*.\n\n/// tip\n\nYou can learn more about environment variables in the [Environment Variables](../../environment-variables.md){.internal-link target=_blank} page.\n\n///\n\nTo do that, use the `envvar` parameter for `typer.Argument()`:\n\n{* docs_src/arguments/envvar/tutorial001_an_py310.py hl[9] *}\n\nIn this case, the *CLI argument* `name` will have a default value of `\"World\"`, but will also read any value passed to the environment variable `AWESOME_NAME` if no value is provided in the command line:\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\nUsage: main.py [OPTIONS] [NAME]\n\nArguments:\n [NAME] [env var: AWESOME_NAME;default: World]\n\nOptions:\n --help Show this message and exit.\n\n// Call it without a CLI argument\n$ python main.py\n\nHello Mr. World\n\n// Now pass a value for the CLI argument\n$ python main.py Czernobog\n\nHello Mr. Czernobog\n\n// And now use the environment variable\n$ AWESOME_NAME=Wednesday python main.py\n\nHello Mr. Wednesday\n\n// CLI arguments take precedence over env vars\n$ AWESOME_NAME=Wednesday python main.py Czernobog\n\nHello Mr. Czernobog\n```\n\n
\n\n## Multiple environment variables\n\nYou are not restricted to a single environment variable, you can declare a list of environment variables that could be used to get a value if it was not passed in the command line:\n\n{* docs_src/arguments/envvar/tutorial002_an_py310.py hl[10] *}\n\nCheck it:\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\nUsage: main.py [OPTIONS] [NAME]\n\nArguments:\n [NAME] [env var: AWESOME_NAME, GOD_NAME;default: World]\n\nOptions:\n --help Show this message and exit.\n\n// Try the first env var\n$ AWESOME_NAME=Wednesday python main.py\n\nHello Mr. Wednesday\n\n// Try the second env var\n$ GOD_NAME=Anubis python main.py\n\nHello Mr. Anubis\n```\n\n
\n\n## Hide an env var from the help text\n\nBy default, environment variables used will be shown in the help text, but you can disable them with `show_envvar=False`:\n\n{* docs_src/arguments/envvar/tutorial003_an_py310.py hl[11] *}\n\nCheck it:\n\n\n\n```console\n//Check the help\n$ python main.py --help\n\n// It won't show the env var\nUsage: main.py [OPTIONS] [NAME]\n\nArguments:\n [NAME] [default: World]\n\nOptions:\n --help Show this message and exit.\n\n// But it will still be able to use it\n$ AWESOME_NAME=Wednesday python main.py\n\nHello Mr. Wednesday\n```\n\n
\n"
},
{
"path": "docs/tutorial/arguments/help.md",
"content": "# CLI Arguments with Help\n\nIn the *First Steps* section you saw how to add help for a CLI app/command by adding it to a function's docstring.\n\nHere's how that last example looked like:\n\n{* docs_src/first_steps/tutorial006_py310.py *}\n\nNow that you also know how to use `typer.Argument()`, let's use it to add documentation specific for a *CLI argument*.\n\n## Add a `help` text for a *CLI argument*\n\nYou can use the `help` parameter to add a help text for a *CLI argument*:\n\n{* docs_src/arguments/help/tutorial001_an_py310.py hl[9] *}\n\nAnd it will be used in the automatic `--help` option:\n\n\n\n```console\n$ python main.py --help\n\n// Check the section with Arguments below ๐\nUsage: main.py [OPTIONS] NAME\n\nArguments:\n NAME The name of the user to greet [required]\n\nOptions:\n --help Show this message and exit.\n```\n\n
\n\n## Combine help text and docstrings\n\nAnd of course, you can also combine that `help` with the docstring:\n\n{* docs_src/arguments/help/tutorial002_an_py310.py hl[9:12] *}\n\nAnd the `--help` option will combine all the information:\n\n\n\n```console\n$ python main.py --help\n\n// Notice that we have the help text from the docstring and also the Arguments ๐\nUsage: main.py [OPTIONS] NAME\n\n Say hi to NAME very gently, like Dirk.\n\nArguments:\n NAME The name of the user to greet [required]\n\nOptions:\n --help Show this message and exit.\n```\n\n
\n\n## Help with defaults\n\nIf you have a *CLI argument* with a default value, like `\"World\"`:\n\n{* docs_src/arguments/help/tutorial003_an_py310.py hl[9] *}\n\nIt will show that default value in the help text:\n\n\n\n```console\n$ python main.py --help\n\n// Notice the [default: World] ๐\nUsage: main.py [OPTIONS] [NAME]\n\n Say hi to NAME very gently, like Dirk.\n\nArguments:\n [NAME] Who to greet [default: World]\n\nOptions:\n --help Show this message and exit.\n```\n\n
\n\nBut you can disable that if you want to, with `show_default=False`:\n\n{* docs_src/arguments/help/tutorial004_an_py310.py hl[11] *}\n\nAnd then it won't show the default value:\n\n\n\n```console\n$ python main.py --help\n\n// Notice the there's no [default: World] now ๐ฅ\nUsage: main.py [OPTIONS] [NAME]\n\n Say hi to NAME very gently, like Dirk.\n\nArguments:\n [NAME] Who to greet\n\nOptions:\n --help Show this message and exit.\n```\n\n
\n\n## Custom default string\n\nYou can use the same `show_default` to pass a custom string (instead of a `bool`) to customize the default value to be shown in the help text:\n\n{* docs_src/arguments/help/tutorial005_an_py310.py hl[13] *}\n\nAnd it will be used in the help text:\n\n\n\n```console\n$ python main.py --help\n\nUsage: main.py [OPTIONS] [NAME]\n\nArguments:\n [NAME] Who to greet [default: (Deadpoolio the amazing's name)]\n\n\nOptions:\n --help Show this message and exit.\n\n// See it shows \"(Deadpoolio the amazing's name)\" instead of the actual default of \"Wade Wilson\"\n```\n\n
\n\n## Custom help name (`metavar`)\n\nYou can also customize the text used in the generated help text to represent a *CLI argument*.\n\nBy default, it will be the same name you declared, in uppercase letters.\n\nSo, if you declare it as:\n\n```Python\nname: str\n```\n\nIt will be shown as:\n\n```\nNAME\n```\n\nBut you can customize it with the `metavar` parameter for `typer.Argument()`.\n\nFor example, let's say you don't want to have the default of `NAME`, you want to have `username`, in lowercase, and you really want โจ emojis โจ everywhere:\n\n{* docs_src/arguments/help/tutorial006_an_py310.py hl[9] *}\n\nNow the generated help text will have `โจusernameโจ` instead of `NAME`:\n\n\n\n```console\n$ python main.py --help\n\nUsage: main.py [OPTIONS] [โจusernameโจ]\n\nArguments:\n [โจusernameโจ] [default: World]\n\nOptions:\n --help Show this message and exit.\n```\n\n
\n\n## *CLI Argument* help panels\n\nYou might want to show the help information for *CLI arguments* in different panels when using the `--help` option.\n\nIf you have installed Rich as described in the docs for [Printing and Colors](../printing.md){.internal-link target=_blank}, you can set the `rich_help_panel` parameter to the name of the panel where you want this *CLI argument* to be shown:\n\n{* docs_src/arguments/help/tutorial007_an_py310.py hl[12,16] *}\n\nThen, if you check the `--help` option, you will see a default panel named \"`Arguments`\" for the *CLI arguments* that don't have a custom `rich_help_panel`.\n\nAnd next you will see other panels for the *CLI arguments* that have a custom panel set in the `rich_help_panel` parameter:\n\n\n\n```console\n$ python main.py --help\n\n Usage: main.py [OPTIONS] NAME [LASTNAME] [AGE] \n \n Say hi to NAME very gently, like Dirk.\n\nโญโ Arguments โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ * name TEXT Who to greet [default: None] [required] โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Secondary Arguments โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ lastname [LASTNAME] The last name โ\nโ age [AGE] The user's age โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --help Show this message and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n```\n\n
\n\nIn this example we have a custom *CLI arguments* panel named \"`Secondary Arguments`\".\n\n## Help with style using Rich\n\nIn a future section you will see how to use custom markup in the `help` for *CLI arguments* when reading about [Commands - Command Help](../commands/help.md#rich-markdown-and-markup){.internal-link target=_blank}.\n\nIf you are in a hurry you can jump there, but otherwise, it would be better to continue reading here and following the tutorial in order.\n\n## Hide a *CLI argument* from the help text\n\nIf you want, you can make a *CLI argument* **not** show up in the `Arguments` section in the help text.\n\nYou will probably not want to do this normally, but it's possible:\n\n{* docs_src/arguments/help/tutorial008_an_py310.py hl[9] *}\n\nCheck it:\n\n\n\n```console\n$ python main.py --help\n\n// Notice there's no Arguments section at all ๐ฅ\nUsage: main.py [OPTIONS] [NAME]\n\n Say hi to NAME very gently, like Dirk.\n\nOptions:\n --help Show this message and exit.\n```\n\n
\n\n/// info\n\nHave in mind that the *CLI argument* will still show up in the first line with `Usage`.\n\nBut it won't show up in the main help text under the `Arguments` section.\n\n///\n\n### Help text for *CLI arguments*\n\n**Typer supports `help` for *CLI arguments*** to make it easier to have consistent help texts with a consistent format for your CLI programs. ๐จ\n\nThis is also to help you create CLI programs that are โจ awesome โจ *by default*. With very little code.\n\nIf you don't want the CLI Argument to be shown in help outputs, you can set the `hidden` parameter to `True`.\n"
},
{
"path": "docs/tutorial/arguments/index.md",
"content": "# CLI Arguments\n\nIn the next few sections we'll see some ways to modify how *CLI arguments* work.\n\nWe'll create optional *CLI arguments*, we'll add integrated help for *CLI arguments*, etc.\n"
},
{
"path": "docs/tutorial/arguments/optional.md",
"content": "# Optional CLI Arguments\n\nWe said before that *by default*:\n\n* *CLI options* are **optional**\n* *CLI arguments* are **required**\n\nAgain, that's how they work *by default*, and that's the convention in many CLI programs and systems.\n\nBut you can change that.\n\nIn fact, it's very common to have **optional** *CLI arguments*, it's way more common than having **required** *CLI options*.\n\nAs an example of how it could be useful, let's see how the `ls` CLI program works.\n\n\n\n```console\n// If you just type\n$ ls\n\n// ls will \"list\" the files and directories in the current directory\ntyper tests README.md LICENSE\n\n// But it also receives an optional CLI argument\n$ ls ./tests/\n\n// And then ls will list the files and directories inside of that directory from the CLI argument\n__init__.py test_tutorial\n```\n\n
\n\n## An alternative *CLI argument* declaration\n\nIn the [First Steps](../first-steps.md#add-a-cli-argument){.internal-link target=_blank} you saw how to add a *CLI argument*:\n\n{* docs_src/first_steps/tutorial002_py310.py hl[4] *}\n\nNow let's see an alternative way to create the same *CLI argument*:\n\n{* docs_src/arguments/optional/tutorial000_an_py310.py hl[6] *}\n\nOr, using an explicit `Typer()` instance creation:\n\n{* docs_src/arguments/optional/tutorial001_an_py310.py hl[9] *}\n\n/// info\n\nTyper added support for `Annotated` (and started recommending it) in version 0.9.0.\n\nIf you have an older version, you would get errors when trying to use `Annotated`.\n\nMake sure you upgrade the Typer version to at least 0.9.0 before using `Annotated`.\n\n///\n\nBefore, you had this function parameter:\n\n```Python\nname: str\n```\n\nAnd now we wrap it with `Annotated`:\n\n```Python\nname: Annotated[str]\n```\n\nBoth of these versions mean the same thing, `Annotated` is part of standard Python and is there for this.\n\nBut the second version using `Annotated` allows us to pass additional metadata that can be used by **Typer**:\n\n```Python\nname: Annotated[str, typer.Argument()]\n```\n\nNow we are being explicit that `name` is a *CLI argument*. It's still a `str` and it's still required (it doesn't have a default value).\n\nAll we did there achieves the same thing as before, a **required** *CLI argument*:\n\n\n\n```console\n$ python main.py\n\nUsage: main.py [OPTIONS] NAME\nTry \"main.py --help\" for help.\n\nError: Missing argument 'NAME'.\n```\n\n
\n\nIt's still not very useful, but it works correctly.\n\nAnd being able to declare a **required** *CLI argument* using\n\n```Python\nname: Annotated[str, typer.Argument()]\n```\n\n...that works exactly the same as\n\n```Python\nname: str\n```\n\n...will come handy later.\n\n## Make an optional *CLI argument*\n\nNow, finally what we came for, an optional *CLI argument*.\n\nTo make a *CLI argument* optional, use `typer.Argument()` and make sure to provide a \"default\" value, for example `\"World\"`:\n\n{* docs_src/arguments/optional/tutorial002_an_py310.py hl[9] *}\n\nNow we have:\n\n```Python\nname: Annotated[str, typer.Argument()] = \"World\"\n```\n\nBecause we are using `typer.Argument()` **Typer** will know that this is a *CLI argument* (no matter if *required* or *optional*).\n\nCheck the help:\n\n\n\n```console\n// First check the help\n$ python main.py --help\n\nUsage: main.py [OPTIONS] [NAME]\n\nArguments:\n [NAME]\n\nOptions:\n --help Show this message and exit.\n```\n\n
\n\n/// tip\n\nNotice that `NAME` is still a *CLI argument*, it's shown up there in the \"`Usage: main.py` ...\".\n\nAlso notice that now `[NAME]` has brackets (\"`[`\" and \"`]`\") around (before it was just `NAME`) to denote that it's **optional**, not **required**.\n\n///\n\nNow run it and test it:\n\n\n\n```console\n// With no CLI argument\n$ python main.py\n\nHello World!\n\n// With one optional CLI argument\n$ python main.py Camila\n\nHello Camila\n```\n\n
\n\n/// tip\n\nNotice that \"`Camila`\" here is an optional *CLI argument*, not a *CLI option*, because we didn't use something like \"`--name Camila`\", we just passed \"`Camila`\" directly to the program.\n\n///\n\n## Alternative (old) `typer.Argument()` as the default value\n\n**Typer** also supports another older alternative syntax for declaring *CLI arguments* with additional metadata.\n\nInstead of using `Annotated`, you can use `typer.Argument()` as the default value:\n\n{* docs_src/arguments/optional/tutorial001_py310.py hl[7] *}\n\n/// tip\n\nPrefer to use the `Annotated` version if possible.\n\n///\n\nBefore, because `name` didn't have any default value it would be a **required parameter** for the Python function, in Python terms.\n\nWhen using `typer.Argument()` as the default value **Typer** does the same and makes it a **required** *CLI argument*.\n\nWe changed it to:\n\n```Python\nname: str = typer.Argument()\n```\n\nBut now as `typer.Argument()` is the \"default value\" of the function's parameter, it would mean that \"it is no longer required\" (in Python terms).\n\nAs we no longer have the Python function default value (or its absence) to tell if something is required or not and what is the default value, `typer.Argument()` receives a first parameter `default` that serves the same purpose of defining that default value, or making it required.\n\nNot passing any value to the `default` argument is the same as marking it as required. But you can also explicitly mark it as *required* by passing `...` as the `default` argument, passed to `typer.Argument(default=...)`.\n\n```Python\nname: str = typer.Argument(default=...)\n```\n\n/// info\n\nIf you hadn't seen that `...` before: it is a special single value, it is part of Python and is called \"Ellipsis\".\n\n///\n\n{* docs_src/arguments/optional/tutorial003_py310.py hl[7] *}\n\nAnd the same way, you can make it optional by passing a different `default` value, for example `\"World\"`:\n\n{* docs_src/arguments/optional/tutorial002_py310.py hl[7] *}\n\nBecause the first parameter passed to `typer.Argument(default=\"World\")` (the new \"default\" value) is `\"World\"`, **Typer** knows that this is an **optional** *CLI argument*, if no value is provided when calling it in the command line, it will have that default value of `\"World\"`.\n\nThe `default` argument is the first one, so it's possible that you see code that passes the value without explicitly using `default=`, like:\n\n```Python\nname: str = typer.Argument(...)\n```\n\n...or like:\n\n```Python\nname: str = typer.Argument(\"World\")\n```\n\n...but again, try to use `Annotated` if possible, that way your code in terms of Python will mean the same thing as with **Typer** and you won't have to remember any of these details.\n"
},
{
"path": "docs/tutorial/arguments/other-uses.md",
"content": "# Other uses\n\n`typer.Argument()` has several other use cases. Such as for data validation, to enable other features, etc.\n\nYou will see about these use cases later in the docs.\n"
},
{
"path": "docs/tutorial/commands/arguments.md",
"content": "# Command CLI Arguments\n\nThe same way as with a CLI application with a single command, subcommands (or just \"commands\") can also have their own *CLI arguments*:\n\n{* docs_src/commands/arguments/tutorial001_py310.py hl[7,12] *}\n\n\n\n```console\n// Check the help for create\n$ python main.py create --help\n\nUsage: main.py create [OPTIONS] USERNAME\n\nOptions:\n --help Show this message and exit.\n\n// Call it with a CLI argument\n$ python main.py create Camila\n\nCreating user: Camila\n\n// The same for delete\n$ python main.py delete Camila\n\nDeleting user: Camila\n```\n\n
\n\n/// tip\n\nEverything to the *right* of the *command* are *CLI parameters* (*CLI arguments* and *CLI options*) for that command.\n\n///\n\n/// note | Technical Details\n\nActually, it's everything to the right of that command, *before any subcommand*.\n\nIt's possible to have groups of *subcommands*, it's like if one *command* also had *subcommands*. And then those *subcommands* could have their own *CLI parameters*, taking their own *CLI parameters*.\n\nYou will see about them later in another section.\n\n///\n"
},
{
"path": "docs/tutorial/commands/callback.md",
"content": "# Typer Callback\n\nWhen you create an `app = typer.Typer()` it works as a group of commands.\n\nAnd you can create multiple commands with it.\n\nEach of those commands can have their own *CLI parameters*.\n\nBut as those *CLI parameters* are handled by each of those commands, they don't allow us to create *CLI parameters* for the main CLI application itself.\n\nBut we can use `@app.callback()` for that.\n\nIt's very similar to `@app.command()`, but it declares the *CLI parameters* for the main CLI application (before the commands):\n\n{* docs_src/commands/callback/tutorial001_py310.py hl[25,26,27,28,29,30,31,32] *}\n\nHere we create a `callback` with a `--verbose` *CLI option*.\n\n/// tip\n\nAfter getting the `--verbose` flag, we modify a global `state`, and we use it in the other commands.\n\nThere are other ways to achieve the same, but this will suffice for this example.\n\n///\n\nAnd as we added a docstring to the callback function, by default it will be extracted and used as the help text.\n\nCheck it:\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\n// Notice the main help text, extracted from the callback function: \"Manage users in the awesome CLI app.\"\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\n Manage users in the awesome CLI app.\n\nOptions:\n --verbose / --no-verbose [default: False]\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n create\n delete\n\n// Check the new top level CLI option --verbose\n\n// Try it normally\n$ python main.py create Camila\n\nCreating user: Camila\n\n// And now with --verbose\n$ python main.py --verbose create Camila\n\nWill write verbose output\nAbout to create a user\nCreating user: Camila\nJust created a user\n\n// Notice that --verbose belongs to the callback, it has to go before create or delete โ๏ธ\n$ python main.py create --verbose Camila\n\nUsage: main.py create [OPTIONS] USERNAME\nTry \"main.py create --help\" for help.\n\nError: No such option: --verbose\n```\n\n
\n\n## Adding a callback on creation\n\nIt's also possible to add a callback when creating the `typer.Typer()` app:\n\n{* docs_src/commands/callback/tutorial002_py310.py hl[4,5,8] *}\n\nThat achieves the same as with `@app.callback()`.\n\nCheck it:\n\n\n\n```console\n$ python main.py create Camila\n\nRunning a command\nCreating user: Camila\n```\n\n
\n\n## Overriding a callback\n\nIf you added a callback when creating the `typer.Typer()` app, it's possible to override it with `@app.callback()`:\n\n{* docs_src/commands/callback/tutorial003_py310.py hl[11,12,13] *}\n\nNow `new_callback()` will be the one used.\n\nCheck it:\n\n\n\n```console\n$ python main.py create Camila\n\n// Notice that the message is the one from new_callback()\nOverride callback, running a command\nCreating user: Camila\n```\n\n
\n\n## Adding a callback only for documentation\n\nYou can also add a callback just to add the documentation in the docstring.\n\nIt can be convenient especially if you have several lines of text, as the indentation will be automatically handled for you:\n\n{* docs_src/commands/callback/tutorial004_py310.py hl[8,9,10,11,12,13,14,15,16] *}\n\nNow the callback will be used mainly to extract the docstring for the help text.\n\nCheck it:\n\n\n\n```console\n$ python main.py --help\n\n// Notice all the help text extracted from the callback docstring\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\n Manage users CLI app.\n\n Use it with the create command.\n\n A new user with the given NAME will be created.\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n create\n\n// And it just works as normally\n$ python main.py create Camila\n\nCreating user: Camila\n```\n\n
\n"
},
{
"path": "docs/tutorial/commands/context.md",
"content": "# Using the Context\n\nWhen you create a **Typer** application it always has a special, hidden object underneath called the \"Context\".\n\nBut you can access the context by declaring a function parameter of type `typer.Context`.\n\nYou might have read it in [CLI Option Callback and Context](../options/callback-and-context.md){.internal-link target=_blank}.\n\nThe same way, in commands or in the main `Typer` callback you can access the context by declaring a function parameter of type `typer.Context`.\n\n## Getting the context\n\nFor example, let's say that you want to execute some logic in a `Typer` callback depending on the subcommand that is being called.\n\nYou can get the name of the subcommand from the context:\n\n{* docs_src/commands/context/tutorial001_py310.py hl[17,21] *}\n\nCheck it:\n\n\n\n```console\n$ python main.py create Camila\n\n// We get the message from the callback\nAbout to execute command: create\nCreating user: Camila\n\n$ python main.py delete Camila\n\n// We get the message from the callback, this time with delete\nAbout to execute command: delete\nDeleting user: Camila\n```\n\n
\n\n## Executable callback\n\nBy default, the callback is only executed right before executing a command.\n\nAnd if no command is provided, the help message is shown.\n\nBut we could make it run even without a subcommand with `invoke_without_command=True`:\n\n{* docs_src/commands/context/tutorial002_py310.py hl[16] *}\n\nCheck it:\n\n\n\n```console\n$ python main.py\n\n// The callback is executed, we don't get the default help message\nInitializing database\n\n// Try with a command\n$ python main.py create Camila\n\n// The callback is still executed\nInitializing database\nCreating user: Camila\n```\n\n
\n\n## Exclusive executable callback\n\nWe might not want the callback to be executed if there's already other command that will be executed.\n\nFor that, we can get the `typer.Context` and check if there's an invoked command in `ctx.invoked_subcommand`.\n\nIf it's `None`, it means that we are not calling a subcommand but the main program (the callback) directly:\n\n{* docs_src/commands/context/tutorial003_py310.py hl[17,21] *}\n\nCheck it:\n\n\n\n```console\n$ python main.py\n\n// The callback is executed\nInitializing database\n\n// Check it with a subcommand\n$ python main.py create Camila\n\n// This time the callback is not executed\nCreating user: Camila\n```\n\n
\n\n## Configuring the context\n\nYou can pass configurations for the context when creating a command or callback.\n\nFor example, you could keep additional *CLI parameters* not declared in your CLI program with `ignore_unknown_options` and `allow_extra_args`.\n\nThen you can access those extra raw *CLI parameters* as a `list` of `str` in `ctx.args`:\n\n{* docs_src/commands/context/tutorial004_py310.py hl[7,9,10] *}\n\n\n\n```console\n$ python main.py --name Camila --city Berlin\n\nGot extra arg: --name\nGot extra arg: Camila\nGot extra arg: --city\nGot extra arg: Berlin\n```\n\n
\n\n/// tip\n\nNotice that it saves all the extra *CLI parameters* as a raw `list` of `str`, including the *CLI option* names and values, everything together.\n\n///\n"
},
{
"path": "docs/tutorial/commands/help.md",
"content": "# Command Help\n\nThe same as before, you can add help for the commands in the docstrings and the *CLI options*.\n\nAnd the `typer.Typer()` application receives a parameter `help` that you can pass with the main help text for your CLI program:\n\n{* docs_src/commands/help/tutorial001_an_py310.py hl[5,10:12,23,27:31,44,48:52,61:63] *}\n\nCheck it:\n\n\n\n```console\n// Check the new help\n$ python main.py --help\n\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\n Awesome CLI user manager.\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n create Create a new user with USERNAME.\n delete Delete a user with USERNAME.\n delete-all Delete ALL users in the database.\n init Initialize the users database.\n\n// Now the commands have inline help ๐\n\n// Check the help for create\n$ python main.py create --help\n\nUsage: main.py create [OPTIONS] USERNAME\n\n Create a new user with USERNAME.\n\nOptions:\n --help Show this message and exit.\n\n// Check the help for delete\n$ python main.py delete --help\n\nUsage: main.py delete [OPTIONS] USERNAME\n\n Delete a user with USERNAME.\n\n If --force is not used, will ask for confirmation.\n\nOptions:\n --force / --no-force Force deletion without confirmation. [required]\n --help Show this message and exit.\n\n// Check the help for delete-all\n$ python main.py delete-all --help\n\nUsage: main.py delete-all [OPTIONS]\n\n Delete ALL users in the database.\n\n If --force is not used, will ask for confirmation.\n\nOptions:\n --force / --no-force Force deletion without confirmation. [required]\n --help Show this message and exit.\n\n// Check the help for init\n$ python main.py init --help\n\nUsage: main.py init [OPTIONS]\n\n Initialize the users database.\n\nOptions:\n --help Show this message and exit.\n```\n\n
\n\n/// tip\n\n`typer.Typer()` receives several other parameters for other things, we'll see that later.\n\nYou will also see how to use \"Callbacks\" later, and those include a way to add this same help message in a function docstring.\n\n///\n\n## Overwrite command help\n\nYou will probably be better adding the help text as a docstring to your functions, but if for some reason you wanted to overwrite it, you can use the `help` function argument passed to `@app.command()`:\n\n{* docs_src/commands/help/tutorial002_py310.py hl[6,14] *}\n\nCheck it:\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\n// Notice it uses the help passed to @app.command()\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy\n it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n create Create a new user with USERNAME.\n delete Delete a user with USERNAME.\n\n// It uses \"Create a new user with USERNAME.\" instead of \"Some internal utility function to create.\"\n```\n\n
\n\n## Deprecate a Command\n\nThere could be cases where you have a command in your app that you need to deprecate, so that your users stop using it, even while it's still supported for a while.\n\nYou can mark it with the parameter `deprecated=True`:\n\n{* docs_src/commands/help/tutorial003_py310.py hl[14] *}\n\nAnd when you show the `--help` option you will see it's marked as \"`deprecated`\":\n\n\n\n```console\n$ python main.py --help\n\n Usage: main.py [OPTIONS] COMMAND [ARGS]... \n \nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --install-completion Install completion for the current โ\nโ shell. โ\nโ --show-completion Show completion for the current โ\nโ shell, to copy it or customize the โ\nโ installation. โ\nโ --help Show this message and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Commands โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ create Create a user. โ\nโ delete Delete a user. (deprecated) โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n```\n\n
\n\nAnd if you check the `--help` for the deprecated command (in this example, the command `delete`), it also shows it as deprecated:\n\n\n\n```console\n$ python main.py delete --help\n\n Usage: main.py delete [OPTIONS] USERNAME \n \n (deprecated) \n Delete a user.\n This is deprecated and will stop being supported soon.\n\nโญโ Arguments โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ * username TEXT [default: None] [required] โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --help Show this message and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n```\n\n
\n\n## Suggest Commands\n\nAs of version 0.20.0, Typer added support for suggesting mistyped command names. This feature is **enabled by default**, but you can disable it with the parameter `suggest_commands=False`:\n\n{* docs_src/commands/index/tutorial005_py310.py hl[3] *}\n\nIf a user mistypes a command, they'll see a helpful suggestion:\n\n\n\n```console\n$ python main.py crate\n\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\nTry 'main.py --help' for help.\nโญโ Error โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ No such command 'crate'. Did you mean 'create'? โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n```\n\n
\n\nIf there are multiple close matches, Typer will suggest them all. This feature uses Python's built-in `difflib.get_close_matches()` to find similar command names, making your CLI more user-friendly by helping users recover from typos.\n\n## Rich Markdown and Markup\n\nTyper installs **Rich** to allow for more formatting in the docstrings and the `help` parameter for *CLI arguments* and *CLI options*. You will see more about it below. ๐\n\n/// info\n\nYou can disable rich text formatting by setting `rich_markup_mode` to `None` for your specific app.\nAlternatively, you can disable it globally using an environmental variable `TYPER_USE_RICH` set to `False` or `0`.\n\n///\n\n### Rich Markup\n\nIf you set `rich_markup_mode=\"rich\"` when creating the `typer.Typer()` app (which is the default), you will be able to use Rich Console Markup in the docstring, and even in the help for the *CLI arguments* and options:\n\n{* docs_src/commands/help/tutorial004_an_py310.py hl[5,11,15:17,22,25,28] *}\n\nWith that, you can use Rich Console Markup to format the text in the docstring for the command `create`, make the word \"`create`\" bold and green, and even use an emoji.\n\nYou can also use markup in the help for the `username` CLI Argument.\n\nAnd the same as before, the help text overwritten for the command `delete` can also use Rich Markup, the same in the CLI Argument and CLI Option.\n\nIf you run the program and check the help, you will see that **Typer** uses **Rich** internally to format the help.\n\nCheck the help for the `create` command:\n\n\n\n```console\n$ python main.py create --help\n\n Usage: main.py create [OPTIONS] USERNAME \n \n Create a new shiny user. โจ\n This requires a username. \n\nโญโ Arguments โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ * username TEXT The username to be created โ\nโ [default: None] โ\nโ [required] โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --help Show this message and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n```\n\n
\n\nAnd check the help for the `delete` command:\n\n\n\n```console\n$ python main.py delete --help\n\n Usage: main.py delete [OPTIONS] USERNAME \n \n Delete a user with USERNAME.\n\nโญโ Arguments โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ * username TEXT The username to be deleted โ\nโ [default: None] โ\nโ [required] โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --force --no-force Force the deletion ๐ฅ โ\nโ [default: no-force] โ\nโ --help Show this message and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n```\n\n
\n\n### Rich Markdown\n\nIf you set `rich_markup_mode=\"markdown\"` when creating the `typer.Typer()` app, you will be able to use Markdown in the docstring:\n\n{* docs_src/commands/help/tutorial005_an_py310.py hl[5,10,13:21,26,28:29] *}\n\nWith that, you can use Markdown to format the text in the docstring for the command `create`, make the word \"`create`\" bold, show a list of items, and even use an emoji.\n\nAnd the same as before, the help text overwritten for the command `delete` can also use Markdown.\n\nCheck the help for the `create` command:\n\n\n\n```console\n$ python main.py create --help\n\n Usage: main.py create [OPTIONS] USERNAME \n \n Create a new shiny user. โจ\n\n โข Create a username \n โข Show that the username is created \n\n โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ\n Learn more at the Typer docs website\n\nโญโ Arguments โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ * username TEXT The username to be created โ\nโ [default: None] โ\nโ [required] โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --help Show this message and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n```\n\n
\n\nAnd the same for the `delete` command:\n\n\n\n```console\n$ python main.py delete --help\n\n Usage: main.py delete [OPTIONS] USERNAME \n \n Delete a user with USERNAME.\n\nโญโ Arguments โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ * username TEXT The username to be deleted โ\nโ [default: None] โ\nโ [required] โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --force --no-force Force the deletion ๐ฅ โ\nโ [default: no-force] โ\nโ --help Show this message and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n```\n\n
\n\n/// info\n\nNotice that in Markdown you cannot define colors. For colors you might prefer to use Rich markup.\n\n///\n\n## Help Panels\n\nIf you have many commands or CLI parameters, you might want to show their documentation in different panels when using the `--help` option.\n\nIf you installed Rich as described in [Printing and Colors](../printing.md){.internal-link target=_blank}, you can configure the panel to use for each command or CLI parameter.\n\n### Help Panels for Commands\n\nTo set the panel for a command you can pass the argument `rich_help_panel` with the name of the panel you want to use:\n\n{* docs_src/commands/help/tutorial006_py310.py hl[22,30,38,46] *}\n\nCommands without a panel will be shown in the default panel `Commands`, and the rest will be shown in the next panels:\n\n\n\n```console\n$ python main.py --help\n\n Usage: main.py [OPTIONS] COMMAND [ARGS]... \n \nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --install-completion Install completion for the current โ\nโ shell. โ\nโ --show-completion Show completion for the current โ\nโ shell, to copy it or customize the โ\nโ installation. โ\nโ --help Show this message and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Commands โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ create Create a new user. โจ โ\nโ delete Delete a user. โ โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Utils and Configs โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ config Configure the system. โ โ\nโ sync Synchronize the system or something fancy like that. โป โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Help and Others โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ help Get help with the system. โ โ\nโ report Report an issue. โ โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n```\n\n
\n\n### Help Panels for CLI Parameters\n\nThe same way, you can configure the panels for *CLI arguments* and *CLI options* with `rich_help_panel`.\n\nAnd of course, in the same application you can also set the `rich_help_panel` for commands.\n\n{* docs_src/commands/help/tutorial007_an_py310.py hl[14,20,26,36] *}\n\nThen if you run the application you will see all the *CLI parameters* in their respective panels.\n\n* First the ***CLI arguments*** that don't have a panel name set in a **default** one named \"`Arguments`\".\n* Next the ***CLI arguments*** with a **custom panel**. In this example named \"`Secondary Arguments`\".\n* After that, the ***CLI options*** that don't have a panel in a **default** one named \"`Options`\".\n* And finally, the ***CLI options*** with a **custom panel** set. In this example named \"`Additional Data`\".\n\nYou can check the `--help` option for the command `create`:\n\n\n\n```console\n$ python main.py create --help\n\n Usage: main.py create [OPTIONS] USERNAME [LASTNAME] \n \n Create a new user. โจ\n\nโญโ Arguments โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ * username TEXT The username to create [default: None] โ\nโ [required] โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Secondary Arguments โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ lastname [LASTNAME] The last name of the new user โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --force --no-force Force the creation of the user โ\nโ [default: no-force] โ\nโ --help Show this message and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Additional Data โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --age INTEGER The age of the new user โ\nโ [default: None] โ\nโ --favorite-color TEXT The favorite color of the new โ\nโ user โ\nโ [default: None] โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n```\n\n
\n\nAnd of course, the `rich_help_panel` can be used in the same way for commands in the same application.\n\nAnd those panels will be shown when you use the main `--help` option.\n\n\n\n```console\n$ python main.py --help\n\n Usage: main.py [OPTIONS] COMMAND [ARGS]... \n \nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --install-completion Install completion for the current โ\nโ shell. โ\nโ --show-completion Show completion for the current โ\nโ shell, to copy it or customize the โ\nโ installation. โ\nโ --help Show this message and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Commands โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ create Create a new user. โจ โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Utils and Configs โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ config Configure the system. โ โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n```\n\n
\n\nYou can see the custom panel for the commands for \"`Utils and Configs`\".\n\n## Epilog\n\nIf you need, you can also add an epilog section to the help of your commands:\n\n{* docs_src/commands/help/tutorial008_py310.py hl[6] *}\n\nAnd when you check the `--help` option it will look like:\n\n\n\n```console\n$ python main.py --help\n\n Usage: main.py [OPTIONS] USERNAME \n \n Create a new user. โจ\n\nโญโ Arguments โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ * username TEXT [default: None] [required] โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --install-completion Install completion for the current โ\nโ shell. โ\nโ --show-completion Show completion for the current โ\nโ shell, to copy it or customize the โ\nโ installation. โ\nโ --help Show this message and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n\n Made with โค in Venus\n```\n\n
\n"
},
{
"path": "docs/tutorial/commands/index.md",
"content": "# Commands\n\nWe have seen how to create a CLI program with possibly several *CLI options* and *CLI arguments*.\n\nBut **Typer** allows you to create CLI programs with several commands (also known as subcommands).\n\nFor example, the program `git` has several commands.\n\nOne command of `git` is `git push`. And `git push` in turn takes its own *CLI arguments* and *CLI options*.\n\nFor example:\n\n\n\n```console\n// The push command with no parameters\n$ git push\n\n---> 100%\n\n// The push command with one CLI option --set-upstream and 2 CLI arguments\n$ git push --set-upstream origin master\n\n---> 100%\n```\n\n
\n\nAnother command of `git` is `git pull`, it also has some *CLI parameters*.\n\nIt's like if the same big program `git` had several small programs inside.\n\n/// tip\n\nA command looks the same as a *CLI argument*, it's just some name without a preceding `--`. But commands have a predefined name, and are used to group different sets of functionalities into the same CLI application.\n\n///\n\n## Command or subcommand\n\nIt's common to call a CLI program a \"command\".\n\nBut when one of these programs have subcommands, those subcommands are also frequently called just \"commands\".\n\nHave that in mind so you don't get confused.\n\nHere I'll use **CLI application** or **program** to refer to the program you are building in Python with Typer, and **command** to refer to one of these \"subcommands\" of your program.\n\n## A CLI application with multiple commands\n\n**Typer** allows creating CLI applications with multiple commands/subcommands.\n\nNow that you know how to create an explicit `typer.Typer()` application and add one command, let's see how to add multiple commands.\n\nLet's say that we have a CLI application to manage users.\n\nWe'll have a command to `create` users and another command to `delete` them.\n\nTo begin, let's say it can only create and delete one single predefined user:\n\n{* docs_src/commands/index/tutorial002_py310.py hl[6,11] *}\n\nNow we have a CLI application with 2 commands, `create` and `delete`:\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n create\n delete\n\n// Test them\n$ python main.py create\n\nCreating user: Hiro Hamada\n\n$ python main.py delete\n\nDeleting user: Hiro Hamada\n\n// Now we have 2 commands! ๐\n```\n\n
\n\nNotice that the help text now shows the 2 commands: `create` and `delete`.\n\n/// tip\n\nBy default, the names of the commands are generated from the function name.\n\n///\n\n## Show the help message if no command is given\n\nBy default, we need to specify `--help` to get the command's help page.\n\nHowever, by setting `no_args_is_help=True` when defining the `typer.Typer()` application, the help function will be shown whenever no argument is given:\n\n{* docs_src/commands/index/tutorial003_py310.py hl[3] *}\n\nNow we can run this:\n\n\n\n```console\n// Check the help without having to type --help\n$ python main.py\n\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n create\n delete\n```\n\n
\n\n\n## Sorting of the commands\n\nNote that by design, **Typer** shows the commands in the order they've been declared.\n\nSo, if we take our original example, with `create` and `delete` commands, and reverse the order in the Python file:\n\n{* docs_src/commands/index/tutorial004_py310.py hl[7,12] *}\n\nThen we will see the `delete` command first in the help output:\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n delete\n create\n```\n\n
\n\n## Decorator Technical Details\n\nWhen you use `@app.command()` the function under the decorator is registered in the **Typer** application and is then used later by the application.\n\nBut Typer doesn't modify that function itself, the function is left as is.\n\nThat means that if your function is simple enough that you could create it without using `typer.Option()` or `typer.Argument()`, you could use the same function for a **Typer** application and a **FastAPI** application putting both decorators on top, or similar tricks.\n"
},
{
"path": "docs/tutorial/commands/name.md",
"content": "# Custom Command Name\n\nBy default, the command names are generated from the function name.\n\nSo, if your function is something like:\n\n```Python\ndef create(username: str):\n ...\n```\n\nThen the command name will be `create`.\n\nBut if you already had a function called `create()` somewhere in your code, you would have to name your CLI function differently.\n\nAnd what if you wanted the command to still be named `create`?\n\nFor this, you can set the name of the command in the first parameter for the `@app.command()` decorator:\n\n{* docs_src/commands/name/tutorial001_py310.py hl[6,11] *}\n\nNow, even though the functions are named `cli_create_user()` and `cli_delete_user()`, the commands will still be named `create` and `delete`:\n\n\n\n```console\n$ python main.py --help\n\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n create\n delete\n\n// Test it\n$ python main.py create Camila\n\nCreating user: Camila\n```\n\n
\n\nNote that any underscores in the function name will be replaced with dashes.\n\nSo if your function is something like:\n\n```Python\ndef create_user(username: str):\n ...\n```\nThen the command name will be `create-user`.\n"
},
{
"path": "docs/tutorial/commands/one-or-multiple.md",
"content": "# One or Multiple Commands\n\nYou might have noticed that if you create a single command, as in the following example:\n\n{* docs_src/typer_app/tutorial001_py310.py hl[3,6,12] *}\n\n**Typer** is smart enough to create a CLI application with that single function as the main CLI application, not as a command/subcommand:\n\n\n\n```console\n// Without a CLI argument\n$ python main.py\n\nUsage: main.py [OPTIONS] NAME\nTry \"main.py --help\" for help.\n\nError: Missing argument 'NAME'.\n\n// With the NAME CLI argument\n$ python main.py Camila\n\nHello Camila\n\n// Asking for help\n$ python main.py\n\nUsage: main.py [OPTIONS] NAME\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n```\n\n
\n\n/// tip\n\nNotice that it doesn't show a command `main`, even though the function name is `main`.\n\n///\n\nBut if you add multiple commands, **Typer** will create one *CLI command* for each one of them:\n\n{* docs_src/commands/index/tutorial002_py310.py hl[6,11] *}\n\nHere we have 2 commands `create` and `delete`:\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n create\n delete\n\n// Test the commands\n$ python main.py create\n\nCreating user: Hiro Hamada\n\n$ python main.py delete\n\nDeleting user: Hiro Hamada\n```\n\n
\n\n## One command and one callback\n\nIf you want to create a CLI app with one single command but you still want it to be a command/subcommand you can just add a callback:\n\n{* docs_src/commands/one_or_multiple/tutorial001_py310.py hl[11,12,13] *}\n\nAnd now your CLI program will have a single command.\n\nCheck it:\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\n// Notice the single command create\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n create\n\n// Try it\n$ python main.py create\n\nCreating user: Hiro Hamada\n```\n\n
\n\n## Using the callback to document\n\nNow that you are using a callback just to have a single command, you might as well use it to add documentation for your app:\n\n{* docs_src/commands/one_or_multiple/tutorial002_py310.py hl[11,12,13,14,15,16,17] *}\n\nAnd now the docstring from the callback will be used as the help text:\n\n\n\n```console\n$ python main.py --help\n\n// Notice the help text from the docstring\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\n Creates a single user Hiro Hamada.\n\n In the next version it will create 5 more users.\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n create\n\n// And it still works the same, the callback does nothing\n$ python main.py create\n\nCreating user: Hiro Hamada\n```\n\n
\n"
},
{
"path": "docs/tutorial/commands/options.md",
"content": "# Command CLI Options\n\nCommands can also have their own *CLI options*.\n\nIn fact, each command can have different *CLI arguments* and *CLI options*:\n\n{* docs_src/commands/options/tutorial001_an_py310.py hl[9,15:18,28:30,39] *}\n\nHere we have multiple commands, with different *CLI parameters*:\n\n* `create`:\n * `username`: a *CLI argument*.\n* `delete`:\n * `username`: a *CLI argument*.\n * `--force`: a *CLI option*, if not provided, it's prompted.\n* `delete-all`:\n * `--force`: a *CLI option*, if not provided, it's prompted.\n* `init`:\n * Doesn't take any *CLI parameters*.\n\n\n\n```console\n// Check the help\npython main.py --help\n\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n create\n delete\n delete-all\n init\n```\n\n
\n\n/// tip\n\nCheck the command `delete-all`, by default command names are generated from the function name, replacing `_` with `-`.\n\n///\n\nTest it:\n\n\n\n```console\n// Check the command create\n$ python main.py create Camila\n\nCreating user: Camila\n\n// Now test the command delete\n$ python main.py delete Camila\n\n# Are you sure you want to delete the user? [y/n]: $ y\n\nDeleting user: Camila\n\n$ python main.py delete Wade\n\n# Are you sure you want to delete the user? [y/n]: $ n\n\nOperation cancelled\n\n// And finally, the command delete-all\n// Notice it doesn't have CLI arguments, only a CLI option\n\n$ python main.py delete-all\n\n# Are you sure you want to delete ALL users? [y/n]: $ y\n\nDeleting all users\n\n$ python main.py delete-all\n\n# Are you sure you want to delete ALL users? [y/n]: $ n\n\nOperation cancelled\n\n// And if you pass the --force CLI option, it doesn't need to confirm\n\n$ python main.py delete-all --force\n\nDeleting all users\n\n// And init that doesn't take any CLI parameter\n$ python main.py init\n\nInitializing user database\n```\n\n
\n"
},
{
"path": "docs/tutorial/exceptions.md",
"content": "# Exceptions and Errors\n\nWhen your code has errors and you run it, it will show the error and an exception.\n\nTyper does some tricks to help you detect those errors quickly.\n\n## Example Broken App\n\nLet's take this example broken app:\n\n{* docs_src/exceptions/tutorial001_py310.py hl[8] *}\n\nThis code is broken because you can't sum a string and a number (`name + 3`).\n\n## Exceptions with Rich\n\n**Typer** will automatically use Rich to automatically show you nicely printed errors.\n\nIt will **omit** all the parts of the traceback (the chain of things that called your function) that come from the internal parts in Typer.\n\nSo, the error you see will be **much clearer** and simpler, to help you detect the problem in your code quickly:\n\n\n\n```console\n$ python main.py\n\nโญโโโโโโโโโโโโโโโโ Traceback (most recent call last) โโโโโโโโโโโโโโโโโฎ\nโ /home/user/code/superapp/main.py:8 in main โ\nโ โ\nโ 5 โ\nโ 6 @app.command() โ\nโ 7 def main(name: str = "morty"): โ\nโ โฑ 8 โ print(name + 3) โ\nโ 9 โ\nโ 10 โ\nโ 11 if __name__ == "__main__": โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nTypeError: can only concatenate str (not "int") to str\n```\n\n
\n\n## Exceptions without Rich\n\nYou can disable Rich globally using the environmental variable `TYPER_USE_RICH`.\n\nIn this case, Typer will still do some tricks to show you the information **as clearly as possible**:\n\n\n\n```console\n$ python main.py\n\nTraceback (most recent call last):\n\n File \"main.py\", line 12, in \n app()\n\n File \"main.py\", line 8, in main\n print(name + 3)\n\nTypeError: can only concatenate str (not \"int\") to str\n```\n\n
\n\n## Show Local Variables for Detailed Debugging\n\nWhen using Rich, you can get more verbose output by printing the values of the local variables as part of the error message.\n\nBy default, this setting is disabled (since Typer 0.23.0) to avoid showing **delicate information**, for example a **password**, a **key** or a **token**.\n\nIn these cases, it could be problematic if the automatic errors show the value in those local variables.\n\nThis would be relevant in particular if your CLI application is being run on some CI (continuous integration) system that is recording the logs.\n\nHowever, if you do want to enable the setting, you can set the parameter `pretty_exceptions_show_locals=True` when creating the `typer.Typer()` application:\n\n{* docs_src/exceptions/tutorial002_py310.py hl[3] *}\n\nNow, when using Rich, you will see the error with the local variables:\n\n\n\n```console\n$ python main.py\n\nโญโโโโโโโโโโโโโโโโ Traceback (most recent call last) โโโโโโโโโโโโโโโโโฎ\nโ /home/user/code/superapp/main.py:5 in main โ\nโ โ\nโ 2 โ\nโ 3 โ\nโ 4 def main(name: str = "morty"): โ\nโ โฑ 5 โ print(name + 3) โ\nโ 6 โ\nโ 7 โ\nโ 8 if __name__ == "__main__": โ\nโ โ\nโ โญโโโโ locals โโโโโฎ โ\nโ โ name = 'morty' โ โ\nโ โฐโโโโโโโโโโโโโโโโโฏ โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nTypeError: can only concatenate str (not "int") to str\n```\n\n
\n\nBeing able to see the values of local variables is very **helpful** to diagnose, **debug**, and fix problems.\n\nBut you should only enable it if you're not dealing with delicate information.\n\n## Disable Short Output\n\nIf you want to show the full exception, including the internal parts in Typer, you can use the parameter `pretty_exceptions_short=False`:\n\n{* docs_src/exceptions/tutorial003_py310.py hl[3] *}\n\nNow when you run it, you will see the whole output:\n\n\n\n```console\n$ python main.py\n\nโญโโโโโโโโโโโโโโโโ Traceback (most recent call last) โโโโโโโโโโโโโโโโโฎ\nโ /home/user/code/superapp/main.py:12 in <module> โ\nโ โ\nโ 9 โ\nโ 10 โ\nโ 11 if __name__ == "__main__": โ\nโ โฑ 12 โ app() โ\nโ 13 โ\nโ โ\nโ โญโโโโโโโโโโโโโโโโโโโโโโโโโโโ locals โโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ โ\nโ โ __annotations__ = {} โ โ\nโ โ __builtins__ = <module 'builtins' (built-in)> โ โ\nโ โ __cached__ = None โ โ\nโ โ __doc__ = None โ โ\nโ โ __file__ = 'main.py' โ โ\nโ โ __loader__ = <_frozen_importlib_external.SourceFileLoadโฆ โ โ\nโ โ object at 0x7f047db1c050> โ โ\nโ โ __name__ = '__main__' โ โ\nโ โ __package__ = None โ โ\nโ โ __spec__ = None โ โ\nโ โ app = <typer.main.Typer object at 0x7f047db51d90> โ โ\nโ โ main = <function main at 0x7f047db56830> โ โ\nโ โ typer = <module 'typer' from โ โ\nโ โ '/home/user/code/superapp/env/lib/python3.โฆ โ โ\nโ โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ โ\nโ โ\nโ /home/user/code/superapp/env/lib/python3.7/site-packages/typer/ma โ\nโ in.py:328 in __call__ โ\nโ โ\nโ /home/user/code/superapp/env/lib/python3.7/site-packages/typer/ma โ\nโ in.py:311 in __call__ โ\nโ โ\nโ /home/user/code/superapp/env/lib/python3.7/site-packages/click/co โ\nโ re.py:1130 in __call__ โ\nโ โ\nโ /home/user/code/superapp/env/lib/python3.7/site-packages/typer/co โ\nโ re.py:723 in main โ\nโ โ\nโ /home/user/code/superapp/env/lib/python3.7/site-packages/typer/co โ\nโ re.py:216 in _main โ\nโ โ\nโ /home/user/code/superapp/env/lib/python3.7/site-packages/click/co โ\nโ re.py:1404 in invoke โ\nโ โ\nโ /home/user/code/superapp/env/lib/python3.7/site-packages/click/co โ\nโ re.py:760 in invoke โ\nโ โ\nโ /home/user/code/superapp/env/lib/python3.7/site-packages/typer/ma โ\nโ in.py:683 in wrapper โ\nโ โ\nโ /home/user/code/superapp/main.py:8 in main โ\nโ โ\nโ 5 โ\nโ 6 @app.command() โ\nโ 7 def main(name: str = "morty"): โ\nโ โฑ 8 โ print(name + 3) โ\nโ 9 โ\nโ 10 โ\nโ 11 if __name__ == "__main__": โ\nโ โ\nโ โญโโโโ locals โโโโโฎ โ\nโ โ name = 'morty' โ โ\nโ โฐโโโโโโโโโโโโโโโโโฏ โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nTypeError: can only concatenate str (not "int") to str\n```\n\n
\n\n## Disable Pretty Exceptions\n\nYou can also entirely disable pretty exceptions with the parameter `pretty_exceptions_enable=False`:\n\n{* docs_src/exceptions/tutorial004_py310.py hl[3] *}\n\nAnd now you will see the full standard exception as with any other Python program:\n\n\n\n```console\n$ python main.py\n\nTraceback (most recent call last):\n File \"main.py\", line 12, in \n app()\n File \"/home/user/code/superapp/env/lib/python3.7/site-packages/typer/main.py\", line 328, in __call__\n raise e\n File \"/home/user/code/superapp/env/lib/python3.7/site-packages/typer/main.py\", line 311, in __call__\n return get_command(self)(*args, **kwargs)\n File \"/home/user/code/superapp/env/lib/python3.7/site-packages/click/core.py\", line 1130, in __call__\n return self.main(*args, **kwargs)\n File \"/home/user/code/superapp/env/lib/python3.7/site-packages/typer/core.py\", line 723, in main\n **extra,\n File \"/home/user/code/superapp/env/lib/python3.7/site-packages/typer/core.py\", line 216, in _main\n rv = self.invoke(ctx)\n File \"/home/user/code/superapp/env/lib/python3.7/site-packages/click/core.py\", line 1404, in invoke\n return ctx.invoke(self.callback, **ctx.params)\n File \"/home/user/code/superapp/env/lib/python3.7/site-packages/click/core.py\", line 760, in invoke\n return __callback(*args, **kwargs)\n File \"/home/user/code/superapp/env/lib/python3.7/site-packages/typer/main.py\", line 683, in wrapper\n return callback(**use_params) # type: ignore\n File \"main.py\", line 8, in main\n print(name + 3)\nTypeError: can only concatenate str (not \"int\") to str\n```\n\n
\n\nYou could also achieve the same with the environment variable `TYPER_STANDARD_TRACEBACK=1` (or by setting the deprecated variable `_TYPER_STANDARD_TRACEBACK=1`).\n\nThis will work for any other Typer program too, in case you need to debug a problem in a Typer program made by someone else:\n\n\n\n```console\nexport TYPER_STANDARD_TRACEBACK=1\n$ python main.py\n\n\nTraceback (most recent call last):\n File \"main.py\", line 12, in \n app()\n File \"/home/user/code/superapp/env/lib/python3.7/site-packages/typer/main.py\", line 328, in __call__\n raise e\n File \"/home/user/code/superapp/env/lib/python3.7/site-packages/typer/main.py\", line 311, in __call__\n return get_command(self)(*args, **kwargs)\n File \"/home/user/code/superapp/env/lib/python3.7/site-packages/click/core.py\", line 1130, in __call__\n return self.main(*args, **kwargs)\n File \"/home/user/code/superapp/env/lib/python3.7/site-packages/typer/core.py\", line 723, in main\n **extra,\n File \"/home/user/code/superapp/env/lib/python3.7/site-packages/typer/core.py\", line 216, in _main\n rv = self.invoke(ctx)\n File \"/home/user/code/superapp/env/lib/python3.7/site-packages/click/core.py\", line 1404, in invoke\n return ctx.invoke(self.callback, **ctx.params)\n File \"/home/user/code/superapp/env/lib/python3.7/site-packages/click/core.py\", line 760, in invoke\n return __callback(*args, **kwargs)\n File \"/home/user/code/superapp/env/lib/python3.7/site-packages/typer/main.py\", line 683, in wrapper\n return callback(**use_params) # type: ignore\n File \"main.py\", line 8, in main\n print(name + 3)\nTypeError: can only concatenate str (not \"int\") to str\n```\n\n
\n"
},
{
"path": "docs/tutorial/first-steps.md",
"content": "# First Steps\n\n## The simplest example\n\nThe simplest **Typer** file could look like this:\n\n{* docs_src/first_steps/tutorial001_py310.py *}\n\nCopy that to a file `main.py`.\n\nTest it:\n\n\n\n```console\n$ python main.py\n\nHello World\n\n// It just prints \"Hello World\".\n\n// Now check the --help\n$ python main.py --help\n\n Usage: main.py [OPTIONS] \n \nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --help Show this message โ\nโ and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n```\n\n
\n\n...but this program is still not very useful. Let's extend it.\n\n## What is a **CLI argument**\n\nHere we will use the word **CLI argument** to refer to **CLI parameters** passed in some specific order to the CLI application. By default, they are *required*.\n\nIf you go to your terminal and type:\n\n\n\n```bash\n$ ls ./myproject\n\nfirst-steps.md intro.md\n```\n\n
\n\n`ls` will show the contents of the directory `./myproject`.\n\n* `ls` is the *program* (or \"command\", \"CLI app\").\n* `./myproject` is a *CLI argument*, in this case it refers to the path of a directory.\n\nThey are a bit different from **CLI options** that you will see later below.\n\n## Add a CLI argument\n\nUpdate the previous example with an argument `name`:\n\n{* docs_src/first_steps/tutorial002_py310.py hl[4,5] *}\n\n\n\n```console\n\n$ python main.py\n\n// If you run it without the argument, it shows a nice error\nUsage: main.py [OPTIONS] NAME\nTry 'main.py --help' for help.\nโญโ Error โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ Missing argument 'NAME'. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n\n// Now pass that NAME CLI argument\n$ python main.py Camila\n\nHello Camila\n\n// Here \"Camila\" is the CLI argument\n\n// To pass a name with spaces for the same CLI argument, use quotes\n$ python main.py \"Camila Gutiรฉrrez\"\n\nHello Camila Gutiรฉrrez\n```\n\n
\n\n/// tip\n\nIf you need to pass a single value that contains spaces to a *CLI argument*, use quotes (`\"`) around it.\n\n///\n\n## Two CLI arguments\n\nNow let's say we want to have the name and last name separated.\n\nSo, extend that to have 2 arguments, `name` and `lastname`:\n\n{* docs_src/first_steps/tutorial003_py310.py hl[4,5] *}\n\n\n\n```console\n// Check the main --help\n$ python main.py --help\n\nUsage: main.py [OPTIONS] NAME\nTry 'main.py --help' for help.\nโญโ Error โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ Missing argument 'NAME'. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n\ntyper on ๎ richify [ยป!?] via ๐ v3.7.5 (env3.7)\nโฏ python main.py\nUsage: main.py [OPTIONS] NAME LASTNAME\nTry 'main.py --help' for help.\nโญโ Error โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ Missing argument 'NAME'. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n\n// There are now 2 CLI arguments, name and lastname\n\n// Now pass a single name argument\n$ python main.py Camila\n\nUsage: main.py [OPTIONS] NAME LASTNAME\nTry 'main.py --help' for help.\nโญโ Error โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ Missing argument 'LASTNAME'. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n\n// These 2 arguments are required, so, pass both:\n$ python main.py Camila Gutiรฉrrez\n\nHello Camila Gutiรฉrrez\n```\n\n
\n\n/// tip\n\nNotice that the order is important. The last name has to go after the first name.\n\nIf you called it with:\n\n```\n$ python main.py Gutiรฉrrez Camila\n```\n\nyour app wouldn't have a way to know which is the `name` and which the `lastname`. It expects the first *CLI argument* to be the `name` and the second *CLI argument* to be the `lastname`.\n\n///\n\n## What is a **CLI option**\n\nHere we will use the word **CLI option** to refer to *CLI parameters* passed to the CLI application with a specific name. For example, if you go to your terminal and type:\n\n\n\n```console\n$ ls ./myproject --size\n\n12 first-steps.md 4 intro.md\n```\n\n
\n\n`ls` will show the contents of the directory `./myproject` with their `size`.\n\n* `ls` is the *program* (or \"command\", \"CLI app\").\n* `./myproject` is a *CLI argument*.\n* `--size` is an optional *CLI option*.\n\nThe program knows it has to show the size because it sees `--size`, not because of the order.\n\nA *CLI option* like `--size` doesn't depend on the order like a *CLI argument*.\n\nSo, if you put the `--size` *before* the *CLI argument*, it still works (in fact, that's the most common way of doing it):\n\n\n\n```console\n$ ls --size ./myproject\n\n12 first-steps.md 4 intro.md\n```\n\n
\n\nThe main visual difference between a *CLI option* and a *CLI argument* is that the *CLI option* has `--` prepended to the name, like in \"`--size`\".\n\nA *CLI option* doesn't depend on the order because it has a predefined name (here it's `--size`). This is because the CLI app is looking specifically for a literal `--size` parameter (also known as \"flag\" or \"switch\"), with that specific \"name\" (here the specific name is \"`--size`\"). The CLI app will check if you typed it or not, it will be actively looking for `--size` even if you didn't type it (to check if it's there or not).\n\nIn contrast, the CLI app is not actively looking for the *CLI argument* with a text \"`./myproject`\", it has no way to know if you would type `./myproject` or `./my-super-awesome-project` or anything else. It's just waiting to get whatever you give it. The only way to know that you refer to a specific *CLI argument* is because of the order. The same way that it knows that the first *CLI argument* was the `name` and the second was the `lastname`, but if you mixed the order, it wouldn't be able to handle it.\n\nInstead, with a *CLI option*, the order doesn't matter.\n\nAlso, by default, a *CLI option* is *optional* (not *required*).\n\nSo, by default:\n\n* A *CLI argument* is **required**\n* A *CLI option* is **optional**\n\nBut the *required* and *optional* defaults can be changed.\n\nSo, the main and **most important** difference is that:\n\n* *CLI options* **start with `--`** and don't depend on the order\n* *CLI arguments* depend on the **sequence order**\n\n/// tip\n\nIn this example above the *CLI option* `--size` is just a \"flag\" or \"switch\" that will contain a boolean value, `True` or `False`, depending on if it was added to the command or not.\n\nThis one doesn't receive any values. But *CLI options* can also receive values like *CLI arguments*. You'll see how later.\n\n///\n\n## Add one *CLI option*\n\nNow add a `--formal` *CLI option*:\n\n{* docs_src/first_steps/tutorial004_py310.py hl[4,5] *}\n\nHere `formal` is a `bool` that is `False` by default.\n\n\n\n```console\n// Get the help\n$ python main.py --help\n\n Usage: main.py [OPTIONS] NAME LASTNAME \n \nโญโ Arguments โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ * name TEXT [default: None] [required] โ\nโ * lastname TEXT [default: None] [required] โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --formal --no-formal [default: no-formal] โ\nโ --help Show this message and โ\nโ exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n```\n\n
\n\n/// tip\n\nNotice that it automatically creates a `--formal` and a `--no-formal` because it detected that `formal` is a `bool`.\n\n///\n\nNow call it normally:\n\n\n\n```console\n$ python main.py Camila Gutiรฉrrez\n\nHello Camila Gutiรฉrrez\n\n// But if you pass --formal\n$ python main.py Camila Gutiรฉrrez --formal\n\nGood day Ms. Camila Gutiรฉrrez.\n\n// And as --formal is a CLI option you can put it anywhere in this command\n$ python main.py Camila --formal Gutiรฉrrez\n\nGood day Ms. Camila Gutiรฉrrez.\n\n$ python main.py --formal Camila Gutiรฉrrez\n\nGood day Ms. Camila Gutiรฉrrez.\n```\n\n
\n\n## A *CLI option* with a value\n\nTo convert the `lastname` from a *CLI argument* to a *CLI option*, give it a default value of `\"\"`:\n\n{* docs_src/first_steps/tutorial005_py310.py hl[4] *}\n\nAs `lastname` now has a default value of `\"\"` (an empty string) it is no longer required in the function, and **Typer** will now by default make it an optional *CLI option*.\n\n\n\n```console\n$ python main.py --help\n\n Usage: main.py [OPTIONS] NAME \n \nโญโ Arguments โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ * name TEXT [default: None] [required] โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --lastname TEXT โ\nโ --formal --no-formal [default: no-formal] โ\nโ --help Show this message โ\nโ and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n```\n\n
\n\n/// tip\n\nNotice the `--lastname`, and notice that it takes a textual value.\n\nA *CLI option* with a value like `--lastname` (contrary to a *CLI option* without a value, a `bool` flag, like `--formal` or `--size`) takes as its value whatever is at the *right side* of the *CLI option*.\n\n///\n\n\n\n```console\n// Call it without a --lastname\n$ python main.py Camila\n\nHello Camila\n\n// Pass the --lastname\n$ python main.py Camila --lastname Gutiรฉrrez\n\nHello Camila Gutiรฉrrez\n```\n\n
\n\n/// tip\n\nNotice that \"`Gutiรฉrrez`\" is at the right side of `--lastname`. A *CLI option* with a value takes as its value whatever is at the *right side*.\n\n///\n\nAnd as `--lastname` is now a *CLI option* that doesn't depend on the order, you can pass it before the name:\n\n\n\n```console\n$ python main.py --lastname Gutiรฉrrez Camila\n\n// and it will still work normally\nHello Camila Gutiรฉrrez\n```\n\n
\n\n## Document your CLI app\n\nIf you add a docstring to your function it will be used in the help text:\n\n{* docs_src/first_steps/tutorial006_py310.py hl[5,6,7,8,9] *}\n\nNow see it with the `--help` option:\n\n\n\n```console\n$ python main.py --help\n\n Usage: main.py [OPTIONS] NAME \n \n Say hi to NAME, optionally with a --lastname.\n If --formal is used, say hi very formally. \n\nโญโ Arguments โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ * name TEXT [default: None] [required] โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --lastname TEXT โ\nโ --formal --no-formal [default: no-formal] โ\nโ --help Show this message โ\nโ and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n```\n\n
\n\n/// tip\n\nThere is another place to document the specific *CLI options* and *CLI arguments* that will show up next to them in the help text as with `--install-completion` or `--help`, you will learn that later in the tutorial.\n\n///\n\n## Arguments, options, parameters, optional, required\n\nBe aware that these terms refer to multiple things depending on the context, and sadly, those \"contexts\" mix frequently, so it's easy to get confused.\n\n### In Python\n\nIn Python, the names of the variables in a function, like `name` and `lastname`:\n\n```Python\ndef main(name: str, lastname: str = \"\"):\n pass\n```\n\nare called \"Python function parameters\" or \"Python function arguments\".\n\n/// note | Technical Details\n\nThere's actually a very small distinction in Python between \"parameter\" and \"argument\".\n\nIt's quite technical... and somewhat pedantic.\n\n*Parameter* refers to the variable name in a function *declaration*. Like:\n\n```\ndef bring_person(name: str, lastname: str = \"\"):\n pass\n```\n\n*Argument* refers to the value passed when *calling* a function. Like:\n\n```\nperson = bring_person(\"Camila\", lastname=\"Gutiรฉrrez\")\n```\n\n...but you will probably see them used interchangeably in most of the places (including here).\n\n///\n\n#### Python default values\n\nIn Python, in a function, a parameter with a *default value* like `lastname` in:\n\n```Python\ndef main(name: str, lastname: str = \"\"):\n pass\n```\n\nis considered an \"optional parameter\" (or \"optional argument\").\n\nThe default value can be anything, like `\"\"` or `None`.\n\nAnd a parameter like `name`, that doesn't have a default value, is considered *required*.\n\n### In CLIs\n\nWhen talking about command line interface applications, the words **\"argument\"** and **\"parameter\"** are commonly used to refer to that data passed to a CLI app, those parameters.\n\nBut those words **don't imply** anything about the data being required, needing to be passed in a certain order, nor having a flag like `--lastname`.\n\nThe parameters that come with a name like `--lastname` (and optionally a value) are commonly optional, not required. So, when talking about CLIs it's common to call them **optional arguments** or **optional parameters**. Sometimes these *optional parameters* that start with `--` are also called a **flag** or a **switch**.\n\nIn reality, the parameters that require an order can be made *optional* too. And the ones that come with a flag (like `--lastname`) can be *required* too.\n\n### In **Typer**\n\nTo try and make it a bit easier, we'll normally use the words \"parameter\" or \"argument\" to refer to \"Python functions parameters\" or \"Python functions arguments\".\n\nWe'll use ***CLI argument*** to refer to those *CLI parameters* that depend on the specific order. That are **required** by default.\n\nAnd we'll use ***CLI option*** to refer to those *CLI parameters* that depend on a name that starts with `--` (like `--lastname`). That are **optional** by default.\n\nWe will use ***CLI parameter*** to refer to both, *CLI arguments* and *CLI options*.\n\n## The `typer` Command\n\nWhen you install `typer`, by default it adds a `typer` command to your shell.\n\nThis `typer` command allows you to run your scripts with โจ auto completion โจ in your terminal.\n\nAs an alternative to running with Python:\n\n\n\n```console\n$ python main.py\n\nHello World\n```\n\n
\n\nYou can run with the `typer` command:\n\n\n\n```console\n$ typer main.py run\n\nHello World\n```\n\n
\n\n...and it will give you auto completion in your terminal when you hit TAB for all your code.\n\nSo you can use it to have auto completion for your own scripts as you continue with the tutorial.\n\n/// tip\n\nYour CLI application built with **Typer** won't need the `typer` command to have auto completion once you create a Python package.\n\nBut for short scripts and for learning, before creating a Python package, it might be useful.\n\n///\n"
},
{
"path": "docs/tutorial/index.md",
"content": "# Learn\n\nLearn how to use **Typer** in this step-by-step **Tutorial** - **User Guide**.\n\nIt covers everything you need to know from the **simplest scripts** to **complex CLI applications**.\n\nYou could consider this a **book**, a **course**, the **official** and recommended way to learn **Typer**. ๐\n\n## Python Types\n\nIf you need a refresher about how to use Python type hints, check the first part of FastAPI's Python types intro.\n\nYou can also check the mypy cheat sheet.\n\nIn short (very short), you can declare a function with parameters like:\n\n```Python\nfrom typing import Optional\n\ndef type_example(name: str, formal: bool = False, intro: Optional[str] = None):\n pass\n```\n\nAnd your editor (and **Typer**) will know that:\n\n* `name` is of type `str` and is a required parameter.\n* `formal` is a `bool` and is by default `False`.\n* `intro` is an optional `str`, by default is `None`.\n\nThese type hints are what give you autocomplete in your editor and several other features.\n\n**Typer** is based on these type hints.\n\n## About this Tutorial\n\nThis tutorial shows you how to use **Typer** with all its features, step by step.\n\nEach section gradually builds on the previous ones, but it's structured to separate topics, so that you can go directly to any specific one to solve your specific CLI needs.\n\nIt is also built to work as a future reference so you can come back and see exactly what you need.\n\n## Run the Code\n\nAll the code blocks can be copied and used directly (they are tested Python files).\n\nTo run any of the examples, copy the code to a file `main.py`, and run it:\n\n\n\n```console\n$ python main.py\n\nโจ The magic happens here โจ\n```\n\n
\n\nIt is **HIGHLY encouraged** that you write or copy the code, edit it and run it locally.\n\nUsing it in your editor is what really shows you the benefits of **Typer**, seeing how little code you have to write, all the **inline errors**, **autocompletion**, etc.\n\nAnd running the examples is what will really help you **understand** what is going on.\n\nYou can learn a lot more by **running some examples** and **playing around** with them than by reading all the docs here.\n"
},
{
"path": "docs/tutorial/install.md",
"content": "# Install **Typer**\n\nThe first step is to install **Typer**.\n\nFirst, make sure you create your [virtual environment](../virtual-environments.md){.internal-link target=_blank}, activate it, and then install it, for example with:\n\n\n\n```console\n$ pip install typer\n---> 100%\nSuccessfully installed typer click shellingham rich\n```\n\n
\n\nBy default, `typer` comes with `rich` and `shellingham`.\n"
},
{
"path": "docs/tutorial/launch.md",
"content": "# Launching Applications\n\nYou can launch applications from your CLI program with `typer.launch()`.\n\nIt will launch the appropriate application depending on the URL or file type you pass it:\n\n{* docs_src/launch/tutorial001_py310.py hl[9] *}\n\nCheck it:\n\n\n\n```console\n$ python main.py\n\nOpening Typer docs\n\n// Opens browser with Typer's docs\n```\n\n
\n\n## Locating a file\n\nYou can also make the operating system open the file browser indicating where a file is located with `locate=True`:\n\n{* docs_src/launch/tutorial002_py310.py hl[20] *}\n\n/// tip\n\nThe rest of the code in this example is just making sure the app directory exists and creating the config file.\n\nBut the most important part is the `typer.launch(config_file_str, locate=True)` with the argument `locate=True`.\n\n///\n\nCheck it:\n\n\n\n```console\n$ python main.py\n\nOpening config directory\n\n// Opens a file browser indicating where the config file is located\n```\n\n
\n"
},
{
"path": "docs/tutorial/multiple-values/arguments-with-multiple-values.md",
"content": "# CLI Arguments with Multiple Values\n\n*CLI arguments* can also receive multiple values.\n\nYou can define the type of a *CLI argument* using `list`.\n\n{* docs_src/multiple_values/arguments_with_multiple_values/tutorial001_py310.py hl[9] *}\n\nAnd then you can pass it as many *CLI arguments* of that type as you want:\n\n\n\n```console\n$ python main.py ./index.md ./first-steps.md woohoo!\n\nThis file exists: index.md\nwoohoo!\nThis file exists: first-steps.md\nwoohoo!\n```\n\n
\n\n/// tip\n\nWe also declared a final *CLI argument* `celebration`, and it's correctly used even if we pass an arbitrary number of `files` first.\n\n///\n\n/// info\n\nA `list` can only be used in the last command (if there are subcommands), as this will take anything to the right and assume it's part of the expected *CLI arguments*.\n\n///\n\n## *CLI arguments* with tuples\n\nIf you want a specific number of values and types, you can use a tuple, and it can even have default values:\n\n{* docs_src/multiple_values/arguments_with_multiple_values/tutorial002_an_py310.py hl[10:12] *}\n\nCheck it:\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\nUsage: main.py [OPTIONS] [NAMES]...\n\nArguments:\n [NAMES]... Select 3 characters to play with [default: Harry, Hermione, Ron]\n\nOptions:\n --help Show this message and exit.\n\n// Use it with its defaults\n$ python main.py\n\nHello Harry\nHello Hermione\nHello Ron\n\n// If you pass an invalid number of arguments you will get an error\n$ python main.py Draco Hagrid\n\nError: Argument 'names' takes 3 values\n\n// And if you pass the exact number of values it will work correctly\n$ python main.py Draco Hagrid Dobby\n\nHello Draco\nHello Hagrid\nHello Dobby\n```\n\n
\n"
},
{
"path": "docs/tutorial/multiple-values/index.md",
"content": "# Multiple Values\n\nThere are several ways to declare multiple values for *CLI options* and *CLI arguments*.\n\nWe'll see them in the next short sections.\n"
},
{
"path": "docs/tutorial/multiple-values/multiple-options.md",
"content": "# Multiple CLI Options\n\nYou can declare a *CLI option* that can be used multiple times, and then get all the values.\n\nFor example, let's say you want to accept several users in a single execution.\n\nFor this, use the standard Python `list` to declare it as a list of `str`:\n\n{* docs_src/multiple_values/multiple_options/tutorial001_an_py310.py hl[9] *}\n\nYou will receive the values as you declared them, as a `list` of `str`.\n\nCheck it:\n\n\n\n```console\n// The default value is 'None'\n$ python main.py\n\nNo provided users (raw input = None)\nAborted!\n\n// Now pass a user\n$ python main.py --user Camila\n\nProcessing user: Camila\n\n// And now try with several users\n$ python main.py --user Camila --user Rick --user Morty\n\nProcessing user: Camila\nProcessing user: Rick\nProcessing user: Morty\n```\n\n
\n\n## Multiple `float`\n\nThe same way, you can use other types and they will be converted by **Typer** to their declared type:\n\n{* docs_src/multiple_values/multiple_options/tutorial002_an_py310.py hl[9] *}\n\nCheck it:\n\n\n\n```console\n$ python main.py\n\nThe sum is 0\n\n// Try with some numbers\n$ python main.py --number 2\n\nThe sum is 2.0\n\n// Try with some numbers\n$ python main.py --number 2 --number 3 --number 4.5\n\nThe sum is 9.5\n```\n\n
\n"
},
{
"path": "docs/tutorial/multiple-values/options-with-multiple-values.md",
"content": "# CLI Options with Multiple Values\n\nYou can also declare a *CLI option* that takes several values of different types.\n\nYou can set the number of values and types to anything you want, but it has to be a fixed number of values.\n\nFor this, use the standard Python `tuple`:\n\n{* docs_src/multiple_values/options_with_multiple_values/tutorial001_an_py310.py hl[9] *}\n\nEach of the internal types defines the type of each value in the tuple.\n\nSo:\n\n```Python\nuser: tuple[str, int, bool]\n```\n\nmeans that the parameter `user` is a tuple of 3 values.\n\n* The first value is a `str`.\n* The second value is an `int`.\n* The third value is a `bool`.\n\nLater we do:\n\n```Python\nusername, coins, is_wizard = user\n```\n\nIf you hadn't seen that, it means that `user` is a tuple with 3 values, and we are assigning each of the values to a new variable:\n\n* The first value in the tuple `user` (a `str`) goes to the variable `username`.\n* The second value in the tuple `user` (an `int`) goes to the variable `coins`.\n* The third value in the tuple `user` (a `bool`) goes to the variable `is_wizard`.\n\nSo, this:\n\n```Python\nusername, coins, is_wizard = user\n```\n\nis equivalent to this:\n\n```Python\nusername = user[0]\ncoins = user[1]\nis_wizard = user[2]\n```\n\n## Check it\n\nNow let's see how this works in the terminal:\n\n\n\n```console\n// check the help\n$ python main.py --help\n\n// Notice the <TEXT INTEGER BOOLEAN>\nUsage: main.py [OPTIONS]\n\nOptions:\n --user <TEXT INTEGER BOOLEAN>...\n --help Show this message and exit.\n\n// Now try it\n$ python main.py --user Camila 50 yes\n\nThe username Camila has 50 coins\nAnd this user is a wizard!\n\n// With other values\n$ python main.py --user Morty 3 no\n\nThe username Morty has 3 coins\n\n// Try with invalid values (not enough)\n$ python main.py --user Camila 50\n\nError: Option '--user' requires 3 arguments\n```\n\n
\n"
},
{
"path": "docs/tutorial/one-file-per-command.md",
"content": "# One File Per Command\n\nWhen your CLI application grows, you can split it into multiple files and modules. This pattern helps maintain a clean and organized code structure. โจ\n\nThis tutorial will show you how to use `add_typer` to create sub commands and organize your commands in multiple files.\n\nWe will create a simple CLI with the following commands:\n\n- `version`\n- `users add NAME`\n- `users delete NAME`\n\n## CLI structure\n\nHere is the structure we'll be working with:\n\n```text\nmycli/\nโโโ __init__.py\nโโโ main.py\nโโโ users/\nโ โโโ __init__.py\nโ โโโ add.py\nโ โโโ delete.py\nโโโ version.py\n```\n\n`mycli` will be our package, and it will contain the following modules:\n\n- `main.py`: The main module that will import the `version` and `users` modules.\n- `version.py`: A module that will contain the `version` command.\n- `users/`: A package (inside of our `mycli` package) that will contain the `add` and `delete` commands.\n\n## Implementation\n\nLet's start implementing our CLI! ๐\n\nWe'll create the `version` module, the `main` module, and the `users` package.\n\n### Version Module (`version.py`)\n\nLet's start by creating the `version` module. This module will contain the `version` command.\n\n{* docs_src/one_file_per_command/app_py310/version.py *}\n\nIn this file we are creating a new Typer app instance for the `version` command.\n\nThis is not required in single-file applications, but in the case of multi-file applications it will allow us to include this command in the main application using `app.add_typer()`.\n\nLet's see that next!\n\n### Main Module (`main.py`)\n\nThe main module will be the entry point of the application. It will import the version module and the users module.\n\n/// tip\n\nWe'll see how to implement the users module in the next section.\n\n///\n\n{* docs_src/one_file_per_command/app_py310/main.py hl[8,9] *}\n\nIn this module, we import the `version` and `users` modules and add them to the main app using `app.add_typer()`.\n\nFor the `users` module, we specify the name as `\"users\"` to group the commands under the `users` sub-command.\n\nNotice that we didn't add a name for the `version_app` Typer app. Because of this, Typer will add the commands (just one in this case) declared in the `version_app` directly at the top level. So, there will be a top-level `version` sub-command.\n\nBut for `users`, we add a name `\"users\"`, this way those commands will be under the sub-command `users` instead of at the top level. So, there will be a `users add` and `users delete` sub-sub-commands. ๐
\n\n/// tip\n\nIf you want a command to group the included commands in a sub-app, add a name.\n\nIf you want to include the commands from a sub-app directly at the top level, don't add a name, or set it to `None`. ๐ค\n\n///\n\nLet's now create the `users` module with the `add` and `delete` commands.\n\n### Users Add Command (`users/add.py`)\n\n{* docs_src/one_file_per_command/app_py310/users/add.py *}\n\nLike the `version` module, we create a new Typer app instance for the `users/add` command. This allows us to include the `add` command in the users app.\n\n### Users Delete Command (`users/delete.py`)\n\n{* docs_src/one_file_per_command/app_py310/users/delete.py *}\n\nAnd once again, we create a new Typer app instance for the `users/delete` command. This allows us to include the `delete` command in the users app.\n\n### Users' app (`users/__init__.py`)\n\nFinally, we need to create an `__init__.py` file in the `users` directory to define the `users` app.\n\n{* docs_src/one_file_per_command/app_py310/users/__init__.py *}\n\nSimilarly to the `version` module, we create a new `Typer` app instance for the `users` module. This allows us to include the `add` and `delete` commands in the users app.\n\n## Running the Application\n\nNow we are ready to run the application! ๐\n\nTo run the application, you can execute it as a Python module:\n\n\n\n```console\n$ python -m mycli.main version\n\nMy CLI Version 1.0\n\n$ python -m mycli.main users add Camila\n\nAdding user: Camila\n```\n\n
\n\nAnd if you built a package and installed your app, you can then use the `mycli` command:\n\n\n\n```console\n$ mycli version\n\nMy CLI Version 1.0\n\n$ mycli users add Camila\n\nAdding user: Camila\n```\n\n
\n\n## Callbacks\n\nHave in mind that if you include a sub-app with `app.add_typer()` **without a name**, the commands will be added to the top level, so **only the top level callback** (if there's any) will be used, the one declared in the main app.\n\nIf you **want to use a callback** for a sub-app, you need to include the sub-app **with a name**, which creates a sub-command grouping the commands in that sub-app. ๐ค\n\nIn the example above, if the `users` sub-app had a callback, it would be used. But if the `version` sub-app had a callback, it would not be used, because the `version` sub-app was included without a name.\n"
},
{
"path": "docs/tutorial/options/callback-and-context.md",
"content": "# CLI Option Callback and Context\n\nIn some occasions you might want to have some custom logic for a specific *CLI parameter* (for a *CLI option* or *CLI argument*) that is executed with the value received from the terminal.\n\nIn those cases you can use a *CLI parameter* callback function.\n\n## Validate *CLI parameters*\n\nFor example, you could do some validation before the rest of the code is executed.\n\n{* docs_src/options/callback/tutorial001_an_py310.py hl[8:11,15] *}\n\nHere you pass a function to `typer.Option()` or `typer.Argument()` with the keyword argument `callback`.\n\nThe function receives the value from the command line. It can do anything with it, and then return the value.\n\nIn this case, if the `--name` is not `Camila` we raise a `typer.BadParameter()` exception.\n\nThe `BadParameter` exception is special, it shows the error with the parameter that generated it.\n\nCheck it:\n\n\n\n```console\n$ python main.py --name Camila\n\nHello Camila\n\n$ python main.py --name Rick\n\nUsage: main.py [OPTIONS]\n\n// We get the error from the callback\nError: Invalid value for '--name': Only Camila is allowed\n```\n\n
\n\n## Handling completion\n\nThere's something to be aware of with callbacks and completion that requires some small special handling.\n\nBut first let's just use completion in your shell (Bash, Zsh, Fish, or PowerShell).\n\nAfter installing completion (for your own Python package), when you use your CLI program and start adding a *CLI option* with `--` and then hit TAB, your shell will show you the available *CLI options* (the same for *CLI arguments*, etc).\n\nTo check it quickly with the previous script use the `typer` command:\n\n\n\n```console\n// Hit the TAB key in your keyboard below where you see the: [TAB]\n$ typer ./main.py [TAB][TAB]\n\n// Depending on your terminal/shell you will get some completion like this โจ\nrun -- Run the provided Typer app.\nutils -- Extra utility commands for Typer apps.\n\n// Then try with \"run\" and --help\n$ typer ./main.py run --help\n\n// You get a help text with your CLI options as you normally would\nUsage: typer run [OPTIONS]\n\n Run the provided Typer app.\n\nOptions:\n --name TEXT [required]\n --help Show this message and exit.\n\n// Then try completion with your program\n$ typer ./main.py run --[TAB][TAB]\n\n// You get completion for CLI options\n--help -- Show this message and exit.\n--name\n\n// And you can run it as if it was with Python directly\n$ typer ./main.py run --name Camila\n\nHello Camila\n```\n\n
\n\n### How shell completion works\n\nThe way it works internally is that the shell/terminal will call your CLI program with some special environment variables (that hold the current *CLI parameters*, etc) and your CLI program will print some special values that the shell will use to present completion. All this is handled for you by **Typer** behind the scenes.\n\nBut the main **important point** is that it is all based on values printed by your program that the shell reads.\n\n### Breaking completion in a callback\n\nLet's say that when the callback is running, we want to show a message saying that it's validating the name:\n\n{* docs_src/options/callback/tutorial002_an_py310.py hl[9] *}\n\nAnd because the callback will be called when the shell calls your program asking for completion, that message `\"Validating name\"` will be printed and it will break completion.\n\nIt will look something like:\n\n\n\n```console\n// Run it normally\n$ typer ./main.py run --name Camila\n\n// See the extra message \"Validating name\"\nValidating name\nHello Camila\n\n$ typer ./main.py run --[TAB][TAB]\n\n// Some weird broken error message โ๏ธ\n(eval):1: command not found: Validating\nrutyper ./main.pyed Typer app.\n```\n\n
\n\n### Fix completion - using the `Context`\n\nEvery Typer application has a special object called a \"Context\" that is normally hidden.\n\nBut you can access the context by declaring a function parameter of type `typer.Context`.\n\nThe \"context\" has some additional data about the current execution of your program:\n\n{* docs_src/options/callback/tutorial003_an_py310.py hl[8:10] *}\n\nThe `ctx.resilient_parsing` will be `True` when handling completion, so you can just return without printing anything else.\n\nBut it will be `False` when calling the program normally. So you can continue the execution of your previous code.\n\nThat's all is needed to fix completion. ๐\n\nCheck it:\n\n\n\n```console\n$ typer ./main.py run --[TAB][TAB]\n\n// Now it works correctly ๐\n--help -- Show this message and exit.\n--name\n\n// And you can call it normally\n$ typer ./main.py run --name Camila\n\nValidating name\nHello Camila\n```\n\n
\n\n## Using the `CallbackParam` object\n\nThe same way you can access the `typer.Context` by declaring a function parameter with its value, you can declare another function parameter with type `typer.CallbackParam` to get the specific `Parameter` object.\n\n{* docs_src/options/callback/tutorial004_an_py310.py hl[8,11] *}\n\nIt's probably not very common, but you could do it if you need it.\n\nFor example if you had a callback that could be used by several *CLI parameters*, that way the callback could know which parameter is each time.\n\nCheck it:\n\n\n\n```console\n$ python main.py --name Camila\n\nValidating param: name\nHello Camila\n```\n\n
\n\n## Technical Details\n\nBecause you get the relevant data in the callback function based on standard Python type annotations, you get type checks and autocompletion in your editor for free.\n\nAnd **Typer** will make sure you get the function parameters you want.\n\nYou don't have to worry about their names, their order, etc.\n\nAs it's based on standard Python types, it \"**just works**\". โจ\n\n### Callback with type annotations\n\nYou can get the `typer.Context` and the `typer.CallbackParam` simply by declaring a function parameter of each type.\n\nThe order doesn't matter, the name of the function parameters doesn't matter.\n\nYou could also get only the `typer.CallbackParam` and not the `typer.Context`, or vice versa, it will still work.\n\n### `value` function parameter\n\nThe `value` function parameter in the callback can also have any name (e.g. `lastname`) and any type, but it should have the same type annotation as in the main function, because that's what it will receive.\n\nIt's also possible to not declare its type. It will still work.\n\nAnd it's possible to not declare the `value` parameter at all, and, for example, only get the `typer.Context`. That will also work.\n"
},
{
"path": "docs/tutorial/options/help.md",
"content": "# CLI Options with Help\n\nYou already saw how to add a help text for *CLI arguments* with the `help` parameter.\n\nLet's now do the same for *CLI options*:\n\n{* docs_src/options/help/tutorial001_an_py310.py hl[11:12] *}\n\nThe same way as with `typer.Argument()`, we can put `typer.Option()` inside of `Annotated`.\n\nWe can then pass the `help` keyword parameter:\n\n```Python\nlastname: Annotated[str, typer.Option(help=\"this option does this and that\")] = \"\"\n```\n\n...to create the help for that *CLI option*.\n\nThe same way as with `typer.Argument()`, **Typer** also supports the old style using the function parameter default value:\n\n```Python\nlastname: str = typer.Option(default=\"\", help=\"this option does this and that\")\n```\n\nCopy that example from above to a file `main.py`.\n\nTest it:\n\n\n\n```console\n$ python main.py --help\n\nUsage: main.py [OPTIONS] NAME\n\n Say hi to NAME, optionally with a --lastname.\n\n If --formal is used, say hi very formally.\n\nArguments:\n NAME [required]\n\nOptions:\n --lastname TEXT Last name of person to greet. [default: ]\n --formal / --no-formal Say hi formally. [default: False]\n --help Show this message and exit.\n\n// Now you have a help text for the --lastname and --formal CLI options ๐\n```\n\n
\n\n## *CLI Options* help panels\n\nThe same as with *CLI arguments*, you can put the help for some *CLI options* in different panels to be shown with the `--help` option.\n\nUsing Rich, you can set the `rich_help_panel` parameter to the name of the panel you want for each *CLI option*:\n\n{* docs_src/options/help/tutorial002_an_py310.py hl[15,21] *}\n\nNow, when you check the `--help` option, you will see a default panel named \"`Options`\" for the *CLI options* that don't have a custom `rich_help_panel`.\n\nAnd below you will see other panels for the *CLI options* that have a custom panel set in the `rich_help_panel` parameter:\n\n\n\n```console\n$ python main.py --help\n\n Usage: main.py [OPTIONS] NAME \n \n Say hi to NAME, optionally with a --lastname.\n If --formal is used, say hi very formally. \n\nโญโ Arguments โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ * name TEXT [default: None] [required] โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --lastname TEXT Last name of person to greet. โ\nโ --help Show this message and exit. โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\nโญโ Customization and Utils โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ\nโ --formal --no-formal Say hi formally. โ\nโ [default: no-formal] โ\nโ --debug --no-debug Enable debugging. โ\nโ [default: no-debug] โ\nโฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ\n```\n\n
\n\nHere we have a custom *CLI options* panel named \"`Customization and Utils`\".\n\n## Help with style using Rich\n\nIn a future section you will see how to use custom markup in the `help` for *CLI options* when reading about [Commands - Command Help](../commands/help.md#rich-markdown-and-markup){.internal-link target=_blank}.\n\nIf you are in a hurry you can jump there, but otherwise, it would be better to continue reading here and following the tutorial in order.\n\n\n## Hide default from help\n\nYou can tell Typer to not show the default value in the help text with `show_default=False`:\n\n{* docs_src/options/help/tutorial003_an_py310.py hl[9] *}\n\nAnd it will no longer show the default value in the help text:\n\n\n\n```console\n$ python main.py\n\nHello Wade Wilson\n\n// Show the help\n$ python main.py --help\n\nUsage: main.py [OPTIONS]\n\nOptions:\n --fullname TEXT\n --help Show this message and exit.\n\n// Notice there's no [default: Wade Wilson] ๐ฅ\n```\n\n
\n\n## Custom default string\n\nYou can use the same `show_default` to pass a custom string (instead of a `bool`) to customize the default value to be shown in the help text:\n\n{* docs_src/options/help/tutorial004_an_py310.py hl[11] *}\n\nAnd it will be used in the help text:\n\n\n\n```console\n$ python main.py\n\nHello Wade Wilson\n\n// Show the help\n$ python main.py --help\n\nUsage: main.py [OPTIONS]\n\nOptions:\n --fullname TEXT [default: (Deadpoolio the amazing's name)]\n --help Show this message and exit.\n\n// Notice how it shows \"(Deadpoolio the amazing's name)\" instead of the actual default of \"Wade Wilson\"\n```\n\n
\n"
},
{
"path": "docs/tutorial/options/index.md",
"content": "# CLI Options\n\nIn the next short sections we will see how to modify *CLI options* using `typer.Option()`.\n\n`typer.Option()` works very similarly to `typer.Argument()`, but has some extra features that we'll see next.\n"
},
{
"path": "docs/tutorial/options/name.md",
"content": "# CLI Option Name\n\nBy default **Typer** will create a *CLI option* name from the function parameter.\n\nSo, if you have a function with:\n\n```Python\ndef main(user_name: Optional[str] = None):\n pass\n```\n\nor\n\n```Python\ndef main(user_name: Annotated[Optional[str], typer.Option()] = None):\n pass\n```\n\n**Typer** will create a *CLI option*:\n\n```\n--user-name\n```\n\nBut you can customize it if you want to.\n\nLet's say the function parameter name is `user_name` as above, but you want the *CLI option* to be just `--name`.\n\nYou can pass the *CLI option* name that you want to have in the following positional argument passed to `typer.Option()`:\n\n{* docs_src/options/name/tutorial001_an_py310.py hl[9] *}\n\n/// info\n\n\"Positional\" means that it's not a function argument with a keyword name.\n\nFor example `show_default=True` is a keyword argument. \"`show_default`\" is the keyword.\n\nBut in `\"--name\"` there's no `option_name=\"--name\"` or something similar, it's just the string value `\"--name\"` that goes in `typer.Option()`.\n\nThat's a \"positional argument\" in a function.\n\n///\n\nCheck it:\n\n\n\n```console\n$ python main.py --help\n\n// Notice the --name instead of --user-name\nUsage: main.py [OPTIONS]\n\nOptions:\n --name TEXT [required]\n --help Show this message and exit.\n\n// Try it\n$ python main.py --name Camila\n\nHello Camila\n```\n\n
\n\n## *CLI option* short names\n\nA short name is a *CLI option* name with a single dash (`-`) instead of 2 (`--`) and a single letter, like `-n` instead of `--name`.\n\nFor example, the `ls` program has a *CLI option* named `--size`, and the same *CLI option* also has a short name `-s`:\n\n\n\n```console\n// With the long name --size\n$ ls ./myproject --size\n\n12 first-steps.md 4 intro.md\n\n// With the short name -s\n$ ls ./myproject -s\n\n12 first-steps.md 4 intro.md\n\n// Both CLI option names do the same\n```\n\n
\n\n### *CLI option* short names together\n\nShort names have another feature, when they have a single letter, as in `-s`, you can put several of these *CLI options* together, with a single dash.\n\nFor example, the `ls` program has these 2 *CLI options* (among others):\n\n* `--size`: show the sizes of the listed files.\n* `--human`: show a human-readable format, like `1MB` instead of just `1024`.\n\nAnd these 2 *CLI options* have short versions too:\n\n* `--size`: short version `-s`.\n* `--human`: short version `-h`.\n\nSo, you can put them together with `-sh` or `-hs`:\n\n\n\n```console\n// Call ls with long CLI options\n$ ls --size --human\n\n12K first-steps.md 4.0K intro.md\n\n// Now with short versions\n$ ls -s -h\n\n12K first-steps.md 4.0K intro.md\n\n// And with short versions together\n$ ls -sh\n\n12K first-steps.md 4.0K intro.md\n\n// Order in short versions doesn't matter\n$ ls -hs\n\n12K first-steps.md 4.0K intro.md\n\n// They all work the same ๐\n```\n\n
\n\n### *CLI option* short names with values\n\nWhen you use *CLI options* with short names, you can put them together if they are just boolean flags, like `--size` or `--human`.\n\nBut if you have a *CLI option* `--file` with a short name `-f` that takes a value, if you put it with other short names for *CLI options*, you have to put it as the last letter, so that it can receive the value that comes right after.\n\nFor example, let's say you are decompressing/extracting a file `myproject.tar.gz` with the program `tar`.\n\nYou can pass these *CLI option* short names to `tar`:\n\n* `-x`: means \"e`X`tract\", to decompress and extract the contents.\n* `-v`: means \"`V`erbose\", to print on the screen what it is doing, so you can know that it's decompressing each file and can entertain yourself while you wait.\n* `-f`: means \"`F`ile\", this one requires a value, the compressed file to extract (in our example, this is `myproject.tar.gz`).\n * So if you use all the short names together, this `-f` has to come last, to receive the value that comes next to it.\n\nFor example:\n\n\n\n```console\n$ tar -xvf myproject.tar.gz\n\nmyproject/\nmyproject/first-steps.md\nmyproject/intro.md\n\n// But if you put the -f before\n$ tar -fxv myproject.tar.gz\n\n// You get an ugly error\ntar: You must specify one of the blah, blah, error, error\n```\n\n
\n\n### Defining *CLI option* short names\n\nIn **Typer** you can also define *CLI option* short names the same way you can customize the long names.\n\nYou can pass *positional* arguments to `typer.Option()` to define the *CLI option* name(s).\n\n/// tip\n\nRemember the *positional* function arguments are those that don't have a keyword.\n\nAll the other function arguments/parameters you pass to `typer.Option()` like `prompt=True` and `help=\"This option blah, blah\"` require the keyword.\n\n///\n\nYou can overwrite the *CLI option* name to use as in the previous example, but you can also declare extra alternatives, including short names.\n\nFor example, extending the previous example, let's add a *CLI option* short name `-n`:\n\n{* docs_src/options/name/tutorial002_an_py310.py hl[9] *}\n\nHere we are overwriting the *CLI option* name that by default would be `--user-name`, and we are defining it to be `--name`. And we are also declaring a *CLI option* short name of `-n`.\n\nCheck it:\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\n// Notice the two CLI option names -n and --name\nUsage: main.py [OPTIONS]\n\nOptions:\n -n, --name TEXT [required]\n --help Show this message and exit.\n\n// Try the short version\n$ python main.py -n Camila\n\nHello Camila\n```\n\n
\n\n### *CLI option* only short name\n\nIf you only declare a short name like `-n` then that will be the only *CLI option* name. And neither `--name` nor `--user-name` will be available.\n\n{* docs_src/options/name/tutorial003_an_py310.py hl[9] *}\n\nCheck it:\n\n\n\n```console\n$ python main.py --help\n\n// Notice there's no --name nor --user-name, only -n\nUsage: main.py [OPTIONS]\n\nOptions:\n -n TEXT [required]\n --help Show this message and exit.\n\n// Try it\n$ python main.py -n Camila\n\nHello Camila\n```\n\n
\n\n### *CLI option* short name and default\n\nContinuing with the example above, as **Typer** allows you to declare a *CLI option* as having only a short name, if you want to have the default long name plus a short name, you have to declare both explicitly:\n\n{* docs_src/options/name/tutorial004_an_py310.py hl[9] *}\n\nCheck it:\n\n\n\n```console\n$ python main.py --help\n\n// Notice that we have the long version --user-name back\n// and we also have the short version -n\nUsage: main.py [OPTIONS]\n\nOptions:\n -n, --user-name TEXT [required]\n --help Show this message and exit.\n\n// Try it\n$ python main.py --user-name Camila\n\nHello Camila\n\n// And try the short version\n$ python main.py -n Camila\n```\n\n
\n\n### *CLI option* short names together\n\nYou can create multiple short names and use them together.\n\nYou don't have to do anything special for it to work (apart from declaring those short versions):\n\n{* docs_src/options/name/tutorial005_an_py310.py hl[10:11] *}\n\n/// tip\n\nNotice that, again, we are declaring the long and short version of the *CLI option* names.\n\n///\n\nCheck it:\n\n\n\n```console\n$ python main.py --help\n\n// We now have short versions -n and -f\n// And also long versions --name and --formal\nUsage: main.py [OPTIONS]\n\nOptions:\n -n, --name TEXT [required]\n -f, --formal\n --help Show this message and exit.\n\n// Try the short versions\n$ python main.py -n Camila -f\n\nGood day Ms. Camila.\n\n// And try the 2 short versions together\n// See how -n has to go last, to be able to get the value\n$ python main.py -fn Camila\n\nGood day Ms. Camila.\n```\n\n
\n"
},
{
"path": "docs/tutorial/options/password.md",
"content": "# Password CLI Option and Confirmation Prompt\n\nApart from having a prompt, you can make a *CLI option* have a `confirmation_prompt=True`:\n\n{* docs_src/options/password/tutorial001_an_py310.py hl[11] *}\n\nAnd the CLI program will ask for confirmation:\n\n\n\n```console\n$ python main.py Camila\n\n// It prompts for the email\n# Email: $ camila@example.com\n# Repeat for confirmation: $ camila@example.com\n\nHello Camila, your email is camila@example.com\n```\n\n
\n\n## A Password prompt\n\nWhen receiving a password, it is very common (in most shells) to not show anything on the screen while typing the password.\n\nThe program will still receive the password, but nothing will be shown on screen, not even `****`.\n\nYou can achieve the same using `hide_input=True`.\n\nAnd if you combine it with `confirmation_prompt=True` you can easily receive a password with double confirmation:\n\n{* docs_src/options/password/tutorial002_an_py310.py hl[12] *}\n\nCheck it:\n\n\n\n```console\n$ python main.py Camila\n\n// It prompts for the password, but doesn't show anything when you type\n# Password: $\n# Repeat for confirmation: $\n\n// Let's imagine the password typed was \"typerrocks\"\nHello Camila. Doing something very secure with password.\n...just kidding, here it is, very insecure: typerrocks\n```\n\n
\n"
},
{
"path": "docs/tutorial/options/prompt.md",
"content": "# CLI Option Prompt\n\nIt's also possible to, instead of just showing an error, ask for the missing value with `prompt=True`:\n\n{* docs_src/options/prompt/tutorial001_an_py310.py hl[9] *}\n\nAnd then your program will ask the user for it in the terminal:\n\n\n\n```console\n// Call it with the NAME CLI argument\n$ python main.py Camila\n\n// It asks for the missing CLI option --lastname\n# Lastname: $ Gutiรฉrrez\n\nHello Camila Gutiรฉrrez\n```\n\n
\n\n## Customize the prompt\n\nYou can also set a custom prompt, passing the string that you want to use instead of just `True`:\n\n{* docs_src/options/prompt/tutorial002_an_py310.py hl[11] *}\n\nAnd then your program will ask for it using with your custom prompt:\n\n\n\n```console\n// Call it with the NAME CLI argument\n$ python main.py Camila\n\n// It uses the custom prompt\n# Please tell me your last name: $ Gutiรฉrrez\n\nHello Camila Gutiรฉrrez\n```\n\n
\n\n## Confirmation prompt\n\nIn some cases you could want to prompt for something and then ask the user to confirm it by typing it twice.\n\nYou can do it passing the parameter `confirmation_prompt=True`.\n\nLet's say it's a CLI app to delete a project:\n\n{* docs_src/options/prompt/tutorial003_an_py310.py hl[10] *}\n\nAnd it will prompt the user for a value and then for the confirmation:\n\n\n\n```console\n$ python main.py\n\n// Your app will first prompt for the project name, and then for the confirmation\n# Project name: $ Old Project\n# Repeat for confirmation: $ Old Project\n\nDeleting project Old Project\n\n// If the user doesn't type the same, receives an error and a new prompt\n$ python main.py\n\n# Project name: $ Old Project\n# Repeat for confirmation: $ New Spice\n\nError: The two entered values do not match\n\n# Project name: $ Old Project\n# Repeat for confirmation: $ Old Project\n\nDeleting project Old Project\n\n// Now it works ๐\n```\n\n
\n"
},
{
"path": "docs/tutorial/options/required.md",
"content": "# Required CLI Options\n\nWe said before that *by default*:\n\n* *CLI options* are **optional**\n* *CLI arguments* are **required**\n\nWell, that's how they work *by default*, and that's the convention in many CLI programs and systems.\n\nBut if you really want, you can change that.\n\nTo make a *CLI option* required, you can put `typer.Option()` inside of `Annotated` and leave the parameter without a default value.\n\nLet's make `--lastname` a required *CLI option*:\n\n{* docs_src/options/required/tutorial001_an_py310.py hl[9] *}\n\nThe same way as with `typer.Argument()`, the old style of using the function parameter default value is also supported, in that case you would just not pass anything to the `default` parameter.\n\n{* docs_src/options/required/tutorial001_py310.py hl[7] *}\n\nOr you can explicitly pass `...` to `typer.Option(default=...)`:\n\n{* docs_src/options/required/tutorial002_py310.py hl[7] *}\n\n/// info\n\nIf you hadn't seen that `...` before: it is a special single value, it is part of Python and is called \"Ellipsis\".\n\n///\n\nThat will tell **Typer** that it's still a *CLI option*, but it doesn't have a default value, and it's required.\n\n/// tip\n\nAgain, prefer to use the `Annotated` version if possible. That way your code will mean the same in standard Python and in **Typer**.\n\n///\n\nAnd test it:\n\n\n\n```console\n// Pass the NAME CLI argument\n$ python main.py Camila\n\n// We didn't pass the now required --lastname CLI option\nUsage: main.py [OPTIONS] NAME\nTry \"main.py --help\" for help.\n\nError: Missing option '--lastname'.\n\n// Now update it to pass the required --lastname CLI option\n$ python main.py Camila --lastname Gutiรฉrrez\n\nHello Camila Gutiรฉrrez\n\n// And if you check the help\n$ python main.py --help\n\nUsage: main.py [OPTIONS] NAME\n\nOptions:\n --lastname TEXT [required]\n --help Show this message and exit.\n\n// It now tells you that --lastname is required ๐\n```\n\n
\n"
},
{
"path": "docs/tutorial/options/version.md",
"content": "# Version CLI Option, `is_eager`\n\nYou could use a callback to implement a `--version` *CLI option*.\n\nIt would show the version of your CLI program and then it would terminate it. Even before any other *CLI parameter* is processed.\n\n## First version of `--version`\n\nLet's see a first version of how it could look like:\n\n{* docs_src/options/version/tutorial001_an_py310.py hl[10:13,19:21] *}\n\n/// tip\n\nNotice that we don't have to get the `typer.Context` and check for `ctx.resilient_parsing` for completion to work, because we only print and modify the program when `--version` is passed, otherwise, nothing is printed or changed from the callback.\n\n///\n\nIf the `--version` *CLI option* is passed, we get a value `True` in the callback.\n\nThen we can print the version and raise `typer.Exit()` to make sure the program is terminated before anything else is executed.\n\nWe also declare the explicit *CLI option* name `--version`, because we don't want an automatic `--no-version`, it would look awkward.\n\nCheck it:\n\n\n\n```console\n$ python main.py --help\n\n// We get a --version, and don't get an awkward --no-version ๐\nUsage: main.py [OPTIONS]\n\nOptions:\n --version\n --name TEXT\n --help Show this message and exit.\n\n\n// We can call it normally\n$ python main.py --name Camila\n\nHello Camila\n\n// And we can get the version\n$ python main.py --version\n\nAwesome CLI Version: 0.1.0\n\n// Because we exit in the callback, we don't get a \"Hello World\" message after the version ๐\n```\n\n
\n\n## Previous parameters and `is_eager`\n\nBut now let's say that the `--name` *CLI option* that we declared before `--version` is required, and it has a callback that could exit the program:\n\n{* docs_src/options/version/tutorial002_an_py310.py hl[16:19,25:27] *}\n\nThen our CLI program could not work as expected in some cases as it is *right now*, because if we use `--version` after `--name` then the callback for `--name` will be processed before and we can get its error:\n\n\n\n```console\n$ python main.py --name Rick --version\n\nOnly Camila is allowed\nAborted!\n```\n\n
\n\n/// tip\n\nWe don't have to check for `ctx.resilient_parsing` in the `name_callback()` for completion to work, because we are not using `typer.echo()`, instead we are raising a `typer.BadParameter`.\n\n///\n\n/// note | Technical Details\n\n`typer.BadParameter` prints the error to \"standard error\", not to \"standard output\", and because the completion system only reads from \"standard output\", it won't break completion.\n\n///\n\n/// info\n\nIf you need a refresher about what is \"standard output\" and \"standard error\" check the section in [Printing and Colors: \"Standard Output\" and \"Standard Error\"](../printing.md#standard-output-and-standard-error){.internal-link target=_blank}.\n\n///\n\n### Fix with `is_eager`\n\nFor those cases, we can mark a *CLI parameter* (a *CLI option* or *CLI argument*) with `is_eager=True`.\n\nThat will tell **Typer** that it should process this *CLI parameter* before the others:\n\n{* docs_src/options/version/tutorial003_an_py310.py hl[25:28] *}\n\nCheck it:\n\n\n\n```console\n$ python main.py --name Rick --version\n\n// Now we only get the version, and the name is not used\nAwesome CLI Version: 0.1.0\n```\n\n
\n"
},
{
"path": "docs/tutorial/options-autocompletion.md",
"content": "# CLI Option autocompletion\n\nAs you have seen, apps built with **Typer** have completion in your shell that works when you create a Python package or using the `typer` command.\n\nIt normally completes *CLI options*, *CLI arguments*, and subcommands (that you will learn about later).\n\nBut you can also provide auto completion for the **values** of *CLI options* and *CLI arguments*. We will learn about that here.\n\n## Review completion\n\nBefore checking how to provide custom completions, let's check again how it works.\n\nAfter installing completion for your own Python package (or using the `typer` command), when you use your CLI program and start adding a *CLI option* with `--` and then hit TAB, your shell will show you the available *CLI options* (the same for *CLI arguments*, etc).\n\nTo check it quickly without creating a new Python package, use the `typer` command.\n\nThen let's create a small example program:\n\n{* docs_src/options_autocompletion/tutorial001_an_py310.py *}\n\nAnd let's try it with the `typer` command to get completion:\n\n\n\n```console\n// Hit the TAB key in your keyboard below where you see the: [TAB]\n$ typer ./main.py [TAB][TAB]\n\n// Depending on your terminal/shell you will get some completion like this โจ\nrun -- Run the provided Typer app.\nutils -- Extra utility commands for Typer apps.\n\n// Then try with \"run\" and --\n$ typer ./main.py run --[TAB][TAB]\n\n// You will get completion for --name, depending on your terminal it will look something like this\n--name -- The name to say hi to.\n\n// And you can run it as if it was with Python directly\n$ typer ./main.py run --name Camila\n\nHello Camila\n```\n\n
\n\n## Custom completion for values\n\nRight now we get completion for the *CLI option* names, but not for the values.\n\nWe can provide completion for the values creating an `autocompletion` function, similar to the `callback` functions from [CLI Option Callback and Context](./options/callback-and-context.md){.internal-link target=_blank}:\n\n{* docs_src/options_autocompletion/tutorial002_an_py310.py hl[6:7,16] *}\n\nWe return a `list` of strings from the `complete_name()` function.\n\nAnd then we get those values when using completion:\n\n\n\n```console\n$ typer ./main.py run --name [TAB][TAB]\n\n// We get the values returned from the function ๐\nCamila Carlos Sebastian\n```\n\n
\n\nWe got the basics working. Now let's improve it.\n\n## Check the incomplete value\n\nRight now, we always return those values, even if users start typing `Sebast` and then hit TAB, they will also get the completion for `Camila` and `Carlos` (depending on the shell), while we should only get completion for `Sebastian`.\n\nBut we can fix that so that it always works correctly.\n\nModify the `complete_name()` function to receive a parameter of type `str`, it will contain the incomplete value.\n\nThen we can check and return only the values that start with the incomplete value from the command line:\n\n{* docs_src/options_autocompletion/tutorial003_an_py310.py hl[8:13] *}\n\nNow let's try it:\n\n\n\n```console\n$ typer ./main.py run --name Ca[TAB][TAB]\n\n// We get the values returned from the function that start with Ca ๐\nCamila Carlos\n```\n\n
\n\nNow we are only returning the valid values, that start with `Ca`, we are no longer returning `Sebastian` as a completion option.\n\n/// tip\n\nYou have to declare the incomplete value of type `str` and that's what you will receive in the function.\n\nNo matter if the actual value will be an `int`, or something else, when doing completion, you will only get a `str` as the incomplete value.\n\nAnd the same way, you can only return `str`, not `int`, etc.\n\n///\n\n## Add help to completions\n\nRight now we are returning a `list` of `str`.\n\nBut some shells (Zsh, Fish, PowerShell) are capable of showing extra help text for completion.\n\nWe can provide that extra help text so that those shells can show it.\n\nIn the `complete_name()` function, instead of providing one `str` per completion element, we provide a `tuple` with 2 items. The first item is the actual completion string, and the second item is the help text.\n\nSo, in the end, we return a `list` of `tuples` of `str`:\n\n{* docs_src/options_autocompletion/tutorial004_an_py310.py hl[5:9,12:18] *}\n\n/// tip\n\nIf you want to have help text for each item, make sure each item in the list is a `tuple`. Not a `list`.\n\nIn the end, the return will be a `list` (or other iterable) of `tuples` of 2 `str`.\n\n///\n\n/// info\n\nThe help text will be visible in Zsh, Fish, and PowerShell.\n\nBash doesn't support showing the help text, but completion will still work the same.\n\n///\n\nIf you have a shell like Zsh, it would look like:\n\n\n\n```console\n$ typer ./main.py run --name [TAB][TAB]\n\n// We get the completion items with their help text ๐\nCamila -- The reader of books.\nCarlos -- The writer of scripts.\nSebastian -- The type hints guy.\n```\n\n
\n\n## Simplify with `yield`\n\nInstead of creating and returning a list with values (`str` or `tuple`), we can use `yield` with each value that we want in the completion.\n\nThat way our function will be a generator that **Typer** can iterate:\n\n{* docs_src/options_autocompletion/tutorial005_an_py310.py hl[12:15] *}\n\nThat simplifies our code a bit and works the same.\n\n/// tip\n\nIf the `yield` part seems complex for you, don't worry, you can just use the version with the `list` above.\n\nIn the end, that's just to save us a couple of lines of code.\n\n///\n\n/// info\n\nThe function can use `yield`, so it doesn't have to return strictly a `list`, it just has to be iterable.\n\nBut each of the elements for completion has to be a `str` or a `tuple` (when containing a help text).\n\n///\n\n## Access other *CLI parameters* with the Context\n\nLet's say that now we want to modify the program to be able to \"say hi\" to multiple people at the same time.\n\nSo, we will allow multiple `--name` *CLI options*.\n\n/// tip\n\nYou will learn more about *CLI parameters* with multiple values later in the tutorial.\n\nSo, for now, take this as a sneak peek ๐.\n\n///\n\nFor this we use a `list` of `str`:\n\n{* docs_src/options_autocompletion/tutorial006_an_py310.py hl[8:13] *}\n\nAnd then we can use it like:\n\n\n\n```console\n$ typer ./main.py run --name Camila --name Sebastian\n\nHello Camila\nHello Sebastian\n```\n\n
\n\n### Getting completion for multiple values\n\nAnd the same way as before, we want to provide **completion** for those names. But we don't want to provide the **same names** for completion if they were already given in previous parameters.\n\nFor that, we will access and use the \"Context\". Every Typer application has a special object called a \"Context\" that is normally hidden.\n\nBut you can access the context by declaring a function parameter of type `typer.Context`.\n\nAnd from that context you can get the current values for each parameter.\n\n{* docs_src/options_autocompletion/tutorial007_an_py310.py hl[12:13,15] *}\n\nWe are getting the `names` already provided with `--name` in the command line before this completion was triggered.\n\nIf there's no `--name` in the command line, it will be `None`, so we use `or []` to make sure we have a `list` (even if empty) to check its contents later.\n\nThen, when we have a completion candidate, we check if each `name` was already provided with `--name` by checking if it's in that list of `names` with `name not in names`.\n\nAnd then we `yield` each item that has not been used yet.\n\nCheck it:\n\n\n\n```console\n$ typer ./main.py run --name [TAB][TAB]\n\n// The first time we trigger completion, we get all the names\nCamila -- The reader of books.\nCarlos -- The writer of scripts.\nSebastian -- The type hints guy.\n\n// Add a name and trigger completion again\n$ typer ./main.py run --name Sebastian --name Ca[TAB][TAB]\n\n// Now we get completion only for the names we haven't used ๐\nCamila -- The reader of books.\nCarlos -- The writer of scripts.\n\n// And if we add another of the available names:\n$ typer ./main.py run --name Sebastian --name Camila --name [TAB][TAB]\n\n// We get completion for the only available one\nCarlos -- The writer of scripts.\n```\n\n
\n\n/// tip\n\nIt's quite possible that if there's only one option left, your shell will complete it right away instead of showing the option with the help text, to save you more typing.\n\n///\n\n## Getting the raw *CLI parameters*\n\nYou can also get the raw *CLI parameters*, just a `list` of `str` with everything passed in the command line before the incomplete value.\n\nFor example, something like `[\"typer\", \"main.py\", \"run\", \"--name\"]`.\n\n/// tip\n\nThis would be for advanced scenarios, in most use cases you would be better off using the context.\n\nBut it's still possible if you need it.\n\n///\n\nAs a simple example, let's show it on the screen before completion.\n\nBecause completion is based on the output printed by your program (handled internally by **Typer**), during completion we can't just print something else as we normally do.\n\n### Printing to \"standard error\"\n\n/// tip\n\nIf you need a refresher about what is \"standard output\" and \"standard error\" check the section in [Printing and Colors: \"Standard Output\" and \"Standard Error\"](./printing.md#standard-output-and-standard-error){.internal-link target=_blank}.\n\n///\n\nThe completion system only reads from \"standard output\", so, printing to \"standard error\" won't break completion. ๐\n\nYou can print to \"standard error\" with a **Rich** `Console(stderr=True)`.\n\nUsing `stderr=True` tells **Rich** that the output should be shown in \"standard error\".\n\n{* docs_src/options_autocompletion/tutorial008_an_py310.py hl[12,15:16] *}\n\n/// info\n\nIf you have disabled Rich, you can also use `print(lastname, file=sys.stderr)` or `typer.echo(\"some text\", err=True)` instead.\n\n///\n\nWe get all the *CLI parameters* as a raw `list` of `str` by declaring a parameter with type `list[str]`, here it's named `args`.\n\n/// tip\n\nHere we name the list of all the raw *CLI parameters* `args` because that's the usual convention.\n\nBut it doesn't contain only *CLI arguments*, it has everything, including *CLI options* and values, as a raw `list` of `str`.\n\n///\n\nAnd then we just print it to \"standard error\".\n\n\n\n```console\n$ typer ./main.py run --name [TAB][TAB]\n\n// First we see the raw CLI parameters\n['./main.py', 'run', '--name']\n\n// And then we see the actual completion\nCamila -- The reader of books.\nCarlos -- The writer of scripts.\nSebastian -- The type hints guy.\n```\n\n
\n\n/// tip\n\nThis is a very simple (and quite useless) example, just so you know how it works and that you can use it.\n\nBut it's probably useful only in very advanced use cases.\n\n///\n\n## Getting the Context and the raw *CLI parameters*\n\nOf course, you can declare everything if you need it, the context, the raw *CLI parameters*, and the incomplete `str`:\n\n{* docs_src/options_autocompletion/tutorial009_an_py310.py hl[15] *}\n\nCheck it:\n\n\n\n```console\n$ typer ./main.py run --name [TAB][TAB]\n\n// First we see the raw CLI parameters\n['./main.py', 'run', '--name']\n\n// And then we see the actual completion\nCamila -- The reader of books.\nCarlos -- The writer of scripts.\nSebastian -- The type hints guy.\n\n$ typer ./main.py run --name Sebastian --name Ca[TAB][TAB]\n\n// Again, we see the raw CLI parameters\n['./main.py', 'run', '--name', 'Sebastian', '--name']\n\n// And then we see the rest of the valid completion items\nCamila -- The reader of books.\nCarlos -- The writer of scripts.\n```\n\n
\n\n## Types, types everywhere\n\n**Typer** uses the type declarations to detect what it has to provide to your `autocompletion` function.\n\nYou can declare function parameters of these types:\n\n* `str`: for the incomplete value.\n* `typer.Context`: for the current context.\n* `list[str]`: for the raw *CLI parameters*.\n\nIt doesn't matter how you name them, in which order, or which ones of the 3 options you declare. It will all \"**just work**\" โจ\n"
},
{
"path": "docs/tutorial/package.md",
"content": "# Building a Package\n\nWhen you create a CLI program with **Typer** you probably want to create your own Python package.\n\nThat's what allows your users to install it and have it as an independent program that they can use in their terminal.\n\nAnd that's also required for shell auto completion to work (unless you use your program through the `typer` command).\n\nNowadays, there are several ways and tools to create Python packages (what you install with `pip install something` or `uv add something`).\n\nYou might even have your favorite already.\n\nHere's a very opinionated, short guide, showing one of the alternative ways of creating a Python package with a **Typer** app, from scratch.\n\n/// tip\n\nIf you already have a favorite way of creating Python packages, feel free to skip this.\n\n///\n\n## Prerequisites\n\nFor this guide we'll use uv.\n\nuv's docs are great, so go ahead, check them and install it.\n\n## Create a project\n\nLet's say we want to create a CLI application called `portal-gun`.\n\nTo make sure your package doesn't collide with the package created by someone else, we'll name it with a prefix of your name.\n\nSo, if your name is Rick, we'll call it `rick-portal-gun`.\n\nCreate a project with uv:\n\n\n\n```console\n$ uv init --package rick-portal-gun\n\nInitialized project `rick-portal-gun` at `/home/rick-portal-gun`\n\n// Enter the new project directory\ncd ./rick-portal-gun\n```\n\n
\n\n## Dependencies and environment\n\nAdd `typer` to your dependencies:\n\n\n\n```console\n$ uv add typer\n\n// It creates a virtual environment for your project\nUsing CPython 3.14.0 interpreter at: /location/of/python/\nCreating virtual environment at: .venv\n\nResolved 10 packages in 21ms\n Built rick-portal-gun @ file:/home/rick-portal-gun\nPrepared 1 package in 19ms\nInstalled 10 packages in 34ms\n + click==8.3.1\n + colorama==0.4.6\n + markdown-it-py==4.0.0\n + mdurl==0.1.2\n + pygments==2.19.2\n + rich==14.2.0\n + rick-portal-gun==0.1.0 (from file:/home/rick-portal-gun)\n + shellingham==1.5.4\n + typer==0.21.0\n + typing-extensions==4.15.0\n\n\n// Activate that new virtual environment\n$ source .venv/bin/activate\n\n// Open an editor using this new environment, for example VS Code\n$ code ./\n```\n\n
\n\nYou can see that you have a generated project structure that looks like:\n\n```\n.\nโโโ pyproject.toml\nโโโ README.md\nโโโ src\nโย ย โโโ rick_portal_gun\nโย ย ย ย โโโ __init__.py\nโโโ uv.lock\n```\n\n## Create your app\n\nNow let's create an extremely simple **Typer** app.\n\nCreate a file `src/rick_portal_gun/main.py` with:\n\n```Python\nimport typer\n\n\napp = typer.Typer()\n\n\n@app.callback()\ndef callback():\n \"\"\"\n Awesome Portal Gun\n \"\"\"\n\n\n@app.command()\ndef shoot():\n \"\"\"\n Shoot the portal gun\n \"\"\"\n typer.echo(\"Shooting portal gun\")\n\n\n@app.command()\ndef load():\n \"\"\"\n Load the portal gun\n \"\"\"\n typer.echo(\"Loading portal gun\")\n```\n\n/// tip\n\nAs we are creating an installable Python package, there's no need to add a section with `if __name__ == \"__main__\":`.\n\n///\n\n## Modify the README\n\nLet's change the README to have something like:\n\n```Markdown\n# Portal Gun\n\nThe awesome Portal Gun\n```\n\n## Add a \"script\"\n\nWe are creating a Python package that can be installed with `uv add` or `pip install`.\n\nBut we want it to provide a CLI program that can be executed in the shell.\n\nTo do that, we add a configuration to the `pyproject.toml` in the section `[project.scripts]`:\n\n```TOML hl_lines=\"12 13\"\n[project]\nname = \"rick-portal-gun\"\nversion = \"0.1.0\"\ndescription = \"Add your description here\"\nreadme = \"README.md\"\nauthors = [\"Rick Sanchez \"]\nrequires-python = \">=3.14\"\ndependencies = [\n \"typer>=0.21.0\",\n]\n\n[project.scripts]\nrick-portal-gun = \"rick_portal_gun.main:app\"\n\n[build-system]\nrequires = [\"uv_build>=0.8.14,<0.9.0\"]\nbuild-backend = \"uv_build\"\n```\n\nHere's what that line means:\n\n`rick-portal-gun`: will be the name of the CLI program. That's how we will call it in the terminal once it is installed. Like:\n\n\n\n```console\n$ rick-portal-gun\n\n// Something happens here โจ\n```\n\n
\n\n`rick_portal_gun.main`, in the part `\"rick_portal_gun.main:app\"`, with underscores, refers to the Python module to import. That's what someone would use in a section like:\n\n```Python\nfrom rick_portal_gun.main import # something goes here\n```\n\nThe `app` in `\"rick_portal_gun.main:app\"` is the thing to import from the module, and to call as a function, like:\n\n```Python\nfrom rick_portal_gun.main import app\napp()\n```\n\nThat config section tells uv that when this package is installed, we want it to create a command line program called `rick-portal-gun`.\n\nAnd that the object to call (like a function) is the one in the variable `app` inside of the module `rick_portal_gun.main`.\n\n## Install your package\n\nThat's what we need to create a package.\n\nYou can now install it:\n\n\n\n```console\n$ uv sync\n\nResolved 10 packages in 1ms\n Built rick-portal-gun @ file:/home/rick-portal-gun\nPrepared 1 package in 18ms\nUninstalled 1 package in 1ms\nInstalled 1 package in 13ms\n ~ rick-portal-gun==0.1.0 (from file:/home/rick-portal-gun)\n\n```\n\n
\n\n## Try your CLI program\n\nYour package is installed in the environment created by uv, but you can already use it.\n\n\n\n```console\n// You can use the which program to check which rick-portal-gun program is available (if any)\n$ which rick-portal-gun\n\n// You get the one from your environment\n/home/rick-portal-gun/.venv/bin/rick-portal-gun\n\n// Try it\n$ rick-portal-gun --help\n\n// You get all the standard help\nUsage: rick-portal-gun [OPTIONS] COMMAND [ARGS]...\n\n Awesome Portal Gun\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n\n --help Show this message and exit.\n\nCommands:\n shoot Shoot the portal gun\n load Load the portal gun\n```\n\n
\n\n## Create a wheel package\n\nPython packages have a standard format called a \"wheel\". It's a file that ends in `.whl`.\n\nYou can create a wheel with uv:\n\n\n\n```console\n$ uv build\n\nBuilding source distribution (uv build backend)...\nBuilding wheel from source distribution (uv build backend)...\nSuccessfully built dist/rick_portal_gun-0.1.0.tar.gz\nSuccessfully built dist/rick_portal_gun-0.1.0-py3-none-any.whl\n```\n\n
\n\nAfter that, if you check in your project directory, you should now have a couple of extra files at `./dist/`:\n\n``` hl_lines=\"3 4\"\n.\nโโโ dist\nโย ย โโโ rick_portal_gun-0.1.0-py3-none-any.whl\nโย ย โโโ rick-portal-gun-0.1.0.tar.gz\nโโโ pyproject.toml\nโโโ README.md\nโโโ ...\n```\n\nThe `.whl` is the wheel file. You can send that wheel file to anyone and they can use it to install your program (we'll see how to upload it to PyPI in a bit).\n\n## Test your wheel package\n\nNow you can open another terminal and install that package from the file for your own user with:\n\n\n\n```console\n$ pip install --user /home/rick/rick-portal-gun/dist/rick_portal_gun-0.1.0-py3-none-any.whl\n\n---> 100%\n```\n\n
\n\n/// warning\n\nThe `--user` is important, that ensures you install it in your user's directory and not in the global system.\n\nIf you installed it in the global system (e.g. with `sudo`) you could install a version of a library (e.g. a sub-dependency) that is incompatible with your system.\n\n///\n\n/// tip\n\nBonus points if you use uvx to install it while keeping an isolated environment for your Python CLI programs ๐\n\n///\n\nNow you have your CLI program installed. And you can use it freely:\n\n\n\n```console\n$ rick-portal-gun shoot\n\n// It works ๐\nShooting portal gun\n```\n\n
\n\nHaving it installed globally (and not in a single environment), you can now install completion globally for it:\n\n\n\n```console\n$ rick-portal-gun --install-completion\n\nzsh completion installed in /home/rick/.zshrc.\nCompletion will take effect once you restart the terminal.\n```\n\n
\n\n/// tip\n\nIf you want to remove completion you can just delete the added line in that file.\n\n///\n\nAnd after you restart the terminal you will get completion for your new CLI program:\n\n\n\n```console\n$ rick-portal-gun [TAB][TAB]\n\n// You get completion for your CLI program โจ\nload -- Load the portal gun\nshoot -- Shoot the portal gun\n```\n\n
\n\n## Support `python -m` (optional)\n\nYou may have seen that you can call many Python modules as scripts with `python -m some-module`.\n\nFor example, one way to call `pip` is:\n\n\n\n```console\n$ pip install fastapi\n```\n\n
\n\nBut you can also call Python with the `-m` *CLI Option* and pass a module for it to execute as if it was a script, like:\n\n\n\n```console\n$ python -m pip install fastapi\n```\n\n
\n\nHere we pass `pip` as the value for `-m`, so, Python will execute the module `pip` as if it was a script. And then it will pass the rest of the *CLI Parameters* (`install fastapi`) to it.\n\nThese two are more or less equivalent, the `install fastapi` will be passed to `pip`.\n\n/// tip\n\nIn the case of `pip`, in many occasions it's actually recommended that you run it with `python -m`, because if you create a virtual environment with its own `python`, that will ensure that you use the `pip` from *that* environment.\n\n///\n\n### Add a `__main__.py`\n\nYou can support that same style of calling the package/module for your own package, simply by adding a file `__main__.py`.\n\nPython will look for that file and execute it.\n\nThe file would live right beside `__init__.py` and `main.py`:\n\n``` hl_lines=\"7\"\n.\nโโโ pyproject.toml\nโโโ README.md\nโโโ src\nโย ย โโโ rick_portal_gun\nโย ย ย ย โโโ __init__.py\nโย ย ย ย โโโ __main__.py\nโย ย ย ย โโโ main.py\nโโโ uv.lock\n```\n\nNo other file has to import it, you don't have to reference it in your `pyproject.toml` or anything else, it just works by default, as it is standard Python behavior.\n\nThen in that file you can execute your **Typer** program:\n\n```Python\nfrom .main import app\napp()\n```\n\nNow, after installing your package, if you call it with `python -m` it will work:\n\n\n\n```console\n$ python -m rick_portal_gun --help\n\nUsage: python -m rick_portal_gun [OPTIONS] COMMAND [ARGS]...\n\n Awesome Portal Gun\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n\n --help Show this message and exit.\n\nCommands:\n shoot Shoot the portal gun\n load Load the portal gun\n```\n\n
\n\n/// tip\n\nNotice that you have to pass the importable version of the package name, so `rick_portal_gun` instead of `rick-portal-gun`.\n\n///\n\nThat works! ๐\n\n### Autocompletion and `python -m`\n\nHave in mind that TAB completion (shell auto-completion) won't work when using `python -m`.\n\nAuto-completion depends on the name of the program called, it's tied to each specific program name.\n\nSo, to have shell completion for `rick-portal-gun` you would have to call it directly:\n\n\n\n```console\n$ rick-portal-gun [TAB][TAB]\n```\n\n
\n\nBut you can still support `python -m` for the cases where it's useful.\n\n## Publish to PyPI (optional)\n\nYou can publish that new package to PyPI to make it public, so others can install it easily.\n\nSo, go ahead and create an account there (it's free).\n\n### PyPI API token\n\nTo do it, you first need to configure a PyPI auth token.\n\nLogin to PyPI.\n\nAnd then go to https://pypi.org/manage/account/token/ to create a new token.\n\nLet's say your new API token is:\n\n```\npypi-wubalubadubdub-deadbeef1234\n```\n\nNow configure uv to use this token by setting an environment variable:\n\n\n\n```console\n$ export UV_PUBLISH_TOKEN=pypi-wubalubadubdub-deadbeef1234\n// It won't show any output, but it's already configured\n```\n\n
\n\n### Publish to PyPI\n\nNow you can publish your package.\n\n\n\n```console\n$ uv publish\n\nPublishing 2 files https://upload.pypi.org/legacy/\nUploading rick_portal_gun-0.1.0-py3-none-any.whl (2.3KiB)\nUploading rick_portal_gun-0.1.0.tar.gz (841.0B)\n```\n\n
\n\nNow you can go to PyPI and check your projects at https://pypi.org/manage/projects/.\n\nYou should now see your new \"rick-portal-gun\" package.\n\n### Install from PyPI\n\nNow to see that we can install it from PyPI, open another terminal, and uninstall the currently installed package.\n\n\n\n```console\n$ pip uninstall rick-portal-gun\n\nFound existing installation: rick-portal-gun 0.1.0\nUninstalling rick-portal-gun-0.1.0:\n Would remove:\n /home/rick/.local/bin/rick-portal-gun\n /home/rick/.local/lib/python3.10/site-packages/rick_portal_gun-0.1.0.dist-info/*\n /home/rick/.local/lib/python3.10/site-packages/rick_portal_gun/*\n# Proceed (Y/n)? $ Y\n Successfully uninstalled rick-portal-gun-0.1.0\n```\n\n
\n\nAnd now install it again, but this time using just the name, so that `pip` pulls it from PyPI:\n\n\n\n```console\n$ pip install --user rick-portal-gun\n\n// Notice that it says \"Downloading\" ๐\nCollecting rick-portal-gun\n Downloading rick_portal_gun-0.1.0-py3-none-any.whl.metadata (435 bytes)\nRequirement already satisfied: typer<0.13.0,>=0.12.3 in ./.local/lib/python3.10/site-packages (from rick-portal-gun==0.1.0) (0.12.3)\nRequirement already satisfied: typing-extensions>=3.7.4.3 in ./.local/lib/python3.10/site-packages (from typer<0.13.0,>=0.12.3->rick-portal-gun==0.1.0) (4.11.0)\nRequirement already satisfied: click>=8.0.0 in ./.local/lib/python3.10/site-packages (from typer<0.13.0,>=0.12.3->rick-portal-gun==0.1.0) (8.1.7)\nRequirement already satisfied: shellingham>=1.3.0 in ./.local/lib/python3.10/site-packages (from typer<0.13.0,>=0.12.3->rick-portal-gun==0.1.0) (1.5.4)\nRequirement already satisfied: rich>=10.11.0 in ./.local/lib/python3.10/site-packages (from typer<0.13.0,>=0.12.3->rick-portal-gun==0.1.0) (13.7.1)\nRequirement already satisfied: pygments<3.0.0,>=2.13.0 in ./.local/lib/python3.10/site-packages (from rich>=10.11.0->typer<0.13.0,>=0.12.3->rick-portal-gun==0.1.0) (2.17.2)\nRequirement already satisfied: markdown-it-py>=2.2.0 in ./.local/lib/python3.10/site-packages (from rich>=10.11.0->typer<0.13.0,>=0.12.3->rick-portal-gun==0.1.0) (3.0.0)\nRequirement already satisfied: mdurl~=0.1 in ./.local/lib/python3.10/site-packages (from markdown-it-py>=2.2.0->rich>=10.11.0->typer<0.13.0,>=0.12.3->rick-portal-gun==0.1.0) (0.1.2)\nDownloading rick_portal_gun-0.1.0-py3-none-any.whl (1.8 kB)\nInstalling collected packages: rick-portal-gun\nSuccessfully installed rick-portal-gun-0.1.0\n```\n\n
\n\nAnd now test the newly installed package from PyPI:\n\n\n\n```console\n$ rick-portal-gun load\n\n// It works! ๐\nLoading portal gun\n```\n\n
\n\n## Generate docs\n\nYou can use the `typer` command to generate docs for your package that you can put in your `README.md`:\n\n\n\n```console\n$ typer rick_portal_gun.main utils docs --output README.md --name rick-portal-gun\n\nDocs saved to: README.md\n```\n\n
\n\nYou just have to pass it the module to import (`rick_portal_gun.main`) and it will detect the `typer.Typer` app automatically.\n\nBy specifying the `--name` of the program it will be able to use it while generating the docs.\n\n### Publish a new version with the docs\n\nNow you can publish a new version with the updated docs.\n\nFor that you need to first increase the version in `pyproject.toml`:\n\n```TOML hl_lines=\"3\"\n[project]\nname = \"rick-portal-gun\"\nversion = \"0.2.0\"\ndescription = \"Add your description here\"\nreadme = \"README.md\"\nauthors = [\"Rick Sanchez \"]\nrequires-python = \">=3.14\"\ndependencies = [\n \"typer>=0.21.0\",\n]\n\n[project.scripts]\nrick-portal-gun = \"rick_portal_gun.main:app\"\n\n[build-system]\nrequires = [\"uv_build>=0.8.14,<0.9.0\"]\nbuild-backend = \"uv_build\"\n```\n\nAnd then build and publish again:\n\n\n\n```console\n$ uv build\n$ uv publish\n\nPublishing 2 files https://upload.pypi.org/legacy/\nUploading rick_portal_gun-0.2.0-py3-none-any.whl (2.3KiB)\nUploading rick_portal_gun-0.2.0.tar.gz (840.0B)\n```\n\n
\n\nAnd now you can go to PyPI, to the project page, and reload it, and it will now have your new generated docs.\n\n## What's next\n\nThis is a very simple guide. You could add many more steps.\n\nFor example, you should use Git, the version control system, to save your code.\n\nYou could use uv to manage your installed CLI Python programs in isolated environments.\n\nMaybe use automatic formatting with Ruff.\n\nYou'll probably want to publish your code as open source to GitHub.\n\nAnd then you could integrate a CI tool to run your tests and deploy your package automatically.\n\nAnd there's a long etc. But now you have the basics and you can continue on your own. ๐\n"
},
{
"path": "docs/tutorial/parameter-types/bool.md",
"content": "# Boolean CLI Options\n\nWe have seen some examples of *CLI options* with `bool`, and how **Typer** creates `--something` and `--no-something` automatically.\n\nBut we can customize those names.\n\n## Only `--force`\n\nLet's say that we want a `--force` *CLI option* only, we want to discard `--no-force`.\n\nWe can do that by specifying the exact name we want:\n\n{* docs_src/parameter_types/bool/tutorial001_an_py310.py hl[9] *}\n\nNow there's only a `--force` *CLI option*:\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\n// Notice there's only --force, we no longer have --no-force\nUsage: main.py [OPTIONS]\n\nOptions:\n --force [default: False]\n --help Show this message and exit.\n\n// Try it:\n$ python main.py\n\nNot forcing\n\n// Now add --force\n$ python main.py --force\n\nForcing operation\n\n// And --no-force no longer exists โ๏ธ\n$ python main.py --no-force\n\nUsage: main.py [OPTIONS]\nTry \"main.py --help\" for help.\n\nError: No such option: --no-force\n```\n\n
\n\n## Alternative names\n\nNow let's imagine we have a *CLI option* `--accept`.\n\nAnd we want to allow setting `--accept` or the contrary, but `--no-accept` looks ugly.\n\nWe might want to instead have `--accept` and `--reject`.\n\nWe can do that by passing a single `str` with the 2 names for the `bool` *CLI option* separated by `/`:\n\n{* docs_src/parameter_types/bool/tutorial002_an_py310.py hl[9] *}\n\nCheck it:\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\n// Notice the --accept / --reject\nUsage: main.py [OPTIONS]\n\nOptions:\n --accept / --reject\n --help Show this message and exit.\n\n// Try it\n$ python main.py\n\nI don't know what you want yet\n\n// Now pass --accept\n$ python main.py --accept\n\nAccepting!\n\n// And --reject\n$ python main.py --reject\n\nRejecting!\n```\n\n
\n\n## Short names\n\nThe same way, you can declare short versions of the names for these *CLI options*.\n\nFor example, let's say we want `-f` for `--force` and `-F` for `--no-force`:\n\n{* docs_src/parameter_types/bool/tutorial003_an_py310.py hl[9] *}\n\nCheck it:\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\n// Notice the -f, --force / -F, --no-force\nUsage: main.py [OPTIONS]\n\nOptions:\n -f, --force / -F, --no-force [default: False]\n --help Show this message and exit.\n\n// Try with the short name -f\n$ python main.py -f\n\nForcing operation\n\n// Try with the short name -F\n$ python main.py -F\n\nNot forcing\n```\n\n
\n\n## Only names for `False`\n\nIf you want to (although it might not be a good idea), you can declare only *CLI option* names to set the `False` value.\n\nTo do that, use a space and a single `/` and pass the negative name after:\n\n{* docs_src/parameter_types/bool/tutorial004_an_py310.py hl[9] *}\n\n/// tip\n\nHave in mind that it's a string with a preceding space and then a `/`.\n\nSo, it's `\" /-S\"` not `\"/-S\"`.\n\n///\n\nCheck it:\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\n// Notice the / -d, --demo\nUsage: main.py [OPTIONS]\n\nOptions:\n / -d, --demo [default: True]\n --help Show this message and exit.\n\n// Try it\n$ python main.py\n\nRunning in production\n\n// Now pass --demo\n$ python main.py --demo\n\nRunning demo\n\n// And the short version\n$ python main.py -d\n\nRunning demo\n```\n\n
\n"
},
{
"path": "docs/tutorial/parameter-types/custom-types.md",
"content": "# Custom Types\n\nYou can easily use your own custom types in your **Typer** applications.\n\nThe way to do it is by providing a way to parse input into your own types.\n\n## Type Parser\n\n`typer.Argument` and `typer.Option` can create custom parameter types with a `parser` callable.\n\n{* docs_src/parameter_types/custom_types/tutorial001_an_py310.py hl[14:15,23:24] *}\n\nThe function (or callable) that you pass to the parameter `parser` will receive the input value as a string and should return the parsed value with your own custom type.\n"
},
{
"path": "docs/tutorial/parameter-types/datetime.md",
"content": "# DateTime\n\nYou can specify a *CLI parameter* as a Python `datetime`.\n\nYour function will receive a standard Python `datetime` object, and again, your editor will give you completion, etc.\n\n{* docs_src/parameter_types/datetime/tutorial001_py310.py hl[1,9,10,11] *}\n\nTyper will accept any string from the following formats:\n\n* `%Y-%m-%d`\n* `%Y-%m-%dT%H:%M:%S`\n* `%Y-%m-%d %H:%M:%S`\n\nCheck it:\n\n\n\n```console\n$ python main.py --help\n\nUsage: main.py [OPTIONS] BIRTH:[%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d %H:%M:%S]\n\nArguments:\n BIRTH:[%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d %H:%M:%S][required]\n\nOptions:\n --help Show this message and exit.\n\n// Pass a datetime\n$ python main.py 1956-01-31T10:00:00\n\nInteresting day to be born: 1956-01-31 10:00:00\nBirth hour: 10\n\n// An invalid date\n$ python main.py july-19-1989\n\nUsage: main.py [OPTIONS] [%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d%H:%M:%S]\n\nError: Invalid value for 'BIRTH:[%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d %H:%M:%S]': 'july-19-1989' does not match the formats '%Y-%m-%d', '%Y-%m-%dT%H:%M:%S', '%Y-%m-%d %H:%M:%S'.\n```\n\n
\n\n## Custom date format\n\nYou can also customize the formats received for the `datetime` with the `formats` parameter.\n\n`formats` receives a list of strings with the date formats that would be passed to datetime.strptime().\n\nFor 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:\n\n* first the month\n* then the day\n* then the year\n* separated with \"`/`\"\n\n...It's a crazy example, but let's say you also needed that strange format:\n\n{* docs_src/parameter_types/datetime/tutorial002_an_py310.py hl[14] *}\n\n/// tip\n\nNotice the last string in `formats`: `\"%m/%d/%Y\"`.\n\n///\n\nCheck it:\n\n\n\n```console\n// ISO dates work\n$ python main.py 1969-10-29\n\nLaunch will be at: 1969-10-29 00:00:00\n\n// But the strange custom format also works\n$ python main.py 10/29/1969\n\nLaunch will be at: 1969-10-29 00:00:00\n```\n\n
\n"
},
{
"path": "docs/tutorial/parameter-types/enum.md",
"content": "# Enum - Choices\n\nTo define a *CLI parameter* that can take a value from a predefined set of values you can use a standard Python `enum.Enum`:\n\n{* docs_src/parameter_types/enum/tutorial001_py310.py hl[1,6:9,16:17] *}\n\n/// tip\n\nNotice that the function parameter `network` will be an `Enum`, not a `str`.\n\nTo get the `str` value in your function's code use `network.value`.\n\n///\n\nCheck it:\n\n\n\n```console\n$ python main.py --help\n\n// Notice the predefined values [simple|conv|lstm]\nUsage: main.py [OPTIONS]\n\nOptions:\n --network [simple|conv|lstm] [default: simple]\n --help Show this message and exit.\n\n// Try it\n$ python main.py --network conv\n\nTraining neural network of type: conv\n\n// Invalid value\n$ python main.py --network capsule\n\nUsage: main.py [OPTIONS]\nTry \"main.py --help\" for help.\n\nError: Invalid value for '--network': 'capsule' is not one of 'simple', 'conv', 'lstm'.\n\n// Note that enums are case sensitive by default\n$ python main.py --network CONV\n\nUsage: main.py [OPTIONS]\nTry \"main.py --help\" for help.\n\nError: Invalid value for '--network': 'CONV' is not one of 'simple', 'conv', 'lstm'.\n```\n\n
\n\n### Case insensitive Enum choices\n\nYou can make an `Enum` (choice) *CLI parameter* be case-insensitive with the `case_sensitive` parameter:\n\n{* docs_src/parameter_types/enum/tutorial002_an_py310.py hl[19] *}\n\nAnd then the values of the `Enum` will be checked no matter if lower case, upper case, or a mix:\n\n\n\n```console\n// Notice the upper case CONV\n$ python main.py --network CONV\n\nTraining neural network of type: conv\n\n// A mix also works\n$ python main.py --network LsTm\n\nTraining neural network of type: lstm\n```\n\n
\n\n### List of Enum values\n\nA *CLI parameter* can also take a list of `Enum` values:\n\n{* docs_src/parameter_types/enum/tutorial003_an_py310.py hl[17] *}\n\nThis works just like any other parameter value taking a list of things:\n\n\n\n```console\n$ python main.py --help\n\n// Notice the default values being shown\nUsage: main.py [OPTIONS]\n\nOptions:\n --groceries [Eggs|Bacon|Cheese] [default: Eggs, Cheese]\n --help Show this message and exit.\n\n// Try it with the default values\n$ python main.py\n\nBuying groceries: Eggs, Cheese\n\n// Try it with a single value\n$ python main.py --groceries \"Eggs\"\n\nBuying groceries: Eggs\n\n// Try it with multiple values\n$ python main.py --groceries \"Eggs\" --groceries \"Bacon\"\n\nBuying groceries: Eggs, Bacon\n```\n\n
\n\n### Literal choices\n\nYou can also use `Literal` to represent a set of possible predefined choices, without having to use an `Enum`:\n\n{* docs_src/parameter_types/enum/tutorial004_an_py310.py hl[10] *}\n\n\n\n```console\n$ python main.py --help\n\n// Notice the predefined values [simple|conv|lstm]\nUsage: main.py [OPTIONS]\n\nOptions:\n --network [simple|conv|lstm] [default: simple]\n --help Show this message and exit.\n\n// Try it\n$ python main.py --network conv\n\nTraining neural network of type: conv\n\n// Invalid value\n$ python main.py --network capsule\n\nUsage: main.py [OPTIONS]\nTry \"main.py --help\" for help.\n\nError: Invalid value for '--network': 'capsule' is not one of 'simple', 'conv', 'lstm'.\n```\n\n
\n"
},
{
"path": "docs/tutorial/parameter-types/file.md",
"content": "# File\n\nApart from `Path` *CLI parameters* you can also declare some types of \"files\".\n\n/// tip\n\nIn most of the cases you are probably fine just using `Path`.\n\nYou can read and write data with `Path` the same way.\n\n///\n\nThe difference is that these types will give you a Python file-like object instead of a Python Path.\n\nA \"file-like object\" is the same type of object returned by `open()` as in:\n\n```Python\nwith open('file.txt') as f:\n # Here f is the file-like object\n read_data = f.read()\n print(read_data)\n```\n\nBut in some special use cases you might want to use these special types. For example if you are migrating an existing application.\n\n## `FileText` reading\n\n`typer.FileText` gives you a file-like object for reading text, you will get `str` data from it.\n\nThis means that even if your file has text written in a non-english language, e.g. a `text.txt` file with:\n\n```\nla cigรผeรฑa trae al niรฑo\n```\n\nYou will have a `str` with the text inside, e.g.:\n\n```Python\ncontent = \"la cigรผeรฑa trae al niรฑo\"\n```\n\ninstead of having `bytes`, e.g.:\n\n```Python\ncontent = b\"la cig\\xc3\\xbce\\xc3\\xb1a trae al ni\\xc3\\xb1o\"\n```\n\nYou will get all the correct editor support, attributes, methods, etc for the file-like object:`\n\n{* docs_src/parameter_types/file/tutorial001_an_py310.py hl[9] *}\n\nCheck it:\n\n\n\n```console\n// Create a quick text config\n$ echo \"some settings\" > config.txt\n\n// Add another line to the config to test it\n$ echo \"some more settings\" >> config.txt\n\n// Now run your program\n$ python main.py --config config.txt\n\nConfig line: some settings\n\nConfig line: some more settings\n```\n\n
\n\n## `FileTextWrite`\n\nFor writing text, you can use `typer.FileTextWrite`:\n\n{* docs_src/parameter_types/file/tutorial002_an_py310.py hl[9:10] *}\n\nThis would be for writing human text, like:\n\n```\nsome settings\nla cigรผeรฑa trae al niรฑo\n```\n\n...not to write binary `bytes`.\n\nCheck it:\n\n\n\n```console\n$ python main.py --config text.txt\n\nConfig written\n\n// Check the contents of the file\n$ cat text.txt\n\nSome config written by the app\n```\n\n
\n\n/// info | Technical Details\n\n`typer.FileTextWrite` is a just a convenience class.\n\nIt's the same as using `typer.FileText` and setting `mode=\"w\"`. You will learn about `mode` later below.\n\n///\n\n## `FileBinaryRead`\n\nTo read binary data you can use `typer.FileBinaryRead`.\n\nYou will receive `bytes` from it.\n\nIt's useful for reading binary files like images:\n\n{* docs_src/parameter_types/file/tutorial003_an_py310.py hl[9] *}\n\nCheck it:\n\n\n\n```console\n$ python main.py --file lena.jpg\n\nProcessed bytes total: 512\nProcessed bytes total: 1024\nProcessed bytes total: 1536\nProcessed bytes total: 2048\n```\n\n
\n\n## `FileBinaryWrite`\n\nTo write binary data you can use `typer.FileBinaryWrite`.\n\nYou would write `bytes` to it.\n\nIt's useful for writing binary files like images.\n\nHave in mind that you have to pass `bytes` to its `.write()` method, not `str`.\n\nIf you have a `str`, you have to encode it first to get `bytes`.\n\n{* docs_src/parameter_types/file/tutorial004_an_py310.py hl[9] *}\n\n\n\n```console\n$ python main.py --file binary.dat\n\nBinary file written\n\n// Check the binary file was created\n$ ls ./binary.dat\n\n./binary.dat\n```\n\n
\n\n## File *CLI parameter* configurations\n\nYou can use several configuration parameters for these types (classes) in `typer.Option()` and `typer.Argument()`:\n\n* `mode`: controls the \"mode\" to open the file with.\n * It's automatically set for you by using the classes above.\n * Read more about it below.\n* `encoding`: to force a specific encoding, e.g. `\"utf-8\"`.\n* `lazy`: delay I/O operations. Automatic by default.\n * By default, when writing files, Typer will generate a file-like object that is not yet the actual file. Once you start writing, it will go, open the file and start writing to it, but not before. This is mainly useful to avoid creating the file until you start writing to it. It's normally safe to leave this automatic. But you can overwrite it setting `lazy=False`. By default, it's `lazy=True` for writing and `lazy=False` for reading.\n* `atomic`: if true, all writes will actually go to a temporal file and then moved to the final destination after completing. This is useful with files modified frequently by several users/programs.\n\n## Advanced `mode`\n\nBy default, **Typer** will configure the `mode` for you:\n\n* `typer.FileText`: `mode=\"r\"`, to read text.\n* `typer.FileTextWrite`: `mode=\"w\"`, to write text.\n* `typer.FileBinaryRead`: `mode=\"rb\"`, to read binary data.\n* `typer.FileBinaryWrite`: `mode=\"wb\"`, to write binary data.\n\n### Note about `FileTextWrite`\n\n`typer.FileTextWrite` is actually just a convenience class. It's the same as using `typer.FileText` with `mode=\"w\"`.\n\nBut it's probably shorter and more intuitive as you can get it with autocompletion in your editor by just starting to type `typer.File`... just like the other classes.\n\n### Customize `mode`\n\nYou can override the `mode` from the defaults above.\n\nFor example, you could use `mode=\"a\"` to write \"appending\" to the same file:\n\n{* docs_src/parameter_types/file/tutorial005_an_py310.py hl[9] *}\n\n/// tip\n\nAs you are manually setting `mode=\"a\"`, you can use `typer.FileText` or `typer.FileTextWrite`, both will work.\n\n///\n\nCheck it:\n\n\n\n```console\n$ python main.py --config config.txt\n\nConfig line written\n\n// Run your program a couple more times to see how it appends instead of overwriting\n$ python main.py --config config.txt\n\nConfig line written\n\n$ python main.py --config config.txt\n\nConfig line written\n\n// Check the contents of the file, it should have each of the 3 lines appended\n$ cat config.txt\n\nThis is a single line\nThis is a single line\nThis is a single line\n```\n\n
\n"
},
{
"path": "docs/tutorial/parameter-types/index.md",
"content": "# CLI Parameter Types\n\nYou can use several data types for the *CLI options* and *CLI arguments*, and you can add data validation requirements too.\n\n## Data conversion\n\nWhen you declare a *CLI parameter* with some type **Typer** will convert the data received in the command line to that data type.\n\nFor example:\n\n{* docs_src/parameter_types/index/tutorial001_py310.py hl[7] *}\n\nIn this example, the value received for the *CLI argument* `NAME` will be treated as `str`.\n\nThe value for the *CLI option* `--age` will be converted to an `int` and `--height-meters` will be converted to a `float`.\n\nAnd as `female` is a `bool` *CLI option*, **Typer** will convert it to a \"flag\" `--female` and the counterpart `--no-female`.\n\nAnd here's how it looks like:\n\n\n\n```console\n$ python main.py --help\n\n// Notice how --age is an INTEGER and --height-meters is a FLOAT\nUsage: main.py [OPTIONS] NAME\n\nArguments:\n NAME [required]\n\nOptions:\n --age INTEGER [default: 20]\n --height-meters FLOAT [default: 1.89]\n --female / --no-female [default: True]\n --help Show this message and exit.\n\n// Call it with CLI parameters\n$ python main.py Camila --age 15 --height-meters 1.70 --female\n\n// All the data has the correct Python type\nNAME is Camila, of type: class 'str'\n--age is 15, of type: class 'int'\n--height-meters is 1.7, of type: class 'float'\n--female is True, of type: class 'bool'\n\n// And if you pass an incorrect type\n$ python main.py Camila --age 15.3\n\nUsage: main.py [OPTIONS] NAME\nTry \"main.py --help\" for help.\n\nError: Invalid value for '--age': '15.3' is not a valid integer\n\n// Because 15.3 is not an INTEGER (it's a float)\n```\n\n
\n\n## Watch next\n\nSee more about specific types and validations in the next sections...\n"
},
{
"path": "docs/tutorial/parameter-types/number.md",
"content": "# Number\n\nYou can define numeric validations with `max` and `min` values for `int` and `float` *CLI parameters*:\n\n{* docs_src/parameter_types/number/tutorial001_an_py310.py hl[10:12] *}\n\n*CLI arguments* and *CLI options* can both use these validations.\n\nYou can specify `min`, `max` or both.\n\nCheck it:\n\n\n\n```console\n$ python main.py --help\n\n// Notice the extra RANGE in the help text for --age and --score\nUsage: main.py [OPTIONS] ID\n\nArguments:\n ID [required]\n\nOptions:\n --age INTEGER RANGE [default: 20]\n --score FLOAT RANGE [default: 0]\n --help Show this message and exit.\n\n// Pass all the CLI parameters\n$ python main.py 5 --age 20 --score 90\n\nID is 5\n--age is 20\n--score is 90.0\n\n// Pass an invalid ID\n$ python main.py 1002\n\nUsage: main.py [OPTIONS] ID\nTry \"main.py --help\" for help.\n\nError: Invalid value for 'ID': 1002 is not in the range 0<=x<=1000.\n\n// Pass an invalid age\n$ python main.py 5 --age 15\n\nUsage: main.py [OPTIONS] ID\nTry \"main.py --help\" for help.\n\nError: Invalid value for '--age': 15 is not in the range x>=18.\n\n// Pass an invalid score\n$ python main.py 5 --age 20 --score 100.5\n\nUsage: main.py [OPTIONS] ID\nTry \"main.py --help\" for help.\n\nError: Invalid value for '--score': 100.5 is not in the range x<=100.\n\n// But as we didn't specify a minimum score, this is accepted\n$ python main.py 5 --age 20 --score -5\n\nID is 5\n--age is 20\n--score is -5.0\n```\n\n
\n\n## Clamping numbers\n\nYou might want to, instead of showing an error, use the closest minimum or maximum valid values.\n\nYou can do it with the `clamp` parameter:\n\n{* docs_src/parameter_types/number/tutorial002_an_py310.py hl[10:12] *}\n\nAnd then, when you pass data that is out of the valid range, it will be \"clamped\", the closest valid value will be used:\n\n\n\n```console\n// ID doesn't have clamp, so it shows an error\n$ python main.py 1002\n\nUsage: main.py [OPTIONS] ID\nTry \"main.py --help\" for help.\n\nError: Invalid value for 'ID': 1002 is not in the range 0<=x<=1000.\n\n// But --rank and --score use clamp\n$ python main.py 5 --rank 11 --score -5\n\nID is 5\n--rank is 10\n--score is 0\n```\n\n
\n\n## Counter *CLI options*\n\nYou can make a *CLI option* work as a counter with the `count` parameter:\n\n{* docs_src/parameter_types/number/tutorial003_an_py310.py hl[9] *}\n\nIt means that the *CLI option* will be like a boolean flag, e.g. `--verbose`.\n\nAnd the value you receive in the function will be the amount of times that `--verbose` was added:\n\n\n\n```console\n// Check it\n$ python main.py\n\nVerbose level is 0\n\n// Now use one --verbose\n$ python main.py --verbose\n\nVerbose level is 1\n\n// Now 3 --verbose\n$ python main.py --verbose --verbose --verbose\n\nVerbose level is 3\n\n// And with the short name\n$ python main.py -v\n\nVerbose level is 1\n\n// And with the short name 3 times\n$ python main.py -v -v -v\n\nVerbose level is 3\n\n// As short names can be put together, this also works\n$ python main.py -vvv\n\nVerbose level is 3\n```\n\n
\n"
},
{
"path": "docs/tutorial/parameter-types/path.md",
"content": "# Path\n\nYou can declare a *CLI parameter* to be a standard Python `pathlib.Path`.\n\nThis is what you would do for directory paths, file paths, etc:\n\n{* docs_src/parameter_types/path/tutorial001_an_py310.py hl[1,10] *}\n\nAnd again, as you receive a standard Python `Path` object the same as the type annotation, your editor will give you autocompletion for all its attributes and methods.\n\nCheck it:\n\n\n\n```console\n// No config\n$ python main.py\n\nNo config file\nAborted!\n\n// Pass a config that doesn't exist\n$ python main.py --config config.txt\n\nThe config doesn't exist\n\n// Now create a quick config\n$ echo \"some settings\" > config.txt\n\n// And try again\n$ python main.py --config config.txt\n\nConfig file contents: some settings\n\n// And with a directory\n$ python main.py --config ./\n\nConfig is a directory, will use all its config files\n```\n\n
\n\n## Path validations\n\nYou can perform several validations for `Path` *CLI parameters*:\n\n* `exists`: if set to true, the file or directory needs to exist for this value to be valid. If this is not required and a file does indeed not exist, then all further checks are silently skipped.\n* `file_okay`: controls if a file is a possible value.\n* `dir_okay`: controls if a directory is a possible value.\n* `writable`: if true, a writable check is performed.\n* `readable`: if true, a readable check is performed.\n* `resolve_path`: if this is true, then the path is fully resolved before the value is passed onwards. This means that itโs absolute and symlinks are resolved.\n\n/// note | Technical Details\n\nIt will not expand a tilde-prefix (something with `~`, like `~/Documents/`), as this is supposed to be done by the shell only.\n\n///\n\nFor example:\n\n{* docs_src/parameter_types/path/tutorial002_an_py310.py hl[14:19] *}\n\nCheck it:\n\n\n\n```console\n$ python main.py --config config.txt\n\nUsage: main.py [OPTIONS]\nTry \"main.py --help\" for help.\n\nError: Invalid value for '--config': File 'config.txt' does not exist.\n\n// Now create a quick config\n$ echo \"some settings\" > config.txt\n\n// And try again\n$ python main.py --config config.txt\n\nConfig file contents: some settings\n\n// And with a directory\n$ python main.py --config ./\n\nUsage: main.py [OPTIONS]\nTry \"main.py --help\" for help.\n\nError: Invalid value for '--config': File './' is a directory.\n```\n\n
\n\n### Advanced `Path` configurations\n\n/// warning | Advanced Details\n\nYou probably won't need these configurations at first, you may want to skip it.\n\nThey are used for more advanced use cases.\n\n///\n\n* `allow_dash`: If this is set to True, a single dash to indicate standard streams is permitted.\n* `path_type`: optionally a string type that should be used to represent the path. The default is `None` which means the return value will be either bytes or unicode depending on what makes most sense given the input data.\n"
},
{
"path": "docs/tutorial/parameter-types/uuid.md",
"content": "# UUID\n\n/// info\n\nA UUID is a \"Universally Unique Identifier\".\n\nIt's a standard format for identifiers, like passport numbers, but for anything, not just people in countries.\n\nThey look like this:\n\n```\nd48edaa6-871a-4082-a196-4daab372d4a1\n```\n\nThe way they are generated makes them sufficiently long and random that you could assume that every UUID generated is unique. Even if it was generated by a different application, database, or system.\n\nSo, if your system uses UUIDs to identify your data, you could mix it with the data from some other system that also uses UUIDs with some confidence that their IDs (UUIDs) won't clash with yours.\n\nThis wouldn't be true if you just used `int`s as identifiers, as most databases do.\n\n///\n\nYou can declare a *CLI parameter* as a UUID:\n\n{* docs_src/parameter_types/uuid/tutorial001_py310.py hl[1,9:11] *}\n\nYour 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.\n\nCheck it:\n\n\n\n```console\n// Pass a valid UUID v4\n$ python main.py d48edaa6-871a-4082-a196-4daab372d4a1\n\nUSER_ID is d48edaa6-871a-4082-a196-4daab372d4a1\nUUID version is: 4\n\n// An invalid value\n$ python main.py 7479706572-72756c6573\n\nUsage: main.py [OPTIONS] USER_ID\nTry \"main.py --help\" for help.\n\nError: Invalid value for 'USER_ID': 7479706572-72756c6573 is not a valid UUID.\n```\n\n
\n"
},
{
"path": "docs/tutorial/printing.md",
"content": "# Printing and Colors\n\nYou can use the normal `print()` to show information on the screen:\n\n{* docs_src/typer_app/tutorial001_py310.py hl[8] *}\n\nIt will show the output normally:\n\n\n\n```console\n$ python main.py World\n\nHello World\n```\n\n
\n\n## Use Rich\n\nYou can also display beautiful and more complex information using Rich. It comes by default when you install `typer`.\n\n### Use Rich `print`\n\nFor the simplest cases, you can just import `print` from `rich` and use it instead of the standard `print`:\n\n{* docs_src/printing/tutorial001_py310.py hl[2,18] *}\n\nJust with that, **Rich** will be able to print your data with nice colors and structure:\n\n\n\n```console\n$ python main.py\n\nHere's the data\n{\n 'name': 'Rick',\n 'age': 42,\n 'items': [\n {'name': 'Portal Gun'},\n {'name': 'Plumbus'}\n ],\n 'active': True,\n 'affiliation': None\n}\n```\n\n
\n\n### Rich Markup\n\nRich also supports a custom markup syntax to set colors and styles, for example:\n\n{* docs_src/printing/tutorial002_py310.py hl[9] *}\n\n\n\n```console\n$ python main.py\n\nAlert! Portal gun shooting! ๐ฅ\n```\n\n
\n\nIn this example you can see how to use font styles, colors, and even emojis.\n\nTo learn more check out the Rich docs.\n\n### Rich Tables\n\nThe way Rich works internally is that it uses a `Console` object to display the information.\n\nWhen you call Rich's `print`, it automatically creates this object and uses it.\n\nBut for advanced use cases, you could create a `Console` yourself.\n\n{* docs_src/printing/tutorial003_py310.py hl[2:3,5,12:15] *}\n\nIn this example, we create a `Console`, and a `Table`. And then we can add some rows to the table, and print it.\n\nIf you run it, you will see a nicely formatted table:\n\n\n\n```console\n$ python main.py\n\nโโโโโโโโโณโโโโโโโโโโโโโ\nโ Name โ Item โ\nโกโโโโโโโโโโโโโโโโโโโโโฉ\nโ Rick โ Portal Gun โ\nโ Morty โ Plumbus โ\nโโโโโโโโโดโโโโโโโโโโโโโ\n```\n\n
\n\nRich has many other features, as an example, you can check the docs for:\n\n* Prompt\n* Markdown\n* Panel\n* ...and more.\n\n### Typer and Rich\n\nIf you are wondering what tool should be used for what, **Typer** is useful for structuring the command line application, with options, arguments, subcommands, data validation, etc.\n\nIn general, **Typer** tends to be the entry point to your program, taking the first input from the user.\n\n**Rich** is useful for the parts that need to *display* information. Showing beautiful content on the screen.\n\nThe best results for your command line application are achieved combining both **Typer** and **Rich**.\n\n## \"Standard Output\" and \"Standard Error\"\n\nThe way printing works underneath is that the **operating system** (Linux, Windows, macOS) treats what we print as if our CLI program was **writing text** to a \"**virtual file**\" called \"**standard output**\".\n\nWhen our code \"prints\" things it is actually \"writing\" to this \"virtual file\" of \"standard output\".\n\nThis might seem strange, but that's how the CLI program and the operating system interact with each other.\n\nAnd then the operating system **shows on the screen** whatever our CLI program \"**wrote**\" to that \"**virtual file**\" called \"**standard output**\".\n\n### Standard Error\n\nAnd there's another \"**virtual file**\" called \"**standard error**\" that is normally only used for errors.\n\nBut we can also \"print\" to \"standard error\". And both are shown on the terminal to the users.\n\n/// info\n\nIf you use PowerShell it's quite possible that what you print to \"standard error\" won't be shown in the terminal.\n\nIn PowerShell, to see \"standard error\" you would have to check the variable `$Error`.\n\nBut it will work normally in Bash, Zsh, and Fish.\n\n///\n\n### Printing to \"standard error\"\n\nYou can print to \"standard error\" creating a Rich `Console` with `stderr=True`.\n\n/// tip\n\n`stderr` is short for \"standard error\".\n\n///\n\nUsing `stderr=True` tells **Rich** that the output should be shown in \"standard error\".\n\n{* docs_src/printing/tutorial004_py310.py hl[4,11] *}\n\nWhen you try it in the terminal, it will probably just look the same:\n\n\n\n```console\n$ python main.py\n\nHere is something written to standard error\n```\n\n
\n\n## \"Standard Input\"\n\nAs a final detail, when you type text in your keyboard to your terminal, the operating system also considers it another \"**virtual file**\" that you are writing text to.\n\nThis virtual file is called \"**standard input**\".\n\n### What is this for\n\nRight now this probably seems quite useless ๐คทโโ.\n\nBut understanding that will come handy in the future, for example for autocompletion and testing.\n\n## Typer Echo\n\n/// warning\n\nIn most of the cases, for displaying advanced information, it is recommended to use Rich.\n\nYou can probably skip the rest of this section. ๐๐\n\n///\n\n**Typer** also has a small utility `typer.echo()` to print information on the screen. But normally you shouldn't need it.\n\nFor the simplest cases, you can use the standard Python `print()`.\n\nAnd for the cases where you want to display data more beautifully, or more advanced content, you should use **Rich** instead.\n\n### Why `typer.echo`\n\n`typer.echo()` (which is actually just `click.echo()`) applies some checks to try and convert binary data to strings, and other similar things.\n\nBut in most of the cases you wouldn't need it, as in modern Python strings (`str`) already support and use Unicode, and you would rarely deal with pure `bytes` that you want to print on the screen.\n\nIf you have some `bytes` objects, you would probably want to decode them intentionally and directly before trying to print them.\n\nAnd if you want to print data with colors and other features, you are much better off with the more advanced tools in **Rich**.\n\n### Color\n\n/// note | Technical Details\n\nThe way color works in terminals is by using some codes (ANSI escape sequences) as part of the text.\n\nSo, a colored text is still just a `str`.\n\n///\n\n/// tip\n\nAgain, you are much better off using Rich for this. ๐\n\n///\n\nYou can create colored strings to output to the terminal with `typer.style()`, that gives you `str`s that you can then pass to `typer.echo()`:\n\n{* docs_src/printing/tutorial005_py310.py hl[10,12] *}\n\n/// tip\n\nThe parameters `fg` and `bg` receive strings with the color names for the \"foreground\" and \"background\" colors. You could simply pass `fg=\"green\"` and `bg=\"red\"`.\n\nBut **Typer** provides them all as variables like `typer.colors.GREEN` just so you can use autocompletion while selecting them.\n\n///\n\nCheck it:\n\n\npython main.py\neverything is good\npython main.py --no-good\neverything is bad\n
\n\nYou can pass these function arguments to `typer.style()`:\n\n* `fg`: the foreground color.\n* `bg`: the background color.\n* `bold`: enable or disable bold mode.\n* `dim`: enable or disable dim mode. This is badly supported.\n* `underline`: enable or disable underline.\n* `blink`: enable or disable blinking.\n* `reverse`: enable or disable inverse rendering (foreground becomes background and the other way round).\n* `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.\n\n### `typer.secho()` - style and print\n\n/// tip\n\nIn case you didn't see above, you are much better off using Rich for this. ๐\n\n///\n\nThere's a shorter form to style and print at the same time with `typer.secho()` it's like `typer.echo()` but also adds style like `typer.style()`:\n\n{* docs_src/printing/tutorial006_py310.py hl[8] *}\n\nCheck it:\n\n\npython main.py Camila\nWelcome here Camila\n
\n"
},
{
"path": "docs/tutorial/progressbar.md",
"content": "# Progress Bar\n\nIf you are executing an operation that can take some time, you can inform it to the user. ๐ค\n\n## Progress Bar\n\nYou can use Rich's Progress Display to show a progress bar, for example:\n\n{* docs_src/progressbar/tutorial001_py310.py hl[4,12] *}\n\nYou put the thing that you want to iterate over inside of Rich's `track()`, and then iterate over that.\n\nCheck it:\n\n\n\n```console\n$ python main.py\n\n---> 100%\n\nProcessed 100 things.\n```\n\n
\n\n...actually, it will look a lot prettier. โจ But I can't show you the animation here in the docs. ๐
\n\nThe colors and information will look something like this:\n\n\n\n```console\n$ python main.py\n\nProcessing... โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโธโโโโโโโโโโ 74% 0:00:01\n```\n\n
\n\n## Spinner\n\nWhen you don't know how long the operation will take, you can use a spinner instead.\n\nRich allows you to display many things in complex and advanced ways.\n\nFor example, this will show two spinners:\n\n{* docs_src/progressbar/tutorial002_py310.py hl[4,11:18] *}\n\nI can't show you the beautiful animation here in the docs. ๐
\n\nBut at some point in time it will look like this (imagine it's spinning). ๐ค\n\n\n\n```console\n$ python main.py\n\nโ น Processing...\nโ น Preparing...\n```\n\n
\n\nYou can learn more about it in the Rich docs for Progress Display.\n\n## Typer `progressbar`\n\nIf you can, you should use **Rich** as explained above, it has more features, it's more advanced, and can display information more beautifully. โจ\n\n/// tip\n\nIf you can use Rich, use the information above, the Rich docs, and skip the rest of this page. ๐\n\n///\n\nBut if you can't use Rich and have it disabled, Typer comes with a simple utility to show progress bars.\n\n### Use `typer.progressbar`\n\n/// tip\n\nRemember, you are much better off using Rich for this. ๐\n\n///\n\nYou can use `typer.progressbar()` with a `with` statement, as in:\n\n```Python\nwith typer.progressbar(something) as progress:\n pass\n```\n\nAnd you pass as function argument to `typer.progressbar()` the thing that you would normally iterate over.\n\n{* docs_src/progressbar/tutorial003_py310.py hl[11] *}\n\nSo, if you have a list of users, this could be:\n\n```Python\nusers = [\"Camila\", \"Rick\", \"Morty\"]\n\nwith typer.progressbar(users) as progress:\n pass\n```\n\nAnd the `with` statement using `typer.progressbar()` gives you an object that you can iterate over, just like if it was the same thing that you would iterate over normally.\n\nBut by iterating over this object **Typer** will know to update the progress bar:\n\n```Python\nusers = [\"Camila\", \"Rick\", \"Morty\"]\n\nwith typer.progressbar(users) as progress:\n for user in progress:\n typer.echo(user)\n```\n\n/// tip\n\nNotice that there are 2 levels of code blocks. One for the `with` statement and one for the `for` statement.\n\n///\n\n/// info\n\nThis is mostly useful for operations that take some time.\n\nIn the example above we are faking it with `time.sleep()`.\n\n///\n\nCheck it:\n\n\n\n```console\n$ python main.py\n\n---> 100%\n\nProcessed 100 things.\n```\n\n
\n\n### Setting a Progress Bar `length`\n\n/// tip\n\nRemember, you are much better off using Rich for this. ๐\n\n///\n\nThe progress bar is generated from the length of the iterable (e.g. the list of users).\n\nBut if the length is not available (for example, with something that fetches a new user from a web API each time) you can pass an explicit `length` to `typer.progressbar()`.\n\n{* docs_src/progressbar/tutorial004_py310.py hl[18] *}\n\nCheck it:\n\n\n\n```console\n$ python main.py\n\n---> 100%\n\nProcessed 100 user IDs.\n```\n\n
\n\n#### About the function with `yield`\n\nIf you hadn't seen something like that `yield` above, that's a \"generator\".\n\nYou can iterate over that function with a `for` and at each iteration it will give you the value at `yield`.\n\n`yield` is like a `return` that gives values multiple times and let's you use the function in a `for` loop.\n\nFor example:\n\n```Python\ndef iterate_user_ids():\n # Let's imagine this is a web API, not a range()\n for i in range(100):\n yield i\n\nfor i in iterate_user_ids():\n print(i)\n```\n\nwould print each of the \"user IDs\" (here it's just the numbers from `0` to `99`).\n\n### Add a `label`\n\n/// tip\n\nRemember, you are much better off using Rich for this. ๐\n\n///\n\nYou can also set a `label`:\n\n{* docs_src/progressbar/tutorial005_py310.py hl[11] *}\n\nCheck it:\n\n\npython main.py\n\nProcessed 100 things.\n
\n\n## Iterate manually\n\nIf you need to manually iterate over something and update the progress bar irregularly, you can do it by not passing an iterable but just a `length` to `typer.progressbar()`.\n\nAnd then calling the `.update()` method in the object from the `with` statement:\n\n{* docs_src/progressbar/tutorial006_py310.py hl[11,17] *}\n\nCheck it:\n\n\npython main.py\n\nProcessed 1000 things in batches.\n
\n"
},
{
"path": "docs/tutorial/prompt.md",
"content": "# Ask with Prompt\n\nWhen you need to ask the user for info interactively you should normally use [*CLI Option*s with Prompt](options/prompt.md){.internal-link target=_blank}, because they allow using the CLI program in a non-interactive way (for example, a Bash script could use it).\n\nBut if you absolutely need to ask for interactive information without using a *CLI option*, you can use `typer.prompt()`:\n\n{* docs_src/prompt/tutorial001_py310.py hl[8] *}\n\nCheck it:\n\n\n\n```console\n$ python main.py\n\n# What's your name?:$ Camila\n\nHello Camila\n```\n\n
\n\n## Confirm\n\nThere's also an alternative to ask for confirmation. Again, if possible, you should use a [*CLI Option* with a confirmation prompt](options/prompt.md){.internal-link target=_blank}:\n\n{* docs_src/prompt/tutorial002_py310.py hl[8] *}\n\nCheck it:\n\n\n\n```console\n$ python main.py\n\n# Are you sure you want to delete it? [y/N]:$ y\n\nDeleting it!\n\n// This time cancel it\n$ python main.py\n\n# Are you sure you want to delete it? [y/N]:$ n\n\nNot deleting\nAborted!\n```\n\n
\n\n## Confirm or abort\n\nAs it's very common to abort if the user doesn't confirm, there's an integrated parameter `abort` that does it automatically:\n\n{* docs_src/prompt/tutorial003_py310.py hl[8] *}\n\n\n\n```console\n$ python main.py\n\n# Are you sure you want to delete it? [y/N]:$ y\n\nDeleting it!\n\n// This time cancel it\n$ python main.py\n\n# Are you sure you want to delete it? [y/N]:$ n\n\nAborted!\n```\n\n
\n\n## Prompt with Rich\n\nYou can use Rich to prompt the user for input:\n\n{* docs_src/prompt/tutorial004_py310.py hl[2,9] *}\n\nAnd when you run it, it will look like:\n\n\n\n```console\n$ python main.py\n\n# Enter your name ๐:$ Morty\n\nHello Morty\n```\n\n
\n"
},
{
"path": "docs/tutorial/subcommands/add-typer.md",
"content": "# Add Typer\n\nWe'll start with the core idea.\n\nTo add a `typer.Typer()` app inside of another.\n\n## Manage items\n\nLet's imagine that you are creating a *CLI program* to manage items in some distant land.\n\nIt could be in an `items.py` file with this:\n\n{* docs_src/subcommands/tutorial001_py310/items.py *}\n\nAnd you would use it like:\n\n\n\n```console\n$ python items.py create Wand\n\nCreating item: Wand\n```\n\n
\n\n## Manage users\n\nBut then you realize that you also have to manage users from your *CLI app*.\n\nIt could be a file `users.py` with something like:\n\n{* docs_src/subcommands/tutorial001_py310/users.py *}\n\nAnd you would use it like:\n\n\n\n```console\n$ python users.py create Camila\n\nCreating user: Camila\n```\n\n
\n\n## Put them together\n\nBoth parts are similar. In fact, `items.py` and `users.py` both have commands `create` and `delete`.\n\nBut we need them to be part of the same *CLI program*.\n\nIn this case, as with `git remote`, we can put them together as subcommands in another `typer.Typer()` *CLI program*.\n\nNow create a `main.py` with:\n\n{* docs_src/subcommands/tutorial001_py310/main.py hl[3,4,7,8] *}\n\nHere's what we do in `main.py`:\n\n* Import the other Python modules (the files `users.py` and `items.py`).\n* Create the main `typer.Typer()` application.\n* Use `app.add_typer()` to include the `app` from `items.py` and `users.py`, each of those 2 was also created with `typer.Typer()`.\n* Define a `name` with the command that will be used for each of these \"sub-Typers\" to group their own commands.\n\nAnd now your *CLI program* has 2 commands:\n\n* `users`: with all of the commands (subcommands) in the `app` from `users.py`.\n* `items` with all the commands (subcommands) in the `app` from `items.py`.\n\nCheck it:\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n items\n users\n```\n\n
\n\nNow you have a *CLI program* with commands `items` and `users`, and they in turn have their own commands (subcommands).\n\nLet's check the `items` command:\n\n\n\n```console\n// Check the help for items\n$ python main.py items --help\n\n// It shows its own commands (subcommands): create, delete, sell\nUsage: main.py items [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n create\n delete\n sell\n\n// Try it\n$ python main.py items create Wand\n\nCreating item: Wand\n\n$ python main.py items sell Vase\n\nSelling item: Vase\n```\n\n
\n\n/// tip\n\nNotice that we are still calling `$ python main.py` but now we are using the command `items`.\n\n///\n\nAnd now check the command `users`, with all its subcommands:\n\n\n\n```console\n$ python main.py users --help\n\nUsage: main.py users [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n create\n delete\n\n// Try it\n$ python main.py users create Camila\n\nCreating user: Camila\n```\n\n
\n\n## Recap\n\nThat's the core idea.\n\nYou can just create `typer.Typer()` apps and add them inside one another.\n\nAnd you can do that with any levels of commands that you want.\n\nDo you need sub-sub-sub-subcommands? Go ahead, create all the `typer.Typer()`s you need and put them together with `app.add_typer()`.\n\nIn the next sections we'll update this with more features, but you already have the core idea.\n\nThis way, **Typer** applications are composable, each `typer.Typer()` can be a *CLI app* by itself, but it can also be added as a command group to another Typer app.\n"
},
{
"path": "docs/tutorial/subcommands/callback-override.md",
"content": "# Sub-Typer Callback Override\n\nWhen creating a **Typer** app you can define a callback function, it always executes and defines the *CLI arguments* and *CLI options* that go before a command.\n\nWhen adding a Typer app inside of another, the sub-Typer can also have its own callback.\n\nIt can handle any *CLI parameters* that go before its own commands and execute any extra code:\n\n{* docs_src/subcommands/callback_override/tutorial001_py310.py hl[9,10,11] *}\n\nIn this case it doesn't define any *CLI parameters*, it just writes a message.\n\nCheck it:\n\n\n\n```console\n$ python main.py users create Camila\n\n// Notice the first message is not created by the command function but by the callback\nRunning a users command\nCreating user: Camila\n```\n\n
\n\n## Add a callback on creation\n\nIt's also possible to add a callback when creating the `typer.Typer()` app that will be added to another Typer app:\n\n{* docs_src/subcommands/callback_override/tutorial002_py310.py hl[6,7,10] *}\n\nThis achieves exactly the same as above, it's just another place to add the callback.\n\nCheck it:\n\n\n\n```console\n$ python main.py users create Camila\n\nRunning a users command\nCreating user: Camila\n```\n\n
\n\n## Overriding the callback on creation\n\nIf a callback was added when creating the `typer.Typer()` app, it's possible to override it with a new one using `@app.callback()`.\n\nThis is the same information you saw on the section about [Commands - Typer Callback](../commands/callback.md){.internal-link target=_blank}, and it applies the same for sub-Typer apps:\n\n{* docs_src/subcommands/callback_override/tutorial003_py310.py hl[6,7,10,14,15,16] *}\n\nHere we had defined a callback when creating the `typer.Typer()` sub-app, but then we override it with a new callback with the function `user_callback()`.\n\nAs `@app.callback()` takes precedence over `typer.Typer(callback=some_function)`, now our CLI app will use this new callback.\n\nCheck it:\n\n\n\n```console\n$ python main.py users create Camila\n\n// Notice the message from the new callback\nCallback override, running users command\nCreating user: Camila\n```\n\n
\n\n## Overriding the callback when adding a sub-Typer\n\nLastly, you can override the callback defined anywhere else when adding a sub-Typer with `app.add_typer()` using the `callback` parameter.\n\nThis has the highest priority:\n\n{* docs_src/subcommands/callback_override/tutorial004_py310.py hl[13,14,17] *}\n\nNotice that the precedence goes to `app.add_typer()` and is not affected by the order of execution. There's another callback defined below, but the one from `app.add_typer()` wins.\n\nNow when you use the CLI program it will use the new callback function `callback_for_add_typer()`.\n\nCheck it:\n\n\n\n```console\n$ python users create Camila\n\n// Notice the message from the callback added in add_typer()\nI have the high land! Running users command\nCreating user: Camila\n```\n\n
\n"
},
{
"path": "docs/tutorial/subcommands/index.md",
"content": "# SubCommands - Command Groups\n\nYou read before how to create a program with [Commands](../commands/index.md){.internal-link target=_blank}.\n\nNow we'll see how to create a *CLI program* with commands that have their own subcommands. Also known as command groups.\n\nFor example, the *CLI program* `git` has a command `remote`.\n\nBut `git remote`, in turn, has its own subcommands, like `add`:\n\n\n\n```console\n// git remote alone shows the current remote repositories\n$ git remote\n\norigin\n\n// Use -v to make it verbose and show more info\n$ git remote -v\n\norigin git@github.com:yourusername/typer.git (fetch)\norigin git@github.com:yourusername/typer.git (push)\n\n// git remote add takes 2 CLI arguments, a name and URL\n$ git remote add upstream https://github.com/fastapi/typer.git\n\n// Doesn't output anything, but now you have another remote repository called upstream\n\n// Now check again\n$ git remote -v\n\norigin git@github.com:yourusername/typer.git (fetch)\norigin git@github.com:yourusername/typer.git (push)\nupstream https://github.com/fastapi/typer.git (fetch)\nupstream https://github.com/fastapi/typer.git (push)\n```\n\n
\n\nIn the next sections we'll see how to create subcommands like these.\n"
},
{
"path": "docs/tutorial/subcommands/name-and-help.md",
"content": "# SubCommand Name and Help\n\nWhen adding a Typer app to another we have seen how to set the `name` to use for the command.\n\nFor example to set the command to `users`:\n\n```Python\napp.add_typer(users.app, name=\"users\")\n```\n\n## Add a help text\n\nWe can also set the `help` text while adding a Typer:\n\n{* docs_src/subcommands/name_help/tutorial001_py310.py hl[6] *}\n\nAnd then we get that help text for that command in the *CLI program*:\n\n\n\n```console\n// Check the main help\n$ python main.py --help\n\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n users Manage users in the app.\n\n// Check the help for the users command\n$ python main.py users --help\n\nUsage: main.py users [OPTIONS] COMMAND [ARGS]...\n\n Manage users in the app.\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n create\n```\n\n
\n\nWe can set the `help` in several places, each one taking precedence over the other, overriding the previous value.\n\nLet's see those locations.\n\n/// tip\n\nThere are other attributes that can be set in that same way in the same places we'll see next.\n\nBut those are documented later in another section.\n\n///\n\n## Inferring help text from callback\n\n### Inferring a command's help text\n\nWhen you create a command with `@app.command()`, by default, it generates the name from the function name.\n\nAnd by default, the help text is extracted from the function's docstring.\n\nFor example:\n\n```Python\n@app.command()\ndef create(item: str):\n \"\"\"\n Create an item.\n \"\"\"\n typer.echo(f\"Creating item: {item}\")\n```\n\n...will create a command `create` with a help text of `Create an item`.\n\n### Inferring the help text from `@app.callback()`\n\nThe same way, if you define a callback in a `typer.Typer()`, the help text is extracted from the callback function's docstring.\n\nHere's an example:\n\n{* docs_src/subcommands/name_help/tutorial002_py310.py hl[9,10,11,12,13] *}\n\nThe help text for that command will be the callback function's docstring: `Manage users in the app.`.\n\nCheck it:\n\n\n\n```console\n// Check the main help\n$ python main.py --help\n\n// Notice the help text \"Manage users in the app.\"\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n users Manage users in the app.\n\n// Check the help for the users command\n$ python main.py users --help\n\n// Notice the main description: \"Manage users in the app.\"\nUsage: main.py users [OPTIONS] COMMAND [ARGS]...\n\n Manage users in the app.\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n create\n```\n\n
\n\n/// note\n\nBefore Typer 0.14.0, in addition to the help text, the command name was also inferred from the callback function name, this is no longer the case.\n\n///\n\n### Help from callback parameter in `typer.Typer()`\n\nIf you pass a `callback` parameter while creating a `typer.Typer(callback=some_function)` it will be used to infer the help text.\n\nThis has the lowest priority, we'll see later what has a higher priority and can override it.\n\nCheck the code:\n\n{* docs_src/subcommands/name_help/tutorial003_py310.py hl[6,7,8,9,12] *}\n\nThis achieves exactly the same as the previous example.\n\nCheck it:\n\n\n\n```console\n// Check the main help\n$ python main.py --help\n\n// Notice the help text \"Manage users in the app.\"\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n users Manage users in the app.\n\n// Check the help for the users command\n$ python main.py users --help\n\n// Notice the main description: \"Manage users in the app.\"\nUsage: main.py users [OPTIONS] COMMAND [ARGS]...\n\n Manage users in the app.\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n create\n```\n\n
\n\n### Override a callback set in `typer.Typer()` with `@app.callback()`\n\nThe same as with normal **Typer** apps, if you pass a `callback` to `typer.Typer(callback=some_function)` and then override it with `@app.callback()`, the help text will be inferred from the new callback:\n\n{* docs_src/subcommands/name_help/tutorial004_py310.py hl[16,17,18,19,20] *}\n\nNow the help text will be `Manage users in the app.` instead of `Old callback help.`.\n\nCheck it:\n\n\n\n```console\n// Check the main help\n$ python main.py --help\n\n// Notice the help text \"Manage users in the app.\"\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n users Manage users in the app.\n\n// Check the help for the users command\n$ python main.py users --help\n\n// Notice the main description: \"Manage users in the app.\"\nUsage: main.py users [OPTIONS] COMMAND [ARGS]...\n\n Manage users in the app.\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n create\n```\n\n
\n\n### Help from callback in `app.add_typer()`\n\nIf you override the callback in `app.add_typer()` when including a sub-app, the help will be inferred from this callback function.\n\nThis takes precedence over inferring the help from a callback set in `@sub_app.callback()` and `typer.Typer(callback=sub_app_callback)`.\n\nCheck the code:\n\n{* docs_src/subcommands/name_help/tutorial005_py310.py hl[15,16,17,18,21] *}\n\nThe help text will be `I have the highland! Create some users.` instead of the previous ones.\n\nCheck it:\n\n\n\n```console\n// Check the main help\n$ python main.py --help\n\n// Check the command new-users and its help text\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n new-users I have the highland! Create some users.\n\n// Now check the help for the new-users command\n$ python main.py new-users --help\n\n// Notice the help text\nUsage: main.py new-users [OPTIONS] COMMAND [ARGS]...\n\n I have the highland! Create some users.\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n create\n```\n\n
\n\n### Enough inferring\n\nSo, when inferring help text, the precedence order from lowest priority to highest is:\n\n* `sub_app = typer.Typer(callback=some_function)`\n* `@sub_app.callback()`\n* `app.add_typer(sub_app, callback=new_function)`\n\nThat's for inferring the help text from functions.\n\nBut if you set the help text explicitly, that has a higher priority than these.\n\n## Set the name and help\n\nLet's now see the places where you can set the command name and help text, from lowest priority to highest.\n\n/// tip\n\nSetting the help text explicitly always has a higher precedence than inferring from a callback function.\n\n///\n\n### Name and help in `typer.Typer()`\n\nYou could have all the callbacks and overrides we defined before, but the help text was inferred from the function docstring.\n\nIf you set it explicitly, that takes precedence over inferring.\n\nYou can set it when creating a new `typer.Typer()`:\n\n{* docs_src/subcommands/name_help/tutorial006_py310.py hl[12] *}\n\n/// info\n\nThe rest of the callbacks and overrides are there only to show you that they don't affect the name and help text when you set it explicitly.\n\n///\n\nWe set an explicit help `Explicit help.`.\n\nSo that will take precedence now.\n\nCheck it:\n\n\n\n```console\n// Check the main help\n$ python main.py --help\n\n// Notice the command name is exp-users and the help text is \"Explicit help.\"\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n exp-users Explicit help.\n\n// Check the help for the exp-users command\n$ python main.py exp-users --help\n\n// Notice the main help text\nUsage: main.py exp-users [OPTIONS] COMMAND [ARGS]...\n\n Explicit help.\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n create\n```\n\n
\n\n### Help text in `@app.callback()`\n\nMany parameters that you use when creating a `typer.Typer()` app can be overridden in the parameters of `@app.callback()`.\n\nContinuing with the previous example, we now override the `help` in `@user_app.callback()`:\n\n{* docs_src/subcommands/name_help/tutorial007_py310.py hl[24] *}\n\nAnd now the help text will be `Help from callback for users.`.\n\nCheck it:\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\n// The help text is now \"Help from callback for users.\".\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n users Help from callback for users.\n\n// Check the users command help\n$ python main.py users --help\n\n// Notice the main help text\nUsage: main.py users [OPTIONS] COMMAND [ARGS]...\n\n Help from callback for users.\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n create\n```\n\n
\n\n### Name and help in `app.add_typer()`\n\nAnd finally, with the highest priority, you can override all that by explicitly setting the `name` and `help` in `app.add_typer()`, just like we did on the first example above:\n\n{* docs_src/subcommands/name_help/tutorial008_py310.py hl[21] *}\n\nAnd now, with the highest priorities of them all, the command name will now be `cake-sith-users` and the help text will be `Unlimited powder! Eh, users.`.\n\nCheck it:\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\n// Notice the command name cake-sith-users and the new help text \"Unlimited powder! Eh, users.\"\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n cake-sith-users Unlimited powder! Eh, users.\n\n// And check the help for the command cake-sith-users\n$ python main.py cake-sith-users --help\n\n// Notice the main help text\nUsage: main.py cake-sith-users [OPTIONS] COMMAND [ARGS]...\n\n Unlimited powder! Eh, users.\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n create\n```\n\n
\n\n## Recap\n\nThe precedence to generate a command's **help**, from lowest priority to highest, is:\n\n* Implicitly inferred from `sub_app = typer.Typer(callback=some_function)`\n* Implicitly inferred from the callback function under `@sub_app.callback()`\n* Implicitly inferred from `app.add_typer(sub_app, callback=some_function)`\n* Explicitly set on `sub_app = typer.Typer(help=\"Some help.\")`\n* Explicitly set on `app.add_typer(sub_app, help=\"Some help.\")`\n\nAnd the priority to set the command's **name**, from lowest priority to highest, is:\n\n* Explicitly set on `sub_app = typer.Typer(name=\"some-name\")`\n* Explicitly set on `app.add_typer(sub_app, name=\"some-name\")`\n\nSo, `app.add_typer(sub_app, name=\"some-name\", help=\"Some help.\")` always wins.\n"
},
{
"path": "docs/tutorial/subcommands/nested-subcommands.md",
"content": "# Nested SubCommands\n\nWe'll now see how these same ideas can be extended for deeply nested commands.\n\nLet's imagine that the same *CLI program* from the previous examples now needs to handle `lands`.\n\nBut a land could be a `reign` or `town`.\n\nAnd each of those could have their own commands, like `create` and `delete`.\n\n## A CLI app for reigns\n\nLet's start with a file `reigns.py`:\n\n{* docs_src/subcommands/tutorial003_py310/reigns.py *}\n\nThis is already a simple *CLI program* to manage reigns:\n\n\n\n```console\n// Check the help\n$ python reigns.py --help\n\nUsage: reigns.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n conquer\n destroy\n\n// Try it\n$ python reigns.py conquer Cintra\n\nConquering reign: Cintra\n\n$ python reigns.py destroy Mordor\n\nDestroying reign: Mordor\n```\n\n
\n\n## A CLI app for towns\n\nAnd now the equivalent for managing towns in `towns.py`:\n\n{* docs_src/subcommands/tutorial003_py310/towns.py *}\n\nWith it, you can manage towns:\n\n\n\n```console\n// Check the help\n$ python towns.py --help\n\nUsage: towns.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n burn\n found\n\n// Try it\n$ python towns.py found \"New Asgard\"\n\nFounding town: New Asgard\n\n$ python towns.py burn Vizima\n\nBurning town: Vizima\n```\n\n
\n\n## Manage the land in a CLI app\n\nNow let's put the `reigns` and `towns` together in the same *CLI program* in `lands.py`:\n\n{* docs_src/subcommands/tutorial003_py310/lands.py *}\n\nAnd now we have a single *CLI program* with a command (or command group) `reigns` that has its own commands. And another command `towns` with its own subcommands.\n\nCheck it:\n\n\n\n```console\n// Check the help\n$ python lands.py --help\n\nUsage: lands.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n reigns\n towns\n\n// We still have the help for reigns\n$ python lands.py reigns --help\n\nUsage: lands.py reigns [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n conquer\n destroy\n\n// And the help for towns\n$ python lands.py towns --help\n\nUsage: lands.py towns [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n burn\n found\n```\n\n
\n\nNow try it, manage the lands through the CLI:\n\n\n\n```console\n// Try the reigns command\n$ python lands.py reigns conquer Gondor\n\nConquering reign: Gondor\n\n$ python lands.py reigns destroy Nilfgaard\n\nDestroying reign: Nilfgaard\n\n// Try the towns command\n$ python lands.py towns found Springfield\n\nFounding town: Springfield\n\n$ python lands.py towns burn Atlantis\n\nBurning town: Atlantis\n```\n\n
\n\n## Deeply nested subcommands\n\nNow let's say that all these commands in the `lands.py` *CLI program* should be part of the previous *CLI program* we built in the first example.\n\nWe want our *CLI program* to have these commands/command groups:\n\n* `users`:\n * `create`\n * `delete`\n* `items`:\n * `create`\n * `delete`\n * `sell`\n* `lands`:\n * `reigns`:\n * `conquer`\n * `destroy`\n * `towns`:\n * `found`\n * `burn`\n\nThis already is a quite deeply nested \"tree\" of commands/command groups.\n\nBut to achieve that, we just have to add the `lands` **Typer** app to the same `main.py` file we already had:\n\n{* docs_src/subcommands/tutorial003_py310/main.py hl[4,10] *}\n\nAnd now we have everything in a single *CLI program*:\n\n\n\n```console\n// Check the main help\n$ python main.py --help\n\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n items\n lands\n users\n\n// Try some users commands\n$ python main.py users create Camila\n\nCreating user: Camila\n\n// Now try some items commands\n$ python main.py items create Sword\n\nCreating item: Sword\n\n// And now some lands commands for reigns\n$ python main.py lands reigns conquer Gondor\n\nConquering reign: Gondor\n\n// And for towns\n$ python main.py lands towns found Cartagena\n\nFounding town: Cartagena\n```\n\n
\n\n## Review the files\n\nHere are all the files if you want to review/copy them:\n\n`reigns.py`:\n\n{* docs_src/subcommands/tutorial003_py310/reigns.py *}\n\n`towns.py`:\n\n{* docs_src/subcommands/tutorial003_py310/towns.py *}\n\n`lands.py`:\n\n{* docs_src/subcommands/tutorial003_py310/lands.py *}\n\n`users.py`:\n\n{* docs_src/subcommands/tutorial003_py310/users.py *}\n\n`items.py`:\n\n{* docs_src/subcommands/tutorial003_py310/items.py *}\n\n`main.py`:\n\n{* docs_src/subcommands/tutorial003_py310/main.py *}\n\n/// tip\n\nAll these files have an `if __name__ == \"__main__\"` block just to demonstrate how each of them can also be an independent *CLI app*.\n\nBut for your final application, only `main.py` would need it.\n\n///\n\n## Recap\n\nThat's it, you can just add **Typer** applications one inside another as much as you want and create complex *CLI programs* while writing simple code.\n\nYou can probably achieve a simpler *CLI program* design that's easier to use than the example here. But if your requirements are complex, **Typer** helps you build your *CLI app* easily.\n\n/// tip\n\nAuto completion helps a lot, specially with complex programs.\n\nCheck the docs about adding auto completion to your *CLI apps*.\n\n///\n"
},
{
"path": "docs/tutorial/subcommands/single-file.md",
"content": "# SubCommands in a Single File\n\nIn some cases, it's possible that your application code needs to live on a single file.\n\nYou can still use the same ideas:\n\n{* docs_src/subcommands/tutorial002_py310/main.py *}\n\nThere are several things to notice here...\n\n## Apps at the top\n\nFirst, you can create `typer.Typer()` objects and add them to another one at the top.\n\nIt doesn't have to be done after creating the subcommands:\n\n{* docs_src/subcommands/tutorial002_py310/main.py hl[4,5,6,7] *}\n\nYou can add the commands (subcommands) to each `typer.Typer()` app later and it will still work.\n\n## Function names\n\nAs you now have subcommands like `create` for `users` and for `items`, you can no longer call the functions with just the name, like `def create()`, because they would overwrite each other.\n\nSo we use longer names:\n\n{* docs_src/subcommands/tutorial002_py310/main.py hl[11,16,21,26,31] *}\n\n## Command name\n\nWe are naming the functions with longer names so that they don't overwrite each other.\n\nBut we still want the subcommands to be `create`, `delete`, etc.\n\nTo call them like:\n\n\n\n```console\n// We want this โ๏ธ\n$ python main.py items create\n```\n\n
\n\ninstead of:\n\n\n\n```console\n// We don't want this โ๏ธ\n$ python main.py items items-create\n```\n\n
\n\nSo we pass the name we want to use for each subcommand as the function argument to the decorator:\n\n{* docs_src/subcommands/tutorial002_py310/main.py hl[10,15,20,25,30] *}\n\n## Check it\n\nIt still works the same:\n\n\n\n\n```console\n// Check the help\n$ python main.py --help\n\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or\n customize the installation.\n --help Show this message and exit.\n\nCommands:\n items\n users\n```\n\n
\n\nCheck the `items` command:\n\n\n\n\n```console\n// Check the help for items\n$ python main.py items --help\n\n// It shows its own commands (subcommands): create, delete, sell\nUsage: main.py items [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n create\n delete\n sell\n\n// Try it\n$ python main.py items create Wand\n\nCreating item: Wand\n\n$ python main.py items sell Vase\n\nSelling item: Vase\n```\n\n
\n\nAnd the same for the `users` command:\n\n\n\n\n```console\n$ python main.py users --help\n\nUsage: main.py users [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n create\n delete\n\n// Try it\n$ python main.py users create Camila\n\nCreating user: Camila\n```\n\n
\n"
},
{
"path": "docs/tutorial/terminating.md",
"content": "# Terminating\n\nThere are some cases where you might want to terminate a command at some point, and stop all subsequent execution.\n\nIt could be that your code determined that the program completed successfully, or it could be an operation aborted.\n\n## `Exit` a CLI program\n\nYou can normally just let the code of your CLI program finish its execution, but in some scenarios, you might want to terminate at some point in the middle of it. And prevent any subsequent code to run.\n\nThis doesn't have to mean that there's an error, just that nothing else needs to be executed.\n\nIn that case, you can raise a `typer.Exit()` exception:\n\n{* docs_src/terminating/tutorial001_py310.py hl[9] *}\n\nThere are several things to see in this example.\n\n* The CLI program is the function `main()`, not the others. This is the one that takes a *CLI argument*.\n* The function `maybe_create_user()` can terminate the program by raising `typer.Exit()`.\n* If the program is terminated by `maybe_create_user()` then `send_new_user_notification()` will never execute inside of `main()`.\n\nCheck it:\n\n\n\n```console\n$ python main.py Camila\n\nUser created: Camila\nNotification sent for new user: Camila\n\n// Try with an existing user\n$ python main.py rick\n\nThe user already exists\n\n// Notice that the notification code was never run, the second message is not printed\n```\n\n
\n\n/// tip\n\nEven though you are raising an exception, it doesn't necessarily mean there's an error.\n\nThis is done with an exception because it works as an \"error\" and stops all execution.\n\nBut then **Typer** catches it and just terminates the program normally.\n\n///\n\n## Exit with an error\n\n`typer.Exit()` takes an optional `code` parameter. By default, `code` is `0`, meaning there was no error.\n\nYou can pass a `code` with a number other than `0` to tell the terminal that there was an error in the execution of the program:\n\n{* docs_src/terminating/tutorial002_py310.py hl[10] *}\n\nCheck it:\n\n\n\n```console\n$ python main.py Camila\n\nNew user created: Camila\n\n// Print the result code of the last program executed\n$ echo $?\n\n0\n\n// Now make it exit with an error\n$ python main.py root\n\nThe root user is reserved\n\n// Print the result code of the last program executed\n$ echo $?\n\n1\n\n// 1 means there was an error, 0 means no errors.\n```\n\n
\n\n/// tip\n\nThe error code might be used by other programs (for example a Bash script) that execute your CLI program.\n\n///\n\n## Abort\n\nThere's a special exception that you can use to \"abort\" a program.\n\nIt works more or less the same as `typer.Exit()` but will print `\"Aborted!\"` to the screen and can be useful in certain cases later to make it explicit that the execution was aborted:\n\n{* docs_src/terminating/tutorial003_py310.py hl[10] *}\n\nCheck it:\n\n\n\n```console\n$ python main.py Camila\n\nNew user created: Camila\n\n// Now make it exit with an error\n$ python main.py root\n\nThe root user is reserved\nAborted!\n```\n\n
\n"
},
{
"path": "docs/tutorial/testing.md",
"content": "# Testing\n\nTesting **Typer** applications is very easy with pytest.\n\nLet's say you have an application `app/main.py` with:\n\n{* docs_src/testing/app01_py310/main.py *}\n\nSo, you would use it like:\n\n\n\n```console\n$ python main.py Camila --city Berlin\n\nHello Camila\nLet's have a coffee in Berlin\n```\n\n
\n\nAnd the directory also has an empty `app/__init__.py` file.\n\nSo, the `app` is a \"Python package\".\n\n## Test the app\n\n### Import and create a `CliRunner`\n\nCreate another file/module `app/test_main.py`.\n\nImport `CliRunner` and create a `runner` object.\n\nThis runner is what will \"invoke\" or \"call\" your command line application.\n\n{* docs_src/testing/app01_py310/test_main.py hl[1,5] *}\n\n/// tip\n\nIt's important that the name of the file starts with `test_`, that way pytest will be able to detect it and use it automatically.\n\n///\n\n### Call the app\n\nThen create a function `test_app()`.\n\nAnd inside of the function, use the `runner` to `invoke` the application.\n\nThe first parameter to `runner.invoke()` is a `Typer` app.\n\nThe second parameter is a `list` of `str`, with all the text you would pass in the command line, right as you would pass it:\n\n{* docs_src/testing/app01_py310/test_main.py hl[8,9] *}\n\n/// tip\n\nThe name of the function has to start with `test_`, that way pytest can detect it and use it automatically.\n\n///\n\n### Check the result\n\nThen, inside of the test function, add `assert` statements to ensure that everything in the result of the call is as it should be.\n\n{* docs_src/testing/app01_py310/test_main.py hl[10,11,12] *}\n\nHere we are checking that the exit code is 0, as it is for programs that exit without errors.\n\nThen we check that the text printed to \"standard output\" contains the text that our CLI program prints.\n\n/// tip\n\nYou could also check the output sent to \"standard error\" (`stderr`) or \"standard output\" (`stdout`) independently by accessing `result.stdout` and `result.stderr` in your tests.\n\n///\n\n/// info\n\nIf you need a refresher about what is \"standard output\" and \"standard error\" check the section in [Printing and Colors: \"Standard Output\" and \"Standard Error\"](printing.md#standard-output-and-standard-error){.internal-link target=_blank}.\n\n///\n\n### Call `pytest`\n\nThen you can call `pytest` in your directory and it will run your tests:\n\n\n\n```console\n$ pytest\n\n================ test session starts ================\nplatform linux -- Python 3.10, pytest-5.3.5, py-1.8.1, pluggy-0.13.1\nrootdir: /home/user/code/superawesome-cli/app\nplugins: forked-1.1.3, xdist-1.31.0, cov-2.8.1\ncollected 1 item\n\n---> 100%\n\ntest_main.py . [100%]\n\n================= 1 passed in 0.03s =================\n```\n\n
\n\n## Testing input\n\nIf you have a CLI with prompts, like:\n\n{* docs_src/testing/app02_an_py310/main.py hl[9] *}\n\nThat you would use like:\n\n\n\n```console\n$ python main.py Camila\n\n# Email: $ camila@example.com\n\nHello Camila, your email is: camila@example.com\n```\n\n
\n\nYou can test the input typed in the terminal using `input=\"camila@example.com\\n\"`.\n\nThis is because what you type in the terminal goes to \"**standard input**\" and is handled by the operating system as if it was a \"virtual file\".\n\n/// info\n\nIf you need a refresher about what is \"standard output\", \"standard error\", and \"standard input\" check the section in [Printing and Colors: \"Standard Output\" and \"Standard Error\"](printing.md#standard-output-and-standard-error){.internal-link target=_blank}.\n\n///\n\nWhen you hit the ENTER key after typing the email, that is just a \"new line character\". And in Python that is represented with `\"\\n\"`.\n\nSo, if you use `input=\"camila@example.com\\n\"` it means: \"type `camila@example.com` in the terminal, then hit the ENTER key\":\n\n{* docs_src/testing/app02_py310/test_main.py hl[9] *}\n\n## Test a function\n\nIf you have a script and you never created an explicit `typer.Typer` app, like:\n\n{* docs_src/testing/app03_py310/main.py hl[9] *}\n\n...you can still test it, by creating an app during testing:\n\n{* docs_src/testing/app03_py310/test_main.py hl[6,7,13] *}\n\nOf course, if you are testing that script, it's probably easier/cleaner to just create the explicit `typer.Typer` app in `main.py` instead of creating it just during the test.\n\nBut if you want to keep it that way, e.g. because it's a simple example in documentation, then you can use that trick.\n\n### About the `app.command` decorator\n\nNotice the `app.command()(main)`.\n\nIf it's not obvious what it's doing, continue reading...\n\nYou would normally write something like:\n\n```Python\n@app.command()\ndef main(name: str = \"World\"):\n # Some code here\n```\n\nBut `@app.command()` is just a decorator.\n\nThat's equivalent to:\n\n```Python\ndef main(name: str = \"World\"):\n # Some code here\n\ndecorator = app.command()\n\nnew_main = decorator(main)\nmain = new_main\n```\n\n`app.command()` returns a function (`decorator`) that takes another function as it's only parameter (`main`).\n\nAnd by using the `@something` you normally tell Python to replace the thing below (the function `main`) with the return of the `decorator` function (`new_main`).\n\nNow, in the specific case of **Typer**, the decorator doesn't change the original function. It registers it internally and returns it unmodified.\n\nSo, `new_main` is actually the same original `main`.\n\nSo, in the case of **Typer**, as it doesn't really modify the decorated function, that would be equivalent to:\n\n```Python\ndef main(name: str = \"World\"):\n # Some code here\n\ndecorator = app.command()\n\ndecorator(main)\n```\n\nBut then we don't need to create the variable `decorator` to use it below, we can just use it directly:\n\n```Python\ndef main(name: str = \"World\"):\n # Some code here\n\napp.command()(main)\n```\n\n...that's it. It's still probably simpler to just create the explicit `typer.Typer` in the `main.py` file ๐
.\n"
},
{
"path": "docs/tutorial/typer-app.md",
"content": "# Typer App\n\n## Explicit application\n\nSo far, you have seen how to create a single function and then pass that function to `typer.run()`.\n\nFor example:\n\n{* docs_src/first_steps/tutorial002_py310.py hl[9] *}\n\nBut that is actually a shortcut. Under the hood, **Typer** converts that to a CLI application with `typer.Typer()` and executes it. All that inside of `typer.run()`.\n\nThere's also a more explicit way to achieve the same:\n\n{* docs_src/typer_app/tutorial001_py310.py hl[3,6,12] *}\n\nWhen you use `typer.run()`, **Typer** is doing more or less the same as above, it will:\n\n* Create a new `typer.Typer()` \"application\".\n* Create a new \"`command`\" with your function.\n* Call the same \"application\" as if it was a function with \"`app()`\".\n\n/// info | `@decorator` Info\n\nThat `@something` syntax in Python is called a \"decorator\".\n\nYou put it on top of a function. Like a pretty decorative hat (I guess that's where the term came from).\n\nA \"decorator\" takes the function below and does something with it.\n\nIn our case, this decorator tells **Typer** that the function below is a \"`command`\".\nYou will learn more about commands later in the section [commands](./commands/index.md){.internal-link target=_blank}.\n\n///\n\nBoth ways, with `typer.run()` and creating the explicit application, achieve almost the same.\n\n/// tip\n\nIf your use case is solved with just `typer.run()`, that's fine, you don't have to create the explicit `app` and use `@app.command()`, etc.\n\nYou might want to do that later when your app needs extra features, but if it doesn't need them yet, that's fine.\n\n///\n\nIf you run the second example, with the explicit `app`, it works exactly the same:\n\n\n\n```console\n// Without a CLI argument\n$ python main.py\n\nUsage: main.py [OPTIONS] NAME\nTry \"main.py --help\" for help.\n\nError: Missing argument 'NAME'.\n\n// With the NAME CLI argument\n$ python main.py Camila\n\nHello Camila\n\n// Asking for help\n$ python main.py --help\n\nUsage: main.py [OPTIONS] NAME\n\nOptions:\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or customize the installation.\n --help Show this message and exit.\n```\n\n
\n\n## CLI application completion\n\nThere's a little detail that is worth noting here.\n\nNow the help shows two new *CLI options*:\n\n* `--install-completion`\n* `--show-completion`\n\nTo get shell/tab completion, it's necessary to build a package that you and your users can install and **call directly**.\n\nSo instead of running a Python script like:\n\n\n\n```console\n$ python main.py\n\nโจ Some magic here โจ\n```\n\n
\n\n...It would be called like:\n\n\n\n```console\n$ magic-app\n\nโจ Some magic here โจ\n```\n\n
\n\nHaving a standalone program like that allows setting up shell/tab completion.\n\nThe first step to be able to create an installable package like that is to use an explicit `typer.Typer()` app.\n\nLater you can learn all the process to create a standalone CLI application and [Build a Package](./package.md){.internal-link target=_blank}.\n\nBut for now, it's just good to know that you are on that path. ๐\n"
},
{
"path": "docs/tutorial/typer-command.md",
"content": "# `typer` command\n\nThe `typer` command provides โจ completion โจ in the Terminal for your own small scripts. Even if they don't use Typer internally. Of course, it works better if you use **Typer** in your script.\n\nIt'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`).\n\nIn that case, you can run your program with the `typer` command in your Terminal, and it will provide completion for your script.\n\nThe `typer` command also has functionality to generate Markdown documentation for your own **Typer** programs ๐.\n\n## Install\n\nWhen you install **Typer** with:\n\n```bash\npip install typer\n```\n\n...it includes the `typer` command.\n\nIf you don't want to use the `typer` command, you can call the Typer library as a module with:\n\n```bash\npython -m typer\n```\n\n## Install completion\n\nYou can then install completion for the `typer` command with:\n\n\n\n```console\n$ typer --install-completion\n\nbash completion installed in /home/user/.bashrc.\nCompletion will take effect once you restart the terminal.\n```\n\n
\n\n### Sample script\n\nLet's say you have a script that uses **Typer** in `my_custom_script.py`:\n\n```Python\nfrom typing import Optional\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef hello(name: Optional[str] = None):\n if name:\n typer.echo(f\"Hello {name}\")\n else:\n typer.echo(\"Hello World!\")\n\n\n@app.command()\ndef bye(name: Optional[str] = None):\n if name:\n typer.echo(f\"Bye {name}\")\n else:\n typer.echo(\"Goodbye!\")\n\n\nif __name__ == \"__main__\":\n app()\n```\n\nFor it to work, you would also install **Typer**:\n\n\n\n```console\n$ python -m pip install typer\n---> 100%\nSuccessfully installed typer\n```\n\n
\n\n### Run with Python\n\nThen you could run your script with normal Python:\n\n\n\n```console\n$ python my_custom_script.py hello\n\nHello World!\n\n$ python my_custom_script.py hello --name Camila\n\nHello Camila!\n\n$ python my_custom_script.py bye --name Camila\n\nBye Camila\n```\n\n
\n\nThere'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.\n\nโ๏ธ But in your terminal, you won't get completion when hitting TAB for any of the subcommands or options, like `hello`, `bye`, and `--name`.\n\n### Run with the `typer` command.\n\nYou can also run the same script with the `typer` command:\n\n\n\n```console\n$ typer my_custom_script.py run hello\n\nHello World!\n\n$ typer my_custom_script.py run hello --name Camila\n\nHello Camila!\n\n$ typer my_custom_script.py run bye --name Camila\n\nBye Camila\n```\n\n
\n\n* Instead of using `python` directly you use the `typer` command.\n* After the name of the file, add the subcommand `run`.\n\nโ๏ธ If you installed completion 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` ๐.\n\n## If main\n\nBecause the `typer` command won't use the block with:\n\n```Python\nif __name__ == \"__main__\":\n app()\n```\n\n...you can also remove it if you are calling that script only with the `typer` command.\n\n## Run other files\n\nThe `typer` command can run any script with **Typer**, but the script doesn't even have to use **Typer** at all.\n\nYou 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.\n\nFor example, a file `main.py` like this will still work:\n\n```Python\ndef main(name: str = \"World\"):\n \"\"\"\n Say hi to someone, by default to the World.\n \"\"\"\n print(f\"Hello {name}\")\n```\n\nThen you can call it with:\n\n\n\n```console\n$ typer main.py run --help\nUsage: typer run [OPTIONS]\n\n Say hi to someone, by default to the World.\n\nOptions:\n --name TEXT\n --help Show this message and exit.\n\n$ typer main.py run --name Camila\n\nHello Camila\n```\n\n
\n\nAnd it will also have completion for things like the `--name` *CLI Option*.\n\n## Run a package or module\n\nInstead of a file path you can pass a module (possibly in a package) to import.\n\nFor example:\n\n\n\n```console\n$ typer my_package.main run --help\nUsage: typer run [OPTIONS]\n\nOptions:\n --name TEXT\n --help Show this message and exit.\n\n$ typer my_package.main run --name Camila\n\nHello Camila\n```\n\n
\n\n## Options\n\nYou can specify one of the following **CLI options**:\n\n* `--app`: the name of the variable with a `Typer()` object to run as the main app.\n* `--func`: the name of the variable with a function that would be used with `typer.run()`.\n\n### Defaults\n\nWhen your run a script with the `typer` command it will use the app from the following priority:\n\n* An app object from the `--app` *CLI Option*.\n* A function to convert to a **Typer** app from `--func` *CLI Option* (like when using `typer.run()`).\n* A **Typer** app in a variable with a name of `app`, `cli`, or `main`.\n* The first **Typer** app available in the file, with any name.\n* A function in a variable with a name of `main`, `cli`, or `app`.\n* The first function in the file, with any name.\n\n## Generate docs\n\nYou can also use the `typer` command to generate Markdown documentation for your **Typer** application.\n\n### Sample script with docs\n\nFor example, you could have a script like:\n\n{* docs_src/commands/help/tutorial001_an_py310.py *}\n\n### Generate docs with the `typer` command\n\nThen you could generate docs for it with the `typer` command.\n\nYou can use the subcommand `utils`.\n\nAnd then the subcommand `docs`.\n\n\n\n```console\n$ typer some_script.py utils docs\n```\n\n
\n\n/// tip\n\nIf you don't want to use the `typer` command, you can still generate docs with:\n\n```console\n$ python -m typer some_script.py utils docs\n```\n\n///\n\n**Options**:\n\n* `--name TEXT`: The name of the CLI program to use in docs.\n* `--output FILE`: An output file to write docs to, like README.md.\n* `--title TEXT`: A title to use in the docs, by default the name of the command.\n\nFor example:\n\n\n\n```console\n$ typer my_package.main utils docs --name awesome-cli --output README.md\n\nDocs saved to: README.md\n```\n\n
\n\n### Sample docs output\n\nFor example, for the previous script, the generated docs would look like:\n\n---\n\n## `awesome-cli`\n\nAwesome CLI user manager.\n\n**Usage**:\n\n```console\n$ awesome-cli [OPTIONS] COMMAND [ARGS]...\n```\n\n**Options**:\n\n* `--install-completion`: Install completion for the current shell.\n* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.\n* `--help`: Show this message and exit.\n\n**Commands**:\n\n* `create`: Create a new user with USERNAME.\n* `delete`: Delete a user with USERNAME.\n* `delete-all`: Delete ALL users in the database.\n* `init`: Initialize the users database.\n\n## `awesome-cli create`\n\nCreate a new user with USERNAME.\n\n**Usage**:\n\n```console\n$ awesome-cli create [OPTIONS] USERNAME\n```\n\n**Options**:\n\n* `--help`: Show this message and exit.\n\n## `awesome-cli delete`\n\nDelete a user with USERNAME.\n\nIf --force is not used, will ask for confirmation.\n\n**Usage**:\n\n```console\n$ awesome-cli delete [OPTIONS] USERNAME\n```\n\n**Options**:\n\n* `--force / --no-force`: Force deletion without confirmation. [required]\n* `--help`: Show this message and exit.\n\n## `awesome-cli delete-all`\n\nDelete ALL users in the database.\n\nIf --force is not used, will ask for confirmation.\n\n**Usage**:\n\n```console\n$ awesome-cli delete-all [OPTIONS]\n```\n\n**Options**:\n\n* `--force / --no-force`: Force deletion without confirmation. [required]\n* `--help`: Show this message and exit.\n\n## `awesome-cli init`\n\nInitialize the users database.\n\n**Usage**:\n\n```console\n$ awesome-cli init [OPTIONS]\n```\n\n**Options**:\n\n* `--help`: Show this message and exit.\n"
},
{
"path": "docs/virtual-environments.md",
"content": "# Virtual Environments\n\nWhen you work in Python projects you probably should use a **virtual environment** (or a similar mechanism) to isolate the packages you install for each project.\n\n/// info\n\nIf you already know about virtual environments, how to create them and use them, you might want to skip this section. ๐ค\n\n///\n\n/// tip\n\nA **virtual environment** is different than an **environment variable**.\n\nAn **environment variable** is a variable in the system that can be used by programs.\n\nA **virtual environment** is a directory with some files in it.\n\n///\n\n/// info\n\nThis page will teach you how to use **virtual environments** and how they work.\n\nIf you are ready to adopt a **tool that manages everything** for you (including installing Python), try uv.\n\n///\n\n## Create a Project\n\nFirst, create a directory for your project.\n\nWhat I normally do is that I create a directory named `code` inside my home/user directory.\n\nAnd inside of that I create one directory per project.\n\n\n\n```console\n// Go to the home directory\n$ cd\n// Create a directory for all your code projects\n$ mkdir code\n// Enter into that code directory\n$ cd code\n// Create a directory for this project\n$ mkdir awesome-project\n// Enter into that project directory\n$ cd awesome-project\n```\n\n
\n\n## Create a Virtual Environment\n\nWhen you start working on a Python project **for the first time**, create a virtual environment **inside your project**.\n\n/// tip\n\nYou only need to do this **once per project**, not every time you work.\n\n///\n\n//// tab | `venv`\n\nTo create a virtual environment, you can use the `venv` module that comes with Python.\n\n\n\n```console\n$ python -m venv .venv\n```\n\n
\n\n/// details | What that command means\n\n* `python`: use the program called `python`\n* `-m`: call a module as a script, we'll tell it which module next\n* `venv`: use the module called `venv` that normally comes installed with Python\n* `.venv`: create the virtual environment in the new directory `.venv`\n\n///\n\n////\n\n//// tab | `uv`\n\nIf you have `uv` installed, you can use it to create a virtual environment.\n\n\n\n```console\n$ uv venv\n```\n\n
\n\n/// tip\n\nBy default, `uv` will create a virtual environment in a directory called `.venv`.\n\nBut you could customize it passing an additional argument with the directory name.\n\n///\n\n////\n\nThat command creates a new virtual environment in a directory called `.venv`.\n\n/// details | `.venv` or other name\n\nYou could create the virtual environment in a different directory, but there's a convention of calling it `.venv`.\n\n///\n\n## Activate the Virtual Environment\n\nActivate the new virtual environment so that any Python command you run or package you install uses it.\n\n/// tip\n\nDo this **every time** you start a **new terminal session** to work on the project.\n\n///\n\n//// tab | Linux, macOS\n\n\n\n```console\n$ source .venv/bin/activate\n```\n\n
\n\n////\n\n//// tab | Windows PowerShell\n\n\n\n```console\n$ .venv\\Scripts\\Activate.ps1\n```\n\n
\n\n////\n\n//// tab | Windows Bash\n\nOr if you use Bash for Windows (e.g. Git Bash):\n\n\n\n```console\n$ source .venv/Scripts/activate\n```\n\n
\n\n////\n\n/// tip\n\nEvery time you install a **new package** in that environment, **activate** the environment again.\n\nThis makes sure that if you use a **terminal (CLI) program** installed by that package, you use the one from your virtual environment and not any other that could be installed globally, probably with a different version than what you need.\n\n///\n\n## Check the Virtual Environment is Active\n\nCheck that the virtual environment is active (the previous command worked).\n\n/// tip\n\nThis is **optional**, but it's a good way to **check** that everything is working as expected and you are using the virtual environment you intended.\n\n///\n\n//// tab | Linux, macOS, Windows Bash\n\n\n\n```console\n$ which python\n\n/home/user/code/awesome-project/.venv/bin/python\n```\n\n
\n\nIf it shows the `python` binary at `.venv/bin/python`, inside of your project (in this case `awesome-project`), then it worked. ๐\n\n////\n\n//// tab | Windows PowerShell\n\n\n\n```console\n$ Get-Command python\n\nC:\\Users\\user\\code\\awesome-project\\.venv\\Scripts\\python\n```\n\n
\n\nIf it shows the `python` binary at `.venv\\Scripts\\python`, inside of your project (in this case `awesome-project`), then it worked. ๐\n\n////\n\n## Upgrade `pip`\n\n/// tip\n\nIf you use `uv` you would use it to install things instead of `pip`, so you don't need to upgrade `pip`. ๐\n\n///\n\nIf you are using `pip` to install packages (it comes by default with Python), you should **upgrade** it to the latest version.\n\nMany exotic errors while installing a package are solved by just upgrading `pip` first.\n\n/// tip\n\nYou would normally do this **once**, right after you create the virtual environment.\n\n///\n\nMake sure the virtual environment is active (with the command above) and then run:\n\n\n\n```console\n$ python -m pip install --upgrade pip\n\n---> 100%\n```\n\n
\n\n## Add `.gitignore`\n\nIf you are using **Git** (you should), add a `.gitignore` file to exclude everything in your `.venv` from Git.\n\n/// tip\n\nIf you used `uv` to create the virtual environment, it already did this for you, you can skip this step. ๐\n\n///\n\n/// tip\n\nDo this **once**, right after you create the virtual environment.\n\n///\n\n\n\n```console\n$ echo \"*\" > .venv/.gitignore\n```\n\n
\n\n/// details | What that command means\n\n* `echo \"*\"`: will \"print\" the text `*` in the terminal (the next part changes that a bit)\n* `>`: anything printed to the terminal by the command to the left of `>` should not be printed but instead written to the file that goes to the right of `>`\n* `.gitignore`: the name of the file where the text should be written\n\nAnd `*` for Git means \"everything\". So, it will ignore everything in the `.venv` directory.\n\nThat command will create a file `.gitignore` with the content:\n\n```gitignore\n*\n```\n\n///\n\n## Install Packages\n\nAfter activating the environment, you can install packages in it.\n\n/// tip\n\nDo this **once** when installing or upgrading the packages your project needs.\n\nIf you need to upgrade a version or add a new package you would **do this again**.\n\n///\n\n### Install Packages Directly\n\nIf you're in a hurry and don't want to use a file to declare your project's package requirements, you can install them directly.\n\n/// tip\n\nIt's a (very) good idea to put the packages and versions your program needs in a file (for example `requirements.txt` or `pyproject.toml`).\n\n///\n\n//// tab | `pip`\n\n\n\n```console\n$ pip install typer\n\n---> 100%\n```\n\n
\n\n////\n\n//// tab | `uv`\n\nIf you have `uv`:\n\n\n\n```console\n$ uv pip install typer\n---> 100%\n```\n\n
\n\n////\n\n### Install from `requirements.txt`\n\nIf you have a `requirements.txt`, you can now use it to install its packages.\n\n//// tab | `pip`\n\n\n\n```console\n$ pip install -r requirements.txt\n---> 100%\n```\n\n
\n\n////\n\n//// tab | `uv`\n\nIf you have `uv`:\n\n\n\n```console\n$ uv pip install -r requirements.txt\n---> 100%\n```\n\n
\n\n////\n\n/// details | `requirements.txt`\n\nA `requirements.txt` with some packages could look like:\n\n```requirements.txt\ntyper==0.13.0\nrich==13.7.1\n```\n\n///\n\n## Run Your Program\n\nAfter you activated the virtual environment, you can run your program, and it will use the Python inside of your virtual environment with the packages you installed there.\n\n\n\n```console\n$ python main.py\n\nHello World\n```\n\n
\n\n## Configure Your Editor\n\nYou would probably use an editor, make sure you configure it to use the same virtual environment you created (it will probably autodetect it) so that you can get autocompletion and inline errors.\n\nFor example:\n\n* VS Code\n* PyCharm\n\n/// tip\n\nYou normally have to do this only **once**, when you create the virtual environment.\n\n///\n\n## Deactivate the Virtual Environment\n\nOnce you are done working on your project you can **deactivate** the virtual environment.\n\n\n\n```console\n$ deactivate\n```\n\n
\n\nThis way, when you run `python` it won't try to run it from that virtual environment with the packages installed there.\n\n## Ready to Work\n\nNow you're ready to start working on your project.\n\n\n\n/// tip\n\nDo you want to understand what's all that above?\n\nContinue reading. ๐๐ค\n\n///\n\n## Why Virtual Environments\n\nTo work with Typer you need to install Python.\n\nAfter that, you would need to **install** Typer and any other **packages** you want to use.\n\nTo install packages you would normally use the `pip` command that comes with Python (or similar alternatives).\n\nNevertheless, if you just use `pip` directly, the packages would be installed in your **global Python environment** (the global installation of Python).\n\n### The Problem\n\nSo, what's the problem with installing packages in the global Python environment?\n\nAt some point, you will probably end up writing many different programs that depend on **different packages**. And some of these projects you work on will depend on **different versions** of the same package. ๐ฑ\n\nFor example, you could create a project called `philosophers-stone`, this program depends on another package called **`harry`, using the version `1`**. So, you need to install `harry`.\n\n```mermaid\nflowchart LR\n stone(philosophers-stone) -->|requires| harry-1[harry v1]\n```\n\nThen, at some point later, you create another project called `prisoner-of-azkaban`, and this project also depends on `harry`, but this project needs **`harry` version `3`**.\n\n```mermaid\nflowchart LR\n azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3]\n```\n\nBut now the problem is, if you install the packages globally (in the global environment) instead of in a local **virtual environment**, you will have to choose which version of `harry` to install.\n\nIf you want to run `philosophers-stone` you will need to first install `harry` version `1`, for example with:\n\n\n\n```console\n$ pip install \"harry==1\"\n```\n\n
\n\nAnd then you would end up with `harry` version `1` installed in your global Python environment.\n\n```mermaid\nflowchart LR\n subgraph global[global env]\n harry-1[harry v1]\n end\n subgraph stone-project[philosophers-stone project]\n stone(philosophers-stone) -->|requires| harry-1\n end\n```\n\nBut then if you want to run `prisoner-of-azkaban`, you will need to uninstall `harry` version `1` and install `harry` version `3` (or just installing version `3` would automatically uninstall version `1`).\n\n\n\n```console\n$ pip install \"harry==3\"\n```\n\n
\n\nAnd then you would end up with `harry` version `3` installed in your global Python environment.\n\nAnd if you try to run `philosophers-stone` again, there's a chance it would **not work** because it needs `harry` version `1`.\n\n```mermaid\nflowchart LR\n subgraph global[global env]\n harry-1[harry v1]\n style harry-1 fill:#ccc,stroke-dasharray: 5 5\n harry-3[harry v3]\n end\n subgraph stone-project[philosophers-stone project]\n stone(philosophers-stone) -.-x|โ๏ธ| harry-1\n end\n subgraph azkaban-project[prisoner-of-azkaban project]\n azkaban(prisoner-of-azkaban) --> |requires| harry-3\n end\n```\n\n/// tip\n\nIt's very common in Python packages to try the best to **avoid breaking changes** in **new versions**, but it's better to be safe, and install newer versions intentionally and when you can run the tests to check everything is working correctly.\n\n///\n\nNow, imagine that with **many** other **packages** that all your **projects depend on**. That's very difficult to manage. And you would probably end up running some projects with some **incompatible versions** of the packages, and not knowing why something isn't working.\n\nAlso, depending on your operating system (e.g. Linux, Windows, macOS), it could have come with Python already installed. And in that case it probably had some packages pre-installed with some specific versions **needed by your system**. If you install packages in the global Python environment, you could end up **breaking** some of the programs that came with your operating system.\n\n## Where are Packages Installed\n\nWhen you install Python, it creates some directories with some files in your computer.\n\nSome of these directories are the ones in charge of having all the packages you install.\n\nWhen you run:\n\n\n\n```console\n// Don't run this now, it's just an example ๐ค\n$ pip install typer\n---> 100%\n```\n\n
\n\nThat will download a compressed file with the Typer code, normally from PyPI.\n\nIt will also **download** files for other packages that Typer depends on.\n\nThen it will **extract** all those files and put them in a directory in your computer.\n\nBy default, it will put those files downloaded and extracted in the directory that comes with your Python installation, that's the **global environment**.\n\n## What are Virtual Environments\n\nThe solution to the problems of having all the packages in the global environment is to use a **virtual environment for each project** you work on.\n\nA virtual environment is a **directory**, very similar to the global one, where you can install the packages for a project.\n\nThis way, each project will have its own virtual environment (`.venv` directory) with its own packages.\n\n```mermaid\nflowchart TB\n subgraph stone-project[philosophers-stone project]\n stone(philosophers-stone) --->|requires| harry-1\n subgraph venv1[.venv]\n harry-1[harry v1]\n end\n end\n subgraph azkaban-project[prisoner-of-azkaban project]\n azkaban(prisoner-of-azkaban) --->|requires| harry-3\n subgraph venv2[.venv]\n harry-3[harry v3]\n end\n end\n stone-project ~~~ azkaban-project\n```\n\n## What Does Activating a Virtual Environment Mean\n\nWhen you activate a virtual environment, for example with:\n\n//// tab | Linux, macOS\n\n\n\n```console\n$ source .venv/bin/activate\n```\n\n
\n\n////\n\n//// tab | Windows PowerShell\n\n\n\n```console\n$ .venv\\Scripts\\Activate.ps1\n```\n\n
\n\n////\n\n//// tab | Windows Bash\n\nOr if you use Bash for Windows (e.g. Git Bash):\n\n\n\n```console\n$ source .venv/Scripts/activate\n```\n\n
\n\n////\n\nThat command will create or modify some [environment variables](environment-variables.md){.internal-link target=_blank} that will be available for the next commands.\n\nOne of those variables is the `PATH` variable.\n\n/// tip\n\nYou can learn more about the `PATH` environment variable in the [Environment Variables](environment-variables.md#path-environment-variable){.internal-link target=_blank} section.\n\n///\n\nActivating a virtual environment adds its path `.venv/bin` (on Linux and macOS) or `.venv\\Scripts` (on Windows) to the `PATH` environment variable.\n\nLet's say that before activating the environment, the `PATH` variable looked like this:\n\n//// tab | Linux, macOS\n\n```plaintext\n/usr/bin:/bin:/usr/sbin:/sbin\n```\n\nThat means that the system would look for programs in:\n\n* `/usr/bin`\n* `/bin`\n* `/usr/sbin`\n* `/sbin`\n\n////\n\n//// tab | Windows\n\n```plaintext\nC:\\Windows\\System32\n```\n\nThat means that the system would look for programs in:\n\n* `C:\\Windows\\System32`\n\n////\n\nAfter activating the virtual environment, the `PATH` variable would look something like this:\n\n//// tab | Linux, macOS\n\n```plaintext\n/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin\n```\n\nThat means that the system will now start looking first look for programs in:\n\n```plaintext\n/home/user/code/awesome-project/.venv/bin\n```\n\nbefore looking in the other directories.\n\nSo, when you type `python` in the terminal, the system will find the Python program in\n\n```plaintext\n/home/user/code/awesome-project/.venv/bin/python\n```\n\nand use that one.\n\n////\n\n//// tab | Windows\n\n```plaintext\nC:\\Users\\user\\code\\awesome-project\\.venv\\Scripts;C:\\Windows\\System32\n```\n\nThat means that the system will now start looking first look for programs in:\n\n```plaintext\nC:\\Users\\user\\code\\awesome-project\\.venv\\Scripts\n```\n\nbefore looking in the other directories.\n\nSo, when you type `python` in the terminal, the system will find the Python program in\n\n```plaintext\nC:\\Users\\user\\code\\awesome-project\\.venv\\Scripts\\python\n```\n\nand use that one.\n\n////\n\nAn important detail is that it will put the virtual environment path at the **beginning** of the `PATH` variable. The system will find it **before** finding any other Python available. This way, when you run `python`, it will use the Python **from the virtual environment** instead of any other `python` (for example, a `python` from a global environment).\n\nActivating a virtual environment also changes a couple of other things, but this is one of the most important things it does.\n\n## Checking a Virtual Environment\n\nWhen you check if a virtual environment is active, for example with:\n\n//// tab | Linux, macOS, Windows Bash\n\n\n\n```console\n$ which python\n\n/home/user/code/awesome-project/.venv/bin/python\n```\n\n
\n\n////\n\n//// tab | Windows PowerShell\n\n\n\n```console\n$ Get-Command python\n\nC:\\Users\\user\\code\\awesome-project\\.venv\\Scripts\\python\n```\n\n
\n\n////\n\nThat means that the `python` program that will be used is the one **in the virtual environment**.\n\nyou use `which` in Linux and macOS and `Get-Command` in Windows PowerShell.\n\nThe way that command works is that it will go and check in the `PATH` environment variable, going through **each path in order**, looking for the program called `python`. Once it finds it, it will **show you the path** to that program.\n\nThe most important part is that when you call `python`, that is the exact \"`python`\" that will be executed.\n\nSo, you can confirm if you are in the correct virtual environment.\n\n/// tip\n\nIt's easy to activate one virtual environment, get one Python, and then **go to another project**.\n\nAnd the second project **wouldn't work** because you are using the **incorrect Python**, from a virtual environment for another project.\n\nIt's useful being able to check what `python` is being used. ๐ค\n\n///\n\n## Why Deactivate a Virtual Environment\n\nFor example, you could be working on a project `philosophers-stone`, **activate that virtual environment**, install packages and work with that environment.\n\nAnd then you want to work on **another project** `prisoner-of-azkaban`.\n\nYou go to that project:\n\n\n\n```console\n$ cd ~/code/prisoner-of-azkaban\n```\n\n
\n\nIf you don't deactivate the virtual environment for `philosophers-stone`, when you run `python` in the terminal, it will try to use the Python from `philosophers-stone`.\n\n\n\n```console\n$ cd ~/code/prisoner-of-azkaban\n\n$ python main.py\n\n// Error importing sirius, it's not installed ๐ฑ\nTraceback (most recent call last):\n File \"main.py\", line 1, in \n import sirius\n```\n\n
\n\nBut if you deactivate the virtual environment and activate the new one for `prisoner-of-askaban` then when you run `python` it will use the Python from the virtual environment in `prisoner-of-azkaban`.\n\n\n\n```console\n$ cd ~/code/prisoner-of-azkaban\n\n// You don't need to be in the old directory to deactivate, you can do it wherever you are, even after going to the other project ๐\n$ deactivate\n\n// Activate the virtual environment in prisoner-of-azkaban/.venv ๐\n$ source .venv/bin/activate\n\n// Now when you run python, it will find the package sirius installed in this virtual environment โจ\n$ python main.py\n\nI solemnly swear ๐บ\n```\n\n
\n\n## Alternatives\n\nThis is a simple guide to get you started and teach you how everything works **underneath**.\n\nThere are many **alternatives** to managing virtual environments, package dependencies (requirements), projects.\n\nOnce you are ready and want to use a tool to **manage the entire project**, packages dependencies, virtual environments, etc. I would suggest you try uv.\n\n`uv` can do a lot of things, it can:\n\n* **Install Python** for you, including different versions\n* Manage the **virtual environment** for your projects\n* Install **packages**\n* Manage package **dependencies and versions** for your project\n* Make sure you have an **exact** set of packages and versions to install, including their dependencies, so that you can be sure that you can run your project in production exactly the same as in your computer while developing, this is called **locking**\n* And many other things\n\n## Conclusion\n\nIf you read and understood all this, now **you know much more** about virtual environments than many developers out there. ๐ค\n\nKnowing these details will most probably be useful in a future time when you are debugging something that seems complex, but you will know **how it all works underneath**. ๐\n"
},
{
"path": "docs_src/app_dir/__init__.py",
"content": ""
},
{
"path": "docs_src/app_dir/tutorial001_py310.py",
"content": "from pathlib import Path\n\nimport typer\n\nAPP_NAME = \"my-super-cli-app\"\n\napp = typer.Typer()\n\n\n@app.command()\ndef main():\n app_dir = typer.get_app_dir(APP_NAME)\n config_path: Path = Path(app_dir) / \"config.json\"\n if not config_path.is_file():\n print(\"Config file doesn't exist yet\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/__init__.py",
"content": ""
},
{
"path": "docs_src/arguments/default/__init__.py",
"content": ""
},
{
"path": "docs_src/arguments/default/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: Annotated[str, typer.Argument()] = \"Wade Wilson\"):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/default/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str = typer.Argument(\"Wade Wilson\")):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/default/tutorial002_an_py310.py",
"content": "import random\nfrom typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\ndef get_name():\n return random.choice([\"Deadpool\", \"Rick\", \"Morty\", \"Hiro\"])\n\n\n@app.command()\ndef main(name: Annotated[str, typer.Argument(default_factory=get_name)]):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/default/tutorial002_py310.py",
"content": "import random\n\nimport typer\n\napp = typer.Typer()\n\n\ndef get_name():\n return random.choice([\"Deadpool\", \"Rick\", \"Morty\", \"Hiro\"])\n\n\n@app.command()\ndef main(name: str = typer.Argument(default_factory=get_name)):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/envvar/__init__.py",
"content": ""
},
{
"path": "docs_src/arguments/envvar/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: Annotated[str, typer.Argument(envvar=\"AWESOME_NAME\")] = \"World\"):\n print(f\"Hello Mr. {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/envvar/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str = typer.Argument(\"World\", envvar=\"AWESOME_NAME\")):\n print(f\"Hello Mr. {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/envvar/tutorial002_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: Annotated[str, typer.Argument(envvar=[\"AWESOME_NAME\", \"GOD_NAME\"])] = \"World\",\n):\n print(f\"Hello Mr. {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/envvar/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str = typer.Argument(\"World\", envvar=[\"AWESOME_NAME\", \"GOD_NAME\"])):\n print(f\"Hello Mr. {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/envvar/tutorial003_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: Annotated[\n str, typer.Argument(envvar=\"AWESOME_NAME\", show_envvar=False)\n ] = \"World\",\n):\n print(f\"Hello Mr. {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/envvar/tutorial003_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str = typer.Argument(\"World\", envvar=\"AWESOME_NAME\", show_envvar=False)):\n print(f\"Hello Mr. {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/help/__init__.py",
"content": ""
},
{
"path": "docs_src/arguments/help/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: Annotated[str, typer.Argument(help=\"The name of the user to greet\")]):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/help/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str = typer.Argument(..., help=\"The name of the user to greet\")):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/help/tutorial002_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: Annotated[str, typer.Argument(help=\"The name of the user to greet\")]):\n \"\"\"\n Say hi to NAME very gently, like Dirk.\n \"\"\"\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/help/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str = typer.Argument(..., help=\"The name of the user to greet\")):\n \"\"\"\n Say hi to NAME very gently, like Dirk.\n \"\"\"\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/help/tutorial003_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: Annotated[str, typer.Argument(help=\"Who to greet\")] = \"World\"):\n \"\"\"\n Say hi to NAME very gently, like Dirk.\n \"\"\"\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/help/tutorial003_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str = typer.Argument(\"World\", help=\"Who to greet\")):\n \"\"\"\n Say hi to NAME very gently, like Dirk.\n \"\"\"\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/help/tutorial004_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: Annotated[\n str, typer.Argument(help=\"Who to greet\", show_default=False)\n ] = \"World\",\n):\n \"\"\"\n Say hi to NAME very gently, like Dirk.\n \"\"\"\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/help/tutorial004_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str = typer.Argument(\"World\", help=\"Who to greet\", show_default=False)):\n \"\"\"\n Say hi to NAME very gently, like Dirk.\n \"\"\"\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/help/tutorial005_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: Annotated[\n str,\n typer.Argument(\n help=\"Who to greet\", show_default=\"Deadpoolio the amazing's name\"\n ),\n ] = \"Wade Wilson\",\n):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/help/tutorial005_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: str = typer.Argument(\n \"Wade Wilson\", help=\"Who to greet\", show_default=\"Deadpoolio the amazing's name\"\n ),\n):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/help/tutorial006_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: Annotated[str, typer.Argument(metavar=\"โจusernameโจ\")] = \"World\"):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/help/tutorial006_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str = typer.Argument(\"World\", metavar=\"โจusernameโจ\")):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/help/tutorial007_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: Annotated[str, typer.Argument(help=\"Who to greet\")],\n lastname: Annotated[\n str, typer.Argument(help=\"The last name\", rich_help_panel=\"Secondary Arguments\")\n ] = \"\",\n age: Annotated[\n str,\n typer.Argument(help=\"The user's age\", rich_help_panel=\"Secondary Arguments\"),\n ] = \"\",\n):\n \"\"\"\n Say hi to NAME very gently, like Dirk.\n \"\"\"\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/help/tutorial007_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: str = typer.Argument(..., help=\"Who to greet\"),\n lastname: str = typer.Argument(\n \"\", help=\"The last name\", rich_help_panel=\"Secondary Arguments\"\n ),\n age: str = typer.Argument(\n \"\", help=\"The user's age\", rich_help_panel=\"Secondary Arguments\"\n ),\n):\n \"\"\"\n Say hi to NAME very gently, like Dirk.\n \"\"\"\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/help/tutorial008_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: Annotated[str, typer.Argument(hidden=True)] = \"World\"):\n \"\"\"\n Say hi to NAME very gently, like Dirk.\n \"\"\"\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/help/tutorial008_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str = typer.Argument(\"World\", hidden=True)):\n \"\"\"\n Say hi to NAME very gently, like Dirk.\n \"\"\"\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/optional/__init__.py",
"content": ""
},
{
"path": "docs_src/arguments/optional/tutorial000_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\n\ndef main(name: Annotated[str, typer.Argument()]):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n typer.run(main)\n"
},
{
"path": "docs_src/arguments/optional/tutorial000_py310.py",
"content": "import typer\n\n\ndef main(name: str = typer.Argument()):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n typer.run(main)\n"
},
{
"path": "docs_src/arguments/optional/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: Annotated[str, typer.Argument()]):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/optional/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str = typer.Argument()):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/optional/tutorial002_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: Annotated[str, typer.Argument()] = \"World\"):\n print(f\"Hello {name}!\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/optional/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str = typer.Argument(default=\"World\")):\n print(f\"Hello {name}!\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/arguments/optional/tutorial003_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str = typer.Argument(default=...)):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/__init__.py",
"content": ""
},
{
"path": "docs_src/commands/arguments/__init__.py",
"content": ""
},
{
"path": "docs_src/commands/arguments/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef create(username: str):\n print(f\"Creating user: {username}\")\n\n\n@app.command()\ndef delete(username: str):\n print(f\"Deleting user: {username}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/callback/__init__.py",
"content": ""
},
{
"path": "docs_src/commands/callback/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\nstate = {\"verbose\": False}\n\n\n@app.command()\ndef create(username: str):\n if state[\"verbose\"]:\n print(\"About to create a user\")\n print(f\"Creating user: {username}\")\n if state[\"verbose\"]:\n print(\"Just created a user\")\n\n\n@app.command()\ndef delete(username: str):\n if state[\"verbose\"]:\n print(\"About to delete a user\")\n print(f\"Deleting user: {username}\")\n if state[\"verbose\"]:\n print(\"Just deleted a user\")\n\n\n@app.callback()\ndef main(verbose: bool = False):\n \"\"\"\n Manage users in the awesome CLI app.\n \"\"\"\n if verbose:\n print(\"Will write verbose output\")\n state[\"verbose\"] = True\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/callback/tutorial002_py310.py",
"content": "import typer\n\n\ndef callback():\n print(\"Running a command\")\n\n\napp = typer.Typer(callback=callback)\n\n\n@app.command()\ndef create(name: str):\n print(f\"Creating user: {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/callback/tutorial003_py310.py",
"content": "import typer\n\n\ndef callback():\n print(\"Running a command\")\n\n\napp = typer.Typer(callback=callback)\n\n\n@app.callback()\ndef new_callback():\n print(\"Override callback, running a command\")\n\n\n@app.command()\ndef create(name: str):\n print(f\"Creating user: {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/callback/tutorial004_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.callback()\ndef callback():\n \"\"\"\n Manage users CLI app.\n\n Use it with the create command.\n\n A new user with the given NAME will be created.\n \"\"\"\n\n\n@app.command()\ndef create(name: str):\n print(f\"Creating user: {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/context/__init__.py",
"content": ""
},
{
"path": "docs_src/commands/context/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef create(username: str):\n print(f\"Creating user: {username}\")\n\n\n@app.command()\ndef delete(username: str):\n print(f\"Deleting user: {username}\")\n\n\n@app.callback()\ndef main(ctx: typer.Context):\n \"\"\"\n Manage users in the awesome CLI app.\n \"\"\"\n print(f\"About to execute command: {ctx.invoked_subcommand}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/context/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef create(username: str):\n print(f\"Creating user: {username}\")\n\n\n@app.command()\ndef delete(username: str):\n print(f\"Deleting user: {username}\")\n\n\n@app.callback(invoke_without_command=True)\ndef main():\n \"\"\"\n Manage users in the awesome CLI app.\n \"\"\"\n print(\"Initializing database\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/context/tutorial003_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef create(username: str):\n print(f\"Creating user: {username}\")\n\n\n@app.command()\ndef delete(username: str):\n print(f\"Deleting user: {username}\")\n\n\n@app.callback(invoke_without_command=True)\ndef main(ctx: typer.Context):\n \"\"\"\n Manage users in the awesome CLI app.\n \"\"\"\n if ctx.invoked_subcommand is None:\n print(\"Initializing database\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/context/tutorial004_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command(\n context_settings={\"allow_extra_args\": True, \"ignore_unknown_options\": True}\n)\ndef main(ctx: typer.Context):\n for extra_arg in ctx.args:\n print(f\"Got extra arg: {extra_arg}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/help/__init__.py",
"content": ""
},
{
"path": "docs_src/commands/help/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer(help=\"Awesome CLI user manager.\")\n\n\n@app.command()\ndef create(username: str):\n \"\"\"\n Create a new user with USERNAME.\n \"\"\"\n print(f\"Creating user: {username}\")\n\n\n@app.command()\ndef delete(\n username: str,\n force: Annotated[\n bool,\n typer.Option(\n prompt=\"Are you sure you want to delete the user?\",\n help=\"Force deletion without confirmation.\",\n ),\n ],\n):\n \"\"\"\n Delete a user with USERNAME.\n\n If --force is not used, will ask for confirmation.\n \"\"\"\n if force:\n print(f\"Deleting user: {username}\")\n else:\n print(\"Operation cancelled\")\n\n\n@app.command()\ndef delete_all(\n force: Annotated[\n bool,\n typer.Option(\n prompt=\"Are you sure you want to delete ALL users?\",\n help=\"Force deletion without confirmation.\",\n ),\n ],\n):\n \"\"\"\n Delete ALL users in the database.\n\n If --force is not used, will ask for confirmation.\n \"\"\"\n if force:\n print(\"Deleting all users\")\n else:\n print(\"Operation cancelled\")\n\n\n@app.command()\ndef init():\n \"\"\"\n Initialize the users database.\n \"\"\"\n print(\"Initializing user database\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/help/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer(help=\"Awesome CLI user manager.\")\n\n\n@app.command()\ndef create(username: str):\n \"\"\"\n Create a new user with USERNAME.\n \"\"\"\n print(f\"Creating user: {username}\")\n\n\n@app.command()\ndef delete(\n username: str,\n force: bool = typer.Option(\n ...,\n prompt=\"Are you sure you want to delete the user?\",\n help=\"Force deletion without confirmation.\",\n ),\n):\n \"\"\"\n Delete a user with USERNAME.\n\n If --force is not used, will ask for confirmation.\n \"\"\"\n if force:\n print(f\"Deleting user: {username}\")\n else:\n print(\"Operation cancelled\")\n\n\n@app.command()\ndef delete_all(\n force: bool = typer.Option(\n ...,\n prompt=\"Are you sure you want to delete ALL users?\",\n help=\"Force deletion without confirmation.\",\n ),\n):\n \"\"\"\n Delete ALL users in the database.\n\n If --force is not used, will ask for confirmation.\n \"\"\"\n if force:\n print(\"Deleting all users\")\n else:\n print(\"Operation cancelled\")\n\n\n@app.command()\ndef init():\n \"\"\"\n Initialize the users database.\n \"\"\"\n print(\"Initializing user database\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/help/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command(help=\"Create a new user with USERNAME.\")\ndef create(username: str):\n \"\"\"\n Some internal utility function to create.\n \"\"\"\n print(f\"Creating user: {username}\")\n\n\n@app.command(help=\"Delete a user with USERNAME.\")\ndef delete(username: str):\n \"\"\"\n Some internal utility function to delete.\n \"\"\"\n print(f\"Deleting user: {username}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/help/tutorial003_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef create(username: str):\n \"\"\"\n Create a user.\n \"\"\"\n print(f\"Creating user: {username}\")\n\n\n@app.command(deprecated=True)\ndef delete(username: str):\n \"\"\"\n Delete a user.\n\n This is deprecated and will stop being supported soon.\n \"\"\"\n print(f\"Deleting user: {username}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/help/tutorial004_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer(rich_markup_mode=\"rich\")\n\n\n@app.command()\ndef create(\n username: Annotated[\n str, typer.Argument(help=\"The username to be [green]created[/green]\")\n ],\n):\n \"\"\"\n [bold green]Create[/bold green] a new [italic]shiny[/italic] user. :sparkles:\n\n This requires a [underline]username[/underline].\n \"\"\"\n print(f\"Creating user: {username}\")\n\n\n@app.command(help=\"[bold red]Delete[/bold red] a user with [italic]USERNAME[/italic].\")\ndef delete(\n username: Annotated[\n str, typer.Argument(help=\"The username to be [red]deleted[/red]\")\n ],\n force: Annotated[\n bool, typer.Option(help=\"Force the [bold red]deletion[/bold red] :boom:\")\n ] = False,\n):\n \"\"\"\n Some internal utility function to delete.\n \"\"\"\n print(f\"Deleting user: {username}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/help/tutorial004_py310.py",
"content": "import typer\n\napp = typer.Typer(rich_markup_mode=\"rich\")\n\n\n@app.command()\ndef create(\n username: str = typer.Argument(\n ..., help=\"The username to be [green]created[/green]\"\n ),\n):\n \"\"\"\n [bold green]Create[/bold green] a new [italic]shiny[/italic] user. :sparkles:\n\n This requires a [underline]username[/underline].\n \"\"\"\n print(f\"Creating user: {username}\")\n\n\n@app.command(help=\"[bold red]Delete[/bold red] a user with [italic]USERNAME[/italic].\")\ndef delete(\n username: str = typer.Argument(..., help=\"The username to be [red]deleted[/red]\"),\n force: bool = typer.Option(\n False, help=\"Force the [bold red]deletion[/bold red] :boom:\"\n ),\n):\n \"\"\"\n Some internal utility function to delete.\n \"\"\"\n print(f\"Deleting user: {username}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/help/tutorial005_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer(rich_markup_mode=\"markdown\")\n\n\n@app.command()\ndef create(\n username: Annotated[str, typer.Argument(help=\"The username to be **created**\")],\n):\n \"\"\"\n **Create** a new *shiny* user. :sparkles:\n\n * Create a username\n\n * Show that the username is created\n\n ---\n\n Learn more at the [Typer docs website](https://typer.tiangolo.com)\n \"\"\"\n print(f\"Creating user: {username}\")\n\n\n@app.command(help=\"**Delete** a user with *USERNAME*.\")\ndef delete(\n username: Annotated[str, typer.Argument(help=\"The username to be **deleted**\")],\n force: Annotated[bool, typer.Option(help=\"Force the **deletion** :boom:\")] = False,\n):\n \"\"\"\n Some internal utility function to delete.\n \"\"\"\n print(f\"Deleting user: {username}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/help/tutorial005_py310.py",
"content": "import typer\n\napp = typer.Typer(rich_markup_mode=\"markdown\")\n\n\n@app.command()\ndef create(username: str = typer.Argument(..., help=\"The username to be **created**\")):\n \"\"\"\n **Create** a new *shiny* user. :sparkles:\n\n * Create a username\n\n * Show that the username is created\n\n ---\n\n Learn more at the [Typer docs website](https://typer.tiangolo.com)\n \"\"\"\n print(f\"Creating user: {username}\")\n\n\n@app.command(help=\"**Delete** a user with *USERNAME*.\")\ndef delete(\n username: str = typer.Argument(..., help=\"The username to be **deleted**\"),\n force: bool = typer.Option(False, help=\"Force the **deletion** :boom:\"),\n):\n \"\"\"\n Some internal utility function to delete.\n \"\"\"\n print(f\"Deleting user: {username}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/help/tutorial006_py310.py",
"content": "import typer\n\napp = typer.Typer(rich_markup_mode=\"rich\")\n\n\n@app.command()\ndef create(username: str):\n \"\"\"\n [green]Create[/green] a new user. :sparkles:\n \"\"\"\n print(f\"Creating user: {username}\")\n\n\n@app.command()\ndef delete(username: str):\n \"\"\"\n [red]Delete[/red] a user. :x:\n \"\"\"\n print(f\"Deleting user: {username}\")\n\n\n@app.command(rich_help_panel=\"Utils and Configs\")\ndef config(configuration: str):\n \"\"\"\n [blue]Configure[/blue] the system. :gear:\n \"\"\"\n print(f\"Configuring the system with: {configuration}\")\n\n\n@app.command(rich_help_panel=\"Utils and Configs\")\ndef sync():\n \"\"\"\n [blue]Synchronize[/blue] the system or something fancy like that. :recycle:\n \"\"\"\n print(\"Syncing the system\")\n\n\n@app.command(rich_help_panel=\"Help and Others\")\ndef help():\n \"\"\"\n Get [yellow]help[/yellow] with the system. :question:\n \"\"\"\n print(\"Opening help portal...\")\n\n\n@app.command(rich_help_panel=\"Help and Others\")\ndef report():\n \"\"\"\n [yellow]Report[/yellow] an issue. :exclamation:\n \"\"\"\n print(\"Please open a new issue online, not a direct message\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/help/tutorial007_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer(rich_markup_mode=\"rich\")\n\n\n@app.command()\ndef create(\n username: Annotated[str, typer.Argument(help=\"The username to create\")],\n lastname: Annotated[\n str,\n typer.Argument(\n help=\"The last name of the new user\", rich_help_panel=\"Secondary Arguments\"\n ),\n ] = \"\",\n force: Annotated[bool, typer.Option(help=\"Force the creation of the user\")] = False,\n age: Annotated[\n int | None,\n typer.Option(help=\"The age of the new user\", rich_help_panel=\"Additional Data\"),\n ] = None,\n favorite_color: Annotated[\n str | None,\n typer.Option(\n help=\"The favorite color of the new user\",\n rich_help_panel=\"Additional Data\",\n ),\n ] = None,\n):\n \"\"\"\n [green]Create[/green] a new user. :sparkles:\n \"\"\"\n print(f\"Creating user: {username}\")\n\n\n@app.command(rich_help_panel=\"Utils and Configs\")\ndef config(configuration: str):\n \"\"\"\n [blue]Configure[/blue] the system. :gear:\n \"\"\"\n print(f\"Configuring the system with: {configuration}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/help/tutorial007_py310.py",
"content": "import typer\n\napp = typer.Typer(rich_markup_mode=\"rich\")\n\n\n@app.command()\ndef create(\n username: str = typer.Argument(..., help=\"The username to create\"),\n lastname: str = typer.Argument(\n \"\", help=\"The last name of the new user\", rich_help_panel=\"Secondary Arguments\"\n ),\n force: bool = typer.Option(False, help=\"Force the creation of the user\"),\n age: int | None = typer.Option(\n None, help=\"The age of the new user\", rich_help_panel=\"Additional Data\"\n ),\n favorite_color: str | None = typer.Option(\n None,\n help=\"The favorite color of the new user\",\n rich_help_panel=\"Additional Data\",\n ),\n):\n \"\"\"\n [green]Create[/green] a new user. :sparkles:\n \"\"\"\n print(f\"Creating user: {username}\")\n\n\n@app.command(rich_help_panel=\"Utils and Configs\")\ndef config(configuration: str):\n \"\"\"\n [blue]Configure[/blue] the system. :gear:\n \"\"\"\n print(f\"Configuring the system with: {configuration}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/help/tutorial008_py310.py",
"content": "import typer\n\napp = typer.Typer(rich_markup_mode=\"rich\")\n\n\n@app.command(epilog=\"Made with :heart: in [blue]Venus[/blue]\")\ndef create(username: str):\n \"\"\"\n [green]Create[/green] a new user. :sparkles:\n \"\"\"\n print(f\"Creating user: {username}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/index/__init__.py",
"content": ""
},
{
"path": "docs_src/commands/index/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef create():\n print(\"Creating user: Hiro Hamada\")\n\n\n@app.command()\ndef delete():\n print(\"Deleting user: Hiro Hamada\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/index/tutorial003_py310.py",
"content": "import typer\n\napp = typer.Typer(no_args_is_help=True)\n\n\n@app.command()\ndef create():\n print(\"Creating user: Hiro Hamada\")\n\n\n@app.command()\ndef delete():\n print(\"Deleting user: Hiro Hamada\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/index/tutorial004_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef delete():\n print(\"Deleting user: Hiro Hamada\")\n\n\n@app.command()\ndef create():\n print(\"Creating user: Hiro Hamada\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/index/tutorial005_py310.py",
"content": "import typer\n\napp = typer.Typer(suggest_commands=True)\n\n\n@app.command()\ndef create():\n typer.echo(\"Creating...\")\n\n\n@app.command()\ndef delete():\n typer.echo(\"Deleting...\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/name/__init__.py",
"content": ""
},
{
"path": "docs_src/commands/name/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command(\"create\")\ndef cli_create_user(username: str):\n print(f\"Creating user: {username}\")\n\n\n@app.command(\"delete\")\ndef cli_delete_user(username: str):\n print(f\"Deleting user: {username}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/one_or_multiple/__init__.py",
"content": ""
},
{
"path": "docs_src/commands/one_or_multiple/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef create():\n print(\"Creating user: Hiro Hamada\")\n\n\n@app.callback()\ndef callback():\n pass\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/one_or_multiple/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef create():\n print(\"Creating user: Hiro Hamada\")\n\n\n@app.callback()\ndef callback():\n \"\"\"\n Creates a single user Hiro Hamada.\n\n In the next version it will create 5 more users.\n \"\"\"\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/options/__init__.py",
"content": ""
},
{
"path": "docs_src/commands/options/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef create(username: str):\n print(f\"Creating user: {username}\")\n\n\n@app.command()\ndef delete(\n username: str,\n force: Annotated[\n bool, typer.Option(prompt=\"Are you sure you want to delete the user?\")\n ],\n):\n if force:\n print(f\"Deleting user: {username}\")\n else:\n print(\"Operation cancelled\")\n\n\n@app.command()\ndef delete_all(\n force: Annotated[\n bool, typer.Option(prompt=\"Are you sure you want to delete ALL users?\")\n ],\n):\n if force:\n print(\"Deleting all users\")\n else:\n print(\"Operation cancelled\")\n\n\n@app.command()\ndef init():\n print(\"Initializing user database\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/commands/options/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef create(username: str):\n print(f\"Creating user: {username}\")\n\n\n@app.command()\ndef delete(\n username: str,\n force: bool = typer.Option(..., prompt=\"Are you sure you want to delete the user?\"),\n):\n if force:\n print(f\"Deleting user: {username}\")\n else:\n print(\"Operation cancelled\")\n\n\n@app.command()\ndef delete_all(\n force: bool = typer.Option(\n ..., prompt=\"Are you sure you want to delete ALL users?\"\n ),\n):\n if force:\n print(\"Deleting all users\")\n else:\n print(\"Operation cancelled\")\n\n\n@app.command()\ndef init():\n print(\"Initializing user database\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/exceptions/__init__.py",
"content": ""
},
{
"path": "docs_src/exceptions/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str = \"morty\"):\n print(name + 3)\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/exceptions/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer(pretty_exceptions_show_locals=True)\n\n\n@app.command()\ndef main(name: str = \"morty\"):\n print(name + 3)\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/exceptions/tutorial003_py310.py",
"content": "import typer\n\napp = typer.Typer(pretty_exceptions_short=False)\n\n\n@app.command()\ndef main(name: str = \"morty\"):\n print(name + 3)\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/exceptions/tutorial004_py310.py",
"content": "import typer\n\napp = typer.Typer(pretty_exceptions_enable=False)\n\n\n@app.command()\ndef main(name: str = \"morty\"):\n print(name + 3)\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/first_steps/__init__.py",
"content": ""
},
{
"path": "docs_src/first_steps/tutorial001_py310.py",
"content": "import typer\n\n\ndef main():\n print(\"Hello World\")\n\n\nif __name__ == \"__main__\":\n typer.run(main)\n"
},
{
"path": "docs_src/first_steps/tutorial002_py310.py",
"content": "import typer\n\n\ndef main(name: str):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n typer.run(main)\n"
},
{
"path": "docs_src/first_steps/tutorial003_py310.py",
"content": "import typer\n\n\ndef main(name: str, lastname: str):\n print(f\"Hello {name} {lastname}\")\n\n\nif __name__ == \"__main__\":\n typer.run(main)\n"
},
{
"path": "docs_src/first_steps/tutorial004_py310.py",
"content": "import typer\n\n\ndef main(name: str, lastname: str, formal: bool = False):\n if formal:\n print(f\"Good day Ms. {name} {lastname}.\")\n else:\n print(f\"Hello {name} {lastname}\")\n\n\nif __name__ == \"__main__\":\n typer.run(main)\n"
},
{
"path": "docs_src/first_steps/tutorial005_py310.py",
"content": "import typer\n\n\ndef main(name: str, lastname: str = \"\", formal: bool = False):\n if formal:\n print(f\"Good day Ms. {name} {lastname}.\")\n else:\n print(f\"Hello {name} {lastname}\")\n\n\nif __name__ == \"__main__\":\n typer.run(main)\n"
},
{
"path": "docs_src/first_steps/tutorial006_py310.py",
"content": "import typer\n\n\ndef main(name: str, lastname: str = \"\", formal: bool = False):\n \"\"\"\n Say hi to NAME, optionally with a --lastname.\n\n If --formal is used, say hi very formally.\n \"\"\"\n if formal:\n print(f\"Good day Ms. {name} {lastname}.\")\n else:\n print(f\"Hello {name} {lastname}\")\n\n\nif __name__ == \"__main__\":\n typer.run(main)\n"
},
{
"path": "docs_src/launch/__init__.py",
"content": ""
},
{
"path": "docs_src/launch/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main():\n print(\"Opening Typer's docs\")\n typer.launch(\"https://typer.tiangolo.com\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/launch/tutorial002_py310.py",
"content": "from pathlib import Path\n\nimport typer\n\nAPP_NAME = \"my-super-cli-app\"\n\napp = typer.Typer()\n\n\n@app.command()\ndef main():\n app_dir = typer.get_app_dir(APP_NAME)\n app_dir_path = Path(app_dir)\n app_dir_path.mkdir(parents=True, exist_ok=True)\n config_path: Path = Path(app_dir) / \"config.json\"\n if not config_path.is_file():\n config_path.write_text('{\"version\": \"1.0.0\"}')\n config_file_str = str(config_path)\n print(\"Opening config directory\")\n typer.launch(config_file_str, locate=True)\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/multiple_values/__init__.py",
"content": ""
},
{
"path": "docs_src/multiple_values/arguments_with_multiple_values/__init__.py",
"content": ""
},
{
"path": "docs_src/multiple_values/arguments_with_multiple_values/tutorial001_py310.py",
"content": "from pathlib import Path\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(files: list[Path], celebration: str):\n for path in files:\n if path.is_file():\n print(f\"This file exists: {path.name}\")\n print(celebration)\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/multiple_values/arguments_with_multiple_values/tutorial002_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n names: Annotated[\n tuple[str, str, str], typer.Argument(help=\"Select 3 characters to play with\")\n ] = (\"Harry\", \"Hermione\", \"Ron\"),\n):\n for name in names:\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/multiple_values/arguments_with_multiple_values/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n names: tuple[str, str, str] = typer.Argument(\n (\"Harry\", \"Hermione\", \"Ron\"), help=\"Select 3 characters to play with\"\n ),\n):\n for name in names:\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/multiple_values/multiple_options/__init__.py",
"content": ""
},
{
"path": "docs_src/multiple_values/multiple_options/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(user: Annotated[list[str] | None, typer.Option()] = None):\n if not user:\n print(f\"No provided users (raw input = {user})\")\n raise typer.Abort()\n for u in user:\n print(f\"Processing user: {u}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/multiple_values/multiple_options/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(user: list[str] | None = typer.Option(None)):\n if not user:\n print(f\"No provided users (raw input = {user})\")\n raise typer.Abort()\n for u in user:\n print(f\"Processing user: {u}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/multiple_values/multiple_options/tutorial002_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(number: Annotated[list[float], typer.Option()] = []):\n print(f\"The sum is {sum(number)}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/multiple_values/multiple_options/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(number: list[float] = typer.Option([])):\n print(f\"The sum is {sum(number)}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/multiple_values/options_with_multiple_values/__init__.py",
"content": ""
},
{
"path": "docs_src/multiple_values/options_with_multiple_values/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(user: Annotated[tuple[str, int, bool], typer.Option()] = (None, None, None)):\n username, coins, is_wizard = user\n if not username:\n print(\"No user provided\")\n raise typer.Abort()\n print(f\"The username {username} has {coins} coins\")\n if is_wizard:\n print(\"And this user is a wizard!\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/multiple_values/options_with_multiple_values/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(user: tuple[str, int, bool] = typer.Option((None, None, None))):\n username, coins, is_wizard = user\n if not username:\n print(\"No user provided\")\n raise typer.Abort()\n print(f\"The username {username} has {coins} coins\")\n if is_wizard:\n print(\"And this user is a wizard!\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/one_file_per_command/__init__.py",
"content": ""
},
{
"path": "docs_src/one_file_per_command/app_py310/__init__.py",
"content": ""
},
{
"path": "docs_src/one_file_per_command/app_py310/main.py",
"content": "import typer\n\nfrom .users import app as users_app\nfrom .version import app as version_app\n\napp = typer.Typer()\n\napp.add_typer(version_app)\napp.add_typer(users_app, name=\"users\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/one_file_per_command/app_py310/users/__init__.py",
"content": "import typer\n\nfrom .add import app as add_app\nfrom .delete import app as delete_app\n\napp = typer.Typer()\n\napp.add_typer(add_app)\napp.add_typer(delete_app)\n"
},
{
"path": "docs_src/one_file_per_command/app_py310/users/add.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef add(name: str):\n print(f\"Adding user: {name}\")\n"
},
{
"path": "docs_src/one_file_per_command/app_py310/users/delete.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef delete(name: str):\n print(f\"Deleting user: {name}\")\n"
},
{
"path": "docs_src/one_file_per_command/app_py310/version.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef version():\n print(\"My CLI Version 1.0\")\n"
},
{
"path": "docs_src/options/__init__.py",
"content": ""
},
{
"path": "docs_src/options/callback/__init__.py",
"content": ""
},
{
"path": "docs_src/options/callback/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\ndef name_callback(value: str):\n if value != \"Camila\":\n raise typer.BadParameter(\"Only Camila is allowed\")\n return value\n\n\n@app.command()\ndef main(name: Annotated[str | None, typer.Option(callback=name_callback)] = None):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/callback/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\ndef name_callback(value: str):\n if value != \"Camila\":\n raise typer.BadParameter(\"Only Camila is allowed\")\n return value\n\n\n@app.command()\ndef main(name: str | None = typer.Option(default=None, callback=name_callback)):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/callback/tutorial002_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\ndef name_callback(value: str):\n print(\"Validating name\")\n if value != \"Camila\":\n raise typer.BadParameter(\"Only Camila is allowed\")\n return value\n\n\n@app.command()\ndef main(name: Annotated[str | None, typer.Option(callback=name_callback)] = None):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/callback/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\ndef name_callback(value: str):\n print(\"Validating name\")\n if value != \"Camila\":\n raise typer.BadParameter(\"Only Camila is allowed\")\n return value\n\n\n@app.command()\ndef main(name: str | None = typer.Option(default=None, callback=name_callback)):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/callback/tutorial003_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\ndef name_callback(ctx: typer.Context, value: str):\n if ctx.resilient_parsing:\n return\n print(\"Validating name\")\n if value != \"Camila\":\n raise typer.BadParameter(\"Only Camila is allowed\")\n return value\n\n\n@app.command()\ndef main(name: Annotated[str | None, typer.Option(callback=name_callback)] = None):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/callback/tutorial003_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\ndef name_callback(ctx: typer.Context, value: str):\n if ctx.resilient_parsing:\n return\n print(\"Validating name\")\n if value != \"Camila\":\n raise typer.BadParameter(\"Only Camila is allowed\")\n return value\n\n\n@app.command()\ndef main(name: str | None = typer.Option(default=None, callback=name_callback)):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/callback/tutorial004_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\ndef name_callback(ctx: typer.Context, param: typer.CallbackParam, value: str):\n if ctx.resilient_parsing:\n return\n print(f\"Validating param: {param.name}\")\n if value != \"Camila\":\n raise typer.BadParameter(\"Only Camila is allowed\")\n return value\n\n\n@app.command()\ndef main(name: Annotated[str | None, typer.Option(callback=name_callback)] = None):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/callback/tutorial004_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\ndef name_callback(ctx: typer.Context, param: typer.CallbackParam, value: str):\n if ctx.resilient_parsing:\n return\n print(f\"Validating param: {param.name}\")\n if value != \"Camila\":\n raise typer.BadParameter(\"Only Camila is allowed\")\n return value\n\n\n@app.command()\ndef main(name: str | None = typer.Option(default=None, callback=name_callback)):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/help/__init__.py",
"content": ""
},
{
"path": "docs_src/options/help/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: str,\n lastname: Annotated[str, typer.Option(help=\"Last name of person to greet.\")] = \"\",\n formal: Annotated[bool, typer.Option(help=\"Say hi formally.\")] = False,\n):\n \"\"\"\n Say hi to NAME, optionally with a --lastname.\n\n If --formal is used, say hi very formally.\n \"\"\"\n if formal:\n print(f\"Good day Ms. {name} {lastname}.\")\n else:\n print(f\"Hello {name} {lastname}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/help/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: str,\n lastname: str = typer.Option(\"\", help=\"Last name of person to greet.\"),\n formal: bool = typer.Option(False, help=\"Say hi formally.\"),\n):\n \"\"\"\n Say hi to NAME, optionally with a --lastname.\n\n If --formal is used, say hi very formally.\n \"\"\"\n if formal:\n print(f\"Good day Ms. {name} {lastname}.\")\n else:\n print(f\"Hello {name} {lastname}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/help/tutorial002_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: str,\n lastname: Annotated[str, typer.Option(help=\"Last name of person to greet.\")] = \"\",\n formal: Annotated[\n bool,\n typer.Option(\n help=\"Say hi formally.\", rich_help_panel=\"Customization and Utils\"\n ),\n ] = False,\n debug: Annotated[\n bool,\n typer.Option(\n help=\"Enable debugging.\", rich_help_panel=\"Customization and Utils\"\n ),\n ] = False,\n):\n \"\"\"\n Say hi to NAME, optionally with a --lastname.\n\n If --formal is used, say hi very formally.\n \"\"\"\n if formal:\n print(f\"Good day Ms. {name} {lastname}.\")\n else:\n print(f\"Hello {name} {lastname}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/help/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: str,\n lastname: str = typer.Option(\"\", help=\"Last name of person to greet.\"),\n formal: bool = typer.Option(\n False, help=\"Say hi formally.\", rich_help_panel=\"Customization and Utils\"\n ),\n debug: bool = typer.Option(\n False, help=\"Enable debugging.\", rich_help_panel=\"Customization and Utils\"\n ),\n):\n \"\"\"\n Say hi to NAME, optionally with a --lastname.\n\n If --formal is used, say hi very formally.\n \"\"\"\n if formal:\n print(f\"Good day Ms. {name} {lastname}.\")\n else:\n print(f\"Hello {name} {lastname}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/help/tutorial003_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(fullname: Annotated[str, typer.Option(show_default=False)] = \"Wade Wilson\"):\n print(f\"Hello {fullname}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/help/tutorial003_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(fullname: str = typer.Option(\"Wade Wilson\", show_default=False)):\n print(f\"Hello {fullname}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/help/tutorial004_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n fullname: Annotated[\n str, typer.Option(show_default=\"Deadpoolio the amazing's name\")\n ] = \"Wade Wilson\",\n):\n print(f\"Hello {fullname}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/help/tutorial004_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n fullname: str = typer.Option(\n \"Wade Wilson\", show_default=\"Deadpoolio the amazing's name\"\n ),\n):\n print(f\"Hello {fullname}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/name/__init__.py",
"content": ""
},
{
"path": "docs_src/options/name/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(user_name: Annotated[str, typer.Option(\"--name\")]):\n print(f\"Hello {user_name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/name/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(user_name: str = typer.Option(..., \"--name\")):\n print(f\"Hello {user_name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/name/tutorial002_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(user_name: Annotated[str, typer.Option(\"--name\", \"-n\")]):\n print(f\"Hello {user_name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/name/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(user_name: str = typer.Option(..., \"--name\", \"-n\")):\n print(f\"Hello {user_name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/name/tutorial003_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(user_name: Annotated[str, typer.Option(\"-n\")]):\n print(f\"Hello {user_name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/name/tutorial003_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(user_name: str = typer.Option(..., \"-n\")):\n print(f\"Hello {user_name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/name/tutorial004_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(user_name: Annotated[str, typer.Option(\"--user-name\", \"-n\")]):\n print(f\"Hello {user_name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/name/tutorial004_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(user_name: str = typer.Option(..., \"--user-name\", \"-n\")):\n print(f\"Hello {user_name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/name/tutorial005_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: Annotated[str, typer.Option(\"--name\", \"-n\")],\n formal: Annotated[bool, typer.Option(\"--formal\", \"-f\")] = False,\n):\n if formal:\n print(f\"Good day Ms. {name}.\")\n else:\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/name/tutorial005_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: str = typer.Option(..., \"--name\", \"-n\"),\n formal: bool = typer.Option(False, \"--formal\", \"-f\"),\n):\n if formal:\n print(f\"Good day Ms. {name}.\")\n else:\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/password/__init__.py",
"content": ""
},
{
"path": "docs_src/options/password/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: str,\n email: Annotated[str, typer.Option(prompt=True, confirmation_prompt=True)],\n):\n print(f\"Hello {name}, your email is {email}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/password/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: str, email: str = typer.Option(..., prompt=True, confirmation_prompt=True)\n):\n print(f\"Hello {name}, your email is {email}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/password/tutorial002_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: str,\n password: Annotated[\n str, typer.Option(prompt=True, confirmation_prompt=True, hide_input=True)\n ],\n):\n print(f\"Hello {name}. Doing something very secure with password.\")\n print(f\"...just kidding, here it is, very insecure: {password}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/password/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: str,\n password: str = typer.Option(\n ..., prompt=True, confirmation_prompt=True, hide_input=True\n ),\n):\n print(f\"Hello {name}. Doing something very secure with password.\")\n print(f\"...just kidding, here it is, very insecure: {password}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/prompt/__init__.py",
"content": ""
},
{
"path": "docs_src/options/prompt/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str, lastname: Annotated[str, typer.Option(prompt=True)]):\n print(f\"Hello {name} {lastname}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/prompt/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str, lastname: str = typer.Option(..., prompt=True)):\n print(f\"Hello {name} {lastname}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/prompt/tutorial002_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: str,\n lastname: Annotated[str, typer.Option(prompt=\"Please tell me your last name\")],\n):\n print(f\"Hello {name} {lastname}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/prompt/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: str, lastname: str = typer.Option(..., prompt=\"Please tell me your last name\")\n):\n print(f\"Hello {name} {lastname}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/prompt/tutorial003_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n project_name: Annotated[str, typer.Option(prompt=True, confirmation_prompt=True)],\n):\n print(f\"Deleting project {project_name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/prompt/tutorial003_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(project_name: str = typer.Option(..., prompt=True, confirmation_prompt=True)):\n print(f\"Deleting project {project_name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/required/__init__.py",
"content": ""
},
{
"path": "docs_src/options/required/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str, lastname: Annotated[str, typer.Option()]):\n print(f\"Hello {name} {lastname}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/required/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str, lastname: str = typer.Option()):\n print(f\"Hello {name} {lastname}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/required/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str, lastname: str = typer.Option(default=...)):\n print(f\"Hello {name} {lastname}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/version/__init__.py",
"content": ""
},
{
"path": "docs_src/options/version/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\n__version__ = \"0.1.0\"\n\napp = typer.Typer()\n\n\ndef version_callback(value: bool):\n if value:\n print(f\"Awesome CLI Version: {__version__}\")\n raise typer.Exit()\n\n\n@app.command()\ndef main(\n name: Annotated[str, typer.Option()] = \"World\",\n version: Annotated[\n bool | None, typer.Option(\"--version\", callback=version_callback)\n ] = None,\n):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/version/tutorial001_py310.py",
"content": "import typer\n\n__version__ = \"0.1.0\"\n\napp = typer.Typer()\n\n\ndef version_callback(value: bool):\n if value:\n print(f\"Awesome CLI Version: {__version__}\")\n raise typer.Exit()\n\n\n@app.command()\ndef main(\n name: str = typer.Option(\"World\"),\n version: bool | None = typer.Option(None, \"--version\", callback=version_callback),\n):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/version/tutorial002_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\n__version__ = \"0.1.0\"\n\napp = typer.Typer()\n\n\ndef version_callback(value: bool):\n if value:\n print(f\"Awesome CLI Version: {__version__}\")\n raise typer.Exit()\n\n\ndef name_callback(name: str):\n if name != \"Camila\":\n raise typer.BadParameter(\"Only Camila is allowed\")\n return name\n\n\n@app.command()\ndef main(\n name: Annotated[str, typer.Option(callback=name_callback)],\n version: Annotated[\n bool | None, typer.Option(\"--version\", callback=version_callback)\n ] = None,\n):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/version/tutorial002_py310.py",
"content": "import typer\n\n__version__ = \"0.1.0\"\n\napp = typer.Typer()\n\n\ndef version_callback(value: bool):\n if value:\n print(f\"Awesome CLI Version: {__version__}\")\n raise typer.Exit()\n\n\ndef name_callback(name: str):\n if name != \"Camila\":\n raise typer.BadParameter(\"Only Camila is allowed\")\n return name\n\n\n@app.command()\ndef main(\n name: str = typer.Option(..., callback=name_callback),\n version: bool | None = typer.Option(None, \"--version\", callback=version_callback),\n):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/version/tutorial003_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\n__version__ = \"0.1.0\"\n\napp = typer.Typer()\n\n\ndef version_callback(value: bool):\n if value:\n print(f\"Awesome CLI Version: {__version__}\")\n raise typer.Exit()\n\n\ndef name_callback(name: str):\n if name != \"Camila\":\n raise typer.BadParameter(\"Only Camila is allowed\")\n return name\n\n\n@app.command()\ndef main(\n name: Annotated[str, typer.Option(callback=name_callback)],\n version: Annotated[\n bool | None,\n typer.Option(\"--version\", callback=version_callback, is_eager=True),\n ] = None,\n):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options/version/tutorial003_py310.py",
"content": "import typer\n\n__version__ = \"0.1.0\"\n\napp = typer.Typer()\n\n\ndef version_callback(value: bool):\n if value:\n print(f\"Awesome CLI Version: {__version__}\")\n raise typer.Exit()\n\n\ndef name_callback(name: str):\n if name != \"Camila\":\n raise typer.BadParameter(\"Only Camila is allowed\")\n return name\n\n\n@app.command()\ndef main(\n name: str = typer.Option(..., callback=name_callback),\n version: bool | None = typer.Option(\n None, \"--version\", callback=version_callback, is_eager=True\n ),\n):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options_autocompletion/__init__.py",
"content": ""
},
{
"path": "docs_src/options_autocompletion/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: Annotated[str, typer.Option(help=\"The name to say hi to.\")] = \"World\"):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options_autocompletion/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str = typer.Option(\"World\", help=\"The name to say hi to.\")):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options_autocompletion/tutorial002_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\n\ndef complete_name():\n return [\"Camila\", \"Carlos\", \"Sebastian\"]\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: Annotated[\n str, typer.Option(help=\"The name to say hi to.\", autocompletion=complete_name)\n ] = \"World\",\n):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options_autocompletion/tutorial002_py310.py",
"content": "import typer\n\n\ndef complete_name():\n return [\"Camila\", \"Carlos\", \"Sebastian\"]\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: str = typer.Option(\n \"World\", help=\"The name to say hi to.\", autocompletion=complete_name\n ),\n):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options_autocompletion/tutorial003_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\nvalid_names = [\"Camila\", \"Carlos\", \"Sebastian\"]\n\n\ndef complete_name(incomplete: str):\n completion = []\n for name in valid_names:\n if name.startswith(incomplete):\n completion.append(name)\n return completion\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: Annotated[\n str, typer.Option(help=\"The name to say hi to.\", autocompletion=complete_name)\n ] = \"World\",\n):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options_autocompletion/tutorial003_py310.py",
"content": "import typer\n\nvalid_names = [\"Camila\", \"Carlos\", \"Sebastian\"]\n\n\ndef complete_name(incomplete: str):\n completion = []\n for name in valid_names:\n if name.startswith(incomplete):\n completion.append(name)\n return completion\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: str = typer.Option(\n \"World\", help=\"The name to say hi to.\", autocompletion=complete_name\n ),\n):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options_autocompletion/tutorial004_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\nvalid_completion_items = [\n (\"Camila\", \"The reader of books.\"),\n (\"Carlos\", \"The writer of scripts.\"),\n (\"Sebastian\", \"The type hints guy.\"),\n]\n\n\ndef complete_name(incomplete: str):\n completion = []\n for name, help_text in valid_completion_items:\n if name.startswith(incomplete):\n completion_item = (name, help_text)\n completion.append(completion_item)\n return completion\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: Annotated[\n str, typer.Option(help=\"The name to say hi to.\", autocompletion=complete_name)\n ] = \"World\",\n):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options_autocompletion/tutorial004_py310.py",
"content": "import typer\n\nvalid_completion_items = [\n (\"Camila\", \"The reader of books.\"),\n (\"Carlos\", \"The writer of scripts.\"),\n (\"Sebastian\", \"The type hints guy.\"),\n]\n\n\ndef complete_name(incomplete: str):\n completion = []\n for name, help_text in valid_completion_items:\n if name.startswith(incomplete):\n completion_item = (name, help_text)\n completion.append(completion_item)\n return completion\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: str = typer.Option(\n \"World\", help=\"The name to say hi to.\", autocompletion=complete_name\n ),\n):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options_autocompletion/tutorial005_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\nvalid_completion_items = [\n (\"Camila\", \"The reader of books.\"),\n (\"Carlos\", \"The writer of scripts.\"),\n (\"Sebastian\", \"The type hints guy.\"),\n]\n\n\ndef complete_name(incomplete: str):\n for name, help_text in valid_completion_items:\n if name.startswith(incomplete):\n yield (name, help_text)\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: Annotated[\n str, typer.Option(help=\"The name to say hi to.\", autocompletion=complete_name)\n ] = \"World\",\n):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options_autocompletion/tutorial005_py310.py",
"content": "import typer\n\nvalid_completion_items = [\n (\"Camila\", \"The reader of books.\"),\n (\"Carlos\", \"The writer of scripts.\"),\n (\"Sebastian\", \"The type hints guy.\"),\n]\n\n\ndef complete_name(incomplete: str):\n for name, help_text in valid_completion_items:\n if name.startswith(incomplete):\n yield (name, help_text)\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: str = typer.Option(\n \"World\", help=\"The name to say hi to.\", autocompletion=complete_name\n ),\n):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options_autocompletion/tutorial006_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: Annotated[list[str], typer.Option(help=\"The name to say hi to.\")] = [\"World\"],\n):\n for each_name in name:\n print(f\"Hello {each_name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options_autocompletion/tutorial006_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: list[str] = typer.Option([\"World\"], help=\"The name to say hi to.\")):\n for each_name in name:\n print(f\"Hello {each_name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options_autocompletion/tutorial007_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\nvalid_completion_items = [\n (\"Camila\", \"The reader of books.\"),\n (\"Carlos\", \"The writer of scripts.\"),\n (\"Sebastian\", \"The type hints guy.\"),\n]\n\n\ndef complete_name(ctx: typer.Context, incomplete: str):\n names = ctx.params.get(\"name\") or []\n for name, help_text in valid_completion_items:\n if name.startswith(incomplete) and name not in names:\n yield (name, help_text)\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: Annotated[\n list[str],\n typer.Option(help=\"The name to say hi to.\", autocompletion=complete_name),\n ] = [\"World\"],\n):\n for n in name:\n print(f\"Hello {n}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options_autocompletion/tutorial007_py310.py",
"content": "import typer\n\nvalid_completion_items = [\n (\"Camila\", \"The reader of books.\"),\n (\"Carlos\", \"The writer of scripts.\"),\n (\"Sebastian\", \"The type hints guy.\"),\n]\n\n\ndef complete_name(ctx: typer.Context, incomplete: str):\n names = ctx.params.get(\"name\") or []\n for name, help_text in valid_completion_items:\n if name.startswith(incomplete) and name not in names:\n yield (name, help_text)\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: list[str] = typer.Option(\n [\"World\"], help=\"The name to say hi to.\", autocompletion=complete_name\n ),\n):\n for n in name:\n print(f\"Hello {n}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options_autocompletion/tutorial008_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\nfrom rich.console import Console\n\nvalid_completion_items = [\n (\"Camila\", \"The reader of books.\"),\n (\"Carlos\", \"The writer of scripts.\"),\n (\"Sebastian\", \"The type hints guy.\"),\n]\n\nerr_console = Console(stderr=True)\n\n\ndef complete_name(args: list[str], incomplete: str):\n err_console.print(f\"{args}\")\n for name, help_text in valid_completion_items:\n if name.startswith(incomplete):\n yield (name, help_text)\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: Annotated[\n list[str],\n typer.Option(help=\"The name to say hi to.\", autocompletion=complete_name),\n ] = [\"World\"],\n):\n for n in name:\n print(f\"Hello {n}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options_autocompletion/tutorial008_py310.py",
"content": "import typer\nfrom rich.console import Console\n\nvalid_completion_items = [\n (\"Camila\", \"The reader of books.\"),\n (\"Carlos\", \"The writer of scripts.\"),\n (\"Sebastian\", \"The type hints guy.\"),\n]\n\nerr_console = Console(stderr=True)\n\n\ndef complete_name(args: list[str], incomplete: str):\n err_console.print(f\"{args}\")\n for name, help_text in valid_completion_items:\n if name.startswith(incomplete):\n yield (name, help_text)\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: list[str] = typer.Option(\n [\"World\"], help=\"The name to say hi to.\", autocompletion=complete_name\n ),\n):\n for n in name:\n print(f\"Hello {n}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options_autocompletion/tutorial009_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\nfrom rich.console import Console\n\nvalid_completion_items = [\n (\"Camila\", \"The reader of books.\"),\n (\"Carlos\", \"The writer of scripts.\"),\n (\"Sebastian\", \"The type hints guy.\"),\n]\n\nerr_console = Console(stderr=True)\n\n\ndef complete_name(ctx: typer.Context, args: list[str], incomplete: str):\n err_console.print(f\"{args}\")\n names = ctx.params.get(\"name\") or []\n for name, help_text in valid_completion_items:\n if name.startswith(incomplete) and name not in names:\n yield (name, help_text)\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: Annotated[\n list[str],\n typer.Option(help=\"The name to say hi to.\", autocompletion=complete_name),\n ] = [\"World\"],\n):\n for n in name:\n print(f\"Hello {n}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/options_autocompletion/tutorial009_py310.py",
"content": "import typer\nfrom rich.console import Console\n\nvalid_completion_items = [\n (\"Camila\", \"The reader of books.\"),\n (\"Carlos\", \"The writer of scripts.\"),\n (\"Sebastian\", \"The type hints guy.\"),\n]\n\nerr_console = Console(stderr=True)\n\n\ndef complete_name(ctx: typer.Context, args: list[str], incomplete: str):\n err_console.print(f\"{args}\")\n names = ctx.params.get(\"name\") or []\n for name, help_text in valid_completion_items:\n if name.startswith(incomplete) and name not in names:\n yield (name, help_text)\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n name: list[str] = typer.Option(\n [\"World\"], help=\"The name to say hi to.\", autocompletion=complete_name\n ),\n):\n for n in name:\n print(f\"Hello {n}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/__init__.py",
"content": ""
},
{
"path": "docs_src/parameter_types/bool/__init__.py",
"content": ""
},
{
"path": "docs_src/parameter_types/bool/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(force: Annotated[bool, typer.Option(\"--force\")] = False):\n if force:\n print(\"Forcing operation\")\n else:\n print(\"Not forcing\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/bool/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(force: bool = typer.Option(False, \"--force\")):\n if force:\n print(\"Forcing operation\")\n else:\n print(\"Not forcing\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/bool/tutorial002_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(accept: Annotated[bool | None, typer.Option(\"--accept/--reject\")] = None):\n if accept is None:\n print(\"I don't know what you want yet\")\n elif accept:\n print(\"Accepting!\")\n else:\n print(\"Rejecting!\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/bool/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(accept: bool | None = typer.Option(None, \"--accept/--reject\")):\n if accept is None:\n print(\"I don't know what you want yet\")\n elif accept:\n print(\"Accepting!\")\n else:\n print(\"Rejecting!\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/bool/tutorial003_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(force: Annotated[bool, typer.Option(\"--force/--no-force\", \"-f/-F\")] = False):\n if force:\n print(\"Forcing operation\")\n else:\n print(\"Not forcing\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/bool/tutorial003_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(force: bool = typer.Option(False, \"--force/--no-force\", \"-f/-F\")):\n if force:\n print(\"Forcing operation\")\n else:\n print(\"Not forcing\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/bool/tutorial004_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(in_prod: Annotated[bool, typer.Option(\" /--demo\", \" /-d\")] = True):\n if in_prod:\n print(\"Running in production\")\n else:\n print(\"Running demo\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/bool/tutorial004_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(in_prod: bool = typer.Option(True, \" /--demo\", \" /-d\")):\n if in_prod:\n print(\"Running in production\")\n else:\n print(\"Running demo\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/custom_types/__init__.py",
"content": ""
},
{
"path": "docs_src/parameter_types/custom_types/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\n\nclass CustomClass:\n def __init__(self, value: str):\n self.value = value\n\n def __str__(self):\n return f\"\"\n\n\ndef parse_custom_class(value: str):\n return CustomClass(value * 2)\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n custom_arg: Annotated[CustomClass, typer.Argument(parser=parse_custom_class)],\n custom_opt: Annotated[CustomClass, typer.Option(parser=parse_custom_class)] = \"Foo\",\n):\n print(f\"custom_arg is {custom_arg}\")\n print(f\"--custom-opt is {custom_opt}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/custom_types/tutorial001_py310.py",
"content": "import typer\n\n\nclass CustomClass:\n def __init__(self, value: str):\n self.value = value\n\n def __str__(self):\n return f\"\"\n\n\ndef parse_custom_class(value: str):\n return CustomClass(value * 2)\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n custom_arg: CustomClass = typer.Argument(parser=parse_custom_class),\n custom_opt: CustomClass = typer.Option(\"Foo\", parser=parse_custom_class),\n):\n print(f\"custom_arg is {custom_arg}\")\n print(f\"--custom-opt is {custom_opt}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/datetime/__init__.py",
"content": ""
},
{
"path": "docs_src/parameter_types/datetime/tutorial001_py310.py",
"content": "from datetime import datetime\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(birth: datetime):\n print(f\"Interesting day to be born: {birth}\")\n print(f\"Birth hour: {birth.hour}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/datetime/tutorial002_an_py310.py",
"content": "from datetime import datetime\nfrom typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n launch_date: Annotated[\n datetime,\n typer.Argument(\n formats=[\"%Y-%m-%d\", \"%Y-%m-%dT%H:%M:%S\", \"%Y-%m-%d %H:%M:%S\", \"%m/%d/%Y\"]\n ),\n ],\n):\n print(f\"Launch will be at: {launch_date}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/datetime/tutorial002_py310.py",
"content": "from datetime import datetime\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n launch_date: datetime = typer.Argument(\n ..., formats=[\"%Y-%m-%d\", \"%Y-%m-%dT%H:%M:%S\", \"%Y-%m-%d %H:%M:%S\", \"%m/%d/%Y\"]\n ),\n):\n print(f\"Launch will be at: {launch_date}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/enum/__init__.py",
"content": ""
},
{
"path": "docs_src/parameter_types/enum/tutorial001_py310.py",
"content": "from enum import Enum\n\nimport typer\n\n\nclass NeuralNetwork(str, Enum):\n simple = \"simple\"\n conv = \"conv\"\n lstm = \"lstm\"\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(network: NeuralNetwork = NeuralNetwork.simple):\n print(f\"Training neural network of type: {network.value}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/enum/tutorial002_an_py310.py",
"content": "from enum import Enum\nfrom typing import Annotated\n\nimport typer\n\n\nclass NeuralNetwork(str, Enum):\n simple = \"simple\"\n conv = \"conv\"\n lstm = \"lstm\"\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n network: Annotated[\n NeuralNetwork, typer.Option(case_sensitive=False)\n ] = NeuralNetwork.simple,\n):\n print(f\"Training neural network of type: {network.value}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/enum/tutorial002_py310.py",
"content": "from enum import Enum\n\nimport typer\n\n\nclass NeuralNetwork(str, Enum):\n simple = \"simple\"\n conv = \"conv\"\n lstm = \"lstm\"\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n network: NeuralNetwork = typer.Option(NeuralNetwork.simple, case_sensitive=False),\n):\n print(f\"Training neural network of type: {network.value}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/enum/tutorial003_an_py310.py",
"content": "from enum import Enum\nfrom typing import Annotated\n\nimport typer\n\n\nclass Food(str, Enum):\n food_1 = \"Eggs\"\n food_2 = \"Bacon\"\n food_3 = \"Cheese\"\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(groceries: Annotated[list[Food], typer.Option()] = [Food.food_1, Food.food_3]):\n print(f\"Buying groceries: {', '.join([f.value for f in groceries])}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/enum/tutorial003_py310.py",
"content": "from enum import Enum\n\nimport typer\n\n\nclass Food(str, Enum):\n food_1 = \"Eggs\"\n food_2 = \"Bacon\"\n food_3 = \"Cheese\"\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(groceries: list[Food] = typer.Option([Food.food_1, Food.food_3])):\n print(f\"Buying groceries: {', '.join([f.value for f in groceries])}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/enum/tutorial004_an_py310.py",
"content": "from typing import Annotated, Literal\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n network: Annotated[Literal[\"simple\", \"conv\", \"lstm\"], typer.Option()] = \"simple\",\n):\n print(f\"Training neural network of type: {network}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/enum/tutorial004_py310.py",
"content": "from typing import Literal\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(network: Literal[\"simple\", \"conv\", \"lstm\"] = typer.Option(\"simple\")):\n print(f\"Training neural network of type: {network}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/file/__init__.py",
"content": ""
},
{
"path": "docs_src/parameter_types/file/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(config: Annotated[typer.FileText, typer.Option()]):\n for line in config:\n print(f\"Config line: {line}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/file/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(config: typer.FileText = typer.Option(...)):\n for line in config:\n print(f\"Config line: {line}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/file/tutorial002_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(config: Annotated[typer.FileTextWrite, typer.Option()]):\n config.write(\"Some config written by the app\")\n print(\"Config written\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/file/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(config: typer.FileTextWrite = typer.Option(...)):\n config.write(\"Some config written by the app\")\n print(\"Config written\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/file/tutorial003_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(file: Annotated[typer.FileBinaryRead, typer.Option()]):\n processed_total = 0\n for bytes_chunk in file:\n # Process the bytes in bytes_chunk\n processed_total += len(bytes_chunk)\n print(f\"Processed bytes total: {processed_total}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/file/tutorial003_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(file: typer.FileBinaryRead = typer.Option(...)):\n processed_total = 0\n for bytes_chunk in file:\n # Process the bytes in bytes_chunk\n processed_total += len(bytes_chunk)\n print(f\"Processed bytes total: {processed_total}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/file/tutorial004_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(file: Annotated[typer.FileBinaryWrite, typer.Option()]):\n first_line_str = \"some settings\\n\"\n # You cannot write str directly to a binary file, you have to encode it to get bytes\n first_line_bytes = first_line_str.encode(\"utf-8\")\n # Then you can write the bytes\n file.write(first_line_bytes)\n # This is already bytes, it starts with b\"\n second_line = b\"la cig\\xc3\\xbce\\xc3\\xb1a trae al ni\\xc3\\xb1o\"\n file.write(second_line)\n print(\"Binary file written\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/file/tutorial004_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(file: typer.FileBinaryWrite = typer.Option(...)):\n first_line_str = \"some settings\\n\"\n # You cannot write str directly to a binary file, you have to encode it to get bytes\n first_line_bytes = first_line_str.encode(\"utf-8\")\n # Then you can write the bytes\n file.write(first_line_bytes)\n # This is already bytes, it starts with b\"\n second_line = b\"la cig\\xc3\\xbce\\xc3\\xb1a trae al ni\\xc3\\xb1o\"\n file.write(second_line)\n print(\"Binary file written\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/file/tutorial005_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(config: Annotated[typer.FileText, typer.Option(mode=\"a\")]):\n config.write(\"This is a single line\\n\")\n print(\"Config line written\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/file/tutorial005_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(config: typer.FileText = typer.Option(..., mode=\"a\")):\n config.write(\"This is a single line\\n\")\n print(\"Config line written\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/index/__init__.py",
"content": ""
},
{
"path": "docs_src/parameter_types/index/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str, age: int = 20, height_meters: float = 1.89, female: bool = True):\n print(f\"NAME is {name}, of type: {type(name)}\")\n print(f\"--age is {age}, of type: {type(age)}\")\n print(f\"--height-meters is {height_meters}, of type: {type(height_meters)}\")\n print(f\"--female is {female}, of type: {type(female)}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/number/__init__.py",
"content": ""
},
{
"path": "docs_src/parameter_types/number/tutorial001_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n id: Annotated[int, typer.Argument(min=0, max=1000)],\n age: Annotated[int, typer.Option(min=18)] = 20,\n score: Annotated[float, typer.Option(max=100)] = 0,\n):\n print(f\"ID is {id}\")\n print(f\"--age is {age}\")\n print(f\"--score is {score}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/number/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n id: int = typer.Argument(..., min=0, max=1000),\n age: int = typer.Option(20, min=18),\n score: float = typer.Option(0, max=100),\n):\n print(f\"ID is {id}\")\n print(f\"--age is {age}\")\n print(f\"--score is {score}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/number/tutorial002_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n id: Annotated[int, typer.Argument(min=0, max=1000)],\n rank: Annotated[int, typer.Option(max=10, clamp=True)] = 0,\n score: Annotated[float, typer.Option(min=0, max=100, clamp=True)] = 0,\n):\n print(f\"ID is {id}\")\n print(f\"--rank is {rank}\")\n print(f\"--score is {score}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/number/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n id: int = typer.Argument(..., min=0, max=1000),\n rank: int = typer.Option(0, max=10, clamp=True),\n score: float = typer.Option(0, min=0, max=100, clamp=True),\n):\n print(f\"ID is {id}\")\n print(f\"--rank is {rank}\")\n print(f\"--score is {score}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/number/tutorial003_an_py310.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(verbose: Annotated[int, typer.Option(\"--verbose\", \"-v\", count=True)] = 0):\n print(f\"Verbose level is {verbose}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/number/tutorial003_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(verbose: int = typer.Option(0, \"--verbose\", \"-v\", count=True)):\n print(f\"Verbose level is {verbose}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/path/__init__.py",
"content": ""
},
{
"path": "docs_src/parameter_types/path/tutorial001_an_py310.py",
"content": "from pathlib import Path\nfrom typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(config: Annotated[Path | None, typer.Option()] = None):\n if config is None:\n print(\"No config file\")\n raise typer.Abort()\n if config.is_file():\n text = config.read_text()\n print(f\"Config file contents: {text}\")\n elif config.is_dir():\n print(\"Config is a directory, will use all its config files\")\n elif not config.exists():\n print(\"The config doesn't exist\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/path/tutorial001_py310.py",
"content": "from pathlib import Path\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(config: Path | None = typer.Option(None)):\n if config is None:\n print(\"No config file\")\n raise typer.Abort()\n if config.is_file():\n text = config.read_text()\n print(f\"Config file contents: {text}\")\n elif config.is_dir():\n print(\"Config is a directory, will use all its config files\")\n elif not config.exists():\n print(\"The config doesn't exist\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/path/tutorial002_an_py310.py",
"content": "from pathlib import Path\nfrom typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n config: Annotated[\n Path,\n typer.Option(\n exists=True,\n file_okay=True,\n dir_okay=False,\n writable=False,\n readable=True,\n resolve_path=True,\n ),\n ],\n):\n text = config.read_text()\n print(f\"Config file contents: {text}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/path/tutorial002_py310.py",
"content": "from pathlib import Path\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(\n config: Path = typer.Option(\n ...,\n exists=True,\n file_okay=True,\n dir_okay=False,\n writable=False,\n readable=True,\n resolve_path=True,\n ),\n):\n text = config.read_text()\n print(f\"Config file contents: {text}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/parameter_types/uuid/__init__.py",
"content": ""
},
{
"path": "docs_src/parameter_types/uuid/tutorial001_py310.py",
"content": "from uuid import UUID\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(user_id: UUID):\n print(f\"USER_ID is {user_id}\")\n print(f\"UUID version is: {user_id.version}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/printing/__init__.py",
"content": ""
},
{
"path": "docs_src/printing/tutorial001_py310.py",
"content": "import typer\nfrom rich import print\n\ndata = {\n \"name\": \"Rick\",\n \"age\": 42,\n \"items\": [{\"name\": \"Portal Gun\"}, {\"name\": \"Plumbus\"}],\n \"active\": True,\n \"affiliation\": None,\n}\n\napp = typer.Typer()\n\n\n@app.command()\ndef main():\n print(\"Here's the data\")\n print(data)\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/printing/tutorial002_py310.py",
"content": "import typer\nfrom rich import print\n\napp = typer.Typer()\n\n\n@app.command()\ndef main():\n print(\"[bold red]Alert![/bold red] [green]Portal gun[/green] shooting! :boom:\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/printing/tutorial003_py310.py",
"content": "import typer\nfrom rich.console import Console\nfrom rich.table import Table\n\nconsole = Console()\n\napp = typer.Typer()\n\n\n@app.command()\ndef main():\n table = Table(\"Name\", \"Item\")\n table.add_row(\"Rick\", \"Portal Gun\")\n table.add_row(\"Morty\", \"Plumbus\")\n console.print(table)\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/printing/tutorial004_py310.py",
"content": "import typer\nfrom rich.console import Console\n\nerr_console = Console(stderr=True)\n\napp = typer.Typer()\n\n\n@app.command()\ndef main():\n err_console.print(\"Here is something written to standard error\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/printing/tutorial005_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(good: bool = True):\n message_start = \"everything is \"\n if good:\n ending = typer.style(\"good\", fg=typer.colors.GREEN, bold=True)\n else:\n ending = typer.style(\"bad\", fg=typer.colors.WHITE, bg=typer.colors.RED)\n message = message_start + ending\n typer.echo(message)\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/printing/tutorial006_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str):\n typer.secho(f\"Welcome here {name}\", fg=typer.colors.MAGENTA)\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/progressbar/__init__.py",
"content": ""
},
{
"path": "docs_src/progressbar/tutorial001_py310.py",
"content": "import time\n\nimport typer\nfrom rich.progress import track\n\napp = typer.Typer()\n\n\n@app.command()\ndef main():\n total = 0\n for value in track(range(100), description=\"Processing...\"):\n # Fake processing time\n time.sleep(0.01)\n total += 1\n print(f\"Processed {total} things.\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/progressbar/tutorial002_py310.py",
"content": "import time\n\nimport typer\nfrom rich.progress import Progress, SpinnerColumn, TextColumn\n\napp = typer.Typer()\n\n\n@app.command()\ndef main():\n with Progress(\n SpinnerColumn(),\n TextColumn(\"[progress.description]{task.description}\"),\n transient=True,\n ) as progress:\n progress.add_task(description=\"Processing...\", total=None)\n progress.add_task(description=\"Preparing...\", total=None)\n time.sleep(5)\n print(\"Done!\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/progressbar/tutorial003_py310.py",
"content": "import time\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main():\n total = 0\n with typer.progressbar(range(100)) as progress:\n for value in progress:\n # Fake processing time\n time.sleep(0.01)\n total += 1\n print(f\"Processed {total} things.\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/progressbar/tutorial004_py310.py",
"content": "import time\n\nimport typer\n\n\ndef iterate_user_ids():\n # Let's imagine this is a web API, not a range()\n for i in range(100):\n yield i\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main():\n total = 0\n with typer.progressbar(iterate_user_ids(), length=100) as progress:\n for value in progress:\n # Fake processing time\n time.sleep(0.01)\n total += 1\n print(f\"Processed {total} user IDs.\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/progressbar/tutorial005_py310.py",
"content": "import time\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main():\n total = 0\n with typer.progressbar(range(100), label=\"Processing\") as progress:\n for value in progress:\n # Fake processing time\n time.sleep(0.01)\n total += 1\n print(f\"Processed {total} things.\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/progressbar/tutorial006_py310.py",
"content": "import time\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main():\n total = 1000\n with typer.progressbar(length=total) as progress:\n for batch in range(4):\n # Fake processing time\n time.sleep(1)\n # Increment by 250 on each loop iteration\n # (it will take 4 seconds to reach 1000)\n progress.update(250)\n print(f\"Processed {total} things in batches.\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/prompt/__init__.py",
"content": ""
},
{
"path": "docs_src/prompt/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main():\n person_name = typer.prompt(\"What's your name?\")\n print(f\"Hello {person_name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/prompt/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main():\n delete = typer.confirm(\"Are you sure you want to delete it?\")\n if not delete:\n print(\"Not deleting\")\n raise typer.Abort()\n print(\"Deleting it!\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/prompt/tutorial003_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main():\n delete = typer.confirm(\"Are you sure you want to delete it?\", abort=True)\n print(\"Deleting it!\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/prompt/tutorial004_py310.py",
"content": "import typer\nfrom rich.prompt import Prompt\n\napp = typer.Typer()\n\n\n@app.command()\ndef main():\n name = Prompt.ask(\"Enter your name :sunglasses:\")\n print(f\"Hey there {name}!\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/__init__.py",
"content": ""
},
{
"path": "docs_src/subcommands/callback_override/__init__.py",
"content": ""
},
{
"path": "docs_src/subcommands/callback_override/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\nusers_app = typer.Typer()\napp.add_typer(users_app, name=\"users\")\n\n\n@users_app.callback()\ndef users_callback():\n print(\"Running a users command\")\n\n\n@users_app.command()\ndef create(name: str):\n print(f\"Creating user: {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/callback_override/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\ndef users_callback():\n print(\"Running a users command\")\n\n\nusers_app = typer.Typer(callback=users_callback)\napp.add_typer(users_app, name=\"users\")\n\n\n@users_app.command()\ndef create(name: str):\n print(f\"Creating user: {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/callback_override/tutorial003_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\ndef default_callback():\n print(\"Running a users command\")\n\n\nusers_app = typer.Typer(callback=default_callback)\napp.add_typer(users_app, name=\"users\")\n\n\n@users_app.callback()\ndef user_callback():\n print(\"Callback override, running users command\")\n\n\n@users_app.command()\ndef create(name: str):\n print(f\"Creating user: {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/callback_override/tutorial004_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\ndef default_callback():\n print(\"Running a users command\")\n\n\nusers_app = typer.Typer(callback=default_callback)\n\n\ndef callback_for_add_typer():\n print(\"I have the high land! Running users command\")\n\n\napp.add_typer(users_app, name=\"users\", callback=callback_for_add_typer)\n\n\n@users_app.callback()\ndef user_callback():\n print(\"Callback override, running users command\")\n\n\n@users_app.command()\ndef create(name: str):\n print(f\"Creating user: {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/name_help/__init__.py",
"content": ""
},
{
"path": "docs_src/subcommands/name_help/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\nusers_app = typer.Typer()\napp.add_typer(users_app, name=\"users\", help=\"Manage users in the app.\")\n\n\n@users_app.command()\ndef create(name: str):\n print(f\"Creating user: {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/name_help/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\nusers_app = typer.Typer()\napp.add_typer(users_app, name=\"users\")\n\n\n@users_app.callback()\ndef users():\n \"\"\"\n Manage users in the app.\n \"\"\"\n\n\n@users_app.command()\ndef create(name: str):\n print(f\"Creating user: {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/name_help/tutorial003_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\ndef users():\n \"\"\"\n Manage users in the app.\n \"\"\"\n\n\nusers_app = typer.Typer(callback=users, name=\"users\")\napp.add_typer(users_app)\n\n\n@users_app.command()\ndef create(name: str):\n print(f\"Creating user: {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/name_help/tutorial004_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\ndef old_callback():\n \"\"\"\n Old callback help.\n \"\"\"\n\n\nusers_app = typer.Typer(callback=old_callback)\napp.add_typer(users_app, name=\"users\")\n\n\n@users_app.callback()\ndef users():\n \"\"\"\n Manage users in the app.\n \"\"\"\n\n\n@users_app.command()\ndef create(name: str):\n print(f\"Creating user: {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/name_help/tutorial005_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\ndef old_callback():\n \"\"\"\n Old callback help.\n \"\"\"\n\n\nusers_app = typer.Typer(callback=old_callback, name=\"users\")\n\n\ndef new_users():\n \"\"\"\n I have the highland! Create some users.\n \"\"\"\n\n\napp.add_typer(users_app, callback=new_users, name=\"new-users\")\n\n\n@users_app.callback()\ndef users():\n \"\"\"\n Manage users in the app.\n \"\"\"\n\n\n@users_app.command()\ndef create(name: str):\n print(f\"Creating user: {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/name_help/tutorial006_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\ndef old_callback():\n \"\"\"\n Old callback help.\n \"\"\"\n\n\nusers_app = typer.Typer(callback=old_callback, name=\"exp-users\", help=\"Explicit help.\")\n\n\ndef new_users():\n \"\"\"\n I have the highland! Create some users.\n \"\"\"\n\n\napp.add_typer(users_app, callback=new_users)\n\n\n@users_app.callback()\ndef users():\n \"\"\"\n Manage users in the app.\n \"\"\"\n\n\n@users_app.command()\ndef create(name: str):\n print(f\"Creating user: {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/name_help/tutorial007_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\ndef old_callback():\n \"\"\"\n Old callback help.\n \"\"\"\n\n\nusers_app = typer.Typer(callback=old_callback, name=\"users\", help=\"Explicit help.\")\n\n\ndef new_users():\n \"\"\"\n I have the highland! Create some users.\n \"\"\"\n\n\napp.add_typer(users_app, callback=new_users)\n\n\n@users_app.callback(help=\"Help from callback for users.\")\ndef users():\n \"\"\"\n Manage users in the app.\n \"\"\"\n\n\n@users_app.command()\ndef create(name: str):\n print(f\"Creating user: {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/name_help/tutorial008_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\ndef old_callback():\n \"\"\"\n Old callback help.\n \"\"\"\n\n\nusers_app = typer.Typer(callback=old_callback, name=\"exp-users\", help=\"Explicit help.\")\n\n\ndef new_users():\n \"\"\"\n I have the highland! Create some users.\n \"\"\"\n\n\napp.add_typer(\n users_app,\n callback=new_users,\n name=\"cake-sith-users\",\n help=\"Unlimited powder! Eh, users.\",\n)\n\n\n@users_app.callback(help=\"Help from callback for users.\")\ndef users():\n \"\"\"\n Manage users in the app.\n \"\"\"\n\n\n@users_app.command()\ndef create(name: str):\n print(f\"Creating user: {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/tutorial001_py310/__init__.py",
"content": ""
},
{
"path": "docs_src/subcommands/tutorial001_py310/items.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef create(item: str):\n print(f\"Creating item: {item}\")\n\n\n@app.command()\ndef delete(item: str):\n print(f\"Deleting item: {item}\")\n\n\n@app.command()\ndef sell(item: str):\n print(f\"Selling item: {item}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/tutorial001_py310/main.py",
"content": "import typer\n\nimport items\nimport users\n\napp = typer.Typer()\napp.add_typer(users.app, name=\"users\")\napp.add_typer(items.app, name=\"items\")\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/tutorial001_py310/users.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef create(user_name: str):\n print(f\"Creating user: {user_name}\")\n\n\n@app.command()\ndef delete(user_name: str):\n print(f\"Deleting user: {user_name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/tutorial002_py310/__init__.py",
"content": ""
},
{
"path": "docs_src/subcommands/tutorial002_py310/main.py",
"content": "import typer\n\napp = typer.Typer()\nitems_app = typer.Typer()\napp.add_typer(items_app, name=\"items\")\nusers_app = typer.Typer()\napp.add_typer(users_app, name=\"users\")\n\n\n@items_app.command(\"create\")\ndef items_create(item: str):\n print(f\"Creating item: {item}\")\n\n\n@items_app.command(\"delete\")\ndef items_delete(item: str):\n print(f\"Deleting item: {item}\")\n\n\n@items_app.command(\"sell\")\ndef items_sell(item: str):\n print(f\"Selling item: {item}\")\n\n\n@users_app.command(\"create\")\ndef users_create(user_name: str):\n print(f\"Creating user: {user_name}\")\n\n\n@users_app.command(\"delete\")\ndef users_delete(user_name: str):\n print(f\"Deleting user: {user_name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/tutorial003_py310/__init__.py",
"content": ""
},
{
"path": "docs_src/subcommands/tutorial003_py310/items.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef create(item: str):\n print(f\"Creating item: {item}\")\n\n\n@app.command()\ndef delete(item: str):\n print(f\"Deleting item: {item}\")\n\n\n@app.command()\ndef sell(item: str):\n print(f\"Selling item: {item}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/tutorial003_py310/lands.py",
"content": "import typer\n\nimport reigns\nimport towns\n\napp = typer.Typer()\napp.add_typer(reigns.app, name=\"reigns\")\napp.add_typer(towns.app, name=\"towns\")\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/tutorial003_py310/main.py",
"content": "import typer\n\nimport items\nimport lands\nimport users\n\napp = typer.Typer()\napp.add_typer(users.app, name=\"users\")\napp.add_typer(items.app, name=\"items\")\napp.add_typer(lands.app, name=\"lands\")\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/tutorial003_py310/reigns.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef conquer(name: str):\n print(f\"Conquering reign: {name}\")\n\n\n@app.command()\ndef destroy(name: str):\n print(f\"Destroying reign: {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/tutorial003_py310/towns.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef found(name: str):\n print(f\"Founding town: {name}\")\n\n\n@app.command()\ndef burn(name: str):\n print(f\"Burning town: {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/subcommands/tutorial003_py310/users.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef create(user_name: str):\n print(f\"Creating user: {user_name}\")\n\n\n@app.command()\ndef delete(user_name: str):\n print(f\"Deleting user: {user_name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/terminating/__init__.py",
"content": ""
},
{
"path": "docs_src/terminating/tutorial001_py310.py",
"content": "import typer\n\nexisting_usernames = [\"rick\", \"morty\"]\n\n\ndef maybe_create_user(username: str):\n if username in existing_usernames:\n print(\"The user already exists\")\n raise typer.Exit()\n else:\n print(f\"User created: {username}\")\n\n\ndef send_new_user_notification(username: str):\n # Somehow send a notification here for the new user, maybe an email\n print(f\"Notification sent for new user: {username}\")\n\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(username: str):\n maybe_create_user(username=username)\n send_new_user_notification(username=username)\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/terminating/tutorial002_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(username: str):\n if username == \"root\":\n print(\"The root user is reserved\")\n raise typer.Exit(code=1)\n print(f\"New user created: {username}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/terminating/tutorial003_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(username: str):\n if username == \"root\":\n print(\"The root user is reserved\")\n raise typer.Abort()\n print(f\"New user created: {username}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/testing/__init__.py",
"content": ""
},
{
"path": "docs_src/testing/app01_py310/__init__.py",
"content": ""
},
{
"path": "docs_src/testing/app01_py310/main.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str, city: str | None = None):\n print(f\"Hello {name}\")\n if city:\n print(f\"Let's have a coffee in {city}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/testing/app01_py310/test_main.py",
"content": "from typer.testing import CliRunner\n\nfrom .main import app\n\nrunner = CliRunner()\n\n\ndef test_app():\n result = runner.invoke(app, [\"Camila\", \"--city\", \"Berlin\"])\n assert result.exit_code == 0\n assert \"Hello Camila\" in result.output\n assert \"Let's have a coffee in Berlin\" in result.output\n"
},
{
"path": "docs_src/testing/app02_an_py310/__init__.py",
"content": ""
},
{
"path": "docs_src/testing/app02_an_py310/main.py",
"content": "from typing import Annotated\n\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str, email: Annotated[str, typer.Option(prompt=True)]):\n print(f\"Hello {name}, your email is: {email}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/testing/app02_an_py310/test_main.py",
"content": "from typer.testing import CliRunner\n\nfrom .main import app\n\nrunner = CliRunner()\n\n\ndef test_app():\n result = runner.invoke(app, [\"Camila\"], input=\"camila@example.com\\n\")\n assert result.exit_code == 0\n assert \"Hello Camila, your email is: camila@example.com\" in result.output\n"
},
{
"path": "docs_src/testing/app02_py310/__init__.py",
"content": ""
},
{
"path": "docs_src/testing/app02_py310/main.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str, email: str = typer.Option(..., prompt=True)):\n print(f\"Hello {name}, your email is: {email}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "docs_src/testing/app02_py310/test_main.py",
"content": "from typer.testing import CliRunner\n\nfrom .main import app\n\nrunner = CliRunner()\n\n\ndef test_app():\n result = runner.invoke(app, [\"Camila\"], input=\"camila@example.com\\n\")\n assert result.exit_code == 0\n assert \"Hello Camila, your email is: camila@example.com\" in result.output\n"
},
{
"path": "docs_src/testing/app03_py310/__init__.py",
"content": ""
},
{
"path": "docs_src/testing/app03_py310/main.py",
"content": "import typer\n\n\ndef main(name: str = \"World\"):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n typer.run(main)\n"
},
{
"path": "docs_src/testing/app03_py310/test_main.py",
"content": "import typer\nfrom typer.testing import CliRunner\n\nfrom .main import main\n\napp = typer.Typer()\napp.command()(main)\n\nrunner = CliRunner()\n\n\ndef test_app():\n result = runner.invoke(app, [\"--name\", \"Camila\"])\n assert result.exit_code == 0\n assert \"Hello Camila\" in result.output\n"
},
{
"path": "docs_src/typer_app/__init__.py",
"content": ""
},
{
"path": "docs_src/typer_app/tutorial001_py310.py",
"content": "import typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef main(name: str):\n print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n app()\n"
},
{
"path": "mkdocs.env.yml",
"content": "# Define this here and not in the main mkdocs.yml file because that one could be auto\n# updated and written, and the script would remove the env var\nmarkdown_extensions:\n pymdownx.highlight:\n linenums: !ENV [LINENUMS, false]\n"
},
{
"path": "mkdocs.yml",
"content": "INHERIT: ./mkdocs.env.yml\nsite_name: Typer\nsite_description: Typer, build great CLIs. Easy to code. Based on Python type hints.\nsite_url: https://typer.tiangolo.com/\n\ntheme:\n name: material\n custom_dir: docs/overrides\n palette:\n - media: \"(prefers-color-scheme)\"\n toggle:\n icon: material/lightbulb-auto\n name: Switch to light mode\n - media: '(prefers-color-scheme: light)'\n scheme: default\n primary: black\n accent: teal\n toggle:\n icon: material/lightbulb\n name: Switch to dark mode\n - media: '(prefers-color-scheme: dark)'\n scheme: slate\n primary: black\n accent: teal\n toggle:\n icon: material/lightbulb-outline\n name: Switch to system preference\n features:\n - content.code.annotate\n - content.code.copy\n # - content.code.select\n - content.footnote.tooltips\n - content.tabs.link\n - content.tooltips\n - navigation.footer\n - navigation.indexes\n - navigation.instant\n - navigation.instant.prefetch\n # - navigation.instant.preview\n - navigation.instant.progress\n - navigation.path\n - navigation.tabs\n - navigation.tabs.sticky\n - navigation.top\n - navigation.tracking\n - search.highlight\n - search.share\n - search.suggest\n - toc.follow\n\n icon:\n repo: fontawesome/brands/github-alt\n logo: img/icon.svg\n favicon: img/favicon.png\n language: en\nrepo_name: fastapi/typer\nrepo_url: https://github.com/fastapi/typer\nplugins:\n # Material for MkDocs\n search:\n social:\n typeset:\n # Other plugins\n macros:\n include_yaml:\n - members: data/members.yml\n redirects:\n redirect_maps:\n typer-cli.md: tutorial/typer-command.md\n mkdocstrings:\n handlers:\n python:\n options:\n extensions:\n - griffe_typingdoc\n show_root_heading: true\n show_if_no_docstring: true\n inherited_members: true\n members_order: source\n separate_signature: true\n unwrap_annotated: true\n filters:\n - '!^_'\n merge_init_into_class: true\n docstring_section_style: spacy\n signature_crossrefs: true\n show_symbol_type_heading: true\n show_symbol_type_toc: true\n\nnav:\n - Typer: index.md\n - features.md\n - Tutorial - User Guide:\n - tutorial/index.md\n - environment-variables.md\n - virtual-environments.md\n - tutorial/install.md\n - tutorial/first-steps.md\n - tutorial/typer-app.md\n - tutorial/printing.md\n - tutorial/terminating.md\n - CLI Arguments:\n - tutorial/arguments/index.md\n - tutorial/arguments/optional.md\n - tutorial/arguments/default.md\n - tutorial/arguments/help.md\n - tutorial/arguments/envvar.md\n - tutorial/arguments/other-uses.md\n - CLI Options:\n - tutorial/options/index.md\n - tutorial/options/help.md\n - tutorial/options/required.md\n - tutorial/options/prompt.md\n - tutorial/options/password.md\n - tutorial/options/name.md\n - tutorial/options/callback-and-context.md\n - tutorial/options/version.md\n - Commands:\n - tutorial/commands/index.md\n - tutorial/commands/arguments.md\n - tutorial/commands/options.md\n - tutorial/commands/help.md\n - tutorial/commands/name.md\n - tutorial/commands/callback.md\n - tutorial/commands/one-or-multiple.md\n - tutorial/commands/context.md\n - tutorial/options-autocompletion.md\n - CLI Parameter Types:\n - tutorial/parameter-types/index.md\n - tutorial/parameter-types/number.md\n - tutorial/parameter-types/bool.md\n - tutorial/parameter-types/uuid.md\n - tutorial/parameter-types/datetime.md\n - tutorial/parameter-types/enum.md\n - tutorial/parameter-types/path.md\n - tutorial/parameter-types/file.md\n - tutorial/parameter-types/custom-types.md\n - SubCommands - Command Groups:\n - tutorial/subcommands/index.md\n - tutorial/subcommands/add-typer.md\n - tutorial/subcommands/single-file.md\n - tutorial/subcommands/nested-subcommands.md\n - tutorial/subcommands/callback-override.md\n - tutorial/subcommands/name-and-help.md\n - Multiple Values:\n - tutorial/multiple-values/index.md\n - tutorial/multiple-values/multiple-options.md\n - tutorial/multiple-values/options-with-multiple-values.md\n - tutorial/multiple-values/arguments-with-multiple-values.md\n - tutorial/prompt.md\n - tutorial/progressbar.md\n - tutorial/app-dir.md\n - tutorial/launch.md\n - tutorial/testing.md\n - tutorial/package.md\n - tutorial/exceptions.md\n - tutorial/one-file-per-command.md\n - tutorial/typer-command.md\n - Reference (Code API):\n - reference/index.md\n - reference/typer.md\n - reference/run_launch.md\n - reference/parameters.md\n - reference/file_objects.md\n - reference/context.md\n - Resources:\n - resources/index.md\n - help-typer.md\n - contributing.md\n - management-tasks.md\n - About:\n - about/index.md\n - alternatives.md\n - management.md\n - release-notes.md\n\nmarkdown_extensions:\n # Material for MkDocs Extensions\n material.extensions.preview:\n targets:\n include:\n - \"*\"\n # Python Markdown\n abbr:\n attr_list:\n footnotes:\n md_in_html:\n tables:\n toc:\n permalink: true\n\n # Python Markdown Extensions\n pymdownx.betterem:\n smart_enable: all\n pymdownx.caret:\n pymdownx.highlight:\n line_spans: __span\n pymdownx.inlinehilite:\n pymdownx.keys:\n pymdownx.mark:\n pymdownx.superfences:\n custom_fences:\n - name: mermaid\n class: mermaid\n format: !!python/name:pymdownx.superfences.fence_code_format\n pymdownx.tilde:\n\n # pymdownx blocks\n pymdownx.blocks.admonition:\n types:\n - note\n - attention\n - caution\n - danger\n - error\n - tip\n - hint\n - warning\n # Custom types\n - info\n - check\n pymdownx.blocks.details:\n pymdownx.blocks.tab:\n alternate_style: True\n\n # Other extensions\n mdx_include:\n markdown_include_variants:\n\nextra:\n social:\n - icon: fontawesome/brands/github-alt\n link: https://github.com/fastapi/typer\n - icon: fontawesome/brands/twitter\n link: https://twitter.com/tiangolo\n - icon: fontawesome/brands/linkedin\n link: https://www.linkedin.com/in/tiangolo\n - icon: fontawesome/brands/dev\n link: https://dev.to/tiangolo\n - icon: fontawesome/brands/medium\n link: https://medium.com/@tiangolo\n - icon: fontawesome/solid/globe\n link: https://tiangolo.com\n\nextra_css:\n - css/termynal.css\n - css/custom.css\n\nextra_javascript:\n - js/termynal.js\n - js/custom.js\n\nhooks:\n - scripts/mkdocs_hooks.py\n"
},
{
"path": "pyproject.toml",
"content": "[build-system]\nrequires = [\"pdm-backend\"]\nbuild-backend = \"pdm.backend\"\n\n[project]\nname = \"typer\"\nlicense = \"MIT\"\nlicense-files = [\"LICENSE\"]\ndynamic = [\"version\"]\ndescription = \"Typer, build great CLIs. Easy to code. Based on Python type hints.\"\nauthors = [\n {name = \"Sebastiรกn Ramรญrez\", email = \"tiangolo@gmail.com\"},\n]\nrequires-python = \">=3.10\"\nclassifiers = [\n \"Intended Audience :: Information Technology\",\n \"Intended Audience :: System Administrators\",\n \"Operating System :: OS Independent\",\n \"Programming Language :: Python :: 3\",\n \"Programming Language :: Python\",\n \"Topic :: Software Development :: Libraries :: Application Frameworks\",\n \"Topic :: Software Development :: Libraries :: Python Modules\",\n \"Topic :: Software Development :: Libraries\",\n \"Topic :: Software Development\",\n \"Typing :: Typed\",\n \"Development Status :: 4 - Beta\",\n \"Intended Audience :: Developers\",\n \"Programming Language :: Python :: 3 :: Only\",\n \"Programming Language :: Python :: 3.10\",\n \"Programming Language :: Python :: 3.11\",\n \"Programming Language :: Python :: 3.12\",\n \"Programming Language :: Python :: 3.13\",\n \"Programming Language :: Python :: 3.14\",\n]\ndependencies = [\n \"click >= 8.2.1\",\n \"shellingham >=1.3.0\",\n \"rich >=12.3.0\",\n \"annotated-doc >=0.0.2\",\n]\nreadme = \"README.md\"\n\n[project.urls]\nHomepage = \"https://github.com/fastapi/typer\"\nDocumentation = \"https://typer.tiangolo.com\"\nRepository = \"https://github.com/fastapi/typer\"\nIssues = \"https://github.com/fastapi/typer/issues\"\nChangelog = \"https://typer.tiangolo.com/release-notes/\"\n\n[project.scripts]\ntyper = \"typer.cli:main\"\n\n[dependency-groups]\ndev = [\n { include-group = \"tests\" },\n { include-group = \"docs\" },\n \"prek >=0.3.2\",\n]\ndocs = [\n \"cairosvg >=2.8.2\",\n \"griffe-typingdoc >=0.3.0\",\n \"griffe-warnings-deprecated >=1.1.0\",\n \"markdown-include-variants >=0.0.8\",\n \"mdx-include >=1.4.1\",\n \"mkdocs-macros-plugin >=1.5.0\",\n \"mkdocs-material >=9.7.1\",\n \"mkdocs-redirects >=1.2.1\",\n \"mkdocstrings[python] >=0.30.1\",\n \"pillow >=11.3.0\",\n \"pyyaml >=5.3.1\",\n]\ngithub-actions = [\n \"httpx >=0.27.0\",\n \"pydantic >=2.5.3\",\n \"pydantic-settings >=2.1.0\",\n \"pygithub >=2.3.0\",\n \"smokeshow >=0.5.0\",\n]\ntests = [\n \"coverage[toml] >=7.13\",\n \"mypy >=1.19.1\",\n \"ty >=0.0.9\",\n \"pytest >=9.0.0\",\n \"pytest-cov >=4.0.0\",\n \"pytest-sugar >=0.9.5\",\n \"pytest-xdist >=1.32.0\",\n \"rich >=12.3.0\",\n \"ruff >=0.15.0\",\n \"shellingham >=1.3.0\",\n]\n\n[tool.pdm]\nversion = { source = \"file\", path = \"typer/__init__.py\" }\ndistribution = true\n\n[tool.pdm.build]\nsource-includes = [\n \"tests/\",\n \"docs_src/\",\n \"scripts/\",\n]\n\n[tool.pytest]\nminversion = \"9.0\"\naddopts = [\n \"--strict-config\",\n \"--strict-markers\",\n]\nstrict_xfail = true\nfilterwarnings = [\n \"error\",\n # For pytest-xdist\n 'ignore::DeprecationWarning:xdist',\n]\n\n[tool.coverage.run]\nparallel = true\ndata_file = \"coverage/.coverage\"\nsource = [\n \"docs_src\",\n \"tests\",\n \"typer\"\n]\nomit = [\n \"typer/_typing.py\",\n]\ncontext = '${CONTEXT}'\nrelative_files = true\n\n[tool.coverage.report]\nexclude_lines = [\n \"pragma: no cover\",\n \"@overload\",\n 'if __name__ == \"__main__\":',\n \"if TYPE_CHECKING:\",\n]\n\n[tool.mypy]\nstrict = true\n\n[[tool.mypy.overrides]]\nmodule = \"docs_src.*\"\ndisallow_incomplete_defs = false\ndisallow_untyped_defs = false\ndisallow_untyped_calls = false\n\n[[tool.mypy.overrides]]\nmodule = \"shellingham\"\nignore_missing_imports = true\n\n[tool.ruff.lint]\nselect = [\n \"E\", # pycodestyle errors\n \"W\", # pycodestyle warnings\n \"F\", # pyflakes\n \"I\", # isort\n \"B\", # flake8-bugbear\n \"C4\", # flake8-comprehensions\n \"UP\", # pyupgrade\n \"TID\", # flake8-tidy-imports\n]\nignore = [\n \"E501\", # line too long, handled by black\n \"B008\", # do not perform function calls in argument defaults\n \"C901\", # too complex\n \"W191\", # indentation contains tabs\n \"TID252\", # relative imports okay\n]\n\n[tool.ruff.lint.per-file-ignores]\n# \"__init__.py\" = [\"F401\"]\n# rich_utils is allowed to use rich imports\n\"typer/rich_utils.py\" = [\"TID251\"]\n# This file is more readable without yield from\n\"docs_src/progressbar/tutorial004_py310.py\" = [\"UP028\", \"B007\"]\n# Default mutable data structure\n\"docs_src/options_autocompletion/tutorial006_an_py310.py\" = [\"B006\"]\n\"docs_src/multiple_values/multiple_options/tutorial002_an_py310.py\" = [\"B006\"]\n\"docs_src/options_autocompletion/tutorial007_an_py310.py\" = [\"B006\"]\n\"docs_src/options_autocompletion/tutorial008_an_py310.py\" = [\"B006\"]\n\"docs_src/options_autocompletion/tutorial009_an_py310.py\" = [\"B006\"]\n\"docs_src/parameter_types/enum/tutorial003_an_py310.py\" = [\"B006\"]\n# Loop control variable `value` not used within loop body\n\"docs_src/progressbar/tutorial001_py310.py\" = [\"B007\"]\n\"docs_src/progressbar/tutorial003_py310.py\" = [\"B007\"]\n\"docs_src/progressbar/tutorial005_py310.py\" = [\"B007\"]\n\"docs_src/progressbar/tutorial006_py310.py\" = [\"B007\"]\n# Local variable `delete` is assigned to but never used\n\"docs_src/prompt/tutorial003_py310.py\" = [\"F841\"]\n# No need to worry about rich imports in docs\n\"docs_src/*\" = [\"TID\"]\n\n[tool.ruff.lint.isort]\nknown-third-party = [\"typer\", \"click\"]\n# For docs_src/subcommands/tutorial003/\nknown-first-party = [\"reigns\", \"towns\", \"lands\", \"items\", \"users\"]\n\n[tool.ruff.lint.pyupgrade]\n# Preserve types, even if a file imports `from __future__ import annotations`.\nkeep-runtime-typing = true\n\n[tool.ruff.lint.flake8-tidy-imports]\n# Import rich_utils from within functions (lazy), not at the module level (TID253)\nbanned-module-level-imports = [\"typer.rich_utils\"]\n\n[tool.ruff.lint.flake8-tidy-imports.banned-api]\n\"rich\".msg = \"Use 'typer.rich_utils' instead of importing from 'rich' directly.\"\n\"shellingham.detect_shell\".msg = \"\"\"\\\nUse 'typer._completion_shared._get_shell_name' instead of using \\\n'shellingham.detect_shell' directly.\n\"\"\"\n"
},
{
"path": "scripts/deploy_docs_status.py",
"content": "import logging\nimport re\nfrom typing import Literal\n\nfrom github import Auth, Github\nfrom pydantic import BaseModel, SecretStr\nfrom pydantic_settings import BaseSettings\n\nsite_domain = \"typer.tiangolo.com\"\n\n\nclass Settings(BaseSettings):\n github_repository: str\n github_token: SecretStr\n deploy_url: str | None = None\n commit_sha: str\n run_id: int\n state: Literal[\"pending\", \"success\", \"error\"] = \"pending\"\n\n\nclass LinkData(BaseModel):\n previous_link: str\n preview_link: str\n\n\ndef main() -> None:\n logging.basicConfig(level=logging.INFO)\n settings = Settings()\n\n logging.info(f\"Using config: {settings.model_dump_json()}\")\n g = Github(auth=Auth.Token(settings.github_token.get_secret_value()))\n repo = g.get_repo(settings.github_repository)\n use_pr = next(\n (pr for pr in repo.get_pulls() if pr.head.sha == settings.commit_sha), None\n )\n if not use_pr:\n logging.error(f\"No PR found for hash: {settings.commit_sha}\")\n return\n commits = list(use_pr.get_commits())\n current_commit = [c for c in commits if c.sha == settings.commit_sha][0]\n run_url = f\"https://github.com/{settings.github_repository}/actions/runs/{settings.run_id}\"\n if settings.state == \"pending\":\n current_commit.create_status(\n state=\"pending\",\n description=\"Deploying Docs\",\n context=\"deploy-docs\",\n target_url=run_url,\n )\n logging.info(\"No deploy URL available yet\")\n return\n if settings.state == \"error\":\n current_commit.create_status(\n state=\"error\",\n description=\"Error Deploying Docs\",\n context=\"deploy-docs\",\n target_url=run_url,\n )\n logging.info(\"Error deploying docs\")\n return\n assert settings.state == \"success\"\n if not settings.deploy_url:\n current_commit.create_status(\n state=\"success\",\n description=\"No Docs Changes\",\n context=\"deploy-docs\",\n target_url=run_url,\n )\n logging.info(\"No docs changes found\")\n return\n assert settings.deploy_url\n current_commit.create_status(\n state=\"success\",\n description=\"Docs Deployed\",\n context=\"deploy-docs\",\n target_url=run_url,\n )\n\n files = list(use_pr.get_files())\n docs_files = [f for f in files if f.filename.startswith(\"docs/\")]\n\n deploy_url = settings.deploy_url.rstrip(\"/\")\n links: list[LinkData] = []\n for f in docs_files:\n match = re.match(r\"docs/(.*)\", f.filename)\n if not match:\n continue\n path = match.group(1)\n if path.endswith(\"index.md\"):\n use_path = path.replace(\"index.md\", \"\")\n else:\n use_path = path.replace(\".md\", \"/\")\n link = LinkData(\n previous_link=f\"https://{site_domain}/{use_path}\",\n preview_link=f\"{deploy_url}/{use_path}\",\n )\n links.append(link)\n links.sort(key=lambda x: x.preview_link)\n\n header = \"## ๐ Docs preview\"\n message = header\n message += f\"\\n\\nLast commit {settings.commit_sha} at: {deploy_url}\"\n\n if links:\n message += \"\\n\\n### Modified Pages\\n\\n\"\n for link in links:\n message += f\"* {link.preview_link}\"\n message += f\" - ([before]({link.previous_link}))\"\n message += \"\\n\"\n\n print(message)\n issue = use_pr.as_issue()\n comments = list(issue.get_comments())\n for comment in comments:\n if (\n comment.body.startswith(header)\n and comment.user.login == \"github-actions[bot]\"\n ):\n comment.edit(message)\n break\n else:\n issue.create_comment(message)\n\n logging.info(\"Finished\")\n\n\nif __name__ == \"__main__\":\n main()\n"
},
{
"path": "scripts/docker/Dockerfile",
"content": "FROM python:latest\n\n# Add Fish\nRUN echo 'deb http://download.opensuse.org/repositories/shells:/fish:/release:/3/Debian_12/ /' | tee /etc/apt/sources.list.d/shells:fish:release:3.list\nRUN curl -fsSL https://download.opensuse.org/repositories/shells:fish:release:3/Debian_12/Release.key | gpg --dearmor | tee /etc/apt/trusted.gpg.d/shells_fish_release_3.gpg > /dev/null\n\n# Install packages including Fish, Zsh, PowerShell\nRUN apt-get update && apt-get install -y \\\n wget \\\n apt-transport-https \\\n software-properties-common \\\n nano \\\n vim \\\n fish \\\n zsh \\\n && wget https://github.com/PowerShell/PowerShell/releases/download/v7.4.4/powershell_7.4.4-1.deb_amd64.deb \\\n && dpkg -i powershell_7.4.4-1.deb_amd64.deb\n\n# Install uv\nCOPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv\n\nENV UV_SYSTEM_PYTHON=1\n\nCOPY . /code\n\nWORKDIR /code\n\nRUN uv pip install -r requirements.txt\n"
},
{
"path": "scripts/docker/compose.yaml",
"content": "services:\n typer:\n build:\n context: ../../\n dockerfile: scripts/docker/Dockerfile\n volumes:\n - ../../:/code\n command: sleep infinity\n"
},
{
"path": "scripts/docs.py",
"content": "import logging\nimport os\nimport re\nimport shutil\nimport subprocess\nfrom http.server import HTTPServer, SimpleHTTPRequestHandler\nfrom pathlib import Path\n\nimport typer\nfrom ruff.__main__ import find_ruff_bin\n\nlogging.basicConfig(level=logging.INFO)\n\nmkdocs_name = \"mkdocs.yml\"\ndocs_path = Path(\"docs\")\nen_docs_path = Path(\"\")\n\napp = typer.Typer()\n\n\n@app.callback()\ndef callback() -> None:\n # For MacOS with Cairo\n os.environ[\"DYLD_FALLBACK_LIBRARY_PATH\"] = \"/opt/homebrew/lib\"\n\n\ndef generate_readme_content() -> str:\n en_index = en_docs_path / \"docs\" / \"index.md\"\n content = en_index.read_text(\"utf-8\")\n match_pre = re.search(r\"\\n\\n\", content)\n if not match_pre:\n raise RuntimeError(\"Couldn't find pre section (![\"Typer\"](\"https://typer.tiangolo.com/img/logo-margin/logo-margin-vector.svg#only-light\"){kind=logo}
\n\n![\"Test\"](\"https://github.com/fastapi/typer/actions/workflows/test.yml/badge.svg?event=push&branch=master\"){kind=icon}
\n![\"Publish\"](\"https://github.com/fastapi/typer/workflows/Publish/badge.svg\"){kind=icon}
\n![\"Coverage\"](\"https://coverage-badge.samuelcolvin.workers.dev/fastapi/typer.svg\"){kind=icon}
\n![\"Package](\"https://img.shields.io/pypi/v/typer?color=%2334D058&label=pypi%20package\")
\n![](\"https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png\"){kind=logo}
\n\n**Typer** is FastAPI's little sibling.\n\nIt follows the same design and ideas. If you know **FastAPI**, you already know **Typer**... more or less.\n\n## Just Modern Python\n\nIt's all based on standard **Python type** declarations. No new syntax to learn. Just standard modern Python.\n\nIf you need a 2 minute refresher of how to use Python types (even if you don't use FastAPI or Typer), check the FastAPI tutorial section: Python types intro.\n\nYou will also see a 20 seconds refresher on the section [Tutorial - User Guide: First Steps](tutorial/first-steps.md){.internal-link target=_blank}.\n\n## Editor support\n\n**Typer** was designed to be easy and intuitive to use, to ensure the best development experience. With autocompletion everywhere.\n\nYou will rarely need to come back to the docs.\n\nHere's how your editor might help you:\n\n* in Visual Studio Code:\n\n\n\n* in PyCharm:\n\n\n\nYou will get completion for everything. That's something no other CLI library provides right now.\n\nNo more guessing what type was that variable, if it could be `None`, etc.\n\n### Short\n\nIt has sensible **defaults** for everything, with optional configurations everywhere. All the parameters can be fine-tuned to do what you need, customize the help, callbacks per parameter, make them required or not, etc.\n\nBut by default, it all **\"just works\"**.\n\n## User friendly CLI apps\n\nThe resulting CLI apps created with **Typer** have the nice features of many \"pro\" command line programs you probably already love.\n\n* Automatic help options for the main CLI program and all its subcommands.\n* Automatic command and subcommand structure handling (you will see more about subcommands in the Tutorial - User Guide).\n* Automatic completion for the CLI app in all operating systems, in all the shells (Bash, Zsh, Fish, PowerShell), so that the final user of your app can just hit TAB and get the available options or subcommands. *\n\n/// note | * Auto completion\n\nAuto completion works when you create a package (installable with `pip`). Or when using the `typer` command.\n\n**Typer** uses `shellingham` to auto-detect the current shell when installing completion.\n\n**Typer** will automatically create 2 *CLI options*:\n\n* `--install-completion`: Install completion for the current shell.\n* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.\n\n///\n\n/// tip\n\n**Typer**'s completion is implemented internally, it uses ideas and components from Click and ideas from `click-completion`, but it doesn't use `click-completion` and re-implements some of the relevant parts of Click.\n\nThen it extends those ideas with features and bug fixes. For example, **Typer** programs also support modern versions of PowerShell (e.g. in Windows 10) among all the other shells.\n\n///\n\n## Tested\n\n* 100% test coverage.\n* 100% type annotated code base.\n* Used in production applications.\n"
},
{
"path": "docs/help-typer.md",
"content": "# Help Typer - Get Help\n\nAre you liking **Typer**?\n\nWould you like to help Typer, other users, and the author?\n\nOr would you like to get help with **Typer**?\n\nThere are very simple ways to help (several involve just one or two clicks).\n\nAnd there are several ways to get help too.\n\n## Subscribe to the newsletter\n\nYou can subscribe to the (infrequent) [**FastAPI and friends** newsletter](https://fastapi.tiangolo.com/newsletter/){.internal-link target=_blank} to stay updated about:\n\n* News about FastAPI and friends, including Typer ๐\n* Guides ๐\n* Features โจ\n* Breaking changes ๐จ\n* Tips and tricks โ
\n\n## Star **Typer** in GitHub\n\nYou can \"star\" Typer in GitHub (clicking the star button at the top right): https://github.com/fastapi/typer.\n\nBy adding a star, other users will be able to find it more easily and see that it has been already useful for others.\n\n## Watch the GitHub repository for releases\n\nYou can \"watch\" Typer in GitHub (clicking the \"watch\" button at the top right): https://github.com/fastapi/typer.\n\nThere you can select \"Releases only\".\n\nBy doing it, you will receive notifications (in your email) whenever there's a new release (a new version) of **Typer** with bug fixes and new features.\n\n## Connect with the author\n\nYou can connect with me (Sebastiรกn Ramรญrez / `tiangolo`), the author.\n\nYou can:\n\n* Follow me on **GitHub**.\n * See other Open Source projects I have created that could help you.\n * Follow me to see when I create a new Open Source project.\n* Follow me on **Twitter**.\n * Tell me how you use Typer (I love to hear that).\n * Hear when I make announcements or release new tools.\n* Connect with me on **Linkedin**.\n * Hear when I make announcements or release new tools (although I use Twitter more often ๐คทโโ).\n* Read what I write (or follow me) on **Dev.to** or **Medium**.\n * Read other ideas, articles, and read about tools I have created.\n * Follow me to read when I publish something new.\n\n## Tweet about **Typer**\n\nTweet about **Typer** and let me and others know why you like it.\n\nI love to hear about how **Typer** is being used, what have you liked in it, in which project/company you are using it, etc.\n\n## Help others with questions in GitHub\n\nYou can try and help others with their questions in:\n\n* GitHub Discussions\n* GitHub Issues\n\nIn many cases you might already know the answer for those questions. ๐ค\n\nJust remember, the most important point is: try to be kind. People come with their frustrations and in many cases don't ask in the best way, but try as best as you can to be kind. ๐ค\n\nThe idea is for the **Typer** community to be kind and welcoming. At the same time, don't accept bullying or disrespectful behavior towards others. We have to take care of each other.\n\n---\n\nHere's how to help others with questions (in discussions or issues):\n\n### Understand the question\n\n* Check if you can understand what is the **purpose** and use case of the person asking.\n\n* Then check if the question (the vast majority are questions) is **clear**.\n\n* In many cases the question asked is about an imaginary solution from the user, but there might be a **better** one. If you can understand the problem and use case better, you might be able to suggest a better **alternative solution**.\n\n* If you can't understand the question, ask for more **details**.\n\n### Reproduce the problem\n\nFor most of the cases and most of the questions there's something related to the person's **original code**.\n\nIn many cases they will only copy a fragment of the code, but that's not enough to **reproduce the problem**.\n\n* You can ask them to provide a minimal, reproducible, example, that you can **copy-paste** and run locally to see the same error or behavior they are seeing, or to understand their use case better.\n\n* If you are feeling too generous, you can try to **create an example** like that yourself, just based on the description of the problem. Just have in mind that this might take a lot of time and it might be better to ask them to clarify the problem first.\n\n### Suggest solutions\n\n* After being able to understand the question, you can give them a possible **answer**.\n\n* In many cases, it's better to understand their **underlying problem or use case**, because there might be a better way to solve it than what they are trying to do.\n\n### Ask to close\n\nIf they reply, there's a high chance you would have solved their problem, congrats, **you're a hero**! ๐ฆธ\n\n* Now, if that solved their problem, you can ask them to:\n\n * In GitHub Discussions: mark the comment as the **answer**.\n * In GitHub Issues: **close** the issue**.\n\n## Watch the GitHub repository\n\nYou can \"watch\" Typer in GitHub (clicking the \"watch\" button at the top right): https://github.com/fastapi/typer.\n\nIf you select \"Watching\" instead of \"Releases only\" you will receive notifications when someone creates a new issue or question. You can also specify that you only want to be notified about new issues, or discussions, or PRs, etc.\n\nThen you can try and help them solve those questions.\n\n## Ask Questions\n\nYou can create a new question in the GitHub repository, for example to:\n\n* Ask a **question** or ask about a **problem**.\n* Suggest a new **feature**.\n\n**Note**: if you do it, then I'm going to ask you to also help others. ๐\n\n## Review Pull Requests\n\nYou can help me review pull requests from others.\n\nAgain, please try your best to be kind. ๐ค\n\n---\n\nHere's what to have in mind and how to review a pull request:\n\n### Understand the problem\n\n* First, make sure you **understand the problem** that the pull request is trying to solve. It might have a longer discussion in a GitHub Discussion or issue.\n\n* There's also a good chance that the pull request is not actually needed because the problem can be solved in a **different way**. Then you can suggest or ask about that.\n\n### Don't worry about style\n\n* Don't worry too much about things like commit message styles, I will squash and merge customizing the commit manually.\n\n* Also don't worry about style rules, there are already automated tools checking that.\n\nAnd if there's any other style or consistency need, I'll ask directly for that, or I'll add commits on top with the needed changes.\n\n### Check the code\n\n* Check and read the code, see if it makes sense, **run it locally** and see if it actually solves the problem.\n\n* Then **comment** saying that you did that, that's how I will know you really checked it.\n\n/// info\n\nUnfortunately, I can't simply trust PRs that just have several approvals.\n\nSeveral times it has happened that there are PRs with 3, 5 or more approvals, probably because the description is appealing, but when I check the PRs, they are actually broken, have a bug, or don't solve the problem they claim to solve. ๐
\n\nSo, it's really important that you actually read and run the code, and let me know in the comments that you did. ๐ค\n\n///\n\n* If the PR can be simplified in a way, you can ask for that, but there's no need to be too picky, there might be a lot of subjective points of view (and I will have my own as well ๐), so it's better if you can focus on the fundamental things.\n\n### Tests\n\n* Help me check that the PR has **tests**.\n\n* Check that the tests **fail** before the PR. ๐จ\n\n* Then check that the tests **pass** after the PR. โ
\n\n* Many PRs don't have tests, you can **remind** them to add tests, or you can even **suggest** some tests yourself. That's one of the things that consume most time and you can help a lot with that.\n\n* Then also comment what you tried, that way I'll know that you checked it. ๐ค\n\n## Create a Pull Request\n\nYou can [contribute](contributing.md){.internal-link target=_blank} to the source code with Pull Requests, for example:\n\n* To fix a typo you found on the documentation.\n* To propose new documentation sections.\n* To fix an existing issue/bug.\n * Make sure to add tests.\n* To add a new feature.\n * Make sure to add tests.\n * Make sure to add documentation if it's relevant.\n\n## Help Maintain Typer\n\nHelp me maintain **Typer**! ๐ค\n\nThere's a lot of work to do, and for most of it, **YOU** can do it.\n\nThe main tasks that you can do right now are:\n\n* [Help others with questions in GitHub](#help-others-with-questions-in-github){.internal-link target=_blank} (see the section above).\n* [Review Pull Requests](#review-pull-requests){.internal-link target=_blank} (see the section above).\n\nThose two tasks are what **consume time the most**. That's the main work of maintaining Typer.\n\nIf you can help me with that, **you are helping me maintain Typer** and making sure it keeps **advancing faster and better**. ๐\n\n## Join the chat\n\nJoin the ๐ฅ FastAPI and Friends Discord chat server ๐ฅ and hang out with others in the community. There's a `#typer` channel.\n\n/// tip\n\nFor questions, ask them in GitHub Discussions, there's a much better chance you will receive help there.\n\nUse the chat only for other general conversations.\n\n///\n\n### Don't use the chat for questions\n\nHave in mind that as chats allow more \"free conversation\", it's easy to ask questions that are too general and more difficult to answer, so, you might not receive answers.\n\nIn GitHub, the template will guide you to write the right question so that you can more easily get a good answer, or even solve the problem yourself even before asking. And in GitHub I can make sure I always answer everything, even if it takes some time. I can't personally do that with the chat. ๐
\n\nConversations in the chat are also not as easily searchable as in GitHub, so questions and answers might get lost in the conversation.\n\nOn the other side, there are thousands of users in the chat, so there's a high chance you'll find someone to talk to there, almost all the time. ๐\n\n## Sponsor the author\n\nYou can also financially support the author (me) through GitHub sponsors.\n\nThere you could buy me a coffee โ๏ธ to say thanks. ๐\n\n## Sponsor the tools that power Typer\n\nAs you have seen in the documentation, Typer is built on top of Click.\n\nYou can also sponsor:\n\n* Pallets Project (Click maintainers) via the PSF or via Tidelift\n\n---\n\nThanks! ๐\n"
},
{
"path": "docs/index.md",
"content": "\n\n![\"Typer\"](\"img/logo-margin/logo-margin-white-vector.svg#only-dark\"){kind=logo}
\n\n