# `argparse` — Parser for command-line options, arguments and subcommands

Added in version 3.2.

Вихідний код: Lib/argparse.py

Примітка

While `argparse` is the default recommended standard library module for implementing basic command line applications, authors with more exacting requirements for exactly how their command line applications behave may find it doesn’t provide the necessary level of control. Refer to Choosing an argument parsing library for alternatives to consider when `argparse` doesn’t support behaviors that the application requires (such as entirely disabling support for interspersed options and positional arguments, or accepting option parameter values that start with `-` even when they correspond to another defined option).

The `argparse` module makes it easy to write user-friendly command-line interfaces. The program defines what arguments it requires, and `argparse` will figure out how to parse those out of `sys.argv`. The `argparse` module also automatically generates help and usage messages. The module will also issue errors when users give the program invalid arguments.

The `argparse` module’s support for command-line interfaces is built around an instance of `argparse.ArgumentParser`. It is a container for argument specifications and has options that apply to the parser as whole:

    parser = argparse.ArgumentParser(
                        prog='ProgramName',
                        description='What the program does',
                        epilog='Text at the bottom of help')

The `ArgumentParser.add_argument()` method attaches individual argument specifications to the parser. It supports positional arguments, options that accept values, and on/off flags:

    parser.add_argument('filename')           # positional argument
    parser.add_argument('-c', '--count')      # option that takes a value
    parser.add_argument('-v', '--verbose',
                        action='store_true')  # on/off flag

The `ArgumentParser.parse_args()` method runs the parser and places the extracted data in a `argparse.Namespace` object:

    args = parser.parse_args()
    print(args.filename, args.count, args.verbose)

Примітка

If you’re looking for a guide about how to upgrade `optparse` code to `argparse`, see Upgrading Optparse Code.

## Об’єкти ArgumentParser

class argparse.ArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True, *, suggest_on_error=True, color=True)

  Створіть новий об’єкт `ArgumentParser`. Усі параметри слід передати як аргументи ключового слова. Кожен параметр має власний більш детальний опис нижче, але коротко вони:

  - prog - The name of the program (default: generated from the `__main__` module attributes and `sys.argv[0]`)

  - usage - рядок, що описує використання програми (за замовчуванням: генерується з аргументів, доданих до аналізатора)

  - description - Text to display before the argument help (by default, no text)

  - epilog - Text to display after the argument help (by default, no text)

  - Parents - список об’єктів `ArgumentParser`, аргументи яких також мають бути включені

  - formatter_class - клас для налаштування виведення довідки

  - prefix_chars - набір символів, які є префіксом необов’язкових аргументів (за замовчуванням: „-„)

  - fromfile_prefix_chars - набір символів, які є префіксами файлів, з яких слід читати додаткові аргументи (за замовчуванням: `None`)

  - argument_default - глобальне значення за замовчуванням для аргументів (за замовчуванням: `None`)

  - конфлікт_обробник - стратегія вирішення конфліктних опцій (зазвичай непотрібних)

  - add_help - додає опцію `-h/--help` до аналізатора (за замовчуванням: `True`)

  - allow_abbrev - Allows long options to be abbreviated if the abbreviation is unambiguous (default: `True`)

  - exit_on_error - Determines whether or not `ArgumentParser` exits with error info when an error occurs. (default: `True`)

  - suggest_on_error - Enables suggestions for mistyped argument choices and subparser names (default: `True`)

  - color - Allow color output (default: `True`)

  Змінено в версії 3.5: Додано параметр allow_abbrev.

  Змінено в версії 3.8: У попередніх версіях allow_abbrev також вимикав групування коротких прапорців, таких як `-vv`, щоб означати `-v -v`.

  Змінено в версії 3.9: Додано параметр exit_on_error.

  Змінено в версії 3.14: suggest_on_error and color parameters were added.

  Змінено в версії 3.15: suggest_on_error default changed to `True`.

У наступних розділах описано, як використовується кожен із них.

### прог

By default, `ArgumentParser` calculates the name of the program to display in help messages depending on the way the Python interpreter was run:

- The `base name` of `sys.argv[0]` if a file was passed as argument.

- The Python interpreter name followed by `sys.argv[0]` if a directory or a zipfile was passed as argument.

- The Python interpreter name followed by `-m` followed by the module or package name if the `-m` option was used.

This default is almost always desirable because it will make the help messages match the string that was used to invoke the program on the command line. However, to change this default behavior, another value can be supplied using the `prog=` argument to `ArgumentParser`:

    >>> parser = argparse.ArgumentParser(prog='myprogram')
    >>> parser.print_help()
    usage: myprogram [-h]

    options:
     -h, --help  show this help message and exit

Note that the program name, whether determined from `sys.argv[0]`, from the `__main__` module attributes or from the `prog=` argument, is available to help messages using the `%(prog)s` format specifier.

    >>> parser = argparse.ArgumentParser(prog='myprogram')
    >>> parser.add_argument('--foo', help='foo of the %(prog)s program')
    >>> parser.print_help()
    usage: myprogram [-h] [--foo FOO]

    options:
     -h, --help  show this help message and exit
     --foo FOO   foo of the myprogram program

Змінено в версії 3.14: The default `prog` value now reflects how `__main__` was actually executed, rather than always being `os.path.basename(sys.argv[0])`.

### використання

By default, `ArgumentParser` calculates the usage message from the arguments it contains. The default message can be overridden with the `usage=` keyword argument:

    >>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
    >>> parser.add_argument('--foo', nargs='?', help='foo help')
    >>> parser.add_argument('bar', nargs='+', help='bar help')
    >>> parser.print_help()
    usage: PROG [options]

    positional arguments:
     bar          bar help

    options:
     -h, --help   show this help message and exit
     --foo [FOO]  foo help

Специфікатор формату `%(prog)s` доступний для заповнення назви програми у ваших повідомленнях про використання.

When a custom usage message is specified for the main parser, you may also want to consider passing the `prog` argument to `add_subparsers()` or the `prog` and the `usage` arguments to `add_parser()`, to ensure consistent command prefixes and usage information across subparsers.

### опис

Most calls to the `ArgumentParser` constructor will use the `description=` keyword argument. This argument gives a brief description of what the program does and how it works. In help messages, the description is displayed between the command-line usage string and the help messages for the various arguments.

За замовчуванням опис буде перенесено на рядок, щоб він поміщався в заданий простір. Щоб змінити цю поведінку, перегляньте аргумент formatter_class.

### епілог

Деякі програми люблять відображати додатковий опис програми після опису аргументів. Такий текст можна вказати за допомогою аргументу `epilog=` для `ArgumentParser`:

    >>> parser = argparse.ArgumentParser(
    ...     description='A foo that bars',
    ...     epilog="And that's how you'd foo a bar")
    >>> parser.print_help()
    usage: argparse.py [-h]

    A foo that bars

    options:
     -h, --help  show this help message and exit

    And that's how you'd foo a bar

Як і в випадку з аргументом description, текст `epilog=` за замовчуванням переносить рядки, але цю поведінку можна налаштувати за допомогою аргументу formatter_class на `ArgumentParser`.

### батьки

Іноді кілька аналізаторів використовують загальний набір аргументів. Замість того, щоб повторювати визначення цих аргументів, можна використати єдиний синтаксичний аналізатор із усіма спільними аргументами та переданим аргументом `parents=` для `ArgumentParser`. Аргумент `parents=` бере список об’єктів `ArgumentParser`, збирає всі позиційні та необов’язкові дії з них і додає ці дії до об’єкта `ArgumentParser`, який створюється:

    >>> parent_parser = argparse.ArgumentParser(add_help=False)
    >>> parent_parser.add_argument('--parent', type=int)

    >>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
    >>> foo_parser.add_argument('foo')
    >>> foo_parser.parse_args(['--parent', '2', 'XXX'])
    Namespace(foo='XXX', parent=2)

    >>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
    >>> bar_parser.add_argument('--bar')
    >>> bar_parser.parse_args(['--bar', 'YYY'])
    Namespace(bar='YYY', parent=None)

Зауважте, що більшість батьківських аналізаторів вказуватимуть `add_help=False`. Інакше `ArgumentParser` побачить два параметри `-h/--help` (один у батьківському і один у дочірньому) і викличе помилку.

Примітка

Ви повинні повністю ініціалізувати аналізатори перед тим, як передавати їх через `parents=`. Якщо ви змінюєте батьківські аналізатори після дочірнього, ці зміни не відображатимуться в дочірньому.

### formatter_class

Об’єкти `ArgumentParser` дозволяють налаштувати форматування довідки шляхом визначення альтернативного класу форматування. На даний момент існує чотири таких класи:

class argparse.RawDescriptionHelpFormatter
class argparse.RawTextHelpFormatter
class argparse.ArgumentDefaultsHelpFormatter
class argparse.MetavarTypeHelpFormatter

