✨ Support common pydantic types

README.md

@@ -53,7 +53,7 @@ Create and activate a <a href="https://typer.tiangolo.com/virtual-environments/"
 ```console
 $ pip install typer
 ---> 100%
-Successfully installed typer rich shellingham
+Successfully installed typer rich shellingham pydantic
 ```
 
 </div>
@@ -357,6 +357,7 @@ For a more complete example including more features, see the <a href="https://ty
 By default it also comes with extra standard dependencies:
 
 * <a href="https://rich.readthedocs.io/en/stable/index.html" class="external-link" target="_blank"><code>rich</code></a>: to show nicely formatted errors automatically.
+* <a href="https://docs.pydantic.dev/latest/" class="external-link" target="_blank"><code>pydantic</code></a>: to support the usage of Pydantic types.
 * <a href="https://github.com/sarugaku/shellingham" class="external-link" target="_blank"><code>shellingham</code></a>: to automatically detect the current shell when installing completion.
     * With `shellingham` you can just use `--install-completion`.
     * Without `shellingham`, you have to pass the name of the shell to install completion for, e.g. `--install-completion bash`.
@@ -377,7 +378,7 @@ pip install typer
 pip install "typer-slim[standard]"
 ```
 
-The `standard` extra dependencies are `rich` and `shellingham`.
+The `standard` extra dependencies are `rich`, `shellingham` and `pydantic`.
 
 **Note**: The `typer` command is only included in the `typer` package.
 

docs/index.md

@@ -59,7 +59,7 @@ Create and activate a <a href="https://typer.tiangolo.com/virtual-environments/"
 ```console
 $ pip install typer
 ---> 100%
-Successfully installed typer rich shellingham
+Successfully installed typer rich shellingham pydantic
 ```
 
 </div>
@@ -363,6 +363,7 @@ For a more complete example including more features, see the <a href="https://ty
 By default it also comes with extra standard dependencies:
 
 * <a href="https://rich.readthedocs.io/en/stable/index.html" class="external-link" target="_blank"><code>rich</code></a>: to show nicely formatted errors automatically.
+* <a href="https://docs.pydantic.dev/latest/" class="external-link" target="_blank"><code>pydantic</code></a>: to support the usage of Pydantic types.
 * <a href="https://github.com/sarugaku/shellingham" class="external-link" target="_blank"><code>shellingham</code></a>: to automatically detect the current shell when installing completion.
     * With `shellingham` you can just use `--install-completion`.
     * Without `shellingham`, you have to pass the name of the shell to install completion for, e.g. `--install-completion bash`.
@@ -383,7 +384,7 @@ pip install typer
 pip install "typer-slim[standard]"
 ```
 
-The `standard` extra dependencies are `rich` and `shellingham`.
+The `standard` extra dependencies are `rich`, `shellingham` and `pydantic`.
 
 **Note**: The `typer` command is only included in the `typer` package.
 

docs/release-notes.md

