Merge branch 'master' into feat/autocompletion

Author: bckohan

.github/workflows/test.yml

@@ -20,7 +20,7 @@ jobs:
     strategy:
       matrix:
         os: [ ubuntu-latest, windows-latest, macos-latest ]
-        python-version: [ "3.12" ]
+        python-version: [ "3.13" ]
         include:
           - os: ubuntu-22.04
             python-version: "3.7"
@@ -32,6 +32,8 @@ jobs:
             python-version: "3.10"
           - os: macos-latest
             python-version: "3.11"
+          - os: windows-latest
+            python-version: "3.12"
       fail-fast: false
     runs-on: ${{ matrix.os }}
     steps:

.pre-commit-config.yaml

@@ -14,7 +14,7 @@ repos:
     -   id: end-of-file-fixer
     -   id: trailing-whitespace
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.9.4
+    rev: v0.9.7
     hooks:
     -   id: ruff
         args:

docs/release-notes.md

@@ -2,12 +2,34 @@
 
 ## Latest Changes
 
+## 0.15.2
+
+### Features
+
+* ✨ Allow custom styles for commands in help output. PR [#1103](https://github.com/fastapi/typer/pull/1103) by [@TheTechromancer](https://github.com/TheTechromancer).
+* ✨ Avoid the unnecessary import of `typing_extensions` in newer Python versions. PR [#1048](https://github.com/fastapi/typer/pull/1048) by [@horta](https://github.com/horta).
+
+### Fixes
+
+* 🐛 Fix shell completions for the fish shell. PR [#1069](https://github.com/fastapi/typer/pull/1069) by [@goraje](https://github.com/goraje).
+
 ### Refactors
 
 * 🚚 Rename test to corner-cases to make it more explicit. PR [#1083](https://github.com/fastapi/typer/pull/1083) by [@tiangolo](https://github.com/tiangolo).
 
+### Docs
+
+* ✏️ Fix small typos in the tutorial documentation. PR [#1137](https://github.com/fastapi/typer/pull/1137) by [@svlandeg](https://github.com/svlandeg).
+* 📝 Update optional CLI argument section in tutorial with `Annotated`. PR [#983](https://github.com/fastapi/typer/pull/983) by [@gkeuccsr](https://github.com/gkeuccsr).
+* 📝 Clarify the need for `mix_stderr` when accessing the output of `stderr` in tests. PR [#1045](https://github.com/fastapi/typer/pull/1045) by [@mrchrisadams](https://github.com/mrchrisadams).
+
 ### Internal
 
+* 🔧 Add support for Python 3.13, tests in CI and add PyPI trove classifier. PR [#1091](https://github.com/fastapi/typer/pull/1091) by [@edgarrmondragon](https://github.com/edgarrmondragon).
+* ⬆ Bump ruff from 0.9.6 to 0.9.7. PR [#1161](https://github.com/fastapi/typer/pull/1161) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* ⬆ [pre-commit.ci] pre-commit autoupdate. PR [#1162](https://github.com/fastapi/typer/pull/1162) by [@pre-commit-ci[bot]](https://github.com/apps/pre-commit-ci).
+* ⬆ Bump ruff from 0.9.5 to 0.9.6. PR [#1153](https://github.com/fastapi/typer/pull/1153) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* ⬆ [pre-commit.ci] pre-commit autoupdate. PR [#1151](https://github.com/fastapi/typer/pull/1151) by [@pre-commit-ci[bot]](https://github.com/apps/pre-commit-ci).
 * ⬆ Bump ruff from 0.9.4 to 0.9.5. PR [#1146](https://github.com/fastapi/typer/pull/1146) by [@dependabot[bot]](https://github.com/apps/dependabot).
 * ⬆ [pre-commit.ci] pre-commit autoupdate. PR [#1142](https://github.com/fastapi/typer/pull/1142) by [@pre-commit-ci[bot]](https://github.com/apps/pre-commit-ci).
 * ⬆ Bump ruff from 0.9.3 to 0.9.4. PR [#1139](https://github.com/fastapi/typer/pull/1139) by [@dependabot[bot]](https://github.com/apps/dependabot).

docs/tutorial/arguments/optional.md

@@ -109,24 +109,18 @@ name: str
 
 Now, finally what we came for, an optional *CLI argument*.
 
-To make a *CLI argument* optional, use `typer.Argument()` and pass a different "default" as the first parameter to `typer.Argument()`, for example `None`:
+To make a *CLI argument* optional, use `typer.Argument()` and make sure to provide a "default" value, for example `"World"`:
 
-{* docs_src/arguments/optional/tutorial002_an.py hl[7] *}
+{* docs_src/arguments/optional/tutorial002_an.py hl[5] *}
 
 Now we have:
 
 ```Python
-name: Annotated[Optional[str], typer.Argument()] = None
+name: Annotated[str, typer.Argument()] = "World"
 ```
 
 Because we are using `typer.Argument()` **Typer** will know that this is a *CLI argument* (no matter if *required* or *optional*).
 
-/// tip
-
-By using `Optional` your editor will be able to know that the value *could* be `None`, and will be able to warn you if you do something assuming it is a `str` that would break if it was `None`.
-
-///
-
 Check the help:
 
 <div class="termy">

docs/tutorial/options-autocompletion.md

@@ -10,7 +10,7 @@ But you can also provide auto completion for the **values** of *CLI options* and
 
 Before checking how to provide custom completions, let's check again how it works.
 
-After 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 `--` an then hit <kbd>TAB</kbd>, your shell will show you the available *CLI options* (the same for *CLI arguments*, etc).
+After 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 <kbd>TAB</kbd>, your shell will show you the available *CLI options* (the same for *CLI arguments*, etc).
 
 To check it quickly without creating a new Python package, use the `typer` command.
 
@@ -165,7 +165,7 @@ That simplifies our code a bit and works the same.
 
 /// tip
 
-If all the `yield` part seems complex for you, don't worry, you can just use the version with the `list` above.
+If the `yield` part seems complex for you, don't worry, you can just use the version with the `list` above.
 
 In the end, that's just to save us a couple of lines of code.
 

docs/tutorial/options/callback-and-context.md

@@ -43,7 +43,7 @@ There's something to be aware of with callbacks and completion that requires som
 
 But first let's just use completion in your shell (Bash, Zsh, Fish, or PowerShell).
 
-After installing completion (for your own Python package), when you use your CLI program and start adding a *CLI option* with `--` an then hit <kbd>TAB</kbd>, your shell will show you the available *CLI options* (the same for *CLI arguments*, etc).
+After installing completion (for your own Python package), when you use your CLI program and start adding a *CLI option* with `--` and then hit <kbd>TAB</kbd>, your shell will show you the available *CLI options* (the same for *CLI arguments*, etc).
 
 To check it quickly with the previous script use the `typer` command:
 

docs/tutorial/testing.md

@@ -71,7 +71,7 @@ Then we check that the text printed to "standard output" contains the text that
 
 /// tip
 
-You could also check `result.stderr` for "standard error" independently from "standard output" if your `CliRunner` instance is created with the `mix_stderr=False` argument.
+You could also check output sent to "standard error" (`stderr`) instead of "standard output" (`stdout`). To do so, make sure your `CliRunner` instance is created with the `mix_stderr=False` argument. You need this setting to be able to access `result.stderr` in tests.
 
 ///
 

docs_src/arguments/optional/tutorial002.py

@@ -1,13 +1,8 @@
-from typing import Optional
-
 import typer
 
 
-def main(name: Optional[str] = typer.Argument(default=None)):
-    if name is None:
-        print("Hello World!")
-    else:
-        print(f"Hello {name}")
+def main(name: str = typer.Argument(default="World")):
+    print(f"Hello {name}!")
 
 
 if __name__ == "__main__":

docs_src/arguments/optional/tutorial002_an.py

@@ -1,14 +1,9 @@
-from typing import Optional
-
 import typer
 from typing_extensions import Annotated
 
 
-def main(name: Annotated[Optional[str], typer.Argument()] = None):
-    if name is None:
-        print("Hello World!")
-    else:
-        print(f"Hello {name}")
+def main(name: Annotated[str, typer.Argument()] = "World"):
+    print(f"Hello {name}!")
 
 
 if __name__ == "__main__":

pyproject.toml

@@ -30,6 +30,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "License :: OSI Approved :: MIT License",
 ]
 dependencies = [

requirements-tests.txt

@@ -6,7 +6,7 @@ coverage[toml] >=6.2,<8.0
 pytest-xdist >=1.32.0,<4.0.0
 pytest-sugar >=0.9.4,<1.1.0
 mypy ==1.4.1
-ruff ==0.9.5
+ruff ==0.9.7
 # Needed explicitly by typer-slim
 rich >=10.11.0
 shellingham >=1.3.0

tests/test_completion/example_rich_tags.py

@@ -0,0 +1,31 @@
+import typer
+
+app = typer.Typer()
+
+
+@app.command()
+def create(username: str):
+    """
+    Create a [green]new[green/] user with USERNAME.
+    """
+    print(f"Creating user: {username}")
+
+
+@app.command()
+def delete(username: str):
+    """
+    Delete a user with [bold]USERNAME[/].
+    """
+    print(f"Deleting user: {username}")
+
+
+@app.command()
+def delete_all():
+    """
+    [red]Delete ALL users[/red] in the database.
+    """
+    print("Deleting all users")
+
+
+if __name__ == "__main__":
+    app()

tests/test_completion/test_completion_complete.py

@@ -79,7 +79,7 @@ def test_completion_complete_subcommand_fish():
         },
     )
     assert (
-        "delete  Delete a user with USERNAME.\ndelete-all      Delete ALL users in the database."
+        "delete\tDelete a user with USERNAME.\ndelete-all\tDelete ALL users in the database."
         in result.stdout
     )
 

tests/test_completion/test_completion_complete_rich.py

@@ -0,0 +1,113 @@
+import os
+import subprocess
+import sys
+
+from . import example_rich_tags as mod
+
+
+def test_script():
+    result = subprocess.run(
+        [sys.executable, "-m", "coverage", "run", mod.__file__, "create", "DeadPool"],
+        capture_output=True,
+        encoding="utf-8",
+    )
+    assert result.returncode == 0
+    assert "Creating user: DeadPool" in result.stdout
+
+    result = subprocess.run(
+        [sys.executable, "-m", "coverage", "run", mod.__file__, "delete", "DeadPool"],
+        capture_output=True,
+        encoding="utf-8",
+    )
+    assert result.returncode == 0
+    assert "Deleting user: DeadPool" in result.stdout
+
+    result = subprocess.run(
+        [sys.executable, "-m", "coverage", "run", mod.__file__, "delete-all"],
+        capture_output=True,
+        encoding="utf-8",
+    )
+    assert result.returncode == 0
+    assert "Deleting all users" in result.stdout
+
+
+def test_completion_complete_subcommand_bash():
+    result = subprocess.run(
+        [sys.executable, "-m", "coverage", "run", mod.__file__, " "],
+        capture_output=True,
+        encoding="utf-8",
+        env={
+            **os.environ,
+            "_EXAMPLE_RICH_TAGS.PY_COMPLETE": "complete_bash",
+            "COMP_WORDS": "example_rich_tags.py del",
+            "COMP_CWORD": "1",
+        },
+    )
+    assert "delete\ndelete-all" in result.stdout
+
+
+def test_completion_complete_subcommand_zsh():
+    result = subprocess.run(
+        [sys.executable, "-m", "coverage", "run", mod.__file__, " "],
+        capture_output=True,
+        encoding="utf-8",
+        env={
+            **os.environ,
+            "_EXAMPLE_RICH_TAGS.PY_COMPLETE": "complete_zsh",
+            "_TYPER_COMPLETE_ARGS": "example_rich_tags.py del",
+        },
+    )
+    assert (
+        """_arguments '*: :(("delete":"Delete a user with USERNAME."\n"""
+        """\"delete-all":"Delete ALL users in the database."))'"""
+    ) in result.stdout
+
+
+def test_completion_complete_subcommand_fish():
+    result = subprocess.run(
+        [sys.executable, "-m", "coverage", "run", mod.__file__, " "],
+        capture_output=True,
+        encoding="utf-8",
+        env={
+            **os.environ,
+            "_EXAMPLE_RICH_TAGS.PY_COMPLETE": "complete_fish",
+            "_TYPER_COMPLETE_ARGS": "example_rich_tags.py del",
+            "_TYPER_COMPLETE_FISH_ACTION": "get-args",
+        },
+    )
+    assert (
+        "delete\tDelete a user with USERNAME.\ndelete-all\tDelete ALL users in the database."
+        in result.stdout
+    )
+
+
+def test_completion_complete_subcommand_powershell():
+    result = subprocess.run(
+        [sys.executable, "-m", "coverage", "run", mod.__file__, " "],
+        capture_output=True,
+        encoding="utf-8",
+        env={
+            **os.environ,
+            "_EXAMPLE_RICH_TAGS.PY_COMPLETE": "complete_powershell",
+            "_TYPER_COMPLETE_ARGS": "example_rich_tags.py del",
+        },
+    )
+    assert (
+        "delete:::Delete a user with USERNAME.\ndelete-all:::Delete ALL users in the database."
+    ) in result.stdout
+
+
+def test_completion_complete_subcommand_pwsh():
+    result = subprocess.run(
+        [sys.executable, "-m", "coverage", "run", mod.__file__, " "],
+        capture_output=True,
+        encoding="utf-8",
+        env={
+            **os.environ,
+            "_EXAMPLE_RICH_TAGS.PY_COMPLETE": "complete_pwsh",
+            "_TYPER_COMPLETE_ARGS": "example_rich_tags.py del",
+        },
+    )
+    assert (
+        "delete:::Delete a user with USERNAME.\ndelete-all:::Delete ALL users in the database."
+    ) in result.stdout

tests/test_completion/test_sanitization.py

@@ -0,0 +1,39 @@
+from importlib.machinery import ModuleSpec
+from typing import Union
+from unittest.mock import patch
+
+import pytest
+from typer._completion_classes import _sanitize_help_text
+
+
+@pytest.mark.parametrize(
+    "find_spec, help_text, expected",
+    [
+        (
+            ModuleSpec("rich", loader=None),
+            "help text without rich tags",
+            "help text without rich tags",
+        ),
+        (
+            None,
+            "help text without rich tags",
+            "help text without rich tags",
+        ),
+        (
+            ModuleSpec("rich", loader=None),
+            "help [bold]with[/] rich tags",
+            "help with rich tags",
+        ),
+        (
+            None,
+            "help [bold]with[/] rich tags",
+            "help [bold]with[/] rich tags",
+        ),
+    ],
+)
+def test_sanitize_help_text(
+    find_spec: Union[ModuleSpec, None], help_text: str, expected: str
+):
+    with patch("importlib.util.find_spec", return_value=find_spec) as mock_find_spec:
+        assert _sanitize_help_text(help_text) == expected
+    mock_find_spec.assert_called_once_with("rich")

typer/__init__.py

@@ -1,6 +1,6 @@
 """Typer, build great CLIs. Easy to code. Based on Python type hints."""
 
-__version__ = "0.15.1"
+__version__ = "0.15.2"
 
 from shutil import get_terminal_size as get_terminal_size