`RawDescriptionHelpFormatter` і `RawTextHelpFormatter` дають більше контролю над тим, як відображаються текстові описи. За замовчуванням об’єкти `ArgumentParser` переносять тексти description і epilog у довідкові повідомлення командного рядка:

    >>> parser = argparse.ArgumentParser(
    ...     prog='PROG',
    ...     description='''this description
    ...         was indented weird
    ...             but that is okay''',
    ...     epilog='''
    ...             likewise for this epilog whose whitespace will
    ...         be cleaned up and whose words will be wrapped
    ...         across a couple lines''')
    >>> parser.print_help()
    usage: PROG [-h]

    this description was indented weird but that is okay

    options:
     -h, --help  show this help message and exit

    likewise for this epilog whose whitespace will be cleaned up and whose words
    will be wrapped across a couple lines

Передача `RawDescriptionHelpFormatter` як `formatter_class=` вказує на те, що description і epilog вже правильно відформатовані і не повинні бути перенесені в рядок:

    >>> parser = argparse.ArgumentParser(
    ...     prog='PROG',
    ...     formatter_class=argparse.RawDescriptionHelpFormatter,
    ...     description=textwrap.dedent('''\
    ...         Please do not mess up this text!
    ...         --------------------------------
    ...             I have indented it
    ...             exactly the way
    ...             I want it
    ...         '''))
    >>> parser.print_help()
    usage: PROG [-h]

    Please do not mess up this text!
    --------------------------------
       I have indented it
       exactly the way
       I want it

    options:
     -h, --help  show this help message and exit

`RawTextHelpFormatter` maintains whitespace for all sorts of help text, including argument descriptions. However, multiple newlines are replaced with one. If you wish to preserve multiple blank lines, add spaces between the newlines.

`ArgumentDefaultsHelpFormatter` автоматично додає інформацію про значення за замовчуванням до кожного довідкового повідомлення аргументу:

    >>> parser = argparse.ArgumentParser(
    ...     prog='PROG',
    ...     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
    >>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
    >>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
    >>> parser.print_help()
    usage: PROG [-h] [--foo FOO] [bar ...]

    positional arguments:
     bar         BAR! (default: [1, 2, 3])

    options:
     -h, --help  show this help message and exit
     --foo FOO   FOO! (default: 42)

`MetavarTypeHelpFormatter` використовує ім’я аргументу type для кожного аргументу як відображуване ім’я для його значень (замість використання dest, як це робить звичайний засіб форматування):

    >>> parser = argparse.ArgumentParser(
    ...     prog='PROG',
    ...     formatter_class=argparse.MetavarTypeHelpFormatter)
    >>> parser.add_argument('--foo', type=int)
    >>> parser.add_argument('bar', type=float)
    >>> parser.print_help()
    usage: PROG [-h] [--foo int] float

    positional arguments:
      float

    options:
      -h, --help  show this help message and exit
      --foo int

### prefix_chars

Most command-line options will use `-` as the prefix, e.g. `-f/--foo`. Parsers that need to support different or additional prefix characters, e.g. for options like `+f` or `/foo`, may specify them using the `prefix_chars=` argument to the `ArgumentParser` constructor:

    >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
    >>> parser.add_argument('+f')
    >>> parser.add_argument('++bar')
    >>> parser.parse_args('+f X ++bar Y'.split())
    Namespace(bar='Y', f='X')

Аргумент `prefix_chars=` за умовчанням має значення `'-'`. Якщо вказати набір символів, який не містить `-`, параметри `-f/--foo` будуть заборонені.

### fromfile_prefix_chars

Sometimes, when dealing with a particularly long argument list, it may make sense to keep the list of arguments in a file rather than typing it out at the command line. If the `fromfile_prefix_chars=` argument is given to the `ArgumentParser` constructor, then arguments that start with any of the specified characters will be treated as files, and will be replaced by the arguments they contain. For example:

    >>> with open('args.txt', 'w', encoding=sys.getfilesystemencoding()) as fp:
    ...     fp.write('-f\nbar')
    ...
    >>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
    >>> parser.add_argument('-f')
    >>> parser.parse_args(['-f', 'foo', '@args.txt'])
    Namespace(f='bar')

Arguments read from a file must be one per line by default (but see also `convert_arg_line_to_args()`) and are treated as if they were in the same place as the original file referencing argument on the command line. So in the example above, the expression `['-f', 'foo', '@args.txt']` is considered equivalent to the expression `['-f', 'foo', '-f', 'bar']`.

Примітка

Empty lines are treated as empty strings (`''`), which are allowed as values but not as arguments. Empty lines that are read as arguments will result in an «unrecognized arguments» error.

`ArgumentParser` uses filesystem encoding and error handler to read the file containing arguments.

Аргумент `fromfile_prefix_chars=` за умовчанням має значення `None`, що означає, що аргументи ніколи не розглядатимуться як посилання на файли.

Змінено в версії 3.12: `ArgumentParser` changed encoding and errors to read arguments files from default (e.g. `locale.getpreferredencoding(False)` and `"strict"`) to the filesystem encoding and error handler. Arguments file should be encoded in UTF-8 instead of ANSI Codepage on Windows.

### аргумент_за замовчуванням

Як правило, параметри за замовчуванням вказуються або передачею значення за замовчуванням `add_argument()`, або викликом методів `set_defaults()` із певним набором пар ім’я-значення. Іноді, однак, може бути корисно вказати єдине значення за замовчуванням для параметрів аналізатора. Це можна зробити, передавши аргумент ключового слова `argument_default=` до `ArgumentParser`. Наприклад, щоб глобально заборонити створення атрибутів у викликах `parse_args()`, ми надаємо `argument_default=SUPPRESS`:

    >>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
    >>> parser.add_argument('--foo')
    >>> parser.add_argument('bar', nargs='?')
    >>> parser.parse_args(['--foo', '1', 'BAR'])
    Namespace(bar='BAR', foo='1')
    >>> parser.parse_args([])
    Namespace()

### дозволити_скорочене

Зазвичай, коли ви передаєте список аргументів у метод `parse_args()` `ArgumentParser`, він розпізнає абревіатури довгих параметрів.

Цю функцію можна вимкнути, встановивши для параметра `allow_abbrev` значення `False`:

    >>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)
    >>> parser.add_argument('--foobar', action='store_true')
    >>> parser.add_argument('--foonley', action='store_false')
    >>> parser.parse_args(['--foon'])
    usage: PROG [-h] [--foobar] [--foonley]
    PROG: error: unrecognized arguments: --foon

Added in version 3.5.

### обробник_конфлікту

Об’єкти `ArgumentParser` не дозволяють дві дії з однаковим рядком параметрів. За замовчуванням об’єкти `ArgumentParser` викликають виняток, якщо робиться спроба створити аргумент із рядком параметрів, який уже використовується:

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('-f', '--foo', help='old foo help')
    >>> parser.add_argument('--foo', help='new foo help')
    Traceback (most recent call last):
     ..
    ArgumentError: argument --foo: conflicting option string(s): --foo

Іноді (наприклад, під час використання батьків) може бути корисним просто замінити будь-які старіші аргументи тим самим рядком параметрів. Щоб отримати таку поведінку, значення `'resolve'` можна надати аргументу `conflict_handler=` `ArgumentParser`:

    >>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
    >>> parser.add_argument('-f', '--foo', help='old foo help')
    >>> parser.add_argument('--foo', help='new foo help')
    >>> parser.print_help()
    usage: PROG [-h] [-f FOO] [--foo FOO]

    options:
     -h, --help  show this help message and exit
     -f FOO      old foo help
     --foo FOO   new foo help

Зауважте, що об’єкти `ArgumentParser` видаляють дію лише в тому випадку, якщо перевизначено всі рядки параметрів. Отже, у наведеному вище прикладі стара дія `-f/--foo` зберігається як дія `-f`, тому що було замінено лише рядок опції `--foo`.

### add_help

By default, `ArgumentParser` objects add an option which simply displays the parser’s help message. If `-h` or `--help` is supplied at the command line, the `ArgumentParser` help will be printed.

Іноді може бути корисним вимкнути додавання цієї опції довідки. Цього можна досягти, передавши `False` як аргумент `add_help=` до `ArgumentParser`:

    >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
    >>> parser.add_argument('--foo', help='foo help')
    >>> parser.print_help()
    usage: PROG [--foo FOO]

    options:
     --foo FOO  foo help

Параметром довідки зазвичай є `-h/--help`. Винятком є те, що `prefix_chars=` указано і не містить `-`, у цьому випадку `-h` і `--help` не є дійсними параметрами. У цьому випадку перший символ у `prefix_chars` використовується для префіксу параметрів довідки:

    >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
    >>> parser.print_help()
    usage: PROG [+h]

    options:
      +h, ++help  show this help message and exit

### exit_on_error

Normally, when you pass an invalid argument list to the `parse_args()` method of an `ArgumentParser`, it will print a message to `sys.stderr` and exit with a status code of 2.

Якщо користувач хоче виловлювати помилки вручну, цю функцію можна ввімкнути, встановивши для `exit_on_error` значення `False`:

    >>> parser = argparse.ArgumentParser(exit_on_error=False)
    >>> parser.add_argument('--integers', type=int)
    _StoreAction(option_strings=['--integers'], dest='integers', nargs=None, const=None, default=None, type=<class 'int'>, choices=None, help=None, metavar=None)
    >>> try:
    ...     parser.parse_args('--integers a'.split())
    ... except argparse.ArgumentError:
    ...     print('Catching an argumentError')
    ...
    Catching an argumentError