@@ -673,7 +673,7 @@ Updated docs [SubCommand Name and Help](https://typer.tiangolo.com/tutorial/subc
 
 Now you don't need to install `typer[all]`. When you install `typer` it comes with the default optional dependencies and the `typer` command.
 
-If you don't want the extra optional dependencies (`rich` and `shellingham`), you can install `typer-slim` instead.
+If you don't want the extra optional dependencies (`rich`, `shellingham` and `pydantic`), you can install `typer-slim` instead.
 
 You can also install `typer-slim[standard]`, which includes the default optional dependencies, but not the `typer` command.
 
@@ -699,7 +699,7 @@ By installing the latest version (`0.12.1`) it fixes it, for any previous versio
 
 In version `0.12.0`, the `typer` package depends on `typer-slim[standard]` which includes the default dependencies (instead of `typer[all]`) and `typer-cli` (that provides the `typer` command).
 
-If you don't want the extra optional dependencies (`rich` and `shellingham`), you can install `typer-slim` instead.
+If you don't want the extra optional dependencies (`rich`, `shellingham` and `pydantic`), you can install `typer-slim` instead.
 
 You can also install `typer-slim[standard]`, which includes the default optional dependencies, but not the `typer` command.
 

docs/tutorial/index.md

@@ -62,3 +62,34 @@ Using it in your editor is what really shows you the benefits of **Typer**, seei
 And running the examples is what will really help you **understand** what is going on.
 
 You can learn a lot more by **running some examples** and **playing around** with them than by reading all the docs here.
+
+---
+
+## Install **Typer**
+
+The first step is to install **Typer**:
+
+<div class="termy">
+
+```console
+$ pip install typer
+---> 100%
+Successfully installed typer click shellingham rich pydantic
+```
+
+</div>
+
+By default, `typer` comes with `rich`, `shellingham` and `pydantic`.
+
+!!! note
+    If you are an advanced user and want to opt out of these default extra dependencies, you can instead install `typer-slim`.
+
+    ```bash
+    pip install typer
+    ```
+
+...includes the same optional dependencies as:
+
+    ```bash
+    pip install "typer-slim[standard]"
+    ```

docs/tutorial/parameter-types/pydantic-types.md

@@ -0,0 +1,37 @@
+Pydantic types such as [AnyUrl](https://docs.pydantic.dev/latest/api/networks/#pydantic.networks.AnyUrl) or [EmailStr](https://docs.pydantic.dev/latest/api/networks/#pydantic.networks.EmailStr) can be very convenient to describe and validate some parameters.
+
+Pydantic is installed automatically when installing Typer with its extra standard dependencies:
+
+<div class="termy">
+
+```console
+// Pydantic comes with typer
+$ pip install typer
+---> 100%
+Successfully installed typer rich shellingham pydantic
+
+// Alternatively, you can install Pydantic independently
+$ pip install pydantic
+---> 100%
+Successfully installed pydantic
+
+// Or if you want to use EmailStr
+$ pip install "pydantic[email]"
+---> 100%
+Successfully installed pydantic, email-validator
+```
+
+</div>
+
+
+You can then use them as parameter types.
+
+{* docs_src/parameter_types/pydantic_types/tutorial001_an_py39.py hl[9] *}
+
+{* docs_src/parameter_types/pydantic_types/tutorial002_an_py39.py hl[9] *}
+
+These types are also supported in lists or tuples:
+
+{* docs_src/parameter_types/pydantic_types/tutorial003_an_py39.py hl[9] *}
+
+{* docs_src/parameter_types/pydantic_types/tutorial004_an_py39.py hl[9] *}

docs_src/parameter_types/pydantic_types/tutorial001_an_py39.py

@@ -0,0 +1,15 @@
+from typing import Annotated
+
+import typer
+from pydantic import AnyHttpUrl
+
+app = typer.Typer()
+
+
+@app.command()
+def main(url_arg: Annotated[AnyHttpUrl, typer.Argument()]):
+    typer.echo(f"url_arg: {url_arg}")
+
+
+if __name__ == "__main__":
+    app()

docs_src/parameter_types/pydantic_types/tutorial001_py39.py

@@ -0,0 +1,13 @@
+import typer
+from pydantic import AnyHttpUrl
+
+app = typer.Typer()
+
+
+@app.command()
+def main(url_arg: AnyHttpUrl):
+    typer.echo(f"url_arg: {url_arg}")
+
+
+if __name__ == "__main__":
+    app()

docs_src/parameter_types/pydantic_types/tutorial002_an_py39.py

@@ -0,0 +1,15 @@
+from typing import Annotated
+
+import typer
+from pydantic import AnyHttpUrl
+
+app = typer.Typer()
+
+
+@app.command()
+def main(url_opt: Annotated[AnyHttpUrl, typer.Option()] = "https://typer.tiangolo.com"):
+    typer.echo(f"url_opt: {url_opt}")
+
+
+if __name__ == "__main__":
+    app()

docs_src/parameter_types/pydantic_types/tutorial002_py39.py

@@ -0,0 +1,13 @@
+import typer
+from pydantic import AnyHttpUrl
+
+app = typer.Typer()
+
+
+@app.command()
+def main(url_opt: AnyHttpUrl = typer.Option("https://typer.tiangolo.com")):
+    typer.echo(f"url_opt: {url_opt}")
+
+
+if __name__ == "__main__":
+    app()

docs_src/parameter_types/pydantic_types/tutorial003_an_py39.py

@@ -0,0 +1,17 @@
+from typing import Annotated
+
+import typer
+from pydantic import AnyHttpUrl
+
+app = typer.Typer()
+
+
+@app.command()
+def main(
+    urls: Annotated[list[AnyHttpUrl], typer.Option("--url", default_factory=list)],
+):
+    typer.echo(f"urls: {urls}")
+
+
+if __name__ == "__main__":
+    app()

docs_src/parameter_types/pydantic_types/tutorial003_py39.py

@@ -0,0 +1,13 @@
+import typer
+from pydantic import AnyHttpUrl
+
+app = typer.Typer()
+
+
+@app.command()
+def main(urls: list[AnyHttpUrl] = typer.Option([], "--url")):
+    typer.echo(f"urls: {urls}")
+
+
+if __name__ == "__main__":
+    app()

docs_src/parameter_types/pydantic_types/tutorial004_an_py39.py

@@ -0,0 +1,23 @@
+from typing import Annotated
+
+import typer
+from pydantic import AnyHttpUrl, IPvAnyAddress
+
+app = typer.Typer()
+
+
+@app.command()
+def main(
+    server: Annotated[
+        tuple[str, IPvAnyAddress, AnyHttpUrl],
+        typer.Option(help="User name, age, email and social media URL"),
+    ],
+):
+    name, address, url = server
+    typer.echo(f"name: {name}")
+    typer.echo(f"address: {address}")
+    typer.echo(f"url: {url}")
+
+
+if __name__ == "__main__":
+    app()

docs_src/parameter_types/pydantic_types/tutorial004_py39.py

@@ -0,0 +1,20 @@
+import typer
+from pydantic import AnyHttpUrl, IPvAnyAddress
+
+app = typer.Typer()
+
+
+@app.command()
+def main(
+    server: tuple[str, IPvAnyAddress, AnyHttpUrl] = typer.Option(
+        ..., help="Server name, IP address and public URL"
+    ),
+):
+    name, address, url = server
+    typer.echo(f"name: {name}")
+    typer.echo(f"address: {address}")
+    typer.echo(f"url: {url}")
+
+
+if __name__ == "__main__":
+    app()

mkdocs.yml

@@ -116,6 +116,7 @@ nav:
           - tutorial/parameter-types/path.md
           - tutorial/parameter-types/file.md
           - tutorial/parameter-types/custom-types.md
+          - tutorial/parameter-types/pydantic-types.md
       - SubCommands - Command Groups:
           - tutorial/subcommands/index.md
           - tutorial/subcommands/add-typer.md

pyproject.toml

@@ -50,6 +50,7 @@ Changelog = "https://typer.tiangolo.com/release-notes/"
 standard = [
     "shellingham >=1.3.0",
     "rich >=10.11.0",
+    "pydantic >=2.0.0",
 ]
 
 [dependency-groups]
@@ -81,6 +82,7 @@ github-actions = [
 tests = [
     "coverage[toml]>=6.2,<8.0",
     "mypy==1.19.1",
+    "pydantic >=2.0.0",
     "pytest>=4.4.0,<9.0.0",
     "pytest-cov>=2.10.0,<8.0.0",
     "pytest-sugar>=0.9.4,<1.2.0",

tests/test_tutorial/test_parameter_types/test_pydantic_types/test_tutorial001.py

@@ -0,0 +1,48 @@
+import importlib
+import subprocess
+import sys
+from types import ModuleType
+
+import pytest
+from typer.testing import CliRunner
+
+runner = CliRunner()
+
+
+@pytest.fixture(
+    name="mod",
+    params=[
+        pytest.param("tutorial001_py39"),
+        pytest.param("tutorial001_an_py39"),
+    ],
+)
+def get_mod(request: pytest.FixtureRequest) -> ModuleType:
+    module_name = f"docs_src.parameter_types.pydantic_types.{request.param}"
+    mod = importlib.import_module(module_name)
+    return mod
+
+
+def test_help(mod: ModuleType):
+    result = runner.invoke(mod.app, ["--help"])
+    assert result.exit_code == 0
+
+
+def test_url_arg(mod: ModuleType):
+    result = runner.invoke(mod.app, ["https://typer.tiangolo.com"])
+    assert result.exit_code == 0
+    assert "url_arg: https://typer.tiangolo.com" in result.output
+
+
+def test_url_arg_invalid(mod: ModuleType):
+    result = runner.invoke(mod.app, ["invalid"])
+    assert result.exit_code != 0
+    assert "Input should be a valid URL" in result.output
+
+
+def test_script(mod: ModuleType):
+    result = subprocess.run(
+        [sys.executable, "-m", "coverage", "run", mod.__file__, "--help"],
+        capture_output=True,
+        encoding="utf-8",
+    )
+    assert "Usage" in result.stdout