Skip to main content

argparse

Standard library module View source

Command-line parsing with a tagged ArgumentValue and a dynamic Namespace.

Parsed attributes are tagged values: use args.count.as_int(), args.name.as_str(), and args.files.values() to access native values.

Custom Actions

Named action registration normalizes constructor arguments to the standard Action fields and does not forward additional constructor keywords. Pass the action class directly to supply custom keywords.

Differences From CPython

  • Positional arguments: Custom actions are supported only for options. Using a custom class, factory, or registered action for a positional raises TypeError before construction.
  • Initializer overloads: Class construction checks only the leading __init__ signature exposed by the compiler; it does not search additional overloads or base initializers. Use a single initializer, or a factory that explicitly calls the desired overload.
  • Parser defaults: For direct classes and factories, defaults from set_defaults() and argument_default are passed as ArgumentValue, not unboxed to a native constructor parameter type. Leave the default parameter unannotated or accept ArgumentValue; alternatively, pass default= directly to add_argument(), which preserves its native type.

Incompatible signatures are rejected at compile time when independent of parser defaults, and with TypeError when they depend on runtime parser defaults.

variable SUPPRESS
SUPPRESS: Literal[str] = "==SUPPRESS=="
variable OPTIONAL
OPTIONAL: Literal[str] = "?"
variable ZERO_OR_MORE
ZERO_OR_MORE: Literal[str] = "*"
variable ONE_OR_MORE
ONE_OR_MORE: Literal[str] = "+"
variable REMAINDER
REMAINDER: Literal[str] = "..."
variable PARSER
PARSER: Literal[str] = "A..."
variable VALUE_NULL
VALUE_NULL: Literal[int] = json._KIND_NULL
variable VALUE_BOOL
VALUE_BOOL: Literal[int] = json._KIND_BOOL
variable VALUE_INT
VALUE_INT: Literal[int] = json._KIND_INT
variable VALUE_FLOAT
VALUE_FLOAT: Literal[int] = json._KIND_FLOAT
variable VALUE_STR
VALUE_STR: Literal[int] = json._KIND_STR
variable VALUE_ARRAY
VALUE_ARRAY: Literal[int] = json._KIND_ARRAY
variable VALUE_OBJECT
VALUE_OBJECT: Literal[int] = 7
class ArgumentValue
@tuple
class ArgumentValue
Constructors 2
__new__
__new__()
__new__
__new__(value)
Properties 1
kind
@property
kind(self: Self, Self: type)
Methods 9
array
array()
is_null
is_null(self: Self, Self: type)
as_str
as_str(self: Self, Self: type)
as_int
as_int(self: Self, Self: type)
as_float
as_float(self: Self, Self: type)
as_bool
as_bool(self: Self, Self: type)
as_type
as_type(self: Self, T: type, Self: type)
values
values(self: Self, Self: type)
append
append(self: Self, value, Self: type)
Special methods 7
__getitem__
__getitem__(self: Self, index: int, Self: type)
__len__
__len__(self: Self, Self: type)
__bool__
__bool__(self: Self, Self: type)
__eq__
__eq__(self: Self, other, Self: type)
__ne__
__ne__(self: Self, other, Self: type)
__repr__
__repr__(self: Self, Self: type)
__str__
__str__(self: Self, Self: type)
class Namespace
class Namespace
Constructors 1
__init__
__init__(self: Self, **kwargs, Self: type)
Special methods 9
__getattr__
__getattr__(self: Self, name: Literal[str], Self: type)
__setattr__
__setattr__(self: Self, name: Literal[str], value, Self: type)
__getitem__
__getitem__(self: Self, name: str, Self: type)
__setitem__
__setitem__(self: Self, name: str, value, Self: type)
__contains__
__contains__(self: Self, name: str, Self: type)
__delitem__
__delitem__(self: Self, name: str, Self: type)
__dict__
__dict__(self: Self, Self: type)
__eq__
__eq__(self: Self, other: Namespace, Self: type)
__repr__
__repr__(self: Self, Self: type)
class ArgumentTypeError
class ArgumentTypeError
Constructors 1
__init__
__init__(self: Self, message: str, Self: type)
class ArgumentError
class ArgumentError
Fields 1
argument_name str
Constructors 1
__init__
__init__(self: Self, argument, message: str, Self: type)
Special methods 1
__str__
__str__(self: Self, Self: type)
class Action
class Action
Fields 15
option_strings List[str]
dest str
nargs str
const ArgumentValue
default ArgumentValue
type Callable[str, ArgumentValue]
type_name str
choices _Choices
has_choices bool
required bool
help Optional[str]
metavar List[str]
deprecated bool
kind int
version Optional[str]
Constructors 1
__init__
__init__(self: Self, option_strings, dest: str, nargs = None, const = None, default = None, choices = None, required: bool = False, help: Optional[str] = None, metavar = None, deprecated: bool = False, **kwargs, Self: type)
Methods 1
format_usage
format_usage(self: Self, Self: type)
Special methods 2
__eq__
__eq__(self: Self, other: Action, Self: type)
__ne__
__ne__(self: Self, other: Action, Self: type)
class BooleanOptionalAction
class BooleanOptionalAction
Constructors 1
__init__
__init__(self: Self, option_strings, dest: str, default = None, choices = None, required: bool = False, help: Optional[str] = None, metavar = None, deprecated: bool = False, **kwargs, Self: type)
class HelpFormatter
class HelpFormatter
Constructors 1
__init__
__init__(self: Self, prog: str, indent_increment: int = 2, max_help_position: int = 24, width: Optional[int] = None, color: bool = True, Self: type)
Methods 7
start_section
start_section(self: Self, heading: Optional[str], Self: type)
end_section
end_section(self: Self, Self: type)
add_text
add_text(self: Self, text: Optional[str], Self: type)
add_usage
add_usage(self: Self, usage: Optional[str], actions: List[Action], groups: List[_MutuallyExclusiveGroup], prefix: Optional[str] = None, Self: type)
add_argument
add_argument(self: Self, action: Action, Self: type)
add_arguments
add_arguments(self: Self, actions: List[Action], Self: type)
format_help
format_help(self: Self, Self: type)
class RawDescriptionHelpFormatter
class RawDescriptionHelpFormatter
Constructors 1
__init__
__init__(self: Self, *args, **kwargs, Self: type)
class RawTextHelpFormatter
class RawTextHelpFormatter
Constructors 1
__init__
__init__(self: Self, *args, **kwargs, Self: type)
class ArgumentDefaultsHelpFormatter
class ArgumentDefaultsHelpFormatter
Constructors 1
__init__
__init__(self: Self, *args, **kwargs, Self: type)
class MetavarTypeHelpFormatter
class MetavarTypeHelpFormatter
Constructors 1
__init__
__init__(self: Self, *args, **kwargs, Self: type)
class FileType
class FileType
Constructors 1
__init__
__init__(self: Self, mode: str = "r", bufsize: int = -1, encoding: Optional[str] = None, errors: Optional[str] = None, Self: type)
Special methods 2
__call__
__call__(self: Self, string: str, Self: type)
__repr__
__repr__(self: Self, Self: type)
class ArgumentParser
class ArgumentParser
Fields 13
prog str
usage Optional[str]
description Optional[str]
epilog Optional[str]
prefix_chars str
fromfile_prefix_chars Optional[str]
argument_default ArgumentValue
conflict_handler str
allow_abbrev bool
exit_on_error bool
suggest_on_error bool
color bool
formatter_class Callable[str, HelpFormatter]
Constructors 1
__init__
__init__(self: Self, prog: Optional[str] = None, usage: Optional[str] = None, description: Optional[str] = None, epilog: Optional[str] = None, parents = None, formatter_class = HelpFormatter, prefix_chars: str = "-", fromfile_prefix_chars: Optional[str] = None, argument_default = None, conflict_handler: str = "error", add_help: bool = True, allow_abbrev: bool = True, exit_on_error: bool = True, suggest_on_error: bool = False, color: bool = True, Self: type)
Methods 18
add_argument
add_argument(self: Self, *names, **kwargs, Self: type)
add_argument_group
add_argument_group(self: Self, title: str = "", description: Optional[str] = None, Self: type)
add_mutually_exclusive_group
add_mutually_exclusive_group(self: Self, required: bool = False, Self: type)
add_subparsers
add_subparsers(self: Self, title: Optional[str] = None, description: Optional[str] = None, prog: Optional[str] = None, parser_class = None, dest: str = SUPPRESS, required: bool = False, help: Optional[str] = None, metavar = None, Self: type)
set_defaults
set_defaults(self: Self, **kwargs, Self: type)
get_default
get_default(self: Self, dest: str, Self: type)
register
register(self: Self, registry_name: Literal[str], value: str, object, Self: type)
parse_args
parse_args(self: Self, args = None, namespace = None, Self: type)
parse_known_args
parse_known_args(self: Self, args = None, namespace = None, Self: type)
parse_intermixed_args
parse_intermixed_args(self: Self, args = None, namespace = None, Self: type)
parse_known_intermixed_args
parse_known_intermixed_args(self: Self, args = None, namespace = None, Self: type)
convert_arg_line_to_args
convert_arg_line_to_args(self: Self, arg_line: str, Self: type)
exit
exit(self: Self, status: int = 0, message: Optional[str] = None, Self: type)
error
error(self: Self, message: str, Self: type)
format_usage
format_usage(self: Self, Self: type)
format_help
format_help(self: Self, Self: type)
print_usage
print_usage(self: Self, file = None, Self: type)
print_help
print_help(self: Self, file = None, Self: type)
class Action
@extend
class Action
Special methods 1
__call__
__call__(self: Self, parser, namespace: Namespace, values: ArgumentValue, option_string: Optional[str] = None, Self: type)
class BooleanOptionalAction
@extend
class BooleanOptionalAction
Special methods 1
__call__
__call__(self: Self, parser: ArgumentParser, namespace: Namespace, values: ArgumentValue, option_string: Optional[str] = None, Self: type)