Added in version 3.9.

### suggest_on_error

By default, when a user passes an invalid argument choice or subparser name, `ArgumentParser` will exit with error info and provide suggestions for mistyped arguments. The error message will list the permissible argument choices (if specified) or subparser names, along with a «maybe you meant» suggestion if a close match is found. Note that this only applies for arguments when the choices specified are strings:

    >>> parser = argparse.ArgumentParser(description='Process some integers.',
                                         suggest_on_error=True)
    >>> parser.add_argument('--action', choices=['sum', 'max'])
    >>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
    ...                     help='an integer for the accumulator')
    >>> parser.parse_args(['--action', 'sumn', 1, 2, 3])
    tester.py: error: argument --action: invalid choice: 'sumn', maybe you meant 'sum'? (choose from 'sum', 'max')

You can disable suggestions by setting `suggest_on_error` to `False`:

    >>> parser = argparse.ArgumentParser(description='Process some integers.',
                                         suggest_on_error=False)

Added in version 3.14.

Змінено в версії 3.15: Changed default value of `suggest_on_error` from `False` to `True`.

### color

By default, the help message is printed in color using ANSI escape sequences. If you want plain text help messages, you can disable this in your local environment, or in the argument parser itself by setting `color` to `False`:

    >>> parser = argparse.ArgumentParser(description='Process some integers.',
    ...                                  color=False)
    >>> parser.add_argument('--action', choices=['sum', 'max'])
    >>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
    ...                     help='an integer for the accumulator')
    >>> parser.parse_args(['--help'])

Note that when `color=True`, colored output depends on both environment variables and terminal capabilities. However, if `color=False`, colored output is always disabled, even if environment variables like `FORCE_COLOR` are set.

Added in version 3.14.

To highlight inline code in your description or epilog text, you can use backticks:

    >>> parser = argparse.ArgumentParser(
    ...     formatter_class=argparse.RawDescriptionHelpFormatter,
    ...     epilog='''Examples:
    ...   `python -m myapp --verbose`
    ...   `python -m myapp --config settings.json`
    ... ''')

When colors are enabled, the text inside backticks will be displayed in a distinct color to help examples stand out. When colors are disabled, backticks are preserved as-is, which is readable in plain text.

Примітка

Backtick markup only applies to description and epilog text. It does not apply to individual argument `help` strings.

Added in version 3.15.

## Метод add_argument().

ArgumentParser.add_argument(name or flags..., *[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest][, deprecated])

  Визначте, як слід аналізувати один аргумент командного рядка. Кожен параметр має власний більш детальний опис нижче, але коротко вони:

  - name or flags - Either a name or a list of option strings, e.g. `'foo'` or `'-f', '--foo'`.

  - action - основний тип дії, яку потрібно виконати, коли цей аргумент зустрічається в командному рядку.

  - nargs – кількість аргументів командного рядка, які мають бути використані.

  - const – постійне значення, необхідне для вибору деяких action і nargs.

  - default – значення, створене, якщо аргумент відсутній у командному рядку та якщо він відсутній в об’єкті простору імен.

  - type – тип, до якого потрібно перетворити аргумент командного рядка.

  - choices - A sequence of the allowable values for the argument.

  - required – чи можна пропустити параметр командного рядка (тільки необов’язковий).

  - help - короткий опис того, що робить аргумент.

  - metavar – назва аргументу в повідомленнях про використання.

  - dest – ім’я атрибута, який буде додано до об’єкта, повернутого `parse_args()`.

  - deprecated - Whether or not use of the argument is deprecated.

У наступних розділах описано, як використовується кожен із них.

### назву чи прапори

The `add_argument()` method must know whether an optional argument, like `-f` or `--foo`, or a positional argument, like a list of filenames, is expected. The first arguments passed to `add_argument()` must therefore be either a series of flags, or a simple argument name.

For example, an optional argument could be created like:

    >>> parser.add_argument('-f', '--foo')

тоді як позиційний аргумент може бути створений таким чином:

    >>> parser.add_argument('bar')

Під час виклику `parse_args()` необов’язкові аргументи ідентифікуються префіксом `-`, а решта аргументів вважатиметься позиційними:

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('-f', '--foo')
    >>> parser.add_argument('bar')
    >>> parser.parse_args(['BAR'])
    Namespace(bar='BAR', foo=None)
    >>> parser.parse_args(['BAR', '--foo', 'FOO'])
    Namespace(bar='BAR', foo='FOO')
    >>> parser.parse_args(['--foo', 'FOO'])
    usage: PROG [-h] [-f FOO] bar
    PROG: error: the following arguments are required: bar

By default, `argparse` automatically handles the internal naming and display names of arguments, simplifying the process without requiring additional configuration. As such, you do not need to specify the dest and metavar parameters. The dest parameter defaults to the argument name with underscores `_` replacing hyphens `-` . The metavar parameter defaults to the upper-cased name. For example:

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('--foo-bar')
    >>> parser.parse_args(['--foo-bar', 'FOO-BAR'])
    Namespace(foo_bar='FOO-BAR')
    >>> parser.print_help()
    usage:  [-h] [--foo-bar FOO-BAR]

    optional arguments:
     -h, --help  show this help message and exit
     --foo-bar FOO-BAR

### дію

Об’єкти `ArgumentParser` пов’язують аргументи командного рядка з діями. Ці дії можуть робити що завгодно з пов’язаними з ними аргументами командного рядка, хоча більшість дій просто додають атрибут до об’єкта, який повертає `parse_args()`. Аргумент ключового слова `action` визначає, як слід обробляти аргументи командного рядка. Надані дії:

- `'store'` - This just stores the argument’s value. This is the default action.

- `'store_const'` - This stores the value specified by the const keyword argument; note that the const keyword argument defaults to `None`. The `'store_const'` action is most commonly used with optional arguments that specify some sort of flag. For example:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', action='store_const', const=42)
      >>> parser.parse_args(['--foo'])
      Namespace(foo=42)

- `'store_true'` and `'store_false'` - These are special cases of `'store_const'` that respectively store the values `True` and `False` with default values of `False` and `True`:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', action='store_true')
      >>> parser.add_argument('--bar', action='store_false')
      >>> parser.add_argument('--baz', action='store_false')
      >>> parser.parse_args('--foo --bar'.split())
      Namespace(foo=True, bar=False, baz=True)

- `'append'` - This appends each argument value to a list. It is useful for allowing an option to be specified multiple times. If the default value is a non-empty list, the parsed value will start with the default list’s elements and any values from the command line will be appended after those default values. Example usage:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', action='append', default=['0'])
      >>> parser.parse_args('--foo 1 --foo 2'.split())
      Namespace(foo=['0', '1', '2'])

- `'append_const'` - This appends the value specified by the const keyword argument to a list; note that the const keyword argument defaults to `None`. The `'append_const'` action is typically useful when multiple arguments need to store constants to the same list. For example:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--str', dest='types', action='append_const', const=str)
      >>> parser.add_argument('--int', dest='types', action='append_const', const=int)
      >>> parser.parse_args('--str --int'.split())
      Namespace(types=[<class 'str'>, <class 'int'>])

- `'extend'` - This appends each item from a multi-value argument to a list. The `'extend'` action is typically used with the nargs keyword argument value `'+'` or `'*'`. Note that when nargs is `None` (the default) or `'?'`, each character of the argument string will be appended to the list. Example usage:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument("--foo", action="extend", nargs="+", type=str)
      >>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
      Namespace(foo=['f1', 'f2', 'f3', 'f4'])

  Added in version 3.8.

- `'count'` - This counts the number of times an argument occurs. For example, this is useful for increasing verbosity levels:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--verbose', '-v', action='count', default=0)
      >>> parser.parse_args(['-vvv'])
      Namespace(verbose=3)

  Зауважте, за замовчуванням буде `None`, якщо явно не встановлено 0.

- `'help'` - друкує повне повідомлення довідки для всіх параметрів у поточному парсері, а потім завершує роботу. За замовчуванням дія довідки автоматично додається до аналізатора. Дивіться `ArgumentParser` для детальної інформації про те, як створюється вихід.

- `'version'` – очікується ключовий аргумент `version=` у виклику `add_argument()`, друкується інформація про версію та завершується після виклику:

      >>> import argparse
      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
      >>> parser.parse_args(['--version'])
      PROG 2.0

You may also specify an arbitrary action by passing an `Action` subclass (e.g. `BooleanOptionalAction`) or other object that implements the same interface. Only actions that consume command-line arguments (e.g. `'store'`, `'append'`, `'extend'`, or custom actions with non-zero `nargs`) can be used with positional arguments.

The recommended way to create a custom action is to extend `Action`, overriding the `__call__()` method and optionally the `__init__()` and `format_usage()` methods. You can also register custom actions using the `register()` method and reference them by their registered name.

