✨ Add support for PEP-593 Annotated for specifying options and argu…

…ments

Implements fastapi#184

.coveragerc

@@ -5,5 +5,8 @@ source =
     tests
     docs_src
 
+omit =
+    typer/_typing.py
+
 parallel = True
 context = '${CONTEXT}'

docs_src/arguments/default/tutorial001_an.py

@@ -0,0 +1,10 @@
+import typer
+from typing_extensions import Annotated
+
+
+def main(name: Annotated[str, typer.Argument()] = "Wade Wilson"):
+    print(f"Hello {name}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/arguments/default/tutorial002_an.py

@@ -0,0 +1,16 @@
+import random
+
+import typer
+from typing_extensions import Annotated
+
+
+def get_name():
+    return random.choice(["Deadpool", "Rick", "Morty", "Hiro"])
+
+
+def main(name: Annotated[str, typer.Argument(default_factory=get_name)]):
+    print(f"Hello {name}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/arguments/envvar/tutorial001_an.py

@@ -0,0 +1,10 @@
+import typer
+from typing_extensions import Annotated
+
+
+def main(name: Annotated[str, typer.Argument(envvar="AWESOME_NAME")] = "World"):
+    print(f"Hello Mr. {name}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/arguments/envvar/tutorial002_an.py

@@ -0,0 +1,12 @@
+import typer
+from typing_extensions import Annotated
+
+
+def main(
+    name: Annotated[str, typer.Argument(envvar=["AWESOME_NAME", "GOD_NAME"])] = "World"
+):
+    print(f"Hello Mr. {name}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/arguments/envvar/tutorial003_an.py

@@ -0,0 +1,14 @@
+import typer
+from typing_extensions import Annotated
+
+
+def main(
+    name: Annotated[
+        str, typer.Argument(envvar="AWESOME_NAME", show_envvar=False)
+    ] = "World"
+):
+    print(f"Hello Mr. {name}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/arguments/help/tutorial001_an.py

@@ -0,0 +1,10 @@
+import typer
+from typing_extensions import Annotated
+
+
+def main(name: Annotated[str, typer.Argument(help="The name of the user to greet")]):
+    print(f"Hello {name}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/arguments/help/tutorial002_an.py

@@ -0,0 +1,13 @@
+import typer
+from typing_extensions import Annotated
+
+
+def main(name: Annotated[str, typer.Argument(help="The name of the user to greet")]):
+    """
+    Say hi to NAME very gently, like Dirk.
+    """
+    print(f"Hello {name}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/arguments/help/tutorial003_an.py

@@ -0,0 +1,13 @@
+import typer
+from typing_extensions import Annotated
+
+
+def main(name: Annotated[str, typer.Argument(help="Who to greet")] = "World"):
+    """
+    Say hi to NAME very gently, like Dirk.
+    """
+    print(f"Hello {name}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/arguments/help/tutorial004_an.py

@@ -0,0 +1,17 @@
+import typer
+from typing_extensions import Annotated
+
+
+def main(
+    name: Annotated[
+        str, typer.Argument(help="Who to greet", show_default=False)
+    ] = "World"
+):
+    """
+    Say hi to NAME very gently, like Dirk.
+    """
+    print(f"Hello {name}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/arguments/help/tutorial005_an.py

@@ -0,0 +1,17 @@
+import typer
+from typing_extensions import Annotated
+
+
+def main(
+    name: Annotated[
+        str,
+        typer.Argument(
+            help="Who to greet", show_default="Deadpoolio the amazing's name"
+        ),
+    ] = "Wade Wilson"
+):
+    print(f"Hello {name}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/arguments/help/tutorial006_an.py

@@ -0,0 +1,10 @@
+import typer
+from typing_extensions import Annotated
+
+
+def main(name: Annotated[str, typer.Argument(metavar="✨username✨")] = "World"):
+    print(f"Hello {name}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/arguments/help/tutorial007_an.py

@@ -0,0 +1,22 @@
+import typer
+from typing_extensions import Annotated
+
+
+def main(
+    name: Annotated[str, typer.Argument(help="Who to greet")],
+    lastname: Annotated[
+        str, typer.Argument(help="The last name", rich_help_panel="Secondary Arguments")
+    ] = "",
+    age: Annotated[
+        str,
+        typer.Argument(help="The user's age", rich_help_panel="Secondary Arguments"),
+    ] = "",
+):
+    """
+    Say hi to NAME very gently, like Dirk.
+    """
+    print(f"Hello {name}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/arguments/help/tutorial008_an.py

@@ -0,0 +1,13 @@
+import typer
+from typing_extensions import Annotated
+
+
+def main(name: Annotated[str, typer.Argument(hidden=True)] = "World"):
+    """
+    Say hi to NAME very gently, like Dirk.
+    """
+    print(f"Hello {name}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/arguments/optional/tutorial001_an.py

@@ -0,0 +1,10 @@
+import typer
+from typing_extensions import Annotated
+
+
+def main(name: Annotated[str, typer.Argument()]):
+    print(f"Hello {name}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/arguments/optional/tutorial002_an.py

@@ -0,0 +1,15 @@
+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}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/commands/help/tutorial001_an.py

@@ -0,0 +1,67 @@
+import typer
+from typing_extensions import Annotated
+
+app = typer.Typer(help="Awesome CLI user manager.")
+
+
+@app.command()
+def create(username: str):
+    """
+    Create a new user with USERNAME.
+    """
+    print(f"Creating user: {username}")
+
+
+@app.command()
+def delete(
+    username: str,
+    force: Annotated[
+        bool,
+        typer.Option(
+            prompt="Are you sure you want to delete the user?",
+            help="Force deletion without confirmation.",
+        ),
+    ],
+):
+    """
+    Delete a user with USERNAME.
+
+    If --force is not used, will ask for confirmation.
+    """
+    if force:
+        print(f"Deleting user: {username}")
+    else:
+        print("Operation cancelled")
+
+
+@app.command()
+def delete_all(
+    force: Annotated[
+        bool,
+        typer.Option(
+            prompt="Are you sure you want to delete ALL users?",
+            help="Force deletion without confirmation.",
+        ),
+    ]
+):
+    """
+    Delete ALL users in the database.
+
+    If --force is not used, will ask for confirmation.
+    """
+    if force:
+        print("Deleting all users")
+    else:
+        print("Operation cancelled")
+
+
+@app.command()
+def init():
+    """
+    Initialize the users database.
+    """
+    print("Initializing user database")
+
+
+if __name__ == "__main__":
+    app()

docs_src/commands/help/tutorial004_an.py

@@ -0,0 +1,37 @@
+import typer
+from typing_extensions import Annotated
+
+app = typer.Typer(rich_markup_mode="rich")
+
+
+@app.command()
+def create(
+    username: Annotated[
+        str, typer.Argument(help="The username to be [green]created[/green]")
+    ]
+):
+    """
+    [bold green]Create[/bold green] a new [italic]shinny[/italic] user. :sparkles:
+
+    This requires a [underline]username[/underline].
+    """
+    print(f"Creating user: {username}")
+
+
+@app.command(help="[bold red]Delete[/bold red] a user with [italic]USERNAME[/italic].")
+def delete(
+    username: Annotated[
+        str, typer.Argument(help="The username to be [red]deleted[/red]")
+    ],
+    force: Annotated[
+        bool, typer.Option(help="Force the [bold red]deletion[/bold red] :boom:")
+    ] = False,
+):
+    """
+    Some internal utility function to delete.
+    """
+    print(f"Deleting user: {username}")
+
+
+if __name__ == "__main__":
+    app()

docs_src/commands/help/tutorial005_an.py

@@ -0,0 +1,37 @@
+import typer
+from typing_extensions import Annotated
+
+app = typer.Typer(rich_markup_mode="markdown")
+
+
+@app.command()
+def create(
+    username: Annotated[str, typer.Argument(help="The username to be **created**")]
+):
+    """
+    **Create** a new *shinny* user. :sparkles:
+
+    * Create a username
+
+    * Show that the username is created
+
+    ---
+
+    Learn more at the [Typer docs website](https://typer.tiangolo.com)
+    """
+    print(f"Creating user: {username}")
+
+
+@app.command(help="**Delete** a user with *USERNAME*.")
+def delete(
+    username: Annotated[str, typer.Argument(help="The username to be **deleted**")],
+    force: Annotated[bool, typer.Option(help="Force the **deletion** :boom:")] = False,
+):
+    """
+    Some internal utility function to delete.
+    """
+    print(f"Deleting user: {username}")
+
+
+if __name__ == "__main__":
+    app()