Skip to content

arg

clap.arg 

arg(
    short_or_long: Optional[AutoFlag] = None,
    long_or_short: Optional[AutoFlag] = None,
    /,
    *,
    short: Optional[Union[str, bool]] = None,
    long: Optional[Union[str, bool]] = None,
    aliases: Optional[Sequence[str]] = None,
    group: Optional[Group] = None,
    action: Optional[Union[type, ArgAction]] = None,
    num_args: Optional[NargsType] = None,
    default_missing_value: Optional[U] = None,
    default_value: Optional[U] = None,
    choices: Optional[Sequence[str]] = None,
    required: Optional[bool] = None,
    help: Optional[str] = None,
    long_help: Optional[str] = None,
    value_name: Optional[str] = None,
    deprecated: bool = False,
) -> Any

Create a command-line argument.

Parameters:

  • short_or_long (Optional[AutoFlag], default: None ) –

    Use clap.short or clap.long to automatically create the short or long version of the argument.

  • long_or_short (Optional[AutoFlag], default: None ) –

    Use clap.short or clap.long to automatically create the short or long version of the argument.

  • short (Optional[Union[str, bool]], default: None ) –

    The short version of the argument without the preceding -. Specify True to automatically create it.

  • long (Optional[Union[str, bool]], default: None ) –

    The long version of the argument without the preceding --. Specify True to automatically create it.

  • aliases (Optional[Sequence[str]], default: None ) –

    Additional flags for the argument.

  • group (Optional[Group], default: None ) –

    The group to which the argument is added.

  • action (Optional[Union[type, ArgAction]], default: None ) –

    How to react to an argument when parsing it.

  • num_args (Optional[NargsType], default: None ) –

    The number of arguments parsed per occurrence.

  • default_missing_value (Optional[U], default: None ) –

    The value for the argument when the flag is present but no value is specified.

  • default_value (Optional[U], default: None ) –

    The value for the argument when not present.

  • choices (Optional[Sequence[str]], default: None ) –

    A sequence of valid choices for the argument.

  • required (Optional[bool], default: None ) –

    Whether the argument must be present.

  • help (Optional[str], default: None ) –

    The description of the argument for short help (-h).

  • long_help (Optional[str], default: None ) –

    The description of the argument for long help (--help).

  • value_name (Optional[str], default: None ) –

    The placeholder for the argument's value in the help message / usage.

  • deprecated (bool, default: False ) –

    Whether this argument is deprecated and should not be used.

Examples:

import clap
from clap import ArgAction, ColorChoice, arg, long, short


@clap.command
class Cli:
    verbose: bool = arg(short, long)
    include_hidden: bool = arg(short="H", long="hidden")
    additional_patterns: list[str] = arg(long="and", action=ArgAction.Append)
    color: ColorChoice = arg(
        long,
        value_name="WHEN",
        default_value=ColorChoice.Auto,
        default_missing_value=ColorChoice.Always,
        num_args="?",
    )
Source code in clap/api.py 
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
def arg[U](
    short_or_long: Optional[AutoFlag] = None,
    long_or_short: Optional[AutoFlag] = None,
    /,
    *,
    short: Optional[Union[str, bool]] = None,
    long: Optional[Union[str, bool]] = None,
    aliases: Optional[Sequence[str]] = None,
    group: Optional[Group] = None,
    action: Optional[Union[type, ArgAction]] = None,
    num_args: Optional[NargsType] = None,
    default_missing_value: Optional[U] = None,
    default_value: Optional[U] = None,
    choices: Optional[Sequence[str]] = None,
    required: Optional[bool] = None,
    help: Optional[str] = None,
    long_help: Optional[str] = None,
    value_name: Optional[str] = None,
    deprecated: bool = False,
) -> Arg:
    """Create a command-line argument.

    Args:
        short_or_long: Use `clap.short` or `clap.long` to automatically create
            the short or long version of the argument.
        long_or_short: Use `clap.short` or `clap.long` to automatically create
            the short or long version of the argument.
        short: The short version of the argument without the preceding `-`. Specify
            `True` to automatically create it.
        long: The long version of the argument without the preceding `--`. Specify
            `True` to automatically create it.
        aliases: Additional flags for the argument.
        group: The group to which the argument is added.
        action: How to react to an argument when parsing it.
        num_args: The number of arguments parsed per occurrence.
        default_missing_value: The value for the argument when the flag is
            present but no value is specified.
        default_value: The value for the argument when not present.
        choices: A sequence of valid choices for the argument.
        required: Whether the argument must be present.
        help: The description of the argument for short help (`-h`).
        long_help: The description of the argument for long help (`--help`).
        value_name: The placeholder for the argument's value in the help message / usage.
        deprecated: Whether this argument is deprecated and should not be used.

    Examples:

    ```python
    import clap
    from clap import ArgAction, ColorChoice, arg, long, short


    @clap.command
    class Cli:
        verbose: bool = arg(short, long)
        include_hidden: bool = arg(short="H", long="hidden")
        additional_patterns: list[str] = arg(long="and", action=ArgAction.Append)
        color: ColorChoice = arg(
            long,
            value_name="WHEN",
            default_value=ColorChoice.Auto,
            default_missing_value=ColorChoice.Always,
            num_args="?",
        )
    ```
    """
    short_name: Optional[Union[AutoFlag, str]] = None
    long_name: Optional[Union[AutoFlag, str]] = None

    match short_or_long:
        case AutoFlag.Short: short_name = AutoFlag.Short
        case AutoFlag.Long: long_name = AutoFlag.Long
        case _: pass

    match long_or_short:
        case AutoFlag.Short: short_name = AutoFlag.Short
        case AutoFlag.Long: long_name = AutoFlag.Long
        case _: pass

    if short is not None:
        if isinstance(short, str):
            if len(short) == 0:
                raise ValueError
            short_name = short
        elif short is True:
            short_name = AutoFlag.Short

    if long is not None:
        if isinstance(long, str):
            if len(long) == 0:
                raise ValueError
            long_name = long
        elif long is True:
            long_name = AutoFlag.Long

    return Arg(
        short=short_name,
        long=long_name,
        help=help,
        long_help=long_help,
        value_name=value_name,
        aliases=aliases or [],
        group=group,
        action=action,
        num_args=num_args,
        default_missing_value=default_missing_value,
        default_value=default_value,
        choices=choices,
        required=required,
        deprecated=deprecated,
    )

arg() returns an Arg object. However, the type stub for this function has return type Any. This way, type checkers are fooled, and the library gets complete information.

clap.short module-attribute 

short = Short

Generate short from the first character in the case-converted field name.

clap.long module-attribute 

long = Long

Generate long from the case-converted field name.