Приклад спеціальної дії:

    >>> class FooAction(argparse.Action):
    ...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
    ...         if nargs is not None:
    ...             raise ValueError("nargs not allowed")
    ...         super().__init__(option_strings, dest, **kwargs)
    ...     def __call__(self, parser, namespace, values, option_string=None):
    ...         print('%r %r %r' % (namespace, values, option_string))
    ...         setattr(namespace, self.dest, values)
    ...
    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo', action=FooAction)
    >>> parser.add_argument('bar', action=FooAction)
    >>> args = parser.parse_args('1 --foo 2'.split())
    Namespace(bar=None, foo=None) '1' None
    Namespace(bar='1', foo=None) '2' '--foo'
    >>> args
    Namespace(bar='1', foo='2')

Для отримання додаткової інформації див. `Action`.

### наргс

`ArgumentParser` objects usually associate a single command-line argument with a single action to be taken. The `nargs` keyword argument associates a different number of command-line arguments with a single action. See also Specifying ambiguous arguments. The supported values are:

- `N` (ціле число). `N` аргументів з командного рядка буде зібрано разом у список. Наприклад:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', nargs=2)
      >>> parser.add_argument('bar', nargs=1)
      >>> parser.parse_args('c --foo a b'.split())
      Namespace(bar=['c'], foo=['a', 'b'])

  Зауважте, що `nargs=1` створює список з одного елемента. Це відрізняється від типового, коли елемент створюється сам по собі.

- `'?'`. Один аргумент буде використано з командного рядка, якщо це можливо, і створено як окремий елемент. Якщо аргумент командного рядка відсутній, буде отримано значення з default. Зауважте, що для необов’язкових аргументів існує додатковий випадок – рядок параметрів присутній, але не слідує за аргументом командного рядка. У цьому випадку буде отримано значення з const. Деякі приклади для ілюстрації:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', nargs='?', const='c', default='d')
      >>> parser.add_argument('bar', nargs='?', default='d')
      >>> parser.parse_args(['XX', '--foo', 'YY'])
      Namespace(bar='XX', foo='YY')
      >>> parser.parse_args(['XX', '--foo'])
      Namespace(bar='XX', foo='c')
      >>> parser.parse_args([])
      Namespace(bar='d', foo='d')

  Одне з найпоширеніших застосувань `nargs='?''` — дозволити додаткові файли введення та виведення:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('infile', nargs='?')
      >>> parser.add_argument('outfile', nargs='?')
      >>> parser.parse_args(['input.txt', 'output.txt'])
      Namespace(infile='input.txt', outfile='output.txt')
      >>> parser.parse_args(['input.txt'])
      Namespace(infile='input.txt', outfile=None)
      >>> parser.parse_args([])
      Namespace(infile=None, outfile=None)

- `'*'`. Усі присутні аргументи командного рядка збираються у список. Зауважте, що зазвичай не має сенсу мати більше одного позиційного аргументу з `nargs='*'`, але кілька необов’язкових аргументів з `nargs='*'` можливі. Наприклад:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', nargs='*')
      >>> parser.add_argument('--bar', nargs='*')
      >>> parser.add_argument('baz', nargs='*')
      >>> parser.parse_args('a b --foo x y --bar 1 2'.split())
      Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])

- `'+'`. Just like `'*'`, all command-line arguments present are gathered into a list. Additionally, an error message will be generated if there wasn’t at least one command-line argument present. For example:

      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> parser.add_argument('foo', nargs='+')
      >>> parser.parse_args(['a', 'b'])
      Namespace(foo=['a', 'b'])
      >>> parser.parse_args([])
      usage: PROG [-h] foo [foo ...]
      PROG: error: the following arguments are required: foo

If the `nargs` keyword argument is not provided, the number of arguments consumed is determined by the action. Generally this means a single command-line argument will be consumed and a single item (not a list) will be produced. Actions that do not consume command-line arguments (e.g. `'store_const'`) set `nargs=0`.

### конст

Аргумент `const` `add_argument()` використовується для зберігання постійних значень, які не читаються з командного рядка, але потрібні для різних дій `ArgumentParser`. Два найпоширеніші його використання:

- When `add_argument()` is called with `action='store_const'` or `action='append_const'`. These actions add the `const` value to one of the attributes of the object returned by `parse_args()`. See the action description for examples. If `const` is not provided to `add_argument()`, it will receive a default value of `None`.

- When `add_argument()` is called with option strings (like `-f` or `--foo`) and `nargs='?'`. This creates an optional argument that can be followed by zero or one command-line arguments. When parsing the command line, if the option string is encountered with no command-line argument following it, the value from `const` will be used. See the nargs description for examples.

Змінено в версії 3.11: `const=None` by default, including when `action='append_const'` or `action='store_const'`.

### за замовчуванням

Усі додаткові аргументи та деякі позиційні аргументи можна пропустити в командному рядку. Аргумент ключового слова `default` `add_argument()`, значення якого за замовчуванням `None`, визначає, яке значення слід використовувати, якщо аргумент командного рядка відсутній. Для необов’язкових аргументів використовується значення `за замовчуванням`, якщо рядок параметрів відсутній у командному рядку:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo', default=42)
    >>> parser.parse_args(['--foo', '2'])
    Namespace(foo='2')
    >>> parser.parse_args([])
    Namespace(foo=42)

If the target namespace already has an attribute set, the action default will not overwrite it:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo', default=42)
    >>> parser.parse_args([], namespace=argparse.Namespace(foo=101))
    Namespace(foo=101)

Якщо значенням `default` є рядок, синтаксичний аналізатор аналізує значення так, ніби це аргумент командного рядка. Зокрема, синтаксичний аналізатор застосовує будь-який аргумент перетворення type, якщо він надається, перед встановленням атрибута для значення, що повертається `Namespace`. В іншому випадку аналізатор використовує значення як є:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--length', default='10', type=int)
    >>> parser.add_argument('--width', default=10.5, type=int)
    >>> parser.parse_args()
    Namespace(length=10, width=10.5)

Для позиційних аргументів, у яких nargs дорівнює `?` або `*`, значення `default` використовується, якщо аргумент командного рядка відсутній:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('foo', nargs='?', default=42)
    >>> parser.parse_args(['a'])
    Namespace(foo='a')
    >>> parser.parse_args([])
    Namespace(foo=42)

For required arguments, the `default` value is ignored. For example, this applies to positional arguments with nargs values other than `?` or `*`, or optional arguments marked as `required=True`.

Якщо вказати `default=argparse.SUPPRESS`, атрибут не буде додано, якщо аргумент командного рядка відсутній:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo', default=argparse.SUPPRESS)
    >>> parser.parse_args([])
    Namespace()
    >>> parser.parse_args(['--foo', '1'])
    Namespace(foo='1')

### типу

За замовчуванням аналізатор читає аргументи командного рядка як прості рядки. Однак досить часто рядок командного рядка слід інтерпретувати як інший тип, наприклад `float` або `int`. Ключове слово `type` для `add_argument()` дозволяє виконувати будь-які необхідні перевірки типів і перетворення типів.

Якщо ключове слово type використовується з ключовим словом default, конвертер типів застосовується, лише якщо значенням за замовчуванням є рядок.

The argument to `type` can be a callable that accepts a single string or the name of a registered type (see `register()`) If the function raises `ArgumentTypeError`, `TypeError`, or `ValueError`, the exception is caught and a nicely formatted error message is displayed. Other exception types are not handled.

Загальні вбудовані типи та функції можна використовувати як перетворювачі типів:

    import argparse
    import pathlib

    parser = argparse.ArgumentParser()
    parser.add_argument('count', type=int)
    parser.add_argument('distance', type=float)
    parser.add_argument('street', type=ascii)
    parser.add_argument('code_point', type=ord)
    parser.add_argument('datapath', type=pathlib.Path)

Також можна використовувати визначені користувачем функції:

    >>> def hyphenated(string):
    ...     return '-'.join([word[:4] for word in string.casefold().split()])
    ...
    >>> parser = argparse.ArgumentParser()
    >>> _ = parser.add_argument('short_title', type=hyphenated)
    >>> parser.parse_args(['"The Tale of Two Cities"'])
    Namespace(short_title='"the-tale-of-two-citi')

Функцію `bool()` не рекомендується використовувати як перетворювач типів. Усе, що він робить, це перетворює порожні рядки на `False`, а непорожні рядки — на `True`. Зазвичай це не те, чого хочеться.

Загалом, ключове слово `type` є зручним, і його слід використовувати лише для простих перетворень, які можуть викликати лише одне з трьох підтримуваних винятків. Усе, що має більш цікаву обробку помилок або керування ресурсами, має бути зроблено нижче за течією після аналізу аргументів.

For example, JSON or YAML conversions have complex error cases that require better reporting than can be given by the `type` keyword. A `JSONDecodeError` would not be well formatted and a `FileNotFoundError` exception would not be handled at all.

Even `FileType` has its limitations for use with the `type` keyword. If one argument uses `FileType` and then a subsequent argument fails, an error is reported but the file is not automatically closed. In this case, it would be better to wait until after the parser has run and then use the `with`-statement to manage the files.

Для засобів перевірки типів, які просто перевіряють фіксований набір значень, подумайте про використання ключового слова choices.

### вибір

