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,
    mutex: Optional[MutexGroup] = 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.

  • mutex (Optional[MutexGroup], default: None ) –

    The mutually exclusive 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 
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
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,
    mutex: Optional[MutexGroup] = 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.
        mutex: The mutually exclusive 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 = None
    long_name = None

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

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

    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,
        mutex=mutex,
        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, the type checker does not complain, and the library gets complete information without inspecting the AST.

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.