argparse.md

1> **Источник:** https://python-all.ru/3.4/library/argparse.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 16.4. [`argparse`](https://python-all.ru/3.4/library/argparse.html#module-argparse) – Парсер для параметров командной строки, аргументов и подкоманд89Новое в версии 3.2.1011**Исходный код:** [Lib/argparse.py](https://python-all.ru/src/3.4/Lib/argparse.py)1213---1415Учебное пособие1617На этой странице содержится справочная информация по API. Для более плавного введения в разбор командной строки Python обратитесь к [*учебному пособию по argparse*](https://python-all.ru/3.4/howto/argparse.html#id1).1819Модуль [`argparse`](https://python-all.ru/3.4/library/argparse.html#module-argparse) упрощает создание удобных интерфейсов командной строки. Программа определяет, какие аргументы ей нужны, а [`argparse`](https://python-all.ru/3.4/library/argparse.html#module-argparse) разбирается, как извлечь их из [`sys.argv`](https://python-all.ru/3.4/library/sys.html#sys.argv). Модуль [`argparse`](https://python-all.ru/3.4/library/argparse.html#module-argparse) также автоматически генерирует сообщения справки и использования, а также выдает ошибки, когда пользователь передает программе недопустимые аргументы.2021## 16.4.1. Пример2223Следующий код представляет собой программу на Python, которая принимает список целых чисел и выводит либо сумму, либо максимум:2425```python26import argparse2728parser = argparse.ArgumentParser(description='Process some integers.')29parser.add_argument('integers', metavar='N', type=int, nargs='+',30                   help='an integer for the accumulator')31parser.add_argument('--sum', dest='accumulate', action='store_const',32                   const=sum, default=max,33                   help='sum the integers (default: find the max)')3435args = parser.parse_args()36print(args.accumulate(args.integers))37```3839Предположим, что приведенный выше код Python сохранен в файл с именем `prog.py`, его можно запустить из командной строки, и он предоставит полезные сообщения справки:4041```python42$ python prog.py -h43usage: prog.py [-h] [--sum] N [N ...]4445Process some integers.4647positional arguments:48 N           an integer for the accumulator4950optional arguments:51 -h, --help  show this help message and exit52 --sum       sum the integers (default: find the max)53```5455При запуске с соответствующими аргументами программа выводит либо сумму, либо максимум переданных целых чисел:5657```python58$ python prog.py 1 2 3 45946061$ python prog.py 1 2 3 4 --sum621063```6465Если передать неверные аргументы, будет выдана ошибка:6667```python68$ python prog.py a b c69usage: prog.py [-h] [--sum] N [N ...]70prog.py: error: argument N: invalid int value: 'a'71```7273В следующих разделах этот пример разбирается подробно.7475### 16.4.1.1. Создание парсера7677Первый шаг при использовании [`argparse`](https://python-all.ru/3.4/library/argparse.html#module-argparse) – создать объект [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser):7879```python80>>> parser = argparse.ArgumentParser(description='Process some integers.')81```8283Объект [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) будет содержать всю информацию, необходимую для синтаксического разбора командной строки в типы данных Python.8485### 16.4.1.2. Добавление аргументов8687Наполнение объекта [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) информацией об аргументах программы осуществляется вызовами метода [`add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument). В общем случае эти вызовы сообщают [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser), как преобразовать строки командной строки в объекты. Эта информация сохраняется и используется при вызове [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args). Например:8889```python90>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',91...                     help='an integer for the accumulator')92>>> parser.add_argument('--sum', dest='accumulate', action='store_const',93...                     const=sum, default=max,94...                     help='sum the integers (default: find the max)')95```9697При последующем вызове [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args) возвращается объект с двумя атрибутами: `integers` и `accumulate`. Атрибут `integers` будет списком из одного или нескольких целых чисел, а атрибут `accumulate` будет либо функцией [`sum()`](https://python-all.ru/3.4/library/functions.html#sum), если в командной строке был указан флаг `--sum`, либо функцией [`max()`](https://python-all.ru/3.4/library/functions.html#max), если не был.9899### 16.4.1.3. Разбор аргументов100101[`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) разбирает аргументы с помощью метода [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args). Он анализирует командную строку, преобразует каждый аргумент в соответствующий тип и затем выполняет соответствующее действие. В большинстве случаев это означает, что будет построен простой объект [`Namespace`](https://python-all.ru/3.4/library/argparse.html#argparse.Namespace) из атрибутов, выделенных из командной строки:102103```python104>>> parser.parse_args(['--sum', '7', '-1', '42'])105Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])106```107108В скрипте [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args) обычно вызывается без аргументов, и [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) автоматически определяет аргументы командной строки из [`sys.argv`](https://python-all.ru/3.4/library/sys.html#sys.argv).109110## 16.4.2. Объекты ArgumentParser111112#### `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)`113114Создаёт новый объект [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser). Все параметры должны передаваться как именованные аргументы. Каждый параметр имеет своё более подробное описание ниже, но вкратце:115116- [prog](https://python-all.ru/3.4/library/argparse.html#prog) – имя программы (по умолчанию: `sys.argv[0]`)117- [usage](https://python-all.ru/3.4/library/argparse.html#usage) - строка, описывающая использование программы (по умолчанию генерируется из аргументов, добавленных в парсер)118- [description](https://python-all.ru/3.4/library/argparse.html#description) – текст, отображаемый перед справкой по аргументам (по умолчанию: нет)119- [epilog](https://python-all.ru/3.4/library/argparse.html#epilog) – текст, отображаемый после справки по аргументам (по умолчанию: нет)120- [parents](https://python-all.ru/3.4/library/argparse.html#parents) – список объектов [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser), чьи аргументы также должны быть включены121- [formatter\_class](https://python-all.ru/3.4/library/argparse.html#formatter-class) - класс для настройки вывода справки122- [prefix\_chars](https://python-all.ru/3.4/library/argparse.html#prefix-chars) - набор символов, которые являются префиксом необязательных аргументов (по умолчанию: ‘-‘)123- [fromfile\_prefix\_chars](https://python-all.ru/3.4/library/argparse.html#fromfile-prefix-chars) – набор символов, предваряющих файлы, из которых следует читать дополнительные аргументы (по умолчанию: `None`)124- [argument\_default](https://python-all.ru/3.4/library/argparse.html#argument-default) – глобальное значение по умолчанию для аргументов (по умолчанию: `None`)125- [conflict\_handler](https://python-all.ru/3.4/library/argparse.html#conflict-handler) - стратегия разрешения конфликтов необязательных аргументов (обычно не требуется)126- [add\_help](https://python-all.ru/3.4/library/argparse.html#add-help) – добавить опцию -h/–help в синтаксический анализатор (по умолчанию: `True`)127128В следующих разделах описывается, как используется каждый из этих параметров.129130### 16.4.2.1. prog131132По умолчанию объекты [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) используют `sys.argv[0]` для определения того, как отображать имя программы в сообщениях справки. Это значение по умолчанию почти всегда желательно, поскольку оно позволяет сообщениям справки соответствовать тому, как программа была вызвана в командной строке. Например, рассмотрим файл с именем `myprogram.py` со следующим кодом:133134```python135import argparse136parser = argparse.ArgumentParser()137parser.add_argument('--foo', help='foo help')138args = parser.parse_args()139```140141Справка для этой программы будет отображать `myprogram.py` в качестве имени программы (независимо от того, откуда была вызвана программа):142143```python144$ python myprogram.py --help145usage: myprogram.py [-h] [--foo FOO]146147optional arguments:148 -h, --help  show this help message and exit149 --foo FOO   foo help150$ cd ..151$ python subdir\myprogram.py --help152usage: myprogram.py [-h] [--foo FOO]153154optional arguments:155 -h, --help  show this help message and exit156 --foo FOO   foo help157```158159Чтобы изменить это поведение по умолчанию, можно указать другое значение с помощью аргумента `prog=` для [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser):160161```python162>>> parser = argparse.ArgumentParser(prog='myprogram')163>>> parser.print_help()164usage: myprogram [-h]165166optional arguments:167 -h, --help  show this help message and exit168```169170Обратите внимание, что имя программы – определённое из `sys.argv[0]` или из аргумента `prog=` – доступно в сообщениях справки с помощью спецификатора формата `%(prog)s`.171172```python173>>> parser = argparse.ArgumentParser(prog='myprogram')174>>> parser.add_argument('--foo', help='foo of the %(prog)s program')175>>> parser.print_help()176usage: myprogram [-h] [--foo FOO]177178optional arguments:179 -h, --help  show this help message and exit180 --foo FOO   foo of the myprogram program181```182183### 16.4.2.2. usage184185По умолчанию [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) вычисляет сообщение об использовании из содержащихся в нём аргументов:186187```python188>>> parser = argparse.ArgumentParser(prog='PROG')189>>> parser.add_argument('--foo', nargs='?', help='foo help')190>>> parser.add_argument('bar', nargs='+', help='bar help')191>>> parser.print_help()192usage: PROG [-h] [--foo [FOO]] bar [bar ...]193194positional arguments:195 bar          bar help196197optional arguments:198 -h, --help   show this help message and exit199 --foo [FOO]  foo help200```201202Сообщение по умолчанию можно переопределить с помощью именованного аргумента `usage=`:203204```python205>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')206>>> parser.add_argument('--foo', nargs='?', help='foo help')207>>> parser.add_argument('bar', nargs='+', help='bar help')208>>> parser.print_help()209usage: PROG [options]210211positional arguments:212 bar          bar help213214optional arguments:215 -h, --help   show this help message and exit216 --foo [FOO]  foo help217```218219Спецификатор формата `%(prog)s` доступен для подстановки имени программы в сообщения об использовании.220221### 16.4.2.3. description222223Большинство вызовов конструктора [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) используют именованный аргумент `description=`. Этот аргумент задаёт краткое описание того, что делает программа и как она работает. В сообщениях справки описание отображается между строкой использования командной строки и сообщениями справки для различных аргументов:224225```python226>>> parser = argparse.ArgumentParser(description='A foo that bars')227>>> parser.print_help()228usage: argparse.py [-h]229230A foo that bars231232optional arguments:233 -h, --help  show this help message and exit234```235236По умолчанию описание переносится по строкам, чтобы уместиться в отведённом пространстве. Чтобы изменить это поведение, обратитесь к аргументу [formatter\_class](https://python-all.ru/3.4/library/argparse.html#formatter-class).237238### 16.4.2.4. epilog239240Некоторые программы предпочитают отображать дополнительное описание после описания аргументов. Такой текст можно указать с помощью аргумента `epilog=` для [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser):241242```python243>>> parser = argparse.ArgumentParser(244...     description='A foo that bars',245...     epilog="And that's how you'd foo a bar")246>>> parser.print_help()247usage: argparse.py [-h]248249A foo that bars250251optional arguments:252 -h, --help  show this help message and exit253254And that's how you'd foo a bar255```256257Как и для аргумента [description](https://python-all.ru/3.4/library/argparse.html#description), текст `epilog=` по умолчанию переносится по строкам, но это поведение можно настроить с помощью аргумента [formatter\_class](https://python-all.ru/3.4/library/argparse.html#formatter-class) для [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser).258259### 16.4.2.5. parents260261Иногда несколько парсеров используют общий набор аргументов. Вместо повторения определений этих аргументов можно использовать один парсер со всеми общими аргументами, который передаётся аргументу `parents=` в [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser). Аргумент `parents=` принимает список объектов [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser), собирает все позиционные и опциональные действия из них и добавляет эти действия к создаваемому объекту [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser):262263```python264>>> parent_parser = argparse.ArgumentParser(add_help=False)265>>> parent_parser.add_argument('--parent', type=int)266267>>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])268>>> foo_parser.add_argument('foo')269>>> foo_parser.parse_args(['--parent', '2', 'XXX'])270Namespace(foo='XXX', parent=2)271272>>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])273>>> bar_parser.add_argument('--bar')274>>> bar_parser.parse_args(['--bar', 'YYY'])275Namespace(bar='YYY', parent=None)276```277278Обратите внимание, что большинство родительских парсеров указывают `add_help=False`. В противном случае [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) увидит две опции `-h/--help` (одну в родительском, другую в дочернем) и вызовет ошибку.279280> **Примечание**281>282> Парсеры должны быть полностью инициализированы перед передачей через `parents=`. Если изменить родительские парсеры после создания дочернего, эти изменения не отразятся в дочернем.283284### 16.4.2.6. formatter\_class285286Объекты [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) позволяют настраивать форматирование справки с помощью указания альтернативного класса форматирования. В настоящее время существует четыре таких класса:287288#### `class argparse.RawDescriptionHelpFormatter`289290#### `class argparse.RawTextHelpFormatter`291292#### `class argparse.ArgumentDefaultsHelpFormatter`293294#### `class argparse.MetavarTypeHelpFormatter`295296[`RawDescriptionHelpFormatter`](https://python-all.ru/3.4/library/argparse.html#argparse.RawDescriptionHelpFormatter) и [`RawTextHelpFormatter`](https://python-all.ru/3.4/library/argparse.html#argparse.RawTextHelpFormatter) дают больше контроля над отображением текстовых описаний. По умолчанию объекты [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) переносят строки в тексте [description](https://python-all.ru/3.4/library/argparse.html#description) и [epilog](https://python-all.ru/3.4/library/argparse.html#epilog) в сообщениях справки командной строки:297298```python299>>> parser = argparse.ArgumentParser(300...     prog='PROG',301...     description='''this description302...         was indented weird303...             but that is okay''',304...     epilog='''305...             likewise for this epilog whose whitespace will306...         be cleaned up and whose words will be wrapped307...         across a couple lines''')308>>> parser.print_help()309usage: PROG [-h]310311this description was indented weird but that is okay312313optional arguments:314 -h, --help  show this help message and exit315316likewise for this epilog whose whitespace will be cleaned up and whose words317will be wrapped across a couple lines318```319320Передача [`RawDescriptionHelpFormatter`](https://python-all.ru/3.4/library/argparse.html#argparse.RawDescriptionHelpFormatter) в качестве `formatter_class=` указывает, что [description](https://python-all.ru/3.4/library/argparse.html#description) и [epilog](https://python-all.ru/3.4/library/argparse.html#epilog) уже правильно отформатированы и не должны переноситься по строкам:321322```python323>>> parser = argparse.ArgumentParser(324...     prog='PROG',325...     formatter_class=argparse.RawDescriptionHelpFormatter,326...     description=textwrap.dedent('''\327...         Please do not mess up this text!328...         --------------------------------329...             I have indented it330...             exactly the way331...             I want it332...         '''))333>>> parser.print_help()334usage: PROG [-h]335336Please do not mess up this text!337--------------------------------338   I have indented it339   exactly the way340   I want it341342optional arguments:343 -h, --help  show this help message and exit344```345346[`RawTextHelpFormatter`](https://python-all.ru/3.4/library/argparse.html#argparse.RawTextHelpFormatter) сохраняет пробелы для всех видов текста справки, включая описания аргументов.347348[`ArgumentDefaultsHelpFormatter`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentDefaultsHelpFormatter) автоматически добавляет информацию о значениях по умолчанию в каждое сообщение справки аргумента:349350```python351>>> parser = argparse.ArgumentParser(352...     prog='PROG',353...     formatter_class=argparse.ArgumentDefaultsHelpFormatter)354>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')355>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')356>>> parser.print_help()357usage: PROG [-h] [--foo FOO] [bar [bar ...]]358359positional arguments:360 bar         BAR! (default: [1, 2, 3])361362optional arguments:363 -h, --help  show this help message and exit364 --foo FOO   FOO! (default: 42)365```366367[`MetavarTypeHelpFormatter`](https://python-all.ru/3.4/library/argparse.html#argparse.MetavarTypeHelpFormatter) использует имя аргумента [type](https://python-all.ru/3.4/library/argparse.html#type) для каждого аргумента в качестве отображаемого имени его значений (вместо использования [dest](https://python-all.ru/3.4/library/argparse.html#dest), как это делает обычный форматировщик):368369```python370>>> parser = argparse.ArgumentParser(371...     prog='PROG',372...     formatter_class=argparse.MetavarTypeHelpFormatter)373>>> parser.add_argument('--foo', type=int)374>>> parser.add_argument('bar', type=float)375>>> parser.print_help()376usage: PROG [-h] [--foo int] float377378positional arguments:379  float380381optional arguments:382  -h, --help  show this help message and exit383  --foo int384```385386### 16.4.2.7. prefix\_chars387388Большинство опций командной строки используют префикс `-`, например, `-f/--foo`. Парсеры, которым требуется поддержка других или дополнительных символов префикса, например, для опций вроде `+f` или `/foo`, могут указать их с помощью аргумента `prefix_chars=` конструктора ArgumentParser:389390```python391>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')392>>> parser.add_argument('+f')393>>> parser.add_argument('++bar')394>>> parser.parse_args('+f X ++bar Y'.split())395Namespace(bar='Y', f='X')396```397398Аргумент `prefix_chars=` по умолчанию равен `'-'`. Если указать набор символов, не включающий `-`, то опции `-f/--foo` будут запрещены.399400### 16.4.2.8. fromfile\_prefix\_chars401402Иногда, например, при работе с особенно длинными списками аргументов, может иметь смысл хранить список аргументов в файле, а не вводить его в командной строке. Если аргумент `fromfile_prefix_chars=` передан конструктору [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser), то аргументы, начинающиеся с любого из указанных символов, будут рассматриваться как файлы и заменяться на содержащиеся в них аргументы. Например:403404```python405>>> with open('args.txt', 'w') as fp:406...    fp.write('-f\nbar')407>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')408>>> parser.add_argument('-f')409>>> parser.parse_args(['-f', 'foo', '@args.txt'])410Namespace(f='bar')411```412413Аргументы, читаемые из файла, по умолчанию должны быть по одному на строку (но см. также [`convert_arg_line_to_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.convert_arg_line_to_args)) и обрабатываются так, как если бы они находились на том же месте, что и исходный аргумент, ссылающийся на файл, в командной строке. Таким образом, в приведённом выше примере выражение `['-f', 'foo', '@args.txt']` считается эквивалентным выражению `['-f', 'foo', '-f', 'bar']`.414415Аргумент `fromfile_prefix_chars=` по умолчанию равен `None`, то есть аргументы никогда не будут рассматриваться как ссылки на файлы.416417### 16.4.2.9. argument\_default418419Обычно значения аргументов по умолчанию задаются либо передачей значения по умолчанию в [`add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument), либо вызовом методов [`set_defaults()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.set_defaults) с определённым набором пар имя-значение. Однако иногда бывает полезно задать единое для всего парсера значение по умолчанию для аргументов. Это можно сделать, передав ключевой аргумент `argument_default=` в [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser). Например, чтобы глобально подавить создание атрибутов при вызовах [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args), укажите `argument_default=SUPPRESS`:420421```python422>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)423>>> parser.add_argument('--foo')424>>> parser.add_argument('bar', nargs='?')425>>> parser.parse_args(['--foo', '1', 'BAR'])426Namespace(bar='BAR', foo='1')427>>> parser.parse_args([])428Namespace()429```430431### 16.4.2.10. conflict\_handler432433Объекты [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) не допускают двух действий с одинаковой строкой опции. По умолчанию объекты [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) вызывают исключение при попытке создать аргумент со строкой опции, которая уже используется:434435```python436>>> parser = argparse.ArgumentParser(prog='PROG')437>>> parser.add_argument('-f', '--foo', help='old foo help')438>>> parser.add_argument('--foo', help='new foo help')439Traceback (most recent call last):440 ..441ArgumentError: argument --foo: conflicting option string(s): --foo442```443444Иногда (например, при использовании [parents](https://python-all.ru/3.4/library/argparse.html#parents)) может быть полезно просто переопределить любые старые аргументы с той же строкой опции. Чтобы получить такое поведение, можно передать значение `'resolve'` аргументу `conflict_handler=` объекта [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser):445446```python447>>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')448>>> parser.add_argument('-f', '--foo', help='old foo help')449>>> parser.add_argument('--foo', help='new foo help')450>>> parser.print_help()451usage: PROG [-h] [-f FOO] [--foo FOO]452453optional arguments:454 -h, --help  show this help message and exit455 -f FOO      old foo help456 --foo FOO   new foo help457```458459Обратите внимание, что объекты [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) удаляют действие только если все его строки опций переопределены. Так, в примере выше старое действие `-f/--foo` сохраняется как действие `-f`, потому что была переопределена только строка опции `--foo`.460461### 16.4.2.11. add\_help462463По умолчанию объекты ArgumentParser добавляют опцию, которая просто отображает справочное сообщение парсера. Например, рассмотрим файл с именем `myprogram.py`, содержащий следующий код:464465```python466import argparse467parser = argparse.ArgumentParser()468parser.add_argument('--foo', help='foo help')469args = parser.parse_args()470```471472Если в командной строке указать `-h` или `--help`, будет выведена справка ArgumentParser:473474```python475$ python myprogram.py --help476usage: myprogram.py [-h] [--foo FOO]477478optional arguments:479 -h, --help  show this help message and exit480 --foo FOO   foo help481```482483Иногда может быть полезно отключить добавление этой опции справки. Это можно сделать, передав `False` в качестве аргумента `add_help=` в [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser):484485```python486>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)487>>> parser.add_argument('--foo', help='foo help')488>>> parser.print_help()489usage: PROG [--foo FOO]490491optional arguments:492 --foo FOO  foo help493```494495Опция справки обычно имеет вид `-h/--help`. Исключением является случай, когда указан `prefix_chars=` и он не включает `-`; в этом случае `-h` и `--help` не являются допустимыми опциями. В таком случае первый символ в `prefix_chars` используется в качестве префикса для опций справки:496497```python498>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')499>>> parser.print_help()500usage: PROG [+h]501502optional arguments:503  +h, ++help  show this help message and exit504```505506## 16.4.3. Метод add\_argument()507508#### `ArgumentParser.add_argument(name or flags...[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest])`509510Определяет, как должен разбираться один аргумент командной строки. Каждый параметр подробно описан ниже, а кратко они таковы:511512- [имя или флаги](https://python-all.ru/3.4/library/argparse.html#name-or-flags) – Имя или список строк параметров, например `foo` или `-f, --foo`.513- [action](https://python-all.ru/3.4/library/argparse.html#action) – базовый тип действия, которое выполняется при встрече этого аргумента в командной строке.514- [nargs](https://python-all.ru/3.4/library/argparse.html#nargs) – количество аргументов командной строки, которое должно быть потреблено.515- [const](https://python-all.ru/3.4/library/argparse.html#const) – постоянное значение, требуемое некоторыми значениями [action](https://python-all.ru/3.4/library/argparse.html#action) и [nargs](https://python-all.ru/3.4/library/argparse.html#nargs).516- [default](https://python-all.ru/3.4/library/argparse.html#default) – Значение, создаваемое, если аргумент отсутствует в командной строке.517- [type](https://python-all.ru/3.4/library/argparse.html#type) – тип, в который следует преобразовать аргумент командной строки.518- [choices](https://python-all.ru/3.4/library/argparse.html#choices) – Контейнер допустимых значений для аргумента.519- [required](https://python-all.ru/3.4/library/argparse.html#required) – может ли параметр командной строки быть опущен (только для опциональных параметров).520- [help](https://python-all.ru/3.4/library/argparse.html#help) – краткое описание того, что делает аргумент.521- [metavar](https://python-all.ru/3.4/library/argparse.html#metavar) – имя аргумента в сообщениях об использовании.522- [dest](https://python-all.ru/3.4/library/argparse.html#dest) – Имя атрибута, который будет добавлен к объекту, возвращаемому [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args).523524В следующих разделах описывается, как используется каждый из этих параметров.525526### 16.4.3.1. name или flags527528Метод [`add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument) должен знать, ожидается ли необязательный аргумент, например `-f` или `--foo`, или позиционный аргумент, например список имен файлов. Поэтому первые аргументы, передаваемые в [`add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument), должны быть либо серией флагов, либо простым именем аргумента. Например, необязательный аргумент можно создать так:529530```python531>>> parser.add_argument('-f', '--foo')532```533534а позиционный – так:535536```python537>>> parser.add_argument('bar')538```539540Когда вызывается [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args), необязательные аргументы будут определяться по префиксу `-`, а остальные аргументы будут считаться позиционными:541542```python543>>> parser = argparse.ArgumentParser(prog='PROG')544>>> parser.add_argument('-f', '--foo')545>>> parser.add_argument('bar')546>>> parser.parse_args(['BAR'])547Namespace(bar='BAR', foo=None)548>>> parser.parse_args(['BAR', '--foo', 'FOO'])549Namespace(bar='BAR', foo='FOO')550>>> parser.parse_args(['--foo', 'FOO'])551usage: PROG [-h] [-f FOO] bar552PROG: error: too few arguments553```554555### 16.4.3.2. action556557Объекты [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) связывают аргументы командной строки с действиями. Эти действия могут делать почти что угодно с связанными с ними аргументами командной строки, хотя большинство действий просто добавляют атрибут к объекту, возвращаемому [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args). Аргумент-ключевое слово `action` определяет, как должны обрабатываться аргументы командной строки. Предоставляются следующие действия:558559- `'store'` – Просто сохраняет значение аргумента. Это действие по умолчанию. Например:560561  ```python562  >>> parser = argparse.ArgumentParser()563  >>> parser.add_argument('--foo')564  >>> parser.parse_args('--foo 1'.split())565  Namespace(foo='1')566  ```567- `'store_const'` – Сохраняет значение, указанное аргументом-ключевым словом [const](https://python-all.ru/3.4/library/argparse.html#const). (Обратите внимание, что аргумент-ключевое слово [const](https://python-all.ru/3.4/library/argparse.html#const) по умолчанию равен довольно бесполезному `None`.) Действие `'store_const'` чаще всего используется с необязательными аргументами, задающими какой-либо флаг. Например:568569  ```python570  >>> parser = argparse.ArgumentParser()571  >>> parser.add_argument('--foo', action='store_const', const=42)572  >>> parser.parse_args('--foo'.split())573  Namespace(foo=42)574  ```575- `'store_true'` и `'store_false'` – Сохраняют значения `True` и `False` соответственно. Это частные случаи `'store_const'`. Например:576577  ```python578  >>> parser = argparse.ArgumentParser()579  >>> parser.add_argument('--foo', action='store_true')580  >>> parser.add_argument('--bar', action='store_false')581  >>> parser.parse_args('--foo --bar'.split())582  Namespace(bar=False, foo=True)583  ```584- `'append'` – Сохраняет список и добавляет каждое значение аргумента в этот список. Это полезно, чтобы позволить указывать параметр несколько раз. Пример использования:585586  ```python587  >>> parser = argparse.ArgumentParser()588  >>> parser.add_argument('--foo', action='append')589  >>> parser.parse_args('--foo 1 --foo 2'.split())590  Namespace(foo=['1', '2'])591  ```592- `'append_const'` – Сохраняет список и добавляет в него значение, указанное аргументом-ключевым словом [const](https://python-all.ru/3.4/library/argparse.html#const). (Обратите внимание, что аргумент-ключевое слово [const](https://python-all.ru/3.4/library/argparse.html#const) по умолчанию равен `None`.) Действие `'append_const'` обычно полезно, когда нескольким аргументам нужно сохранять константы в один и тот же список. Например:593594  ```python595  >>> parser = argparse.ArgumentParser()596  >>> parser.add_argument('--str', dest='types', action='append_const', const=str)597  >>> parser.add_argument('--int', dest='types', action='append_const', const=int)598  >>> parser.parse_args('--str --int'.split())599  Namespace(types=[<class 'str'>, <class 'int'>])600  ```601- `'count'` – Подсчитывает количество появлений аргумента-ключевого слова. Например, это полезно для повышения уровня подробности вывода:602603  ```python604  >>> parser = argparse.ArgumentParser()605  >>> parser.add_argument('--verbose', '-v', action='count')606  >>> parser.parse_args('-vvv'.split())607  Namespace(verbose=3)608  ```609- `'help'` – Выводит полное сообщение справки для всех параметров текущего парсера и завершает работу. По умолчанию действие help автоматически добавляется к парсеру. Подробнее о том, как создается вывод, см. в [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser).610- `'version'` – Ожидает аргумент-ключевое слово `version=` в вызове [`add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument) и выводит информацию о версии и завершает работу при вызове:611612  ```python613  >>> import argparse614  >>> parser = argparse.ArgumentParser(prog='PROG')615  >>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')616  >>> parser.parse_args(['--version'])617  PROG 2.0618  ```619620Можно также указать произвольное действие, передав подкласс Action или другой объект, реализующий тот же интерфейс. Рекомендуемый способ – расширить [`Action`](https://python-all.ru/3.4/library/argparse.html#argparse.Action), переопределив метод `__call__` и, при необходимости, метод `__init__`.621622Пример пользовательского действия:623624```python625>>> class FooAction(argparse.Action):626...     def __init__(self, option_strings, dest, nargs=None, **kwargs):627...         if nargs is not None:628...             raise ValueError("nargs not allowed")629...         super(FooAction, self).__init__(option_strings, dest, **kwargs)630...     def __call__(self, parser, namespace, values, option_string=None):631...         print('%r %r %r' % (namespace, values, option_string))632...         setattr(namespace, self.dest, values)633...634>>> parser = argparse.ArgumentParser()635>>> parser.add_argument('--foo', action=FooAction)636>>> parser.add_argument('bar', action=FooAction)637>>> args = parser.parse_args('1 --foo 2'.split())638Namespace(bar=None, foo=None) '1' None639Namespace(bar='1', foo=None) '2' '--foo'640>>> args641Namespace(bar='1', foo='2')642```643644Подробнее см. в [`Action`](https://python-all.ru/3.4/library/argparse.html#argparse.Action).645646### 16.4.3.3. nargs647648Объекты ArgumentParser обычно связывают один аргумент командной строки с одним действием. Аргумент-ключевое слово `nargs` связывает другое количество аргументов командной строки с одним действием. Поддерживаемые значения:649650- `N` (целое число). `N` аргументов из командной строки будут собраны вместе в список. Например:651652  ```python653  >>> parser = argparse.ArgumentParser()654  >>> parser.add_argument('--foo', nargs=2)655  >>> parser.add_argument('bar', nargs=1)656  >>> parser.parse_args('c --foo a b'.split())657  Namespace(bar=['c'], foo=['a', 'b'])658  ```659660  Обратите внимание, что `nargs=1` создает список из одного элемента. Это отличается от поведения по умолчанию, при котором элемент создается сам по себе.661- `'?'`. Если возможно, будет потреблён один аргумент командной строки и выдан как отдельный элемент. Если аргумент командной строки отсутствует, будет выдано значение из [default](https://python-all.ru/3.4/library/argparse.html#default). Обратите внимание, что для необязательных аргументов есть дополнительный случай: строка параметра присутствует, но за ней не следует аргумент командной строки. В этом случае будет выдано значение из [const](https://python-all.ru/3.4/library/argparse.html#const). Некоторые примеры для иллюстрации:662663  ```python664  >>> parser = argparse.ArgumentParser()665  >>> parser.add_argument('--foo', nargs='?', const='c', default='d')666  >>> parser.add_argument('bar', nargs='?', default='d')667  >>> parser.parse_args('XX --foo YY'.split())668  Namespace(bar='XX', foo='YY')669  >>> parser.parse_args('XX --foo'.split())670  Namespace(bar='XX', foo='c')671  >>> parser.parse_args(''.split())672  Namespace(bar='d', foo='d')673  ```674675  Одно из наиболее распространенных применений `nargs='?'` – это разрешение необязательных входных и выходных файлов:676677  ```python678  >>> parser = argparse.ArgumentParser()679  >>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),680  ...                     default=sys.stdin)681  >>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),682  ...                     default=sys.stdout)683  >>> parser.parse_args(['input.txt', 'output.txt'])684  Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,685            outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)686  >>> parser.parse_args([])687  Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,688            outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)689  ```690- `'*'`. Все имеющиеся аргументы командной строки собираются в список. Обратите внимание, что обычно нет большого смысла иметь более одного позиционного аргумента с `nargs='*'`, но несколько необязательных аргументов с `nargs='*'` – это возможно. Например:691692  ```python693  >>> parser = argparse.ArgumentParser()694  >>> parser.add_argument('--foo', nargs='*')695  >>> parser.add_argument('--bar', nargs='*')696  >>> parser.add_argument('baz', nargs='*')697  >>> parser.parse_args('a b --foo x y --bar 1 2'.split())698  Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])699  ```700- `'+'`. Как и `'*'`, все присутствующие аргументы командной строки собираются в список. Кроме того, будет выдано сообщение об ошибке, если не было хотя бы одного аргумента командной строки. Например:701702  ```python703  >>> parser = argparse.ArgumentParser(prog='PROG')704  >>> parser.add_argument('foo', nargs='+')705  >>> parser.parse_args('a b'.split())706  Namespace(foo=['a', 'b'])707  >>> parser.parse_args(''.split())708  usage: PROG [-h] foo [foo ...]709  PROG: error: too few arguments710  ```711- `argparse.REMAINDER`. Все оставшиеся аргументы командной строки собираются в список. Это часто полезно для утилит командной строки, которые передают управление другим утилитам командной строки:712713  ```python714  >>> parser = argparse.ArgumentParser(prog='PROG')715  >>> parser.add_argument('--foo')716  >>> parser.add_argument('command')717  >>> parser.add_argument('args', nargs=argparse.REMAINDER)718  >>> print(parser.parse_args('--foo B cmd --arg1 XX ZZ'.split()))719  Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')720  ```721722Если аргумент-ключевое слово `nargs` не указан, количество потребляемых аргументов определяется действием [action](https://python-all.ru/3.4/library/argparse.html#action). Обычно это означает, что будет потреблен один аргумент командной строки и создан один элемент (не список).723724### 16.4.3.4. const725726Аргумент `const` функции [`add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument) используется для хранения постоянных значений, которые не считываются из командной строки, но требуются для различных действий [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser). Два наиболее распространенных применения:727728- Когда [`add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument) вызывается с `action='store_const'` или `action='append_const'`. Эти действия добавляют значение `const` к одному из атрибутов объекта, возвращаемого [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args). См. описание [action](https://python-all.ru/3.4/library/argparse.html#action) для примеров.729- Когда [`add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument) вызывается со строками параметров (например, `-f` или `--foo`) и `nargs='?'`. Это создает необязательный аргумент, за которым может следовать ноль или один аргумент командной строки. При разборе командной строки, если строка параметра встречается без следующего за ней аргумента командной строки, вместо него будет использовано значение `const`. См. описание [nargs](https://python-all.ru/3.4/library/argparse.html#nargs) для примеров.730731Аргумент-ключевое слово `const` по умолчанию равен `None`.732733### 16.4.3.5. default734735Все необязательные аргументы и некоторые позиционные аргументы могут быть опущены в командной строке. Аргумент-ключевое слово `default` функции [`add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument), значение которого по умолчанию равно `None`, определяет, какое значение следует использовать, если аргумент командной строки отсутствует. Для необязательных аргументов значение `default` используется, когда строка параметра не присутствовала в командной строке:736737```python738>>> parser = argparse.ArgumentParser()739>>> parser.add_argument('--foo', default=42)740>>> parser.parse_args('--foo 2'.split())741Namespace(foo='2')742>>> parser.parse_args(''.split())743Namespace(foo=42)744```745746Если значением `default` является строка, анализатор разбирает его так, как если бы это был аргумент командной строки. В частности, анализатор применяет любой аргумент преобразования [type](https://python-all.ru/3.4/library/argparse.html#type), если он указан, перед установкой атрибута в возвращаемом значении [`Namespace`](https://python-all.ru/3.4/library/argparse.html#argparse.Namespace). В противном случае анализатор использует значение как есть:747748```python749>>> parser = argparse.ArgumentParser()750>>> parser.add_argument('--length', default='10', type=int)751>>> parser.add_argument('--width', default=10.5, type=int)752>>> parser.parse_args()753Namespace(length=10, width=10.5)754```755756Для позиционных аргументов с [nargs](https://python-all.ru/3.4/library/argparse.html#nargs) равным `?` или `*` значение `default` используется, когда аргумент командной строки отсутствовал:757758```python759>>> parser = argparse.ArgumentParser()760>>> parser.add_argument('foo', nargs='?', default=42)761>>> parser.parse_args('a'.split())762Namespace(foo='a')763>>> parser.parse_args(''.split())764Namespace(foo=42)765```766767Указание `default=argparse.SUPPRESS` приводит к тому, что атрибут не добавляется, если аргумент командной строки отсутствовал.:768769```python770>>> parser = argparse.ArgumentParser()771>>> parser.add_argument('--foo', default=argparse.SUPPRESS)772>>> parser.parse_args([])773Namespace()774>>> parser.parse_args(['--foo', '1'])775Namespace(foo='1')776```777778### 16.4.3.6. type779780По умолчанию объекты [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) читают аргументы командной строки как простые строки. Однако довольно часто строку командной строки следует интерпретировать как другой тип, например [`float`](https://python-all.ru/3.4/library/functions.html#float) или [`int`](https://python-all.ru/3.4/library/functions.html#int). Именованный аргумент `type` функции [`add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument) позволяет выполнять любые необходимые проверки и преобразования типов. Встроенные типы и функции могут использоваться непосредственно как значение аргумента `type`:781782```python783>>> parser = argparse.ArgumentParser()784>>> parser.add_argument('foo', type=int)785>>> parser.add_argument('bar', type=open)786>>> parser.parse_args('2 temp.txt'.split())787Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)788```789790Смотрите раздел об именованном аргументе [default](https://python-all.ru/3.4/library/argparse.html#default) для получения информации о том, когда аргумент `type` применяется к значениям по умолчанию.791792Чтобы упростить работу с различными типами файлов, модуль argparse предоставляет фабрику FileType, которая принимает аргументы `mode=`, `bufsize=`, `encoding=` и `errors=` функции [`open()`](https://python-all.ru/3.4/library/functions.html#open). Например, `FileType('w')` можно использовать для создания файла для записи:793794```python795>>> parser = argparse.ArgumentParser()796>>> parser.add_argument('bar', type=argparse.FileType('w'))797>>> parser.parse_args(['out.txt'])798Namespace(bar=<_io.TextIOWrapper name='out.txt' encoding='UTF-8'>)799```800801`type=` может принимать любой вызываемый объект, который принимает один строковый аргумент и возвращает преобразованное значение:802803```python804>>> def perfect_square(string):805...     value = int(string)806...     sqrt = math.sqrt(value)807...     if sqrt != int(sqrt):808...         msg = "%r is not a perfect square" % string809...         raise argparse.ArgumentTypeError(msg)810...     return value811...812>>> parser = argparse.ArgumentParser(prog='PROG')813>>> parser.add_argument('foo', type=perfect_square)814>>> parser.parse_args('9'.split())815Namespace(foo=9)816>>> parser.parse_args('7'.split())817usage: PROG [-h] foo818PROG: error: argument foo: '7' is not a perfect square819```820821Ключевой аргумент [choices](https://python-all.ru/3.4/library/argparse.html#choices) может быть удобнее для проверок типов, которые просто проверяют попадание в диапазон значений:822823```python824>>> parser = argparse.ArgumentParser(prog='PROG')825>>> parser.add_argument('foo', type=int, choices=range(5, 10))826>>> parser.parse_args('7'.split())827Namespace(foo=7)828>>> parser.parse_args('11'.split())829usage: PROG [-h] {5,6,7,8,9}830PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)831```832833См. раздел [choices](https://python-all.ru/3.4/library/argparse.html#choices) для получения дополнительных сведений.834835### 16.4.3.7. choices836837Some command-line arguments should be selected from a restricted set of values. These can be handled by passing a container object as the *choices* keyword argument to [`add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.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:838839```python840>>> parser = argparse.ArgumentParser(prog='game.py')841>>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])842>>> parser.parse_args(['rock'])843Namespace(move='rock')844>>> parser.parse_args(['fire'])845usage: game.py [-h] {rock,paper,scissors}846game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',847'paper', 'scissors')848```849850Обратите внимание: вхождение в контейнер *choices* проверяется после всех преобразований типа [type](https://python-all.ru/3.4/library/argparse.html#type), поэтому тип объектов в *choices* должен соответствовать указанному [type](https://python-all.ru/3.4/library/argparse.html#type):851852```python853>>> parser = argparse.ArgumentParser(prog='doors.py')854>>> parser.add_argument('door', type=int, choices=range(1, 4))855>>> print(parser.parse_args(['3']))856Namespace(door=3)857>>> parser.parse_args(['4'])858usage: doors.py [-h] {1,2,3}859doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)860```861862Any object that supports the `in` operator can be passed as the *choices* value, so [`dict`](https://python-all.ru/3.4/library/stdtypes.html#dict) objects, [`set`](https://python-all.ru/3.4/library/stdtypes.html#set) objects, custom containers, etc. are all supported.863864### 16.4.3.8. required865866In general, the [`argparse`](https://python-all.ru/3.4/library/argparse.html#module-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()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument):867868```python869>>> parser = argparse.ArgumentParser()870>>> parser.add_argument('--foo', required=True)871>>> parser.parse_args(['--foo', 'BAR'])872Namespace(foo='BAR')873>>> parser.parse_args([])874usage: argparse.py [-h] [--foo FOO]875argparse.py: error: option --foo is required876```877878Как показывает пример, если опция помечена как `required`, [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args) сообщит об ошибке, если эта опция отсутствует в командной строке.879880> **Примечание**881>882> Обязательные опции обычно считаются дурным тоном, поскольку пользователи ожидают, что *опции* будут *необязательными*, поэтому их следует по возможности избегать.883884### 16.4.3.9. help885886Значение `help` – это строка, содержащая краткое описание аргумента. Когда пользователь запрашивает справку (обычно с помощью `-h` или `--help` в командной строке), эти описания `help` будут отображаться для каждого аргумента:887888```python889>>> parser = argparse.ArgumentParser(prog='frobble')890>>> parser.add_argument('--foo', action='store_true',891...         help='foo the bars before frobbling')892>>> parser.add_argument('bar', nargs='+',893...         help='one of the bars to be frobbled')894>>> parser.parse_args('-h'.split())895usage: frobble [-h] [--foo] bar [bar ...]896897positional arguments:898 bar     one of the bars to be frobbled899900optional arguments:901 -h, --help  show this help message and exit902 --foo   foo the bars before frobbling903```904905Строки `help` могут содержать различные спецификаторы формата, чтобы избежать повторения таких вещей, как имя программы или значение [default](https://python-all.ru/3.4/library/argparse.html#default). Доступные спецификаторы включают имя программы `%(prog)s` и большинство именованных аргументов функции [`add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument), например `%(default)s`, `%(type)s` и т. д.:906907```python908>>> parser = argparse.ArgumentParser(prog='frobble')909>>> parser.add_argument('bar', nargs='?', type=int, default=42,910...         help='the bar to %(prog)s (default: %(default)s)')911>>> parser.print_help()912usage: frobble [-h] [bar]913914positional arguments:915 bar     the bar to frobble (default: 42)916917optional arguments:918 -h, --help  show this help message and exit919```920921Поскольку строка справки поддерживает %-форматирование, если требуется, чтобы в ней отображался литерал `%`, его нужно экранировать как `%%`.922923[`argparse`](https://python-all.ru/3.4/library/argparse.html#module-argparse) поддерживает скрытие записи справки для определённых опций путём установки значения `help` в `argparse.SUPPRESS`:924925```python926>>> parser = argparse.ArgumentParser(prog='frobble')927>>> parser.add_argument('--foo', help=argparse.SUPPRESS)928>>> parser.print_help()929usage: frobble [-h]930931optional arguments:932  -h, --help  show this help message and exit933```934935### 16.4.3.10. мета-переменная936937Когда [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) генерирует сообщения справки, ему нужен способ ссылаться на каждый ожидаемый аргумент. По умолчанию объекты ArgumentParser используют значение [dest](https://python-all.ru/3.4/library/argparse.html#dest) в качестве «имени» каждого объекта. По умолчанию для действий позиционных аргументов значение [dest](https://python-all.ru/3.4/library/argparse.html#dest) используется непосредственно, а для действий необязательных аргументов значение [dest](https://python-all.ru/3.4/library/argparse.html#dest) приводится к верхнему регистру. Таким образом, одиночный позиционный аргумент с `dest='bar'` будет называться `bar`. Одиночный необязательный аргумент `--foo`, за которым должен следовать один аргумент командной строки, будет называться `FOO`. Пример:938939```python940>>> parser = argparse.ArgumentParser()941>>> parser.add_argument('--foo')942>>> parser.add_argument('bar')943>>> parser.parse_args('X --foo Y'.split())944Namespace(bar='X', foo='Y')945>>> parser.print_help()946usage:  [-h] [--foo FOO] bar947948positional arguments:949 bar950951optional arguments:952 -h, --help  show this help message and exit953 --foo FOO954```955956Альтернативное имя можно указать с помощью `metavar`:957958```python959>>> parser = argparse.ArgumentParser()960>>> parser.add_argument('--foo', metavar='YYY')961>>> parser.add_argument('bar', metavar='XXX')962>>> parser.parse_args('X --foo Y'.split())963Namespace(bar='X', foo='Y')964>>> parser.print_help()965usage:  [-h] [--foo YYY] XXX966967positional arguments:968 XXX969970optional arguments:971 -h, --help  show this help message and exit972 --foo YYY973```974975Обратите внимание, что `metavar` изменяет только *отображаемое* имя – имя атрибута в объекте, возвращаемом [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args), по-прежнему определяется значением [dest](https://python-all.ru/3.4/library/argparse.html#dest).976977Различные значения `nargs` могут привести к многократному использованию metavar. Передача кортежа в `metavar` задаёт различное отображение для каждого из аргументов:978979```python980>>> parser = argparse.ArgumentParser(prog='PROG')981>>> parser.add_argument('-x', nargs=2)982>>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))983>>> parser.print_help()984usage: PROG [-h] [-x X X] [--foo bar baz]985986optional arguments:987 -h, --help     show this help message and exit988 -x X X989 --foo bar baz990```991992### 16.4.3.11. dest993994Most [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) actions add some value as an attribute of the object returned by [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args). The name of this attribute is determined by the `dest` keyword argument of [`add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument). For positional argument actions, `dest` is normally supplied as the first argument to [`add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument):995996```python997>>> parser = argparse.ArgumentParser()998>>> parser.add_argument('bar')999>>> parser.parse_args('XXX'.split())1000Namespace(bar='XXX')1001```10021003Для действий необязательных аргументов значение `dest` обычно выводится из строк опций. [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) генерирует значение `dest` путём взятия первой длинной строки опции и удаления начальной строки `--`. Если длинные строки опций не были указаны, `dest` будет получен из первой короткой строки опции путём удаления начального символа `-`. Любые внутренние символы `-` будут преобразованы в символы `_`, чтобы строка была допустимым именем атрибута. Примеры ниже иллюстрируют это поведение:10041005```python1006>>> parser = argparse.ArgumentParser()1007>>> parser.add_argument('-f', '--foo-bar', '--foo')1008>>> parser.add_argument('-x', '-y')1009>>> parser.parse_args('-f 1 -x 2'.split())1010Namespace(foo_bar='1', x='2')1011>>> parser.parse_args('--foo 1 -y 2'.split())1012Namespace(foo_bar='1', x='2')1013```10141015`dest` позволяет указать пользовательское имя атрибута:10161017```python1018>>> parser = argparse.ArgumentParser()1019>>> parser.add_argument('--foo', dest='bar')1020>>> parser.parse_args('--foo XXX'.split())1021Namespace(bar='XXX')1022```10231024### 16.4.3.12. Классы действий10251026Классы действий реализуют API Action – вызываемый объект, который возвращает вызываемый объект, обрабатывающий аргументы командной строки. Любой объект, следующий этому API, может быть передан в качестве параметра `action` функции `add_argument()`.10271028#### `class argparse.Action(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)`10291030Объекты Action используются ArgumentParser для представления информации, необходимой для разбора одного аргумента из одной или нескольких строк командной строки. Класс Action должен принимать два позиционных аргумента, а также любые именованные аргументы, переданные в [`ArgumentParser.add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument), за исключением самого `action`.10311032Экземпляры Action (или возвращаемое значение любого вызываемого объекта для параметра `action`) должны иметь определённые атрибуты “dest”, “option\_strings”, “default”, “type”, “required”, “help” и т. д. Самый простой способ гарантировать, что эти атрибуты определены – вызвать `Action.__init__`.10331034Экземпляры Action должны быть вызываемыми, поэтому подклассы должны переопределять метод `__call__`, который должен принимать четыре параметра:10351036- `parser` – объект ArgumentParser, который содержит это действие.1037- `namespace` – объект [`Namespace`](https://python-all.ru/3.4/library/argparse.html#argparse.Namespace), который будет возвращён [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args). Большинство действий добавляют атрибут к этому объекту с помощью [`setattr()`](https://python-all.ru/3.4/library/functions.html#setattr).1038- `values` – соответствующие аргументы командной строки, после применения всех преобразований типов. Преобразования типов задаются именованным аргументом [type](https://python-all.ru/3.4/library/argparse.html#type) в [`add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument).1039- `option_string` – строка опции, которая использовалась для вызова этого действия. Аргумент `option_string` является необязательным и будет отсутствовать, если действие связано с позиционным аргументом.10401041Метод `__call__` может выполнять произвольные действия, но обычно устанавливает атрибуты в `namespace` на основе `dest` и `values`.10421043## 16.4.4. Метод parse\_args()10441045#### `ArgumentParser.parse_args(args=None, namespace=None)`10461047Преобразует строки аргументов в объекты и назначает их в качестве атрибутов пространства имён. Возвращает заполненное пространство имён.10481049Предыдущие вызовы [`add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument) определяют, какие именно объекты создаются и как они назначаются. Подробнее см. документацию к [`add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument).10501051По умолчанию строки аргументов берутся из [`sys.argv`](https://python-all.ru/3.4/library/sys.html#sys.argv), и создаётся новый пустой объект [`Namespace`](https://python-all.ru/3.4/library/argparse.html#argparse.Namespace) для атрибутов.10521053### 16.4.4.1. Синтаксис значений опций10541055Метод [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args) поддерживает несколько способов указания значения опции (если она принимает значение). В простейшем случае опция и её значение передаются как два отдельных аргумента:10561057```python1058>>> parser = argparse.ArgumentParser(prog='PROG')1059>>> parser.add_argument('-x')1060>>> parser.add_argument('--foo')1061>>> parser.parse_args('-x X'.split())1062Namespace(foo=None, x='X')1063>>> parser.parse_args('--foo FOO'.split())1064Namespace(foo='FOO', x=None)1065```10661067Для длинных параметров (с именами длиннее одного символа) параметр и значение могут быть переданы как один аргумент командной строки, используя `=` для их разделения:10681069```python1070>>> parser.parse_args('--foo=FOO'.split())1071Namespace(foo='FOO', x=None)1072```10731074Для коротких опций (опции длиной в один символ) опция и её значение могут быть объединены:10751076```python1077>>> parser.parse_args('-xX'.split())1078Namespace(foo=None, x='X')1079```10801081Несколько коротких опций можно объединить, используя только один префикс `-`, при условии, что только последняя опция (или ни одна из них) требует значения:10821083```python1084>>> parser = argparse.ArgumentParser(prog='PROG')1085>>> parser.add_argument('-x', action='store_true')1086>>> parser.add_argument('-y', action='store_true')1087>>> parser.add_argument('-z')1088>>> parser.parse_args('-xyzZ'.split())1089Namespace(x=True, y=True, z='Z')1090```10911092### 16.4.4.2. Недопустимые аргументы10931094При разборе командной строки [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args) проверяет на наличие различных ошибок, включая неоднозначные опции, недопустимые типы, неверные опции, неправильное количество позиционных аргументов и т.д. Когда такая ошибка обнаруживается, он завершает работу и выводит сообщение об ошибке вместе с сообщением об использовании:10951096```python1097>>> parser = argparse.ArgumentParser(prog='PROG')1098>>> parser.add_argument('--foo', type=int)1099>>> parser.add_argument('bar', nargs='?')11001101>>> # недопустимый тип1102>>> parser.parse_args(['--foo', 'spam'])1103usage: PROG [-h] [--foo FOO] [bar]1104PROG: error: argument --foo: invalid int value: 'spam'11051106>>> # недопустимая опция1107>>> parser.parse_args(['--bar'])1108usage: PROG [-h] [--foo FOO] [bar]1109PROG: error: no such option: --bar11101111>>> # неверное количество аргументов1112>>> parser.parse_args(['spam', 'badger'])1113usage: PROG [-h] [--foo FOO] [bar]1114PROG: error: extra arguments found: badger1115```11161117### 16.4.4.3. Аргументы, содержащие `-`11181119Метод [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args) старается выдавать ошибки всякий раз, когда пользователь явно допустил ошибку, но некоторые ситуации по своей сути неоднозначны. Например, аргумент командной строки `-1` может быть как попыткой указать опцию, так и попыткой передать позиционный аргумент. Метод [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args) в этом случае действует осторожно: позиционные аргументы могут начинаться с `-` только если они выглядят как отрицательные числа и в синтаксическом анализаторе нет опций, которые выглядят как отрицательные числа:11201121```python1122>>> parser = argparse.ArgumentParser(prog='PROG')1123>>> parser.add_argument('-x')1124>>> parser.add_argument('foo', nargs='?')11251126>>> # нет опций с отрицательными числами, поэтому -1 – позиционный аргумент1127>>> parser.parse_args(['-x', '-1'])1128Namespace(foo=None, x='-1')11291130>>> # нет опций с отрицательными числами, поэтому -1 и -5 – позиционные аргументы1131>>> parser.parse_args(['-x', '-1', '-5'])1132Namespace(foo='-5', x='-1')11331134>>> parser = argparse.ArgumentParser(prog='PROG')1135>>> parser.add_argument('-1', dest='one')1136>>> parser.add_argument('foo', nargs='?')11371138>>> # опции с отрицательными числами присутствуют, поэтому -1 – это опция1139>>> parser.parse_args(['-1', 'X'])1140Namespace(foo=None, one='X')11411142>>> # опции с отрицательными числами присутствуют, поэтому -2 – это опция1143>>> parser.parse_args(['-2'])1144usage: PROG [-h] [-1 ONE] [foo]1145PROG: error: no such option: -211461147>>> # опции с отрицательными числами присутствуют, поэтому обе -1 – это опции1148>>> parser.parse_args(['-1', '-1'])1149usage: PROG [-h] [-1 ONE] [foo]1150PROG: error: argument -1: expected one argument1151```11521153Если у вас есть позиционные аргументы, которые должны начинаться с `-` и не выглядят как отрицательные числа, можно вставить псевдоаргумент `'--'`, который сообщает [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args), что всё после этого является позиционным аргументом:11541155```python1156>>> parser.parse_args(['--', '-f'])1157Namespace(foo='-f', one=None)1158```11591160### 16.4.4.4. Сокращения аргументов (совпадение по префиксу)11611162Метод [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args) позволяет сокращать длинные опции до префикса, если сокращение однозначно (префикс соответствует единственной опции):11631164```python1165>>> parser = argparse.ArgumentParser(prog='PROG')1166>>> parser.add_argument('-bacon')1167>>> parser.add_argument('-badger')1168>>> parser.parse_args('-bac MMM'.split())1169Namespace(bacon='MMM', badger=None)1170>>> parser.parse_args('-bad WOOD'.split())1171Namespace(bacon=None, badger='WOOD')1172>>> parser.parse_args('-ba BA'.split())1173usage: PROG [-h] [-bacon BACON] [-badger BADGER]1174PROG: error: ambiguous option: -ba could match -badger, -bacon1175```11761177Для аргументов, которые могут соответствовать более чем одной опции, выдаётся ошибка.11781179### 16.4.4.5. За пределами `sys.argv`11801181Sometimes it may be useful to have an ArgumentParser parse arguments other than those of [`sys.argv`](https://python-all.ru/3.4/library/sys.html#sys.argv). This can be accomplished by passing a list of strings to [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args). This is useful for testing at the interactive prompt:11821183```python1184>>> parser = argparse.ArgumentParser()1185>>> parser.add_argument(1186...     'integers', metavar='int', type=int, choices=range(10),1187...  nargs='+', help='an integer in the range 0..9')1188>>> parser.add_argument(1189...     '--sum', dest='accumulate', action='store_const', const=sum,1190...   default=max, help='sum the integers (default: find the max)')1191>>> parser.parse_args(['1', '2', '3', '4'])1192Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])1193>>> parser.parse_args('1 2 3 4 --sum'.split())1194Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])1195```11961197### 16.4.4.6. Объект Namespace11981199#### `class argparse.Namespace`12001201Простой класс, используемый по умолчанию методом [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args) для создания объекта, содержащего атрибуты, и его возврата.12021203Этот класс намеренно простой, всего лишь подкласс [`object`](https://python-all.ru/3.4/library/functions.html#object) с читаемым строковым представлением. Если вы предпочитаете словареподобное представление атрибутов, можно использовать стандартный идиоматический приём Python, [`vars()`](https://python-all.ru/3.4/library/functions.html#vars):12041205```python1206>>> parser = argparse.ArgumentParser()1207>>> parser.add_argument('--foo')1208>>> args = parser.parse_args(['--foo', 'BAR'])1209>>> vars(args)1210{'foo': 'BAR'}1211```12121213Также может быть полезно заставить [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) присваивать атрибуты уже существующему объекту, а не новому объекту [`Namespace`](https://python-all.ru/3.4/library/argparse.html#argparse.Namespace). Этого можно достичь, указав именованный аргумент `namespace=`:12141215```python1216>>> class C:1217...     pass1218...1219>>> c = C()1220>>> parser = argparse.ArgumentParser()1221>>> parser.add_argument('--foo')1222>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)1223>>> c.foo1224'BAR'1225```12261227## 16.4.5. Другие утилиты12281229### 16.4.5.1. Подкоманды12301231#### `ArgumentParser.add_subparsers([title][, description][, prog][, parser_class][, action][, option_string][, dest][, help][, metavar])`12321233Многие программы разделяют свою функциональность на ряд подкоманд, например, программа `svn` может вызывать подкоманды, такие как `svn checkout`, `svn update` и `svn commit`. Разделение функциональности таким образом может быть особенно хорошей идеей, когда программа выполняет несколько разных функций, требующих различных типов аргументов командной строки. [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) поддерживает создание таких подкоманд с помощью метода [`add_subparsers()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_subparsers). Метод [`add_subparsers()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_subparsers) обычно вызывается без аргументов и возвращает специальный объект действия. Этот объект имеет единственный метод, `add_parser()`, который принимает имя команды и любые аргументы конструктора [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser), и возвращает объект [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser), который можно изменять как обычно.12341235Описание параметров:12361237- title – заголовок для группы подпарсеров в выводе справки; по умолчанию «subcommands», если указано описание, в противном случае используется заголовок для позиционных аргументов.1238- description – описание для группы подпарсеров в выводе справки, по умолчанию None1239- prog – информация об использовании, которая будет отображаться в справке подкоманды; по умолчанию – имя программы и любые позиционные аргументы перед аргументом подпарсера1240- parser\_class – класс, который будет использоваться для создания экземпляров подпарсера; по умолчанию – класс текущего парсера (например, ArgumentParser)1241- [action](https://python-all.ru/3.4/library/argparse.html#action) – базовый тип действия, которое будет выполнено при обнаружении этого аргумента в командной строке1242- [dest](https://python-all.ru/3.4/library/argparse.html#dest) – имя атрибута, в котором будет храниться имя подкоманды; по умолчанию None, и значение не сохраняется1243- [help](https://python-all.ru/3.4/library/argparse.html#help) – справка для группы подпарсеров в выводе справки, по умолчанию None1244- [metavar](https://python-all.ru/3.4/library/argparse.html#metavar) – строка, представляющая доступные подкоманды в справке; по умолчанию она равна None, и подкоманды отображаются в виде {cmd1, cmd2, ..}12451246Пример использования:12471248```python1249>>> # создать парсер верхнего уровня1250>>> parser = argparse.ArgumentParser(prog='PROG')1251>>> parser.add_argument('--foo', action='store_true', help='foo help')1252>>> subparsers = parser.add_subparsers(help='sub-command help')1253>>>1254>>> # создать парсер для команды "a"1255>>> parser_a = subparsers.add_parser('a', help='a help')1256>>> parser_a.add_argument('bar', type=int, help='bar help')1257>>>1258>>> # создать парсер для команды "b"1259>>> parser_b = subparsers.add_parser('b', help='b help')1260>>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')1261>>>1262>>> # разобрать некоторые списки аргументов1263>>> parser.parse_args(['a', '12'])1264Namespace(bar=12, foo=False)1265>>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])1266Namespace(baz='Z', foo=True)1267```12681269Обратите внимание, что объект, возвращаемый [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args), будет содержать только атрибуты для основного синтаксического анализатора и того подпарсера, который был выбран командной строкой (и никаких других подпарсеров). Так, в приведённом выше примере, когда указана команда `a`, присутствуют только атрибуты `foo` и `bar`, а когда указана команда `b`, присутствуют только атрибуты `foo` и `baz`.12701271Аналогично, когда запрашивается справка от подпарсера, будет выведена только справка для этого конкретного синтаксического анализатора. Сообщение справки не будет включать сообщения родительского или дочерних синтаксических анализаторов. (Однако справку для каждой подкоманды подпарсера можно задать, передав аргумент `help=` в `add_parser()`, как указано выше.)12721273```python1274>>> parser.parse_args(['--help'])1275usage: PROG [-h] [--foo] {a,b} ...12761277positional arguments:1278  {a,b}   sub-command help1279    a     a help1280    b     b help12811282optional arguments:1283  -h, --help  show this help message and exit1284  --foo   foo help12851286>>> parser.parse_args(['a', '--help'])1287usage: PROG a [-h] bar12881289positional arguments:1290  bar     bar help12911292optional arguments:1293  -h, --help  show this help message and exit12941295>>> parser.parse_args(['b', '--help'])1296usage: PROG b [-h] [--baz {X,Y,Z}]12971298optional arguments:1299  -h, --help     show this help message and exit1300  --baz {X,Y,Z}  baz help1301```13021303Метод [`add_subparsers()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_subparsers) также поддерживает именованные аргументы `title` и `description`. Когда любой из них присутствует, команды подпарсера будут отображаться в собственной группе в выводе справки. Например:13041305```python1306>>> parser = argparse.ArgumentParser()1307>>> subparsers = parser.add_subparsers(title='subcommands',1308...                                    description='valid subcommands',1309...                                    help='additional help')1310>>> subparsers.add_parser('foo')1311>>> subparsers.add_parser('bar')1312>>> parser.parse_args(['-h'])1313usage:  [-h] {foo,bar} ...13141315optional arguments:1316  -h, --help  show this help message and exit13171318subcommands:1319  valid subcommands13201321  {foo,bar}   additional help1322```13231324Кроме того, `add_parser` поддерживает дополнительный аргумент `aliases`, который позволяет нескольким строкам ссылаться на один и тот же подпарсер. В этом примере, как и в `svn`, псевдоним `co` задаётся как сокращение для `checkout`:13251326```python1327>>> parser = argparse.ArgumentParser()1328>>> subparsers = parser.add_subparsers()1329>>> checkout = subparsers.add_parser('checkout', aliases=['co'])1330>>> checkout.add_argument('foo')1331>>> parser.parse_args(['co', 'bar'])1332Namespace(foo='bar')1333```13341335Один из особенно эффективных способов работы с подкомандами – комбинировать использование метода [`add_subparsers()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_subparsers) с вызовами [`set_defaults()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.set_defaults), чтобы каждый подпарсер знал, какую функцию Python он должен выполнять. Например:13361337```python1338>>> # функции подкоманд1339>>> def foo(args):1340...     print(args.x * args.y)1341...1342>>> def bar(args):1343...     print('((%s))' % args.z)1344...1345>>> # создать парсер верхнего уровня1346>>> parser = argparse.ArgumentParser()1347>>> subparsers = parser.add_subparsers()1348>>>1349>>> # создать парсер для команды "foo"1350>>> parser_foo = subparsers.add_parser('foo')1351>>> parser_foo.add_argument('-x', type=int, default=1)1352>>> parser_foo.add_argument('y', type=float)1353>>> parser_foo.set_defaults(func=foo)1354>>>1355>>> # создать парсер для команды "bar"1356>>> parser_bar = subparsers.add_parser('bar')1357>>> parser_bar.add_argument('z')1358>>> parser_bar.set_defaults(func=bar)1359>>>1360>>> # разобрать аргументы и вызвать выбранную функцию1361>>> args = parser.parse_args('foo 1 -x 2'.split())1362>>> args.func(args)13632.01364>>>1365>>> # разобрать аргументы и вызвать выбранную функцию1366>>> args = parser.parse_args('bar XYZYX'.split())1367>>> args.func(args)1368((XYZYX))1369```13701371Таким образом, можно позволить [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args) выполнить вызов соответствующей функции после завершения разбора аргументов. Связывание функций с действиями таким образом – это, как правило, самый простой способ обрабатывать разные действия для каждого из ваших подпарсеров. Однако, если необходимо проверить имя вызванного подпарсера, именованный аргумент `dest` вызова [`add_subparsers()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_subparsers) сработает:13721373```python1374>>> parser = argparse.ArgumentParser()1375>>> subparsers = parser.add_subparsers(dest='subparser_name')1376>>> subparser1 = subparsers.add_parser('1')1377>>> subparser1.add_argument('-x')1378>>> subparser2 = subparsers.add_parser('2')1379>>> subparser2.add_argument('y')1380>>> parser.parse_args(['2', 'frobble'])1381Namespace(subparser_name='2', y='frobble')1382```13831384### 16.4.5.2. Объекты FileType13851386#### `class argparse.FileType(mode='r', bufsize=-1, encoding=None, errors=None)`13871388Фабрика [`FileType`](https://python-all.ru/3.4/library/argparse.html#argparse.FileType) создаёт объекты, которые можно передать в аргумент type метода [`ArgumentParser.add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument). Аргументы, для которых в качестве type указаны объекты [`FileType`](https://python-all.ru/3.4/library/argparse.html#argparse.FileType), будут открывать аргументы командной строки как файлы с заданными режимами, размерами буфера, кодировками и обработкой ошибок (подробнее см. функцию [`open()`](https://python-all.ru/3.4/library/functions.html#open)).13891390```python1391>>> parser = argparse.ArgumentParser()1392>>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))1393>>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8'))1394>>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])1395Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)1396```13971398Объекты FileType распознают псевдоаргумент `'-'` и автоматически преобразуют его в `sys.stdin` для читаемых объектов [`FileType`](https://python-all.ru/3.4/library/argparse.html#argparse.FileType) и в `sys.stdout` для записываемых объектов [`FileType`](https://python-all.ru/3.4/library/argparse.html#argparse.FileType).13991400```python1401>>> parser = argparse.ArgumentParser()1402>>> parser.add_argument('infile', type=argparse.FileType('r'))1403>>> parser.parse_args(['-'])1404Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)1405```14061407Новое в версии 3.4: Именованные аргументы *encodings* и *errors*.14081409### 16.4.5.3. Группы аргументов14101411#### `ArgumentParser.add_argument_group(title=None, description=None)`14121413По умолчанию [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) группирует аргументы командной строки на «позиционные аргументы» и «опциональные аргументы» при выводе справочных сообщений. Если есть более удачная логическая группировка, чем эта стандартная, можно создать подходящие группы с помощью метода [`add_argument_group()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument_group).14141415```python1416>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)1417>>> group = parser.add_argument_group('group')1418>>> group.add_argument('--foo', help='foo help')1419>>> group.add_argument('bar', help='bar help')1420>>> parser.print_help()1421usage: PROG [--foo FOO] bar14221423group:1424  bar    bar help1425  --foo FOO  foo help1426```14271428Метод [`add_argument_group()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument_group) возвращает объект группы аргументов, у которого есть метод [`add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument), как у обычного [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser). Когда аргумент добавляется в группу, синтаксический анализатор обрабатывает его как обычный аргумент, но при выводе справки показывает его в отдельной группе. Метод [`add_argument_group()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument_group) принимает аргументы *title* и *description*, с помощью которых можно настроить отображение.14291430```python1431>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)1432>>> group1 = parser.add_argument_group('group1', 'group1 description')1433>>> group1.add_argument('foo', help='foo help')1434>>> group2 = parser.add_argument_group('group2', 'group2 description')1435>>> group2.add_argument('--bar', help='bar help')1436>>> parser.print_help()1437usage: PROG [--bar BAR] foo14381439group1:1440  group1 description14411442  foo    foo help14431444group2:1445  group2 description14461447  --bar BAR  bar help1448```14491450Обратите внимание, что любые аргументы, не входящие в ваши пользовательские группы, окажутся обратно в обычных разделах «позиционные аргументы» и «опциональные аргументы».14511452### 16.4.5.4. Взаимное исключение14531454#### `ArgumentParser.add_mutually_exclusive_group(required=False)`14551456Создаёт взаимоисключающую группу. [`argparse`](https://python-all.ru/3.4/library/argparse.html#module-argparse) гарантирует, что в командной строке будет присутствовать только один из аргументов взаимоисключающей группы.14571458```python1459>>> parser = argparse.ArgumentParser(prog='PROG')1460>>> group = parser.add_mutually_exclusive_group()1461>>> group.add_argument('--foo', action='store_true')1462>>> group.add_argument('--bar', action='store_false')1463>>> parser.parse_args(['--foo'])1464Namespace(bar=True, foo=True)1465>>> parser.parse_args(['--bar'])1466Namespace(bar=False, foo=False)1467>>> parser.parse_args(['--foo', '--bar'])1468usage: PROG [-h] [--foo | --bar]1469PROG: error: argument --bar: not allowed with argument --foo1470```14711472Метод [`add_mutually_exclusive_group()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_mutually_exclusive_group) также принимает аргумент *required*, который указывает, что хотя бы один из взаимоисключающих аргументов обязателен.14731474```python1475>>> parser = argparse.ArgumentParser(prog='PROG')1476>>> group = parser.add_mutually_exclusive_group(required=True)1477>>> group.add_argument('--foo', action='store_true')1478>>> group.add_argument('--bar', action='store_false')1479>>> parser.parse_args([])1480usage: PROG [-h] (--foo | --bar)1481PROG: error: one of the arguments --foo --bar is required1482```14831484Обратите внимание, что взаимоисключающие группы аргументов в настоящее время не поддерживают аргументы *title* и *description* из метода [`add_argument_group()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument_group).14851486### 16.4.5.5. Значения по умолчанию анализатора14871488#### `ArgumentParser.set_defaults(**kwargs)`14891490В большинстве случаев атрибуты объекта, возвращаемого [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args), полностью определяются анализом аргументов командной строки и действий над аргументами. [`set_defaults()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.set_defaults) позволяет добавить дополнительные атрибуты, которые определяются без анализа командной строки.14911492```python1493>>> parser = argparse.ArgumentParser()1494>>> parser.add_argument('foo', type=int)1495>>> parser.set_defaults(bar=42, baz='badger')1496>>> parser.parse_args(['736'])1497Namespace(bar=42, baz='badger', foo=736)1498```14991500Обратите внимание: значения по умолчанию на уровне анализатора всегда переопределяют значения по умолчанию на уровне аргументов:15011502```python1503>>> parser = argparse.ArgumentParser()1504>>> parser.add_argument('--foo', default='bar')1505>>> parser.set_defaults(foo='spam')1506>>> parser.parse_args([])1507Namespace(foo='spam')1508```15091510Значения по умолчанию на уровне синтаксического анализатора особенно полезны при работе с несколькими анализаторами. Пример такого использования см. в методе [`add_subparsers()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_subparsers).15111512#### `ArgumentParser.get_default(dest)`15131514Возвращает значение по умолчанию для атрибута пространства имён, заданное либо методом [`add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument), либо методом [`set_defaults()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.set_defaults).15151516```python1517>>> parser = argparse.ArgumentParser()1518>>> parser.add_argument('--foo', default='badger')1519>>> parser.get_default('foo')1520'badger'1521```15221523### 16.4.5.6. Вывод справки15241525В большинстве типичных приложений [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args) берёт на себя форматирование и вывод сообщений об использовании и ошибках. Однако доступно несколько методов форматирования:15261527#### `ArgumentParser.print_usage(file=None)`15281529Выводит краткое описание того, как [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) должен вызываться в командной строке. Если *file* равно `None`, подразумевается [`sys.stdout`](https://python-all.ru/3.4/library/sys.html#sys.stdout).15301531#### `ArgumentParser.print_help(file=None)`15321533Выводит справочное сообщение, включая использование программы и информацию об аргументах, зарегистрированных в [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser). Если *file* равно `None`, подразумевается [`sys.stdout`](https://python-all.ru/3.4/library/sys.html#sys.stdout).15341535Существуют также варианты этих методов, которые просто возвращают строку вместо её вывода:15361537#### `ArgumentParser.format_usage()`15381539Возвращает строку, содержащую краткое описание того, как [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser) должен вызываться в командной строке.15401541#### `ArgumentParser.format_help()`15421543Возвращает строку, содержащую справочное сообщение, включая использование программы и информацию об аргументах, зарегистрированных в [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser).15441545### 16.4.5.7. Частичный разбор15461547#### `ArgumentParser.parse_known_args(args=None, namespace=None)`15481549Иногда скрипту нужно разобрать лишь часть аргументов командной строки, передавая оставшиеся другому скрипту или программе. В таких случаях может быть полезен метод [`parse_known_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_known_args). Он работает аналогично [`parse_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.parse_args), но не вызывает ошибку при наличии лишних аргументов. Вместо этого он возвращает кортеж из двух элементов: заполненное пространство имён и список оставшихся строк аргументов.15501551```python1552>>> parser = argparse.ArgumentParser()1553>>> parser.add_argument('--foo', action='store_true')1554>>> parser.add_argument('bar')1555>>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])1556(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])1557```15581559> **Предупреждение**1560>1561> Правила [*сопоставления по префиксу*](https://python-all.ru/3.4/library/argparse.html#prefix-matching) применяются к `parse_known_args()`. Синтаксический анализатор может использовать опцию, даже если она является лишь префиксом одной из известных опций, вместо того чтобы оставлять её в списке оставшихся аргументов.15621563### 16.4.5.8. Настройка разбора файлов15641565#### `ArgumentParser.convert_arg_line_to_args(arg_line)`15661567Аргументы, читаемые из файла (см. именованный аргумент *fromfile\_prefix\_chars* конструктора [`ArgumentParser`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser)), читаются по одному аргументу на строку. Метод [`convert_arg_line_to_args()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.convert_arg_line_to_args) можно переопределить для более сложного чтения.15681569Этот метод принимает один аргумент *arg\_line* – строку, прочитанную из файла аргументов. Он возвращает список аргументов, разобранных из этой строки. Метод вызывается по одному разу для каждой строки из файла аргументов, по порядку.15701571Полезный вариант переопределения этого метода – такой, который воспринимает каждое слово, разделённое пробелом, как отдельный аргумент.15721573```python1574def convert_arg_line_to_args(self, arg_line):1575    return arg_line.split()1576```15771578### 16.4.5.9. Методы выхода15791580#### `ArgumentParser.exit(status=0, message=None)`15811582Этот метод завершает программу, выходя с указанным *статус* и, если задан, выводит *сообщение* перед этим.15831584#### `ArgumentParser.error(message)`15851586Этот метод выводит сообщение об использовании, включая *message*, в стандартный поток ошибок и завершает программу с кодом возврата 2.15871588## 16.4.6. Обновление кода optparse15891590Originally, the [`argparse`](https://python-all.ru/3.4/library/argparse.html#module-argparse) module had attempted to maintain compatibility with [`optparse`](https://python-all.ru/3.4/library/optparse.html#module-optparse). However, [`optparse`](https://python-all.ru/3.4/library/optparse.html#module-optparse) was difficult to extend transparently, particularly with the changes required to support the new `nargs=` specifiers and better usage messages. When most everything in [`optparse`](https://python-all.ru/3.4/library/optparse.html#module-optparse) had either been copy-pasted over or monkey-patched, it no longer seemed practical to try to maintain the backwards compatibility.15911592Модуль [`argparse`](https://python-all.ru/3.4/library/argparse.html#module-argparse) улучшает стандартный модуль [`optparse`](https://python-all.ru/3.4/library/optparse.html#module-optparse) по ряду параметров, в том числе:15931594- Обработка позиционных аргументов.1595- Поддержка подкоманд.1596- Разрешение альтернативных префиксов параметров, например `+` и `/`.1597- Обработка аргументов в стиле «ноль или более» и «один или более».1598- Формирование более информативных сообщений об использовании.1599- Предоставляет гораздо более простой интерфейс для настраиваемых `type` и `action`.16001601Частичный путь обновления с [`optparse`](https://python-all.ru/3.4/library/optparse.html#module-optparse) на [`argparse`](https://python-all.ru/3.4/library/argparse.html#module-argparse):16021603- Замените все вызовы [`optparse.OptionParser.add_option()`](https://python-all.ru/3.4/library/optparse.html#optparse.OptionParser.add_option) на вызовы [`ArgumentParser.add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument).1604- Замените `(options, args) = parser.parse_args()` на `args = parser.parse_args()` и добавьте дополнительные вызовы [`ArgumentParser.add_argument()`](https://python-all.ru/3.4/library/argparse.html#argparse.ArgumentParser.add_argument) для позиционных аргументов. Учтите, что то, что ранее называлось `options`, теперь в контексте [`argparse`](https://python-all.ru/3.4/library/argparse.html#module-argparse) называется `args`.1605- Замените колбэк-действия и именованные аргументы `callback_*` на аргументы `type` или `action`.1606- Замените строковые имена для именованных аргументов `type` соответствующими объектами типов (например, int, float, complex и т.д.).1607- Замените `optparse.Values` на [`Namespace`](https://python-all.ru/3.4/library/argparse.html#argparse.Namespace), а `optparse.OptionError` и `optparse.OptionValueError` на `ArgumentError`.1608- Замените строки с неявными аргументами, такими как `%default` или `%prog`, на стандартный синтаксис Python с использованием словарей для форматирования строк, а именно `%(default)s` и `%(prog)s`.1609- Замените аргумент `version` конструктора OptionParser вызовом `parser.add_argument('--version', action='version', version='<the version>')`.1610