Some command-line arguments should be selected from a restricted set of values. These can be handled by passing a sequence object as the choices keyword argument to `add_argument()`. When the command line is parsed, argument values will be checked, and an error message will be displayed if the argument was not one of the acceptable values:

    >>> parser = argparse.ArgumentParser(prog='game.py')
    >>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
    >>> parser.parse_args(['rock'])
    Namespace(move='rock')
    >>> parser.parse_args(['fire'])
    usage: game.py [-h] {rock,paper,scissors}
    game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
    'paper', 'scissors')

Any sequence can be passed as the choices value, so `list` objects, `tuple` objects, and custom sequences are all supported.

Використання `enum.Enum` не рекомендується, оскільки важко контролювати його появу в повідомленнях про використання, довідці та помилках.

Note that choices are checked after any type conversions have been performed, so objects in choices should match the type specified. This can make choices appear unfamiliar in usage, help, or error messages.

To keep choices user-friendly, consider a custom type wrapper that converts and formats values, or omit type and handle conversion in your application code.

Formatted choices override the default metavar which is normally derived from dest. This is usually what you want because the user never sees the dest parameter. If this display isn’t desirable (perhaps because there are many choices), just specify an explicit metavar.

### вимагається

In general, the `argparse` module assumes that flags like `-f` and `--bar` indicate optional arguments, which can always be omitted at the command line. To make an option required, `True` can be specified for the `required=` keyword argument to `add_argument()`:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo', required=True)
    >>> parser.parse_args(['--foo', 'BAR'])
    Namespace(foo='BAR')
    >>> parser.parse_args([])
    usage: [-h] --foo FOO
    : error: the following arguments are required: --foo

Як показує приклад, якщо параметр позначено як `required`, `parse_args()` повідомить про помилку, якщо цей параметр відсутній у командному рядку.

Примітка

Обов’язкові параметри зазвичай вважаються поганим тоном, оскільки користувачі очікують, що параметри будуть необов’язковими, тому їх слід уникати, коли це можливо.

### допомогти

The `help` value is a string containing a brief description of the argument. When a user requests help (usually by using `-h` or `--help` at the command line), these `help` descriptions will be displayed with each argument.

Рядки `help` можуть містити різні специфікатори формату, щоб уникнути повторення таких речей, як назва програми або аргумент default. Доступні специфікатори включають назву програми, `%(prog)s` та більшість ключових аргументів для `add_argument()`, напр. `%(default)s`, `%(type)s` тощо:

    >>> parser = argparse.ArgumentParser(prog='frobble')
    >>> parser.add_argument('bar', nargs='?', type=int, default=42,
    ...                     help='the bar to %(prog)s (default: %(default)s)')
    >>> parser.print_help()
    usage: frobble [-h] [bar]

    positional arguments:
     bar     the bar to frobble (default: 42)

    options:
     -h, --help  show this help message and exit

Оскільки рядок довідки підтримує %-formatting, якщо ви хочете, щоб літерал `%` з’явився в рядку довідки, ви повинні екранувати його як `%%`.

`argparse` supports silencing the help entry for certain options, by setting the `help` value to `argparse.SUPPRESS`:

    >>> parser = argparse.ArgumentParser(prog='frobble')
    >>> parser.add_argument('--foo', help=argparse.SUPPRESS)
    >>> parser.print_help()
    usage: frobble [-h]

    options:
      -h, --help  show this help message and exit

### метавар

When `ArgumentParser` generates help messages, it needs some way to refer to each expected argument. By default, `ArgumentParser` objects use the dest value as the «name» of each object. By default, for positional argument actions, the dest value is used directly, and for optional argument actions, the dest value is uppercased. So, a single positional argument with `dest='bar'` will be referred to as `bar`. A single optional argument `--foo` that should be followed by a single command-line argument will be referred to as `FOO`. An example:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo')
    >>> parser.add_argument('bar')
    >>> parser.parse_args('X --foo Y'.split())
    Namespace(bar='X', foo='Y')
    >>> parser.print_help()
    usage:  [-h] [--foo FOO] bar

    positional arguments:
     bar

    options:
     -h, --help  show this help message and exit
     --foo FOO

Альтернативну назву можна вказати за допомогою `metavar`:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo', metavar='YYY')
    >>> parser.add_argument('bar', metavar='XXX')
    >>> parser.parse_args('X --foo Y'.split())
    Namespace(bar='X', foo='Y')
    >>> parser.print_help()
    usage:  [-h] [--foo YYY] XXX

    positional arguments:
     XXX

    options:
     -h, --help  show this help message and exit
     --foo YYY

Зауважте, що `metavar` змінює лише відображене ім’я – ім’я атрибута об’єкта `parse_args()` все ще визначається значенням dest.

Різні значення `nargs` можуть спричинити багаторазове використання метаперемінної. Надання кортежу для `metavar` визначає інше відображення для кожного з аргументів:

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('-x', nargs=2)
    >>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
    >>> parser.print_help()
    usage: PROG [-h] [-x X X] [--foo bar baz]

    options:
     -h, --help     show this help message and exit
     -x X X
     --foo bar baz

### дест

Більшість дій `ArgumentParser` додають певне значення як атрибут об’єкта, який повертає `parse_args()`. Ім’я цього атрибута визначається ключовим аргументом `dest` `add_argument()`. Для дій позиційного аргументу `dest` зазвичай надається як перший аргумент `add_argument()`:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('bar')
    >>> parser.parse_args(['XXX'])
    Namespace(bar='XXX')

For optional argument actions, the value of `dest` is normally inferred from the option strings. `ArgumentParser` generates the value of `dest` by taking the first double-dash long option string and stripping away the initial `-` characters. If no double-dash long option strings were supplied, `dest` will be derived from the first single-dash long option string by stripping the initial `-` character. If no long option strings were supplied, `dest` will be derived from the first short option string by stripping the initial `-` character. Any internal `-` characters will be converted to `_` characters to make sure the string is a valid attribute name. The examples below illustrate this behavior:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('-f', '--foo-bar', '--foo')
    >>> parser.add_argument('-q', '-quz')
    >>> parser.add_argument('-x', '-y')
    >>> parser.parse_args('-f 1 -q 2 -x 3'.split())
    Namespace(foo_bar='1', quz='2', x='3')
    >>> parser.parse_args('--foo 1 -quz 2 -y 3'.split())
    Namespace(foo_bar='1', quz='2', x='2')

`dest` дозволяє надати ім’я спеціального атрибута:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo', dest='bar')
    >>> parser.parse_args('--foo XXX'.split())
    Namespace(bar='XXX')

Змінено в версії 3.15: Single-dash long option now takes precedence over short options.

### deprecated

During a project’s lifetime, some arguments may need to be removed from the command line. Before removing them, you should inform your users that the arguments are deprecated and will be removed. The `deprecated` keyword argument of `add_argument()`, which defaults to `False`, specifies if the argument is deprecated and will be removed in the future. For arguments, if `deprecated` is `True`, then a warning will be printed to `sys.stderr` when the argument is used:

    >>> import argparse
    >>> parser = argparse.ArgumentParser(prog='snake.py')
    >>> parser.add_argument('--legs', default=0, type=int, deprecated=True)
    >>> parser.parse_args([])
    Namespace(legs=0)
    >>> parser.parse_args(['--legs', '4'])
    snake.py: warning: option '--legs' is deprecated
    Namespace(legs=4)

Added in version 3.13.

### Класи дії

`Action` classes implement the Action API, a callable which returns a callable which processes arguments from the command-line. Any object which follows this API may be passed as the `action` parameter to `add_argument()`.

