tessl/pypi-types-click

Typing stubs for click - a command line interface creation kit for Python

Overview

Eval results

Files

Parameters

Name: tessl/pypi-types-click
Author: tessl

Decorators and classes for defining command-line options and arguments with rich type validation, default values, prompts, and help text. Parameters provide the interface between users and command functionality.

Capabilities

Option Definition

Creates command-line options (flags and named parameters) with extensive configuration options for validation, prompting, and user interaction.

def option(
    *param_decls: str,
    cls: Type[Option] = Option,
    show_default: bool | str = False,
    prompt: bool | str = False,
    confirmation_prompt: bool = False,
    hide_input: bool = False,
    is_flag: bool | None = None,
    flag_value: Any | None = None,
    multiple: bool = False,
    count: bool = False,
    allow_from_autoenv: bool = True,
    type: _ConvertibleType | None = None,
    help: str | None = None,
    show_choices: bool = True,
    show_envvar: bool = False,
    hidden: bool = False,
    autocompletion: Callable[[Context, list[str], str], Iterable[str | tuple[str, str]]] | None = None,
    default: Any | None = None,
    required: bool = False,
    callback: _Callback | None = None,
    nargs: int | None = None,
    metavar: str | None = None,
    expose_value: bool = True,
    is_eager: bool = False,
    envvar: str | list[str] | None = None,
    **kwargs: Any,
) -> IdentityFunction:
    """
    Decorator that adds an option to a command.

    Parameters:
    - param_decls: Option declarations (e.g., '--verbose', '-v')
    - cls: Option class to use
    - show_default: Show default value in help
    - prompt: Prompt for value if not provided
    - confirmation_prompt: Require confirmation for sensitive input
    - hide_input: Hide input (for passwords)
    - is_flag: Whether this is a boolean flag
    - flag_value: Value when flag is present
    - multiple: Allow multiple values
    - count: Count occurrences of flag
    - allow_from_autoenv: Allow value from environment
    - type: Parameter type for validation
    - help: Help text
    - show_choices: Show choices in help for Choice type
    - show_envvar: Show environment variable name in help
    - hidden: Hide option from help output
    - autocompletion: Function for shell autocompletion
    - default: Default value
    - required: Whether parameter is required
    - callback: Validation/transformation callback
    - nargs: Number of arguments
    - metavar: Placeholder for help text
    - expose_value: Whether to pass value to function
    - is_eager: Process before other parameters
    - envvar: Environment variable name(s)

    Returns:
    Option decorator function
    """

Usage Examples:

# Basic flag
@click.option('--verbose', is_flag=True, help='Enable verbose output')

# Option with default value
@click.option('--count', default=1, help='Number of iterations')

# Required option
@click.option('--name', required=True, help='Your name')

# Option with prompt
@click.option('--password', prompt=True, hide_input=True)

# Option with choices
@click.option('--format', type=click.Choice(['json', 'xml', 'yaml']))

# Multiple values
@click.option('--tag', multiple=True, help='Tags to apply')

# Environment variable support
@click.option('--debug', envvar='DEBUG', is_flag=True)

Argument Definition

Creates positional command-line arguments with validation and type conversion.

def argument(
    *param_decls: str,
    cls: Type[Argument] = Argument,
    required: bool | None = None,
    type: _ConvertibleType | None = None,
    default: Any | None = None,
    callback: _Callback | None = None,
    nargs: int | None = None,
    metavar: str | None = None,
    expose_value: bool = True,
    is_eager: bool = False,
    envvar: str | list[str] | None = None,
    autocompletion: Callable[[Context, list[str], str], Iterable[str | tuple[str, str]]] | None = None,
) -> IdentityFunction:
    """
    Decorator that adds an argument to a command.

    Parameters:
    - param_decls: Argument declarations
    - cls: Argument class to use  
    - required: Whether argument is required
    - type: Parameter type for validation
    - default: Default value
    - callback: Validation/transformation callback
    - nargs: Number of arguments (-1 for unlimited)
    - metavar: Placeholder for help text
    - expose_value: Whether to pass value to function
    - is_eager: Process before other parameters
    - envvar: Environment variable name(s)
    - autocompletion: Function for shell autocompletion

    Returns:
    Argument decorator function
    """

Usage Examples:

# Basic argument
@click.argument('filename')

# Multiple arguments
@click.argument('files', nargs=-1)

# Typed argument
@click.argument('port', type=int)

# Optional argument with default
@click.argument('output', default='output.txt')

Specialized Option Decorators

Pre-configured option decorators for common patterns.

