Python Typer Annotated Metadata Guide

Python Typer makes CLI development easy. With annotated metadata, you can create richer option definitions. This guide shows you how.

What is Annotated Metadata in Typer?

Annotated metadata lets you add extra information to CLI options. It works with Python's type hints. You can define help text, default values, and more.

The Annotated type comes from Python's typing module. Typer uses it to enhance option definitions. This creates more descriptive and powerful CLIs.

Basic Annotated Metadata Example

Here's a simple example using annotated metadata:

from typing import Annotated
import typer

def greet(
    name: Annotated[str, typer.Option(help="Your name")],
    age: Annotated[int, typer.Option(min=0, max=120)]
):
    print(f"Hello {name}, age {age}")

app = typer.Typer()
app.command()(greet)

if __name__ == "__main__":
    app()

This defines two options with metadata. The name has help text. The age has validation bounds.

Key Benefits of Annotated Metadata

Improved readability: Code becomes self-documenting. The options clearly show their purpose.

Better validation: You can set constraints like min/max values. Typer enforces these automatically.

Richer help text: Options show detailed descriptions. Users understand them better.

Common Metadata Parameters

Typer's Option supports many parameters:

• help: Description for help text
• default: Default value if none provided
• min/max: Value range constraints
• hidden: Hide from help text

Combine these for powerful options. For more on help text, see our Python Typer Help Text Guide.

Advanced Metadata Usage

You can combine Annotated with other Typer features. Here's an example with enum choices:

from enum import Enum
from typing import Annotated
import typer

class Color(str, Enum):
    RED = "red"
    GREEN = "green"
    BLUE = "blue"

def pick_color(
    color: Annotated[Color, typer.Option(case_sensitive=False)]
):
    print(f"You chose {color.value}")

app = typer.Typer()
app.command()(pick_color)

This creates a color picker with case-insensitive matching. For more on enums, check our Python Typer Enum Guide.

Real-World Example

Here's a practical file processor using metadata:

from typing import Annotated
import typer
from pathlib import Path

def process_file(
    input: Annotated[Path, typer.Option(exists=True, dir_okay=False)],
    output: Annotated[Path, typer.Option(dir_okay=False, writable=True)],
    verbose: Annotated[bool, typer.Option("--verbose/-v")] = False
):
    """Process input file to output location."""
    if verbose:
        print(f"Processing {input} to {output}")
    # Processing logic here

app = typer.Typer()
app.command()(process_file)

This shows several metadata features:

• File existence validation
• Directory permission checks
• Boolean flag with short/long forms

For boolean flags, see our Boolean Flags Guide.

Conclusion

Typer's annotated metadata supercharges your CLI options. It makes them more descriptive and robust. You get better validation, help text, and user experience.

Start using Annotated in your Typer apps today. Your users will appreciate the improved interface. Your code will be clearer and more maintainable.