class argparse.Action(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

  `Action` objects are used by an `ArgumentParser` to represent the information needed to parse a single argument from one or more strings from the command line. The `Action` class must accept the two positional arguments plus any keyword arguments passed to `ArgumentParser.add_argument()` except for the `action` itself.

  Instances of `Action` (or return value of any callable to the `action` parameter) should have attributes `dest`, `option_strings`, `default`, `type`, `required`, `help`, etc. defined. The easiest way to ensure these attributes are defined is to call `Action.__init__()`.

  __call__(parser, namespace, values, option_string=None)

    `Action` instances should be callable, so subclasses must override the `__call__()` method, which should accept four parameters:

    - parser - The `ArgumentParser` object which contains this action.

    - namespace - The `Namespace` object that will be returned by `parse_args()`. Most actions add an attribute to this object using `setattr()`.

    - values - The associated command-line arguments, with any type conversions applied. Type conversions are specified with the type keyword argument to `add_argument()`.

    - option_string - The option string that was used to invoke this action. The `option_string` argument is optional, and will be absent if the action is associated with a positional argument.

    The `__call__()` method may perform arbitrary actions, but will typically set attributes on the `namespace` based on `dest` and `values`.

  format_usage()

    `Action` subclasses can define a `format_usage()` method that takes no argument and return a string which will be used when printing the usage of the program. If such method is not provided, a sensible default will be used.

class argparse.BooleanOptionalAction

  A subclass of `Action` for handling boolean flags with positive and negative options. Adding a single argument such as `--foo` automatically creates both `--foo` and `--no-foo` options, storing `True` and `False` respectively:

      >>> import argparse
      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
      >>> parser.parse_args(['--no-foo'])
      Namespace(foo=False)

  Single-dash long options are also supported. For example, negative option `-nofoo` is automatically added for positive option `-foo`. But no additional options are added for short options such as `-f`.

  Added in version 3.9.

  Змінено в версії 3.15: Added support for single-dash options.

  Added support for alternate prefix_chars.

## Метод parse_args().

ArgumentParser.parse_args(args=None, namespace=None)

  Перетворіть рядки аргументів на об’єкти та призначте їх як атрибути простору імен. Повернути заповнений простір імен.

  Previous calls to `add_argument()` determine exactly what objects are created and how they are assigned. See the documentation for `add_argument()` for details.

  - args - список рядків для аналізу. Типове значення взято з `sys.argv`.

  - namespace – об’єкт для отримання атрибутів. Типовим є новий порожній об’єкт `Namespace`.

### Синтаксис значення опції

Метод `parse_args()` підтримує кілька способів визначення значення параметра (якщо воно приймається). У найпростішому випадку параметр і його значення передаються як два окремих аргументи:

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('-x')
    >>> parser.add_argument('--foo')
    >>> parser.parse_args(['-x', 'X'])
    Namespace(foo=None, x='X')
    >>> parser.parse_args(['--foo', 'FOO'])
    Namespace(foo='FOO', x=None)

Для довгих параметрів (параметрів з іменами, довшими за один символ), параметр і значення також можна передати як один аргумент командного рядка, використовуючи `=`, щоб розділити їх:

    >>> parser.parse_args(['--foo=FOO'])
    Namespace(foo='FOO', x=None)

Для коротких опцій (опції лише з одного символу) опцію та її значення можна об’єднати:

    >>> parser.parse_args(['-xX'])
    Namespace(foo=None, x='X')

Кілька коротких опцій можна об’єднати разом, використовуючи лише один префікс `-`, якщо тільки остання опція (або жодна з них) вимагає значення:

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('-x', action='store_true')
    >>> parser.add_argument('-y', action='store_true')
    >>> parser.add_argument('-z')
    >>> parser.parse_args(['-xyzZ'])
    Namespace(x=True, y=True, z='Z')

### Недійсні аргументи

Під час аналізу командного рядка `parse_args()` перевіряє наявність різноманітних помилок, включаючи неоднозначні параметри, недійсні типи, недійсні параметри, неправильну кількість позиційних аргументів тощо. Коли він стикається з такою помилкою, він виходить і друкує помилку разом із повідомленням про використання:

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('--foo', type=int)
    >>> parser.add_argument('bar', nargs='?')

    >>> # invalid type
    >>> parser.parse_args(['--foo', 'spam'])
    usage: PROG [-h] [--foo FOO] [bar]
    PROG: error: argument --foo: invalid int value: 'spam'

    >>> # invalid option
    >>> parser.parse_args(['--bar'])
    usage: PROG [-h] [--foo FOO] [bar]
    PROG: error: no such option: --bar

    >>> # wrong number of arguments
    >>> parser.parse_args(['spam', 'badger'])
    usage: PROG [-h] [--foo FOO] [bar]
    PROG: error: extra arguments found: badger

### Аргументи, що містять `-`

Метод `parse_args()` намагається видавати помилки щоразу, коли користувач явно зробив помилку, але деякі ситуації за своєю суттю неоднозначні. Наприклад, аргумент командного рядка «-1» може бути або спробою вказати параметр, або спробою надати позиційний аргумент. Метод `parse_args()` тут обережний: позиційні аргументи можуть починатися лише з `-`, якщо вони виглядають як від’ємні числа, і в аналізаторі немає параметрів, які виглядають як від’ємні числа:

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('-x')
    >>> parser.add_argument('foo', nargs='?')

    >>> # no negative number options, so -1 is a positional argument
    >>> parser.parse_args(['-x', '-1'])
    Namespace(foo=None, x='-1')

    >>> # no negative number options, so -1 and -5 are positional arguments
    >>> parser.parse_args(['-x', '-1', '-5'])
    Namespace(foo='-5', x='-1')

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('-1', dest='one')
    >>> parser.add_argument('foo', nargs='?')

    >>> # negative number options present, so -1 is an option
    >>> parser.parse_args(['-1', 'X'])
    Namespace(foo=None, one='X')

    >>> # negative number options present, so -2 is an option
    >>> parser.parse_args(['-2'])
    usage: PROG [-h] [-1 ONE] [foo]
    PROG: error: no such option: -2

    >>> # negative number options present, so both -1s are options
    >>> parser.parse_args(['-1', '-1'])
    usage: PROG [-h] [-1 ONE] [foo]
    PROG: error: argument -1: expected one argument

Якщо у вас є позиційні аргументи, які повинні починатися з `-` і не виглядати як від’ємні числа, ви можете вставити псевдоаргумент `''--'`, який повідомляє `parse_args()`, що все після цього є позиційним аргументом:

    >>> parser.parse_args(['--', '-f'])
    Namespace(foo='-f', one=None)

See also the argparse howto on ambiguous arguments for more details.

### Скорочення аргументів (відповідність префіксу)

Метод `parse_args()` за замовчуванням дозволяє скорочувати довгі параметри до префікса, якщо скорочення є однозначним (префікс відповідає унікальному параметру):

    >>> parser = argparse.ArgumentParser(prog='PROG')
    >>> parser.add_argument('-bacon')
    >>> parser.add_argument('-badger')
    >>> parser.parse_args('-bac MMM'.split())
    Namespace(bacon='MMM', badger=None)
    >>> parser.parse_args('-bad WOOD'.split())
    Namespace(bacon=None, badger='WOOD')
    >>> parser.parse_args('-ba BA'.split())
    usage: PROG [-h] [-bacon BACON] [-badger BADGER]
    PROG: error: ambiguous option: -ba could match -badger, -bacon

Помилка створюється для аргументів, які можуть давати більше одного варіанту. Цю функцію можна вимкнути, встановивши для дозволити_скорочене значення `False`.

### За межами `sys.argv`

Sometimes it may be useful to have an `ArgumentParser` parse arguments other than those of `sys.argv`. This can be accomplished by passing a list of strings to `parse_args()`. This is useful for testing at the interactive prompt:

    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument(
    ...     'integers', metavar='int', type=int, choices=range(10),
    ...     nargs='+', help='an integer in the range 0..9')
    >>> parser.add_argument(
    ...     '--sum', dest='accumulate', action='store_const', const=sum,
    ...     default=max, help='sum the integers (default: find the max)')
    >>> parser.parse_args(['1', '2', '3', '4'])
    Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
    >>> parser.parse_args(['1', '2', '3', '4', '--sum'])
    Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])

### Об’єкт простору імен

class argparse.Namespace

  Простий клас, який за замовчуванням використовується `parse_args()` для створення об’єкта з атрибутами та повернення його.

  Цей клас навмисне простий, просто підклас `object` із читабельним представленням рядка. Якщо ви віддаєте перевагу перегляду атрибутів у форматі dict, ви можете використовувати стандартну ідіому Python `vars()`:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo')
      >>> args = parser.parse_args(['--foo', 'BAR'])
      >>> vars(args)
      {'foo': 'BAR'}

  Також може бути корисним, щоб `ArgumentParser` призначав атрибути вже існуючому об’єкту, а не новому об’єкту `Namespace`. Цього можна досягти, вказавши аргумент ключового слова `namespace=`:

      >>> class C:
      ...     pass
      ...
      >>> c = C()
      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo')
      >>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
      >>> c.foo
      'BAR'

## Інші комунальні послуги

### Subcommands