def confirmation_option(
    *param_decls: str,
    cls: Type[Option] = Option,
    help: str = "Confirm the action.",
    is_flag: bool = True,
    expose_value: bool = False,
    prompt: bool | str = False,
    **kwargs: Any,
) -> Callable:
    """
    Decorator for confirmation options (--yes, --force, etc.).

    Parameters:
    - param_decls: Option declarations
    - cls: Option class to use
    - help: Help text
    - is_flag: Whether this is a boolean flag
    - expose_value: Whether to pass value to function
    - prompt: Prompt for confirmation

    Returns:
    Option decorator function
    """

def password_option(
    *param_decls: str,
    cls: Type[Option] = Option,
    prompt: bool | str = True,
    hide_input: bool = True,
    confirmation_prompt: bool = False,
    **kwargs: Any,
) -> Callable:
    """
    Decorator for password input options.

    Parameters:
    - param_decls: Option declarations  
    - cls: Option class to use
    - prompt: Prompt for password
    - hide_input: Hide password input
    - confirmation_prompt: Require confirmation

    Returns:
    Option decorator function
    """

def version_option(
    version: str | None = None,
    *param_decls: str,
    cls: Type[Option] = Option,
    prog_name: str | None = None,
    message: str | None = None,
    is_flag: bool = True,
    **kwargs: Any,
) -> Callable:
    """
    Decorator for version display options.

    Parameters:
    - version: Version string or callable
    - param_decls: Option declarations
    - cls: Option class to use
    - prog_name: Program name for display
    - message: Custom version message format
    - is_flag: Whether this is a boolean flag

    Returns:
    Option decorator function
    """

def help_option(
    *param_decls: str,
    cls: Type[Option] = Option,
    help: str = "Show this message and exit.",
    is_flag: bool = True,
    **kwargs: Any,
) -> Callable:
    """
    Decorator for help display options.

    Parameters:
    - param_decls: Option declarations
    - cls: Option class to use  
    - help: Help text
    - is_flag: Whether this is a boolean flag

    Returns:
    Option decorator function
    """

Parameter Classes

Direct parameter classes for programmatic parameter creation.

class Parameter:
    param_type_name: str
    name: str
    opts: list[str]
    secondary_opts: list[str]
    type: ParamType
    required: bool
    callback: Callable | None
    nargs: int
    multiple: bool
    expose_value: bool
    default: Any
    is_eager: bool
    metavar: str | None
    envvar: str | list[str] | None

    def __init__(
        self,
        param_decls: Iterable[str] | None = None,
        type: Any = None,
        required: bool = False,
        default: Any | None = None,
        callback: Callable | None = None,
        nargs: int | None = None,
        metavar: str | None = None,
        expose_value: bool = True,
        is_eager: bool = False,
        envvar: str | list[str] | None = None,
    ) -> None:
        """
        Base parameter class.

        Parameters:
        - param_decls: Parameter declarations
        - type: Parameter type for validation
        - required: Whether parameter is required
        - default: Default value
        - callback: Validation/transformation callback
        - nargs: Number of arguments
        - metavar: Placeholder for help text
        - expose_value: Whether to pass value to function
        - is_eager: Process before other parameters
        - envvar: Environment variable name(s)
        """

    def get_default(self, ctx: Context) -> Any: ...
    def type_cast_value(self, ctx: Context, value: Any) -> Any: ...
    def process_value(self, ctx: Context, value: Any) -> Any: ...
    def full_process_value(self, ctx: Context, value: Any) -> Any: ...

class Option(Parameter):
    prompt: str
    confirmation_prompt: bool
    hide_input: bool
    is_flag: bool
    flag_value: Any
    is_bool_flag: bool
    count: bool
    multiple: bool
    allow_from_autoenv: bool
    help: str | None
    hidden: bool
    show_default: bool
    show_choices: bool
    show_envvar: bool

    def __init__(
        self,
        param_decls: Iterable[str] | None = None,
        show_default: bool = False,
        prompt: bool | str = False,
        confirmation_prompt: bool = False,
        hide_input: bool = False,
        is_flag: bool | None = None,
        flag_value: Any | None = None,
        multiple: bool = False,
        count: bool = False,
        allow_from_autoenv: bool = True,
        type: Any = None,
        help: str | None = None,
        hidden: bool = False,
        show_choices: bool = True,
        show_envvar: bool = False,
        **attrs: Any,
    ) -> None:
        """
        Option parameter class.

        Parameters:
        - param_decls: Option declarations
        - show_default: Show default value in help
        - prompt: Prompt for value if not provided
        - confirmation_prompt: Require confirmation
        - hide_input: Hide input display
        - is_flag: Whether this is a boolean flag
        - flag_value: Value when flag is present
        - multiple: Allow multiple values
        - count: Count flag occurrences
        - allow_from_autoenv: Allow environment variable
        - type: Parameter type
        - help: Help text
        - hidden: Hide from help
        - show_choices: Show choices in help
        - show_envvar: Show environment variable in help
        """

    def prompt_for_value(self, ctx: Context) -> Any: ...

