Skip to main content

Parameter Configuration with ArgumentInfo and OptionInfo

In Typer, the configuration of CLI parameters is managed through a set of metadata classes defined in typer/models.py. While developers typically interact with the typer.Argument() and typer.Option() functions, these are factory functions that return instances of ArgumentInfo and OptionInfo. These classes store the validation rules, help text, and behavioral settings that Typer uses to construct the underlying Click parameter objects.

The Parameter Metadata Hierarchy​

The foundation of parameter configuration is the ParameterInfo class. It serves as the base for both positional arguments and named options, containing the vast majority of shared configuration logic.

  • ParameterInfo: The base class containing core metadata like default values, help strings, environment variable mappings, and validation constraints.
  • ArgumentInfo: A subclass of ParameterInfo used specifically for positional CLI arguments.
  • OptionInfo: A subclass of ParameterInfo used for CLI options (flags and named parameters). it adds features like interactive prompts and confirmation prompts.

In modern Typer usage, these objects are typically attached to function parameters using typing.Annotated:

from typing import Annotated
import typer

app = typer.Typer()

@app.command()
def main(
    name: Annotated[str, typer.Argument(help="The user's name")],
    force: Annotated[bool, typer.Option(help="Force the operation")] = False
):
    ...

Shared Configuration and Validation​

Because ArgumentInfo and OptionInfo both inherit from ParameterInfo, they share a extensive set of validation and metadata attributes.

Core Metadata​

  • help: The documentation string displayed in the CLI help output.
  • envvar: A string or list of strings representing environment variables that can provide the parameter value.
  • show_default: Controls whether the default value is shown in help text. It can be a boolean or a custom string.
  • rich_help_panel: A string used by the Rich-based help formatter to group parameters into specific visual panels.

Numeric Validation​

For parameters with numeric types, ParameterInfo provides attributes to enforce ranges:

  • min / max: Enforce inclusive lower and upper bounds.
  • clamp: If True, values outside the range are clamped to the nearest bound instead of raising a validation error.

Path and File Constraints​

When a parameter is a pathlib.Path or a file-like object, ParameterInfo supports detailed filesystem checks:

  • exists: If True, the path must exist on the filesystem.
  • file_okay / dir_okay: Control whether the path can be a file or a directory.
  • writable / readable: Ensure the process has appropriate permissions.
  • resolve_path: If True, Typer will resolve the absolute path before passing it to your function.

Option-Specific Features​

OptionInfo extends the base configuration with behaviors unique to named CLI options. These are primarily focused on interactive user input.

Interactive Prompts​

Options can be configured to prompt the user if they are not provided on the command line:

  • prompt: Can be a boolean (uses the parameter name) or a custom string for the prompt message.
  • confirmation_prompt: If True, the user must enter the value twice to confirm.
  • hide_input: Useful for sensitive data like passwords; masks the user's input during the prompt.

Flag Handling​

While Typer handles boolean flags automatically based on type hints, OptionInfo includes a count attribute. When count=True, the option can be provided multiple times (e.g., -vvv), and the resulting value will be the integer count of occurrences.

Note on Deprecation: The is_flag and flag_value parameters in OptionInfo are deprecated and will be removed in a future release. Typer's parser determines flag behavior primarily through Python type hints.

Custom Type Handling and Constraints​

ParameterInfo allows for advanced type conversion through custom parsers. However, there is a strict constraint on how these are provided.

Custom Parsers vs. Click Types​

You can customize how a string from the CLI is converted into a Python object using either:

  1. parser: A callable that takes a string and returns the parsed value.
  2. click_type: A direct instance of a click.ParamType.

The ParameterInfo.__init__ method enforces that these are mutually exclusive. Providing both will raise a ValueError:

# From typer/models.py
if parser and click_type:
    raise ValueError(
                "Multiple custom type parsers provided. "
                "`parser` and `click_type` may not both be provided."
            )

Completion Support​

The shell_complete attribute allows for custom shell completion logic. However, the codebase notes that shell_complete is not fully supported and is slated for removal in versions following 0.16.0. Developers should look toward the autocompletion attribute for similar (though also legacy) functionality or rely on Typer's automatic completion for Enum and Choice types.