ArgumentParser.add_subparsers(*[, title][, description][, prog][, parser_class][, action][, dest][, required][, help][, metavar])

  Many programs split up their functionality into a number of subcommands, for example, the `svn` program can invoke subcommands like `svn checkout`, `svn update`, and `svn commit`. Splitting up functionality this way can be a particularly good idea when a program performs several different functions which require different kinds of command-line arguments. `ArgumentParser` supports the creation of such subcommands with the `add_subparsers()` method. The `add_subparsers()` method is normally called with no arguments and returns a special action object. This object has a single method, `add_parser()`, which takes a command name and any `ArgumentParser` constructor arguments, and returns an `ArgumentParser` object that can be modified as usual.

  Опис параметрів:

  - title - title for the sub-parser group in help output; by default «subcommands» if description is provided, otherwise uses title for positional arguments

  - description - description for the sub-parser group in help output, by default `None`

  - prog - usage information that will be displayed with subcommand help, by default the name of the program and any positional arguments before the subparser argument

  - parser_class - class which will be used to create sub-parser instances, by default the class of the current parser (e.g. `ArgumentParser`)

  - action - основний тип дії, яка виконується, коли цей аргумент зустрічається в командному рядку

  - dest - name of the attribute under which subcommand name will be stored; by default `None` and no value is stored

  - required - чи потрібно надавати підкоманду, за замовчуванням `False` (додано в 3.7)

  - help - довідка для групи суб-парсера у виведенні довідки, за замовчуванням `None`

  - metavar - string presenting available subcommands in help; by default it is `None` and presents subcommands in form {cmd1, cmd2, ..}

  Деякі приклади використання:

      >>> # create the top-level parser
      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> parser.add_argument('--foo', action='store_true', help='foo help')
      >>> subparsers = parser.add_subparsers(help='subcommand help')
      >>>
      >>> # create the parser for the "a" command
      >>> parser_a = subparsers.add_parser('a', help='a help')
      >>> parser_a.add_argument('bar', type=int, help='bar help')
      >>>
      >>> # create the parser for the "b" command
      >>> parser_b = subparsers.add_parser('b', help='b help')
      >>> parser_b.add_argument('--baz', choices=('X', 'Y', 'Z'), help='baz help')
      >>>
      >>> # parse some argument lists
      >>> parser.parse_args(['a', '12'])
      Namespace(bar=12, foo=False)
      >>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
      Namespace(baz='Z', foo=True)

  Note that the object returned by `parse_args()` will only contain attributes for the main parser and the subparser that was selected by the command line (and not any other subparsers). So in the example above, when the `a` command is specified, only the `foo` and `bar` attributes are present, and when the `b` command is specified, only the `foo` and `baz` attributes are present.

  Similarly, when a help message is requested from a subparser, only the help for that particular parser will be printed. The help message will not include parent parser or sibling parser messages. (A help message for each subparser command, however, can be given by supplying the `help=` argument to `add_parser()` as above.)

      >>> parser.parse_args(['--help'])
      usage: PROG [-h] [--foo] {a,b} ...

      positional arguments:
        {a,b}   subcommand help
          a     a help
          b     b help

      options:
        -h, --help  show this help message and exit
        --foo   foo help

      >>> parser.parse_args(['a', '--help'])
      usage: PROG a [-h] bar

      positional arguments:
        bar     bar help

      options:
        -h, --help  show this help message and exit

      >>> parser.parse_args(['b', '--help'])
      usage: PROG b [-h] [--baz {X,Y,Z}]

      options:
        -h, --help     show this help message and exit
        --baz {X,Y,Z}  baz help

  The `add_subparsers()` method also supports `title` and `description` keyword arguments. When either is present, the subparser’s commands will appear in their own group in the help output. For example:

      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers(title='subcommands',
      ...                                    description='valid subcommands',
      ...                                    help='additional help')
      >>> subparsers.add_parser('foo')
      >>> subparsers.add_parser('bar')
      >>> parser.parse_args(['-h'])
      usage:  [-h] {foo,bar} ...

      options:
        -h, --help  show this help message and exit

      subcommands:
        valid subcommands

        {foo,bar}   additional help

  One particularly effective way of handling subcommands is to combine the use of the `add_subparsers()` method with calls to `set_defaults()` so that each subparser knows which Python function it should execute. For example:

      >>> # subcommand functions
      >>> def foo(args):
      ...     print(args.x * args.y)
      ...
      >>> def bar(args):
      ...     print('((%s))' % args.z)
      ...
      >>> # create the top-level parser
      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers(required=True)
      >>>
      >>> # create the parser for the "foo" command
      >>> parser_foo = subparsers.add_parser('foo')
      >>> parser_foo.add_argument('-x', type=int, default=1)
      >>> parser_foo.add_argument('y', type=float)
      >>> parser_foo.set_defaults(func=foo)
      >>>
      >>> # create the parser for the "bar" command
      >>> parser_bar = subparsers.add_parser('bar')
      >>> parser_bar.add_argument('z')
      >>> parser_bar.set_defaults(func=bar)
      >>>
      >>> # parse the args and call whatever function was selected
      >>> args = parser.parse_args('foo 1 -x 2'.split())
      >>> args.func(args)
      2.0
      >>>
      >>> # parse the args and call whatever function was selected
      >>> args = parser.parse_args('bar XYZYX'.split())
      >>> args.func(args)
      ((XYZYX))

  This way, you can let `parse_args()` do the job of calling the appropriate function after argument parsing is complete. Associating functions with actions like this is typically the easiest way to handle the different actions for each of your subparsers. However, if it is necessary to check the name of the subparser that was invoked, the `dest` keyword argument to the `add_subparsers()` call will work:

      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers(dest='subparser_name')
      >>> subparser1 = subparsers.add_parser('1')
      >>> subparser1.add_argument('-x')
      >>> subparser2 = subparsers.add_parser('2')
      >>> subparser2.add_argument('y')
      >>> parser.parse_args(['2', 'frobble'])
      Namespace(subparser_name='2', y='frobble')

  Змінено в версії 3.7: New required keyword-only parameter.

  Змінено в версії 3.14: Subparser’s prog is no longer affected by a custom usage message in the main parser.

_SubParsersAction.add_parser(name, *, help=None, aliases=None,
deprecated=False, **kwargs)

  Create and return a new `ArgumentParser` object for the subcommand name.

  The name argument is the name of the sub-command.

  The help argument provides a short description for this sub-command.

  The aliases argument allows providing alternative names for this sub-command. For example:

      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers()
      >>> checkout = subparsers.add_parser('checkout', aliases=['co'])
      >>> checkout.add_argument('foo')
      >>> parser.parse_args(['co', 'bar'])
      Namespace(foo='bar')

  The deprecated argument, if `True`, marks the sub-command as deprecated and will issue a warning when used. For example:

      >>> parser = argparse.ArgumentParser(prog='chicken.py')
      >>> subparsers = parser.add_subparsers()
      >>> fly = subparsers.add_parser('fly', deprecated=True)
      >>> args = parser.parse_args(['fly'])
      chicken.py: warning: command 'fly' is deprecated
      Namespace()

  All other keyword arguments are passed directly to the `ArgumentParser` constructor.

  Added in version 3.13: Added the deprecated parameter.

### Об’єкти FileType

class argparse.FileType(mode='r', bufsize=-1, encoding=None, errors=None)

  Фабрика `FileType` створює об’єкти, які можна передати в аргумент типу `ArgumentParser.add_argument()`. Аргументи, які мають тип об’єктів `FileType`, відкриватимуть аргументи командного рядка як файли з потрібними режимами, розмірами буфера, кодуванням і обробкою помилок (додаткову інформацію див. у функції `open()`):

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))
      >>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8'))
      >>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])
      Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)

  FileType objects understand the pseudo-argument `'-'` and automatically convert this into `sys.stdin` for readable `FileType` objects and `sys.stdout` for writable `FileType` objects:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('infile', type=argparse.FileType('r'))
      >>> parser.parse_args(['-'])
      Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)

  Примітка

  If one argument uses FileType and then a subsequent argument fails, an error is reported but the file is not automatically closed. This can also clobber the output files. In this case, it would be better to wait until after the parser has run and then use the `with`-statement to manage the files.

  Змінено в версії 3.4: Added the encodings and errors parameters.

  Застаріло починаючи з версії 3.14.

### Групи аргументів

ArgumentParser.add_argument_group(title=None, description=None, *[, argument_default][, conflict_handler])

  By default, `ArgumentParser` groups command-line arguments into «positional arguments» and «options» when displaying help messages. When there is a better conceptual grouping of arguments than this default one, appropriate groups can be created using the `add_argument_group()` method:

      >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
      >>> group = parser.add_argument_group('group')
      >>> group.add_argument('--foo', help='foo help')
      >>> group.add_argument('bar', help='bar help')
      >>> parser.print_help()
      usage: PROG [--foo FOO] bar

      group:
        bar    bar help
        --foo FOO  foo help

  The `add_argument_group()` method returns an argument group object which has an `add_argument()` method just like a regular `ArgumentParser`. When an argument is added to the group, the parser treats it just like a normal argument, but displays the argument in a separate group for help messages. The `add_argument_group()` method accepts title and description arguments which can be used to customize this display:

      >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
      >>> group1 = parser.add_argument_group('group1', 'group1 description')
      >>> group1.add_argument('foo', help='foo help')
      >>> group2 = parser.add_argument_group('group2', 'group2 description')
      >>> group2.add_argument('--bar', help='bar help')
      >>> parser.print_help()
      usage: PROG [--bar BAR] foo

      group1:
        group1 description

        foo    foo help

      group2:
        group2 description

        --bar BAR  bar help

  The optional, keyword-only parameters argument_default and conflict_handler allow for finer-grained control of the behavior of the argument group. These parameters have the same meaning as in the `ArgumentParser` constructor, but apply specifically to the argument group rather than the entire parser.

  Зверніть увагу, що будь-які аргументи, які не входять до визначених користувачем груп, повертаються до звичайних розділів «позиційні аргументи» та «необов’язкові аргументи».

  Deprecated since version 3.11, removed in version 3.14: Calling `add_argument_group()` on an argument group now raises an exception. This nesting was never supported, often failed to work correctly, and was unintentionally exposed through inheritance.

  Застаріло починаючи з версії 3.14: Passing prefix_chars to `add_argument_group()` is now deprecated.

### Взаємне виключення