class Argument(Parameter):
    def __init__(
        self, 
        param_decls: Iterable[str] | None = None, 
        required: bool | None = None, 
        **attrs: Any
    ) -> None:
        """
        Argument parameter class.

        Parameters:
        - param_decls: Argument declarations
        - required: Whether argument is required
        - **attrs: Additional parameter attributes
        """

Special Decorators

Convenience decorators for common parameter patterns and specialized options.

Confirmation Option

Creates a confirmation option that aborts execution if user declines.

def confirmation_option(
    *param_decls: str,
    help: str = 'Confirm the action.',
    **kwargs: Any,
) -> IdentityFunction:
    """
    Add a confirmation option (typically --yes/-y).
    
    Parameters:
    - param_decls: Option declarations (defaults to '--yes/-y')
    - help: Help text for the option
    - **kwargs: Additional option parameters
    
    Usage:
    @click.command()
    @click.confirmation_option()
    def dangerous_operation():
        click.echo("Performing dangerous operation...")
    
    # Command line usage:
    # myapp dangerous_operation --yes
    """

Password Option

Creates a password option with hidden input and optional confirmation.

def password_option(
    *param_decls: str,
    confirmation_prompt: bool = False,
    help: str | None = None,
    **kwargs: Any,
) -> IdentityFunction:
    """
    Add a password option with hidden input.
    
    Parameters:
    - param_decls: Option declarations (defaults to '--password')
    - confirmation_prompt: Require password confirmation
    - help: Help text for the option
    - **kwargs: Additional option parameters
    
    Usage:
    @click.command()
    @click.password_option()
    def login(password):
        authenticate(password)
    
    @click.command()
    @click.password_option(confirmation_prompt=True)
    def create_user(password):
        create_user_account(password)
    """

Version Option

Creates a version option that displays version information and exits.

def version_option(
    version: str | None = None,
    *param_decls: str,
    prog_name: str | None = None,
    message: str | None = None,
    help: str = 'Show the version and exit.',
    **kwargs: Any,
) -> IdentityFunction:
    """
    Add a version option that shows version and exits.
    
    Parameters:
    - version: Version string (auto-detected if None)
    - param_decls: Option declarations (defaults to '--version')
    - prog_name: Program name for display
    - message: Custom version message format
    - help: Help text for the option
    - **kwargs: Additional option parameters
    
    Usage:
    @click.command()
    @click.version_option(version='1.0.0')
    def cli():
        click.echo("Hello World!")
    
    # Custom message format
    @click.command()
    @click.version_option(
        version='2.1.0',
        prog_name='MyApp',
        message='%(prog)s version %(version)s'
    )
    def cli():
        pass
    """

Help Option

Creates a help option that displays help text and exits.

def help_option(
    *param_decls: str,
    help: str = 'Show this message and exit.',
    **kwargs: Any,
) -> IdentityFunction:
    """
    Add a help option (typically --help/-h).
    
    Parameters:
    - param_decls: Option declarations (defaults to '--help/-h')
    - help: Help text for the option
    - **kwargs: Additional option parameters
    
    Usage:
    @click.command(add_help_option=False)  # Disable auto help
    @click.help_option('--info', '-i')
    def cli():
        click.echo("Custom help option example")
    """

Pass Decorators

Decorators for passing context and objects to command functions.

def pass_context(f: _T) -> _T:
    """
    Pass the current context as first argument to decorated function.
    
    Usage:
    @click.command()
    @click.pass_context
    def cli(ctx):
        click.echo(f"Command: {ctx.info_name}")
        click.echo(f"Parent: {ctx.parent.info_name if ctx.parent else 'None'}")
    """

def pass_obj(f: _T) -> _T:
    """
    Pass the context object as first argument to decorated function.
    
    Usage:
    @click.group()
    @click.pass_context
    def cli(ctx):
        ctx.obj = {'database': 'mydb.sqlite'}
    
    @cli.command()
    @click.pass_obj
    def status(obj):
        click.echo(f"Database: {obj['database']}")
    """

def make_pass_decorator(object_type: type, ensure: bool = False) -> IdentityFunction:
    """
    Create a custom pass decorator for specific object types.
    
    Parameters:
    - object_type: Type of object to pass
    - ensure: Create object if it doesn't exist
    
    Usage:
    pass_database = click.make_pass_decorator(Database)
    
    @click.command()
    @pass_database
    def query(db):
        results = db.execute("SELECT * FROM users")
    """

Install with Tessl CLI