✨ Use Pydantic for parameter validation

docs/tutorial/parameter-types/enum.md

@@ -19,11 +19,11 @@ Check it:
 ```console
 $ python main.py --help
 
-// Notice the predefined values [simple|conv|lstm]
+// Notice the predefined values <simple|conv|lstm>
 Usage: main.py [OPTIONS]
 
 Options:
-  --network [simple|conv|lstm]  [default: simple]
+  --network <simple|conv|lstm>  [default: simple]
   --help                        Show this message and exit.
 
 // Try it
@@ -91,8 +91,8 @@ $ python main.py --help
 Usage: main.py [OPTIONS]
 
 Options:
-  --groceries [Eggs|Bacon|Cheese]  [default: Eggs, Cheese]
-  --help                           Show this message and exit.
+  --groceries <list[Eggs|Bacon|Cheese]>   [default: Eggs, Cheese]
+  --help                                  Show this message and exit.
 
 // Try it with the default values
 $ python main.py
@@ -123,11 +123,11 @@ You can also use `Literal` to represent a set of possible predefined choices, wi
 ```console
 $ python main.py --help
 
-// Notice the predefined values [simple|conv|lstm]
+// Notice the predefined values <simple|conv|lstm>
 Usage: main.py [OPTIONS]
 
 Options:
-  --network [simple|conv|lstm]  [default: simple]
+  --network <simple|conv|lstm>  [default: simple]
   --help                        Show this message and exit.
 
 // Try it

docs_src/parameter_types/number/tutorial001_an_py310.py

@@ -7,11 +7,11 @@
 
 @app.command()
 def main(
-    id: Annotated[int, typer.Argument(min=0, max=1000)],
+    ID: Annotated[int, typer.Argument(min=0, max=1000)],
     age: Annotated[int, typer.Option(min=18)] = 20,
     score: Annotated[float, typer.Option(max=100)] = 0,
 ):
-    print(f"ID is {id}")
+    print(f"ID is {ID}")
     print(f"--age is {age}")
     print(f"--score is {score}")
 

docs_src/parameter_types/number/tutorial001_py310.py

@@ -5,11 +5,11 @@
 
 @app.command()
 def main(
-    id: int = typer.Argument(..., min=0, max=1000),
+    ID: int = typer.Argument(..., min=0, max=1000),
     age: int = typer.Option(20, min=18),
     score: float = typer.Option(0, max=100),
 ):
-    print(f"ID is {id}")
+    print(f"ID is {ID}")
     print(f"--age is {age}")
     print(f"--score is {score}")
 

docs_src/parameter_types/number/tutorial002_an_py310.py

@@ -7,11 +7,11 @@
 
 @app.command()
 def main(
-    id: Annotated[int, typer.Argument(min=0, max=1000)],
+    ID: Annotated[int, typer.Argument(min=0, max=1000)],
     rank: Annotated[int, typer.Option(max=10, clamp=True)] = 0,
     score: Annotated[float, typer.Option(min=0, max=100, clamp=True)] = 0,
 ):
-    print(f"ID is {id}")
+    print(f"ID is {ID}")
     print(f"--rank is {rank}")
     print(f"--score is {score}")
 

docs_src/parameter_types/number/tutorial002_py310.py

@@ -5,11 +5,11 @@
 
 @app.command()
 def main(
-    id: int = typer.Argument(..., min=0, max=1000),
+    ID: int = typer.Argument(..., min=0, max=1000),
     rank: int = typer.Option(0, max=10, clamp=True),
     score: float = typer.Option(0, min=0, max=100, clamp=True),
 ):
-    print(f"ID is {id}")
+    print(f"ID is {ID}")
     print(f"--rank is {rank}")
     print(f"--score is {score}")
 

pyproject.toml