ArgumentParser.add_mutually_exclusive_group(required=False)

  Create a mutually exclusive group. `argparse` will make sure that only one of the arguments in the mutually exclusive group was present on the command line:

      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> group = parser.add_mutually_exclusive_group()
      >>> group.add_argument('--foo', action='store_true')
      >>> group.add_argument('--bar', action='store_false')
      >>> parser.parse_args(['--foo'])
      Namespace(bar=True, foo=True)
      >>> parser.parse_args(['--bar'])
      Namespace(bar=False, foo=False)
      >>> parser.parse_args(['--foo', '--bar'])
      usage: PROG [-h] [--foo | --bar]
      PROG: error: argument --bar: not allowed with argument --foo

  Метод `add_mutually_exclusive_group()` також приймає обов’язковий аргумент, щоб вказати, що потрібен принаймні один із взаємовиключних аргументів:

      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> group = parser.add_mutually_exclusive_group(required=True)
      >>> group.add_argument('--foo', action='store_true')
      >>> group.add_argument('--bar', action='store_false')
      >>> parser.parse_args([])
      usage: PROG [-h] (--foo | --bar)
      PROG: error: one of the arguments --foo --bar is required

  Note that currently mutually exclusive argument groups do not support the title and description arguments of `add_argument_group()`. However, a mutually exclusive group can be added to an argument group that has a title and description. For example:

      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> group = parser.add_argument_group('Group title', 'Group description')
      >>> exclusive_group = group.add_mutually_exclusive_group(required=True)
      >>> exclusive_group.add_argument('--foo', help='foo help')
      >>> exclusive_group.add_argument('--bar', help='bar help')
      >>> parser.print_help()
      usage: PROG [-h] (--foo FOO | --bar BAR)

      options:
        -h, --help  show this help message and exit

      Group title:
        Group description

        --foo FOO   foo help
        --bar BAR   bar help

  Deprecated since version 3.11, removed in version 3.14: Calling `add_argument_group()` or `add_mutually_exclusive_group()` on a mutually exclusive group now raises an exception. This nesting was never supported, often failed to work correctly, and was unintentionally exposed through inheritance.

### Параметри аналізатора за замовчуванням

ArgumentParser.set_defaults(**kwargs)

  У більшості випадків атрибути об’єкта, які повертає `parse_args()`, будуть повністю визначені шляхом перевірки аргументів командного рядка та дій аргументів. `set_defaults()` дозволяє додавати деякі додаткові атрибути, які визначаються без перевірки командного рядка:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('foo', type=int)
      >>> parser.set_defaults(bar=42, baz='badger')
      >>> parser.parse_args(['736'])
      Namespace(bar=42, baz='badger', foo=736)

  Note that defaults can be set at both the parser level using `set_defaults()` and at the argument level using `add_argument()`. If both are called for the same argument, the last default set for an argument is used:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', default='bar')
      >>> parser.set_defaults(foo='spam')
      >>> parser.parse_args([])
      Namespace(foo='spam')

  Значення за замовчуванням на рівні парсера можуть бути особливо корисними під час роботи з декількома парсерами. Перегляньте метод `add_subparsers()` для прикладу цього типу.

ArgumentParser.get_default(dest)

  Отримати значення за замовчуванням для атрибута простору імен, встановлене або `add_argument()`, або `set_defaults()`:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', default='badger')
      >>> parser.get_default('foo')
      'badger'

### Друк довідки

У більшості типових програм `parse_args()` подбає про форматування та друк будь-яких повідомлень про використання чи помилки. Однак доступно кілька методів форматування:

ArgumentParser.print_usage(file=None)

  Надрукуйте короткий опис того, як `ArgumentParser` слід викликати в командному рядку. Якщо file має значення `None`, передбачається `sys.stdout`.

ArgumentParser.print_help(file=None)

  Надрукуйте довідкове повідомлення, включно з використанням програми та інформацією про аргументи, зареєстровані в `ArgumentParser`. Якщо file має значення `None`, передбачається `sys.stdout`.

Існують також варіанти цих методів, які просто повертають рядок замість того, щоб друкувати його:

ArgumentParser.format_usage()

  Повертає рядок, що містить короткий опис того, як `ArgumentParser` слід викликати в командному рядку.

ArgumentParser.format_help()

  Повертає рядок, що містить довідкове повідомлення, включаючи використання програми та інформацію про аргументи, зареєстровані в `ArgumentParser`.

### Частковий розбір

ArgumentParser.parse_known_args(args=None, namespace=None)

  Sometimes a script only needs to handle a specific set of command-line arguments, leaving any unrecognized arguments for another script or program. In these cases, the `parse_known_args()` method can be useful.

  This method works similarly to `parse_args()`, but it does not raise an error for extra, unrecognized arguments. Instead, it parses the known arguments and returns a two item tuple that contains the populated namespace and the list of any unrecognized arguments.

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', action='store_true')
      >>> parser.add_argument('bar')
      >>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
      (Namespace(bar='BAR', foo=True), ['--badger', 'spam'])

Попередження

Prefix matching rules apply to `parse_known_args()`. The parser may consume an option even if it’s just a prefix of one of its known options, instead of leaving it in the remaining arguments list.

### Налаштування аналізу файлів

ArgumentParser.convert_arg_line_to_args(arg_line)

  Аргументи, які зчитуються з файлу (див. аргумент ключового слова fromfile_prefix_chars конструктора `ArgumentParser`), зчитуються по одному аргументу на рядок. `convert_arg_line_to_args()` можна замінити для кращого читання.

  Цей метод приймає один аргумент arg_line, який є рядком, прочитаним з файлу аргументів. Він повертає список аргументів, розібраних із цього рядка. Метод викликається один раз на рядок, який читається з файлу аргументів, по порядку.

  Корисною заміною цього методу є те, що розглядає кожне розділене пробілом слово як аргумент. Наступний приклад демонструє, як це зробити:

      class MyArgumentParser(argparse.ArgumentParser):
          def convert_arg_line_to_args(self, arg_line):
              return arg_line.split()

### Методи виходу

ArgumentParser.exit(status=0, message=None)

  This method terminates the program, exiting with the specified status and, if given, it prints a message to `sys.stderr` before that. The user can override this method to handle these steps differently:

      class ErrorCatchingArgumentParser(argparse.ArgumentParser):
          def exit(self, status=0, message=None):
              if status:
                  raise Exception(f'Exiting because of an error: {message}')
              exit(status)

ArgumentParser.error(message)

  This method prints a usage message, including the message, to `sys.stderr` and terminates the program with a status code of 2.

### Змішаний розбір

ArgumentParser.parse_intermixed_args(args=None, namespace=None)

ArgumentParser.parse_known_intermixed_args(args=None, namespace=None)

  Ряд команд Unix дозволяє користувачеві змішувати додаткові аргументи з позиційними. Методи `parse_intermixed_args()` і `parse_known_intermixed_args()` підтримують цей стиль аналізу.

  These parsers do not support all the `argparse` features, and will raise exceptions if unsupported features are used. In particular, subparsers, and mutually exclusive groups that include both optionals and positionals are not supported.

  У наступному прикладі показано різницю між `parse_known_args()` і `parse_intermixed_args()`: перший повертає `['2', '3']` як нерозібрані аргументи, а другий збирає всі позиційні елементи в `rest`.

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo')
      >>> parser.add_argument('cmd')
      >>> parser.add_argument('rest', nargs='*', type=int)
      >>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())
      (Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])
      >>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
      Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])

  `parse_known_intermixed_args()` повертає кортеж із двома елементами, що містить заповнений простір імен і список решти рядків аргументів. `parse_intermixed_args()` викликає помилку, якщо залишилися нерозібрані рядки аргументів.

  Added in version 3.7.

### Registering custom types or actions

ArgumentParser.register(registry_name, value, object)

  Sometimes it’s desirable to use a custom string in error messages to provide more user-friendly output. In these cases, `register()` can be used to register custom actions or types with a parser and allow you to reference the type by their registered name instead of their callable name.

  The `register()` method accepts three arguments - a registry_name, specifying the internal registry where the object will be stored (e.g., `action`, `type`), value, which is the key under which the object will be registered, and object, the callable to be registered.

  The following example shows how to register a custom type with a parser:

      >>> import argparse
      >>> parser = argparse.ArgumentParser()
      >>> parser.register('type', 'hexadecimal integer', lambda s: int(s, 16))
      >>> parser.add_argument('--foo', type='hexadecimal integer')
      _StoreAction(option_strings=['--foo'], dest='foo', nargs=None, const=None, default=None, type='hexadecimal integer', choices=None, required=False, help=None, metavar=None, deprecated=False)
      >>> parser.parse_args(['--foo', '0xFA'])
      Namespace(foo=250)
      >>> parser.parse_args(['--foo', '1.2'])
      usage: PROG [-h] [--foo FOO]
      PROG: error: argument --foo: invalid 'hexadecimal integer' value: '1.2'

## Винятки

exception argparse.ArgumentError

  An error from creating or using an argument (optional or positional).

  The string value of this exception is the message, augmented with information about the argument that caused it.

exception argparse.ArgumentTypeError

  Raised when something goes wrong converting a command line string to a type.

Посібники та підручники

- Підручник Argparse
- Migrating `optparse` code to `argparse`