@@ -33,6 +33,7 @@ classifiers = [
     "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
+    "pydantic >=2.5.3",
     "shellingham >=1.3.0",
     "rich >=13.8.0",
     "annotated-doc >=0.0.2",

tests/assets/cli/multiapp-docs-title.md

@@ -65,8 +65,8 @@ $ multiapp sub hello [OPTIONS]
 
 **Options**:
 
-* `--name TEXT`: [default: World]
-* `--age INTEGER`: The age of the user  [default: 0]
+* `--name <str>`: [default: World]
+* `--age <int>`: The age of the user  [default: 0]
 * `--help`: Show this message and exit.
 
 ### `multiapp sub hi`
@@ -76,12 +76,12 @@ Say Hi
 **Usage**:
 
 ```console
-$ multiapp sub hi [OPTIONS] [USER]
+$ multiapp sub hi [OPTIONS] [user]
 ```
 
 **Arguments**:
 
-* `[USER]`: The name of the user to greet  [default: World]
+* `[user]`: The name of the user to greet  [default: World]
 
 **Options**:
 

tests/assets/cli/multiapp-docs.md

@@ -65,8 +65,8 @@ $ multiapp sub hello [OPTIONS]
 
 **Options**:
 
-* `--name TEXT`: [default: World]
-* `--age INTEGER`: The age of the user  [default: 0]
+* `--name <str>`: [default: World]
+* `--age <int>`: The age of the user  [default: 0]
 * `--help`: Show this message and exit.
 
 ### `multiapp sub hi`
@@ -76,12 +76,12 @@ Say Hi
 **Usage**:
 
 ```console
-$ multiapp sub hi [OPTIONS] [USER]
+$ multiapp sub hi [OPTIONS] [user]
 ```
 
 **Arguments**:
 
-* `[USER]`: The name of the user to greet  [default: World]
+* `[user]`: The name of the user to greet  [default: World]
 
 **Options**:
 

tests/assets/cli/richformattedapp-docs.md

@@ -5,13 +5,13 @@ Say <span style="color: #800000; text-decoration-color: #800000; font-weight: bo
 **Usage**:
 
 ```console
-$ hello [OPTIONS] USER_1 [USER_2]
+$ hello [OPTIONS] {user_1} [user_2]
 ```
 
 **Arguments**:
 
-* `USER_1`: The <span style="font-weight: bold">cool</span> name of the <span style="color: #008000; text-decoration-color: #008000">user</span>  [required]
-* `[USER_2]`: The world  [default: The World]
+* `user_1`: The <span style="font-weight: bold">cool</span> name of the <span style="color: #008000; text-decoration-color: #008000">user</span>  [required]
+* `[user_2]`: The world  [default: The World]
 
 **Options**:
 

tests/assets/completion_argument.py

@@ -1,10 +1,11 @@
 import typer
 from typer import _click
+from typer.core import TyperParameter
 
 app = typer.Typer()
 
 
-def shell_complete(ctx: _click.Context, param: _click.Parameter, incomplete: str):
+def shell_complete(ctx: _click.Context, param: TyperParameter, incomplete: str):
     typer.echo(f"ctx: {ctx.info_name}", err=True)
     typer.echo(f"arg is: {param.name}", err=True)
     typer.echo(f"incomplete is: {incomplete}", err=True)

tests/test_cli/test_help.py

@@ -121,7 +121,7 @@ def cmd(value: str) -> None:
     output_lines = result.output.splitlines()
     usage_idx = output_lines.index("Usage: very-long-program-name-that-forces-wrap ")
     args_line = output_lines[usage_idx + 1]
-    assert args_line.lstrip() == "[OPTIONS] VALUE"
+    assert args_line.lstrip() == "[OPTIONS] {value}"
     assert args_line.startswith(" ")
 
 

tests/test_coercion.py

@@ -0,0 +1,129 @@
+from pathlib import Path
+
+import typer
+from typer.testing import CliRunner
+
+runner = CliRunner()
+
+
+def test_coercion() -> None:
+    app = typer.Typer()
+    seen: dict[str, object] = {}
+
+    @app.command()
+    def main(items: list[int], active: bool = False, val=42):
+        seen["items"] = items
+        seen["active"] = active
+        seen["val"] = val
+
+    result = runner.invoke(app, ["1", "2", "--active", "--val", "7"])
+    assert result.exit_code == 0, result.output
+    assert seen == {"items": [1, 2], "active": True, "val": 7}
+
+
+def test_coercion_invalid() -> None:
+    app = typer.Typer()
+
+    @app.command()
+    def main(age: int):
+        pass
+
+    result = runner.invoke(app, ["not-an-int"])
+    assert "Input should be a valid integer" in result.stderr
+    assert result.exit_code == 2
+
+
+def test_coercion_path(tmp_path: Path) -> None:
+    target = tmp_path / "config.txt"
+    target.write_text("hello\n", encoding="utf-8")
+    app = typer.Typer()
+    seen: list[Path] = []
+
+    @app.command()
+    def main(config: Path = typer.Option(..., exists=True)):
+        seen.append(config)
+
+    result = runner.invoke(app, ["--config", str(target)])
+    assert result.exit_code == 0
+    assert seen == [target]
+
+
+def test_coercion_tuple_files(tmp_path: Path) -> None:
+    first = tmp_path / "first.txt"
+    second = tmp_path / "second.txt"
+    first.write_text("first-content\n", encoding="utf-8")
+    second.write_text("second-content\n", encoding="utf-8")
+    app = typer.Typer()
+    seen: list[str] = []
+
+    @app.command()
+    def main(files: tuple[typer.FileText, typer.FileText]):
+        seen.append(files[0].read())
+        seen.append(files[1].read())
+
+    result = runner.invoke(app, [str(first), str(second)])
+    assert result.exit_code == 0, result.output
+    assert seen == ["first-content\n", "second-content\n"]
+
+
+def test_passthrough_runtime_param_default() -> None:
+    class Widget:
+        def __init__(self, value: int) -> None:
+            self.value = value
+
+        def __repr__(self) -> str:
+            return f"Widget({self.value})"
+
+    app = typer.Typer()
+    seen: dict[str, Widget] = {}
+
+    @app.command()
+    def main(val=Widget(42)):
+        seen["val"] = val
+
+    param = next(p for p in typer.main.get_command(app).params if p.name == "val")
+    assert param.runtime_param is not None
+    assert param.runtime_param.annotation is Widget
+
+    result = runner.invoke(app)
+    assert result.exit_code == 0
+    assert isinstance(seen["val"], Widget)
+    assert seen["val"].value == 42
+
+    result = runner.invoke(app, ["--val", "666"])
+    assert result.exit_code == 2
+    # This doesn't work because there's no parser
+    assert "is not a valid Widget" in result.output
+
+
+def test_widget_parsed_from_cli_with_parser() -> None:
+    class Widget:
+        def __init__(self, value: int) -> None:
+            self.value = value
+
+        def __repr__(self) -> str:
+            return f"Widget({self.value})"
+
+    def parse_widget(value: str) -> Widget:
+        return Widget(int(value))
+
+    app = typer.Typer()
+    seen: dict[str, Widget] = {}
+
+    @app.command()
+    def main(val: Widget = typer.Option("42", parser=parse_widget)):
+        seen["val"] = val
+
+    param = next(p for p in typer.main.get_command(app).params if p.name == "val")
+    assert param.runtime_param is not None
+    assert param.runtime_param.annotation is Widget
+
+    result = runner.invoke(app)
+    assert result.exit_code == 0
+    assert isinstance(seen["val"], Widget)
+    assert seen["val"].value == 42
+
+    result = runner.invoke(app, ["--val", "666"])
+    assert result.exit_code == 0
+    assert isinstance(seen["val"], Widget)
+    assert seen["val"].value == 666