argparse.md
1> **Источник:** https://python-all.ru/3.15/library/argparse.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `argparse` – парсер для параметров командной строки, аргументов и подкоманд89Добавлено в версии 3.2.1011**Исходный код:** [Lib/argparse.py](https://python-all.ru/src/3.15/Lib/argparse.py)1213> **Примечание**14>15> Хотя `argparse` является рекомендуемым модулем стандартной библиотеки для реализации простых приложений командной строки, у авторов с более строгими требованиями к точному поведению их приложений командной строки может возникнуть ощущение, что он не обеспечивает необходимый уровень контроля. Обратитесь к [Выбор библиотеки для разбора аргументов](https://python-all.ru/3.15/library/optparse.html#choosing-an-argument-parser) для альтернатив, которые стоит рассмотреть, если `argparse` не поддерживает поведение, необходимое приложению (например, полное отключение поддержки перемешанных параметров и позиционных аргументов, или принятие значений параметров, начинающихся с `-`, даже если они соответствуют другому определённому параметру).1617---1819Учебное пособие2021На этой странице содержится справочная информация по API. Для более плавного введения в разбор командной строки Python обратитесь к [учебному пособию по argparse](https://python-all.ru/3.15/howto/argparse.html#argparse-tutorial).2223Модуль `argparse` упрощает создание удобных интерфейсов командной строки. Программа определяет, какие аргументы ей требуются, а `argparse` разбирается, как извлечь их из [`sys.argv`](https://python-all.ru/3.15/library/sys.html#sys.argv). Модуль `argparse` также автоматически генерирует сообщения справки и использования. Модуль также выводит ошибки, когда пользователи передают программе недопустимые аргументы.2425Поддержка интерфейсов командной строки модуля `argparse` построена вокруг экземпляра [`argparse.ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser). Он является контейнером для спецификаций аргументов и имеет параметры, которые применяются к парсеру в целом:2627```python28parser = argparse.ArgumentParser(29 prog='ProgramName',30 description='What the program does',31 epilog='Text at the bottom of help')32```3334Метод [`ArgumentParser.add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument) добавляет в парсер отдельные спецификации аргументов. Он поддерживает позиционные аргументы, опции, принимающие значения, и флаги вкл/выкл:3536```python37parser.add_argument('filename') # позиционный аргумент38parser.add_argument('-c', '--count') # опция, которая принимает значение39parser.add_argument('-v', '--verbose',40 action='store_true') # флаг вкл/выкл41```4243Метод [`ArgumentParser.parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args) запускает парсер и помещает извлечённые данные в объект [`argparse.Namespace`](https://python-all.ru/3.15/library/argparse.html#argparse.Namespace):4445```python46args = parser.parse_args()47print(args.filename, args.count, args.verbose)48```4950> **Примечание**51>52> Если вы ищете руководство по обновлению кода с [`optparse`](https://python-all.ru/3.15/library/optparse.html#module-optparse) на `argparse`, смотрите [Обновление кода Optparse](https://python-all.ru/3.15/howto/argparse-optparse.html#upgrading-optparse-code).5354## Объекты ArgumentParser5556#### `class argparse.ArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True, *, suggest_on_error=True, color=True)`5758Создаёт новый объект `ArgumentParser`. Все параметры должны передаваться как именованные аргументы. Каждый параметр имеет собственное подробное описание ниже, но вкратце они таковы:5960- [prog](https://python-all.ru/3.15/library/argparse.html#prog) - имя программы (по умолчанию генерируется из атрибутов модуля `__main__` и `sys.argv[0]`)61- [usage](https://python-all.ru/3.15/library/argparse.html#usage) - строка, описывающая использование программы (по умолчанию генерируется из аргументов, добавленных в парсер)62- [description](https://python-all.ru/3.15/library/argparse.html#description) - текст, отображаемый перед справкой по аргументам (по умолчанию отсутствует)63- [epilog](https://python-all.ru/3.15/library/argparse.html#epilog) - текст, отображаемый после справки по аргументам (по умолчанию отсутствует)64- [parents](https://python-all.ru/3.15/library/argparse.html#parents) - список объектов `ArgumentParser`, аргументы которых также должны быть включены65- [formatter\_class](https://python-all.ru/3.15/library/argparse.html#formatter-class) - класс для настройки вывода справки66- [prefix\_chars](https://python-all.ru/3.15/library/argparse.html#prefix-chars) - набор символов, которые являются префиксом необязательных аргументов (по умолчанию: ‘-‘)67- [fromfile\_prefix\_chars](https://python-all.ru/3.15/library/argparse.html#fromfile-prefix-chars) - набор символов, которые являются префиксом файлов, из которых должны читаться дополнительные аргументы (по умолчанию: `None`)68- [argument\_default](https://python-all.ru/3.15/library/argparse.html#argument-default) - глобальное значение по умолчанию для аргументов (по умолчанию: `None`)69- [conflict\_handler](https://python-all.ru/3.15/library/argparse.html#conflict-handler) - стратегия разрешения конфликтов необязательных аргументов (обычно не требуется)70- [add\_help](https://python-all.ru/3.15/library/argparse.html#add-help) - добавить опцию `-h/--help` в парсер (по умолчанию: `True`)71- [allow\_abbrev](https://python-all.ru/3.15/library/argparse.html#allow-abbrev) - разрешает сокращать длинные опции, если сокращение однозначно (по умолчанию: `True`)72- [exit\_on\_error](https://python-all.ru/3.15/library/argparse.html#exit-on-error) - определяет, завершает ли `ArgumentParser` работу с сообщением об ошибке при возникновении ошибки (по умолчанию: `True`)73- [suggest\_on\_error](https://python-all.ru/3.15/library/argparse.html#suggest-on-error) - включает предложения для неправильно введённых значений аргументов и имён подпарсеров (по умолчанию: `True`)74- [color](https://python-all.ru/3.15/library/argparse.html#color) - разрешает цветной вывод (по умолчанию: `True`)7576Изменено в версии 3.5: *allow\_abbrev* – добавлен параметр.7778Изменено в версии 3.8: В предыдущих версиях *allow\_abbrev* также отключал группировку коротких флагов, например `-vv` для обозначения `-v -v`.7980Изменено в версии 3.9: *exit\_on\_error* – добавлен параметр.8182Изменено в версии 3.14: *suggest\_on\_error* и *color* – добавлены параметры.8384Изменено в версии 3.15: *suggest\_on\_error* – значение по умолчанию изменено на `True`.8586В следующих разделах описывается, как используется каждый из этих параметров.8788### prog8990По умолчанию [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) вычисляет имя программы для отображения в справочных сообщениях в зависимости от того, как был запущен интерпретатор Python:9192- Имя [`base name`](https://python-all.ru/3.15/library/os.path.html#os.path.basename) `sys.argv[0]`, если в качестве аргумента был передан файл.93- Имя интерпретатора Python, за которым следует `sys.argv[0]`, если в качестве аргумента была передана директория или zip-файл.94- Имя интерпретатора Python, за которым следует `-m`, а затем имя модуля или пакета, если была использована опция [`-m`](https://python-all.ru/3.15/using/cmdline.html#cmdoption-m).9596Это поведение по умолчанию почти всегда желательно, поскольку оно делает сообщения справки соответствующими строке, которая использовалась для запуска программы в командной строке. Однако чтобы изменить это поведение, можно указать другое значение с помощью аргумента `prog=` для [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser):9798```python99>>> parser = argparse.ArgumentParser(prog='myprogram')100>>> parser.print_help()101usage: myprogram [-h]102103options:104 -h, --help show this help message and exit105```106107Обратите внимание, что имя программы, определённое из `sys.argv[0]`, из атрибутов модуля `__main__` или из аргумента `prog=`, доступно в сообщениях справки с помощью спецификатора формата `%(prog)s`.108109```python110>>> parser = argparse.ArgumentParser(prog='myprogram')111>>> parser.add_argument('--foo', help='foo of the %(prog)s program')112>>> parser.print_help()113usage: myprogram [-h] [--foo FOO]114115options:116 -h, --help show this help message and exit117 --foo FOO foo of the myprogram program118```119120Изменено в версии 3.14: Значение по умолчанию `prog` теперь отражает то, как на самом деле была выполнена `__main__`, а не всегда равно `os.path.basename(sys.argv[0])`.121122### использование123124По умолчанию [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) формирует сообщение об использовании из своих аргументов. Стандартное сообщение можно переопределить с помощью именованного аргумента `usage=`:125126```python127>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')128>>> parser.add_argument('--foo', nargs='?', help='foo help')129>>> parser.add_argument('bar', nargs='+', help='bar help')130>>> parser.print_help()131usage: PROG [options]132133positional arguments:134 bar bar help135136options:137 -h, --help show this help message and exit138 --foo [FOO] foo help139```140141Спецификатор формата `%(prog)s` используется для подстановки имени программы в сообщения об использовании.142143Если для главного парсера указывается собственное сообщение об использовании, возможно, стоит также передать аргумент `prog` в [`add_subparsers()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_subparsers) или аргументы `prog` и `usage` в [`add_parser()`](https://python-all.ru/3.15/library/argparse.html#argparse._SubParsersAction.add_parser), чтобы обеспечить единообразие префиксов команд и информации об использовании во всех подпарсерах.144145### описание146147Большинство вызовов конструктора [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) используют именованный аргумент `description=`. Этот аргумент задаёт краткое описание того, что делает программа и как она работает. В сообщениях справки описание отображается между строкой использования командной строки и справкой по различным аргументам.148149По умолчанию описание переносится по строкам, чтобы уместиться в отведённом пространстве. Чтобы изменить это поведение, обратитесь к аргументу [formatter\_class](https://python-all.ru/3.15/library/argparse.html#formatter-class).150151### эпилог152153Некоторые программы выводят дополнительное описание после описания аргументов. Такой текст можно указать с помощью аргумента `epilog=` для [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser):154155```python156>>> parser = argparse.ArgumentParser(157... description='A foo that bars',158... epilog="And that's how you'd foo a bar")159>>> parser.print_help()160usage: argparse.py [-h]161162A foo that bars163164options:165 -h, --help show this help message and exit166167And that's how you'd foo a bar168```169170Как и для аргумента [description](https://python-all.ru/3.15/library/argparse.html#description), текст `epilog=` по умолчанию переносится по строкам, но это поведение можно настроить с помощью аргумента [formatter\_class](https://python-all.ru/3.15/library/argparse.html#formatter-class) для [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser).171172### родительские парсеры173174Иногда несколько парсеров используют общий набор аргументов. Вместо того чтобы повторять определения этих аргументов, можно использовать один парсер со всеми общими аргументами, передав его в аргумент `parents=` для [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser). Аргумент `parents=` принимает список объектов `ArgumentParser`, собирает из них все позиционные и опциональные действия и добавляет эти действия в создаваемый объект `ArgumentParser`:175176```python177>>> parent_parser = argparse.ArgumentParser(add_help=False)178>>> parent_parser.add_argument('--parent', type=int)179180>>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])181>>> foo_parser.add_argument('foo')182>>> foo_parser.parse_args(['--parent', '2', 'XXX'])183Namespace(foo='XXX', parent=2)184185>>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])186>>> bar_parser.add_argument('--bar')187>>> bar_parser.parse_args(['--bar', 'YYY'])188Namespace(bar='YYY', parent=None)189```190191Обратите внимание, что большинство родительских парсеров указывают `add_help=False`. В противном случае [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) увидит две опции `-h/--help` (одну в родительском парсере, другую – в дочернем) и вызовет ошибку.192193> **Примечание**194>195> Парсеры должны быть полностью инициализированы перед передачей через `parents=`. Если изменить родительские парсеры после создания дочернего, эти изменения не отразятся на дочернем парсере.196197### класс форматирования198199Объекты [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) позволяют настраивать форматирование справки, указывая альтернативный класс форматирования. На данный момент существует четыре таких класса:200201#### `class argparse.RawDescriptionHelpFormatter`202203#### `class argparse.RawTextHelpFormatter`204205#### `class argparse.ArgumentDefaultsHelpFormatter`206207#### `class argparse.MetavarTypeHelpFormatter`208209[`RawDescriptionHelpFormatter`](https://python-all.ru/3.15/library/argparse.html#argparse.RawDescriptionHelpFormatter) и [`RawTextHelpFormatter`](https://python-all.ru/3.15/library/argparse.html#argparse.RawTextHelpFormatter) дают больше контроля над отображением текстовых описаний. По умолчанию объекты [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) переносят текст [description](https://python-all.ru/3.15/library/argparse.html#description) и [epilog](https://python-all.ru/3.15/library/argparse.html#epilog) в сообщениях справки командной строки:210211```python212>>> parser = argparse.ArgumentParser(213... prog='PROG',214... description='''this description215... was indented weird216... but that is okay''',217... epilog='''218... likewise for this epilog whose whitespace will219... be cleaned up and whose words will be wrapped220... across a couple lines''')221>>> parser.print_help()222usage: PROG [-h]223224this description was indented weird but that is okay225226options:227 -h, --help show this help message and exit228229likewise for this epilog whose whitespace will be cleaned up and whose words230will be wrapped across a couple lines231```232233Передача [`RawDescriptionHelpFormatter`](https://python-all.ru/3.15/library/argparse.html#argparse.RawDescriptionHelpFormatter) в качестве `formatter_class=` означает, что [description](https://python-all.ru/3.15/library/argparse.html#description) и [epilog](https://python-all.ru/3.15/library/argparse.html#epilog) уже правильно отформатированы и не должны переноситься по строкам:234235```python236>>> parser = argparse.ArgumentParser(237... prog='PROG',238... formatter_class=argparse.RawDescriptionHelpFormatter,239... description=textwrap.dedent('''\240... Please do not mess up this text!241... --------------------------------242... I have indented it243... exactly the way244... I want it245... '''))246>>> parser.print_help()247usage: PROG [-h]248249Please do not mess up this text!250--------------------------------251 I have indented it252 exactly the way253 I want it254255options:256 -h, --help show this help message and exit257```258259[`RawTextHelpFormatter`](https://python-all.ru/3.15/library/argparse.html#argparse.RawTextHelpFormatter) сохраняет пробельные символы для всех видов текста справки, включая описания аргументов. Однако несколько символов новой строки заменяются на один. Если нужно сохранить несколько пустых строк, добавьте пробелы между ними.260261[`ArgumentDefaultsHelpFormatter`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentDefaultsHelpFormatter) автоматически добавляет информацию о значениях по умолчанию в сообщения справки каждого аргумента:262263```python264>>> parser = argparse.ArgumentParser(265... prog='PROG',266... formatter_class=argparse.ArgumentDefaultsHelpFormatter)267>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')268>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')269>>> parser.print_help()270usage: PROG [-h] [--foo FOO] [bar ...]271272positional arguments:273 bar BAR! (default: [1, 2, 3])274275options:276 -h, --help show this help message and exit277 --foo FOO FOO! (default: 42)278```279280[`MetavarTypeHelpFormatter`](https://python-all.ru/3.15/library/argparse.html#argparse.MetavarTypeHelpFormatter) использует имя аргумента [type](https://python-all.ru/3.15/library/argparse.html#type) для каждого аргумента в качестве отображаемого имени для его значений (вместо [dest](https://python-all.ru/3.15/library/argparse.html#dest), как это делает обычный форматировщик):281282```python283>>> parser = argparse.ArgumentParser(284... prog='PROG',285... formatter_class=argparse.MetavarTypeHelpFormatter)286>>> parser.add_argument('--foo', type=int)287>>> parser.add_argument('bar', type=float)288>>> parser.print_help()289usage: PROG [-h] [--foo int] float290291positional arguments:292 float293294options:295 -h, --help show this help message and exit296 --foo int297```298299### символы префикса300301Большинство опций командной строки используют `-` в качестве префикса, например `-f/--foo`. Парсеры, которым нужно поддерживать другие или дополнительные символы префикса, например для опций вроде `+f` или `/foo`, могут указать их с помощью аргумента `prefix_chars=` конструктора [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser):302303```python304>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')305>>> parser.add_argument('+f')306>>> parser.add_argument('++bar')307>>> parser.parse_args('+f X ++bar Y'.split())308Namespace(bar='Y', f='X')309```310311Аргумент `prefix_chars=` по умолчанию равен `'-'`. Если указать набор символов, не включающий `-`, то опции `-f/--foo` будут запрещены.312313### символы префикса из файла314315Иногда при работе с особенно длинным списком аргументов может иметь смысл хранить список аргументов в файле, а не набирать его в командной строке. Если аргумент `fromfile_prefix_chars=` передан конструктору [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser), то аргументы, начинающиеся с любого из указанных символов, будут рассматриваться как файлы и заменяться на содержащиеся в них аргументы. Например:316317```python318>>> with open('args.txt', 'w', encoding=sys.getfilesystemencoding()) as fp:319... fp.write('-f\nbar')320...321>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')322>>> parser.add_argument('-f')323>>> parser.parse_args(['-f', 'foo', '@args.txt'])324Namespace(f='bar')325```326327По умолчанию аргументы из файла должны быть по одному на строку (но см. также [`convert_arg_line_to_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.convert_arg_line_to_args)) и обрабатываются так, как если бы они находились на том же месте, что и исходный аргумент, ссылающийся на файл в командной строке. Таким образом, в примере выше выражение `['-f', 'foo', '@args.txt']` считается эквивалентным выражению `['-f', 'foo', '-f', 'bar']`.328329> **Примечание**330>331> Каждая строка рассматривается как отдельный аргумент, поэтому пустая строка читается как пустая строка (`''`).332333[`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) использует [кодировку и обработчик ошибок файловой системы](https://python-all.ru/3.15/glossary.html#term-filesystem-encoding-and-error-handler) для чтения файла, содержащего аргументы.334335Аргумент `fromfile_prefix_chars=` по умолчанию равен `None`, что означает, что аргументы никогда не будут рассматриваться как ссылки на файлы.336337Изменено в версии 3.12: [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) изменил кодировку и обработку ошибок при чтении файлов аргументов с используемых по умолчанию (например, [`locale.getpreferredencoding(False)`](https://python-all.ru/3.15/library/locale.html#locale.getpreferredencoding) и `"strict"`) на [кодировку и обработчик ошибок файловой системы](https://python-all.ru/3.15/glossary.html#term-filesystem-encoding-and-error-handler). Файлы аргументов должны быть закодированы в UTF-8 вместо кодовой страницы ANSI в Windows.338339### argument\_default340341Обычно значения аргументов по умолчанию задаются либо передачей значения по умолчанию в [`add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument), либо вызовом методов [`set_defaults()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.set_defaults) с определённым набором пар имя-значение. Однако иногда может быть полезно указать единое значение по умолчанию для всех аргументов синтаксического анализатора. Это можно сделать, передав именованный аргумент `argument_default=` в [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser). Например, чтобы глобально отключить создание атрибутов при вызовах [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args), укажите `argument_default=SUPPRESS`:342343```python344>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)345>>> parser.add_argument('--foo')346>>> parser.add_argument('bar', nargs='?')347>>> parser.parse_args(['--foo', '1', 'BAR'])348Namespace(bar='BAR', foo='1')349>>> parser.parse_args([])350Namespace()351```352353### allow\_abbrev354355Обычно при передаче списка аргументов методу [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args) объекта [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) он [распознаёт сокращения](https://python-all.ru/3.15/library/argparse.html#prefix-matching) длинных опций.356357Эту возможность можно отключить, установив `allow_abbrev` в `False`:358359```python360>>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)361>>> parser.add_argument('--foobar', action='store_true')362>>> parser.add_argument('--foonley', action='store_false')363>>> parser.parse_args(['--foon'])364usage: PROG [-h] [--foobar] [--foonley]365PROG: error: unrecognized arguments: --foon366```367368Добавлено в версии 3.5.369370### conflict\_handler371372Объекты [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) не допускают два действия с одной и той же строкой опции. По умолчанию объекты `ArgumentParser` вызывают исключение при попытке создать аргумент со строкой опции, которая уже используется:373374```python375>>> parser = argparse.ArgumentParser(prog='PROG')376>>> parser.add_argument('-f', '--foo', help='old foo help')377>>> parser.add_argument('--foo', help='new foo help')378Traceback (most recent call last):379 ..380ArgumentError: argument --foo: conflicting option string(s): --foo381```382383Иногда (например, при использовании [parents](https://python-all.ru/3.15/library/argparse.html#parents)) бывает полезно просто переопределить все старые аргументы с той же строкой опции. Для получения такого поведения значение `'resolve'` можно передать в аргумент `conflict_handler=` функции [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser):384385```python386>>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')387>>> parser.add_argument('-f', '--foo', help='old foo help')388>>> parser.add_argument('--foo', help='new foo help')389>>> parser.print_help()390usage: PROG [-h] [-f FOO] [--foo FOO]391392options:393 -h, --help show this help message and exit394 -f FOO old foo help395 --foo FOO new foo help396```397398Обратите внимание, что объекты [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) удаляют действие только в том случае, если все его строки опций переопределены. Поэтому в приведённом выше примере старое действие `-f/--foo` сохраняется как действие `-f`, поскольку была переопределена только строка опции `--foo`.399400### add\_help401402По умолчанию объекты [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) добавляют опцию, которая просто отображает справочное сообщение синтаксического анализатора. Если в командной строке указано `-h` или `--help`, будет выведена справка `ArgumentParser`.403404Иногда может быть полезно отключить добавление этой опции справки. Это можно сделать, передав `False` в качестве аргумента `add_help=` функции [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser):405406```python407>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)408>>> parser.add_argument('--foo', help='foo help')409>>> parser.print_help()410usage: PROG [--foo FOO]411412options:413 --foo FOO foo help414```415416Обычно опция справки – это `-h/--help`. Исключение составляет случай, когда указан `prefix_chars=` и не включает `-`; в этом случае `-h` и `--help` не являются допустимыми опциями. В таком случае первый символ в `prefix_chars` используется в качестве префикса для опций справки:417418```python419>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')420>>> parser.print_help()421usage: PROG [+h]422423options:424 +h, ++help show this help message and exit425```426427### exit\_on\_error428429Обычно при передаче недопустимого списка аргументов методу [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args) объекта [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) он выводит *сообщение* в [`sys.stderr`](https://python-all.ru/3.15/library/sys.html#sys.stderr) и завершает работу с кодом возврата 2.430431Если требуется перехватывать ошибки вручную, эту возможность можно включить, установив `exit_on_error` в `False`:432433```python434>>> parser = argparse.ArgumentParser(exit_on_error=False)435>>> parser.add_argument('--integers', type=int)436_StoreAction(option_strings=['--integers'], dest='integers', nargs=None, const=None, default=None, type=<class 'int'>, choices=None, help=None, metavar=None)437>>> try:438... parser.parse_args('--integers a'.split())439... except argparse.ArgumentError:440... print('Catching an argumentError')441...442Catching an argumentError443```444445Добавлено в версии 3.9.446447### suggest\_on\_error448449По умолчанию, когда пользователь передаёт недопустимый вариант аргумента или имя подсинтаксического анализатора, [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) завершает работу с сообщением об ошибке и предлагает варианты для ошибочно набранных аргументов. В сообщении об ошибке будут перечислены допустимые варианты аргументов (если они указаны) или имена подсинтаксических анализаторов, а также предложение «возможно, вы имели в виду» при обнаружении близкого совпадения. Обратите внимание, что это применимо только для аргументов, для которых в качестве вариантов указаны строки:450451```python452>>> parser = argparse.ArgumentParser(suggest_on_error=True)453>>> parser.add_argument('--action', choices=['debug', 'dryrun'])454>>> parser.parse_args(['--action', 'debugg'])455usage: tester.py [-h] [--action {debug,dryrun}]456tester.py: error: argument --action: invalid choice: 'debugg', maybe you meant 'debug'? (choose from debug, dryrun)457```458459Подсказки можно отключить, установив `suggest_on_error` в `False`.460461Добавлено в версии 3.14.462463Изменено в версии 3.15: Изменено значение по умолчанию `suggest_on_error` с `False` на `True`.464465### color466467По умолчанию справочное сообщение выводится в цвете с использованием [ANSI escape-последовательностей](https://python-all.ru/3.15/library/argparse.html). Если нужны неформатированные текстовые справки, можно отключить это [в локальном окружении](https://python-all.ru/3.15/using/cmdline.html#using-on-controlling-color) или в самом синтаксическом анализаторе, установив `color` в `False`:468469```python470>>> parser = argparse.ArgumentParser(description='Process some integers.',471... color=False)472>>> parser.add_argument('--action', choices=['sum', 'max'])473>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',474... help='an integer for the accumulator')475>>> parser.parse_args(['--help'])476```477478Обратите внимание, что когда `color=True`, цветной вывод зависит как от переменных окружения, так и от возможностей терминала. Однако если `color=False`, цветной вывод всегда отключён, даже если установлены такие переменные окружения, как `FORCE_COLOR`.479480Добавлено в версии 3.14.481482Чтобы выделить встроенный код в описании, эпилоге или тексте аргумента `help`, можно использовать одинарные или двойные обратные кавычки:483484```python485>>> parser = argparse.ArgumentParser(486... formatter_class=argparse.RawDescriptionHelpFormatter,487... description='Run ``python -m myapp`` to start.',488... epilog='''Examples:489... `python -m myapp --verbose`490... ``python -m myapp --config settings.json``491... ''')492>>> parser.add_argument('--foo', help='set the `foo` value')493```494495Если цвета включены, текст внутри обратных кавычек отображается отдельным цветом, чтобы примеры лучше выделялись. Если цвета отключены, обратные кавычки сохраняются как есть, что читаемо в обычном тексте.496497Добавлено в версии 3.15.498499## Метод add\_argument()500501#### `ArgumentParser.add_argument(name or flags..., *[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest][, deprecated])`502503Определяет, как должен разбираться один аргумент командной строки. Каждый параметр подробно описан ниже, а кратко они таковы:504505- [name or flags](https://python-all.ru/3.15/library/argparse.html#name-or-flags) – имя или список строк параметров, например `'foo'` или `'-f', '--foo'`.506- [action](https://python-all.ru/3.15/library/argparse.html#action) – базовый тип действия, которое выполняется при встрече этого аргумента в командной строке.507- [nargs](https://python-all.ru/3.15/library/argparse.html#nargs) – количество аргументов командной строки, которое должно быть потреблено.508- [const](https://python-all.ru/3.15/library/argparse.html#const) – постоянное значение, требуемое некоторыми значениями [action](https://python-all.ru/3.15/library/argparse.html#action) и [nargs](https://python-all.ru/3.15/library/argparse.html#nargs).509- [default](https://python-all.ru/3.15/library/argparse.html#default) – значение, которое используется, если аргумент отсутствует в командной строке и в объекте namespace.510- [type](https://python-all.ru/3.15/library/argparse.html#type) – тип, в который следует преобразовать аргумент командной строки.511- [choices](https://python-all.ru/3.15/library/argparse.html#choices) – последовательность допустимых значений для аргумента.512- [required](https://python-all.ru/3.15/library/argparse.html#required) – может ли параметр командной строки быть опущен (только для опциональных параметров).513- [help](https://python-all.ru/3.15/library/argparse.html#help) – краткое описание того, что делает аргумент.514- [metavar](https://python-all.ru/3.15/library/argparse.html#metavar) – имя аргумента в сообщениях об использовании.515- [dest](https://python-all.ru/3.15/library/argparse.html#dest) – имя атрибута, добавляемого в объект, возвращаемый [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args).516- [deprecated](https://python-all.ru/3.15/library/argparse.html#deprecated) – указывает, устарел ли аргумент.517518Метод возвращает объект [`Action`](https://python-all.ru/3.15/library/argparse.html#argparse.Action), представляющий аргумент.519520В следующих разделах описывается, как используется каждый из этих параметров.521522### name or flags523524Методу [`add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument) необходимо знать, ожидается ли опциональный аргумент (например, `-f` или `--foo`) или позиционный (например, список имён файлов). Поэтому первыми аргументами, передаваемыми в `add_argument()`, должны быть либо серия флагов, либо просто имя аргумента.525526Например, опциональный аргумент можно создать так:527528```python529>>> parser.add_argument('-f', '--foo')530```531532а позиционный – так:533534```python535>>> parser.add_argument('bar')536```537538При вызове [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args) опциональные аргументы опознаются по префиксу `-`, а остальные аргументы считаются позиционными:539540```python541>>> parser = argparse.ArgumentParser(prog='PROG')542>>> parser.add_argument('-f', '--foo')543>>> parser.add_argument('bar')544>>> parser.parse_args(['BAR'])545Namespace(bar='BAR', foo=None)546>>> parser.parse_args(['BAR', '--foo', 'FOO'])547Namespace(bar='BAR', foo='FOO')548>>> parser.parse_args(['--foo', 'FOO'])549usage: PROG [-h] [-f FOO] bar550PROG: error: the following arguments are required: bar551```552553По умолчанию `argparse` автоматически управляет внутренними и отображаемыми именами аргументов, упрощая процесс без необходимости дополнительной настройки. Таким образом, не требуется указывать параметры [dest](https://python-all.ru/3.15/library/argparse.html#dest) и [metavar](https://python-all.ru/3.15/library/argparse.html#metavar). Для опциональных аргументов [dest](https://python-all.ru/3.15/library/argparse.html#dest) по умолчанию равен имени аргумента, причём символы подчёркивания `_` заменяют дефисы `-`. Параметр [metavar](https://python-all.ru/3.15/library/argparse.html#metavar) по умолчанию равен имени в верхнем регистре. Например:554555```python556>>> parser = argparse.ArgumentParser(prog='PROG')557>>> parser.add_argument('--foo-bar')558>>> parser.parse_args(['--foo-bar', 'FOO-BAR'])559Namespace(foo_bar='FOO-BAR')560>>> parser.print_help()561usage: [-h] [--foo-bar FOO-BAR]562563optional arguments:564 -h, --help show this help message and exit565 --foo-bar FOO-BAR566```567568### action569570Объекты [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) связывают аргументы командной строки с действиями. Эти действия могут делать с аргументами практически что угодно, но чаще всего они просто добавляют атрибут в объект, возвращаемый [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args). Ключевой аргумент `action` определяет, как следует обрабатывать аргументы командной строки. Доступны следующие действия:571572- `'store'` – просто сохраняет значение аргумента. Это действие по умолчанию.573- `'store_const'` – сохраняет значение, указанное ключевым аргументом [const](https://python-all.ru/3.15/library/argparse.html#const); обратите внимание, что ключевой аргумент [const](https://python-all.ru/3.15/library/argparse.html#const) по умолчанию равен `None`. Действие `'store_const'` чаще всего используется с опциональными аргументами, задающими какой-либо флаг. Например:574575 ```python576 >>> parser = argparse.ArgumentParser()577 >>> parser.add_argument('--foo', action='store_const', const=42)578 >>> parser.parse_args(['--foo'])579 Namespace(foo=42)580 ```581- `'store_true'` и `'store_false'` – частные случаи `'store_const'`, которые сохраняют значения `True` и `False` соответственно, со значениями по умолчанию `False` и `True`:582583 ```python584 >>> parser = argparse.ArgumentParser()585 >>> parser.add_argument('--foo', action='store_true')586 >>> parser.add_argument('--bar', action='store_false')587 >>> parser.add_argument('--baz', action='store_false')588 >>> parser.parse_args('--foo --bar'.split())589 Namespace(foo=True, bar=False, baz=True)590 ```591- `'append'` – добавляет каждое значение аргумента в список. Удобно, когда параметр можно указать несколько раз. Если значением по умолчанию является непустой список, разобранное значение будет начинаться с элементов этого списка, а все значения из командной строки будут добавлены после них. Пример использования:592593 ```python594 >>> parser = argparse.ArgumentParser()595 >>> parser.add_argument('--foo', action='append', default=['0'])596 >>> parser.parse_args('--foo 1 --foo 2'.split())597 Namespace(foo=['0', '1', '2'])598 ```599- `'append_const'` – добавляет значение, указанное ключевым аргументом [const](https://python-all.ru/3.15/library/argparse.html#const), в список; обратите внимание, что [const](https://python-all.ru/3.15/library/argparse.html#const) по умолчанию равно `None`. Действие `'append_const'` обычно полезно, когда несколько аргументов должны сохранять константы в один и тот же список. Например:600601 ```python602 >>> parser = argparse.ArgumentParser()603 >>> parser.add_argument('--str', dest='types', action='append_const', const=str)604 >>> parser.add_argument('--int', dest='types', action='append_const', const=int)605 >>> parser.parse_args('--str --int'.split())606 Namespace(types=[<class 'str'>, <class 'int'>])607 ```608- `'extend'` – добавляет каждый элемент многозначного аргумента в список. Действие `'extend'` обычно используется с ключевым аргументом [nargs](https://python-all.ru/3.15/library/argparse.html#nargs), имеющим значение `'+'` или `'*'`. Обратите внимание: если [nargs](https://python-all.ru/3.15/library/argparse.html#nargs) равно `None` (по умолчанию) или `'?'`, каждый символ строки аргумента будет добавлен в список. Пример использования:609610 ```python611 >>> parser = argparse.ArgumentParser()612 >>> parser.add_argument("--foo", action="extend", nargs="+", type=str)613 >>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])614 Namespace(foo=['f1', 'f2', 'f3', 'f4'])615 ```616617 Добавлено в версии 3.8.618- `'count'` – подсчитывает, сколько раз встречается аргумент. Например, это удобно для увеличения уровня подробности вывода:619620 ```python621 >>> parser = argparse.ArgumentParser()622 >>> parser.add_argument('--verbose', '-v', action='count', default=0)623 >>> parser.parse_args(['-vvv'])624 Namespace(verbose=3)625 ```626627 Обратите внимание: значение *default* будет `None`, если только оно явно не установлено в *0*.628- `'help'` – выводит полное справочное сообщение для всех параметров текущего анализатора и завершает работу. По умолчанию действие справки автоматически добавляется в анализатор. Подробности о том, как формируется вывод, см. в [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser).629- `'version'` – ожидает именованный аргумент `version=` в вызове [`add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument) и при вызове выводит информацию о версии и завершает работу:630631 ```python632 >>> import argparse633 >>> parser = argparse.ArgumentParser(prog='PROG')634 >>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')635 >>> parser.parse_args(['--version'])636 PROG 2.0637 ```638639Можно также указать произвольное действие, передав подкласс [`Action`](https://python-all.ru/3.15/library/argparse.html#argparse.Action) (например, [`BooleanOptionalAction`](https://python-all.ru/3.15/library/argparse.html#argparse.BooleanOptionalAction)) или другой объект, реализующий тот же интерфейс. Только действия, которые потребляют аргументы командной строки (например, `'store'`, `'append'`, `'extend'` или пользовательские действия с ненулевым `nargs`), могут использоваться с позиционными аргументами.640641Рекомендуемый способ создания пользовательского действия – расширить [`Action`](https://python-all.ru/3.15/library/argparse.html#argparse.Action), переопределив метод `__call__()` и, при необходимости, методы `__init__()` и `format_usage()`. Также можно зарегистрировать пользовательские действия с помощью метода [`register()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.register) и ссылаться на них по зарегистрированному имени.642643Пример пользовательского действия:644645```python646>>> class FooAction(argparse.Action):647... def __init__(self, option_strings, dest, nargs=None, **kwargs):648... if nargs is not None:649... raise ValueError("nargs not allowed")650... super().__init__(option_strings, dest, **kwargs)651... def __call__(self, parser, namespace, values, option_string=None):652... print('%r %r %r' % (namespace, values, option_string))653... setattr(namespace, self.dest, values)654...655>>> parser = argparse.ArgumentParser()656>>> parser.add_argument('--foo', action=FooAction)657>>> parser.add_argument('bar', action=FooAction)658>>> args = parser.parse_args('1 --foo 2'.split())659Namespace(bar=None, foo=None) '1' None660Namespace(bar='1', foo=None) '2' '--foo'661>>> args662Namespace(bar='1', foo='2')663```664665Подробнее см. в [`Action`](https://python-all.ru/3.15/library/argparse.html#argparse.Action).666667### nargs668669Объекты [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) обычно связывают один аргумент командной строки с одним выполняемым действием. Именованный аргумент `nargs` связывает другое количество аргументов командной строки с одним действием. См. также [Указание неоднозначных аргументов](https://python-all.ru/3.15/howto/argparse.html#specifying-ambiguous-arguments). Поддерживаемые значения:670671- `N` (целое число). Аргументы `N` из командной строки будут собраны в список. Например:672673 ```python674 >>> parser = argparse.ArgumentParser()675 >>> parser.add_argument('--foo', nargs=2)676 >>> parser.add_argument('bar', nargs=1)677 >>> parser.parse_args('c --foo a b'.split())678 Namespace(bar=['c'], foo=['a', 'b'])679 ```680681 Обратите внимание, что `nargs=1` создаёт список из одного элемента. Это отличается от поведения по умолчанию, при котором элемент создаётся сам по себе.682683- `'?'`. Если возможно, будет потреблён один аргумент командной строки и выдан как отдельный элемент. Если аргумент командной строки отсутствует, будет выдано значение из [default](https://python-all.ru/3.15/library/argparse.html#default). Обратите внимание, что для необязательных аргументов есть дополнительный случай: строка параметра присутствует, но за ней не следует аргумент командной строки. В этом случае будет выдано значение из [const](https://python-all.ru/3.15/library/argparse.html#const). Некоторые примеры для иллюстрации:684685 ```python686 >>> parser = argparse.ArgumentParser()687 >>> parser.add_argument('--foo', nargs='?', const='c', default='d')688 >>> parser.add_argument('bar', nargs='?', default='d')689 >>> parser.parse_args(['XX', '--foo', 'YY'])690 Namespace(bar='XX', foo='YY')691 >>> parser.parse_args(['XX', '--foo'])692 Namespace(bar='XX', foo='c')693 >>> parser.parse_args([])694 Namespace(bar='d', foo='d')695 ```696697 Одно из наиболее распространённых применений `nargs='?'` – разрешение необязательных входных и выходных файлов:698699 ```python700 >>> parser = argparse.ArgumentParser()701 >>> parser.add_argument('infile', nargs='?')702 >>> parser.add_argument('outfile', nargs='?')703 >>> parser.parse_args(['input.txt', 'output.txt'])704 Namespace(infile='input.txt', outfile='output.txt')705 >>> parser.parse_args(['input.txt'])706 Namespace(infile='input.txt', outfile=None)707 >>> parser.parse_args([])708 Namespace(infile=None, outfile=None)709 ```710711- `'*'`. Все присутствующие аргументы командной строки собираются в список. Обратите внимание, что обычно не имеет смысла указывать более одного позиционного аргумента с `nargs='*'`, но возможно несколько необязательных аргументов с `nargs='*'`. Например:712713 ```python714 >>> parser = argparse.ArgumentParser()715 >>> parser.add_argument('--foo', nargs='*')716 >>> parser.add_argument('--bar', nargs='*')717 >>> parser.add_argument('baz', nargs='*')718 >>> parser.parse_args('a b --foo x y --bar 1 2'.split())719 Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])720 ```721722- `'+'`. Как и `'*'`, все присутствующие аргументы командной строки собираются в список. Дополнительно будет сгенерировано сообщение об ошибке, если не было хотя бы одного аргумента командной строки. Например:723724 ```python725 >>> parser = argparse.ArgumentParser(prog='PROG')726 >>> parser.add_argument('foo', nargs='+')727 >>> parser.parse_args(['a', 'b'])728 Namespace(foo=['a', 'b'])729 >>> parser.parse_args([])730 usage: PROG [-h] foo [foo ...]731 PROG: error: the following arguments are required: foo732 ```733734Если именованный аргумент `nargs` не указан, количество потребляемых аргументов определяется действием [action](https://python-all.ru/3.15/library/argparse.html#action). Обычно это означает, что будет потреблён один аргумент командной строки и выдан один элемент (не список). Действия, которые не потребляют аргументы командной строки (например, `'store_const'`), устанавливают `nargs=0`.735736### const737738Аргумент `const` функции [`add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument) используется для хранения постоянных значений, которые не считываются из командной строки, но требуются для различных действий [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser). Два наиболее распространённых его применения:739740- Когда [`add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument) вызывается с `action='store_const'` или `action='append_const'`. Эти действия добавляют значение `const` к одному из атрибутов объекта, возвращаемого [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args). Примеры см. в описании [action](https://python-all.ru/3.15/library/argparse.html#action). Если `const` не передан в `add_argument()`, он получит значение по умолчанию `None`.741- Когда [`add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument) вызывается со строками параметров (например, `-f` или `--foo`) и `nargs='?'`. Это создаёт необязательный аргумент, за которым может следовать ноль или один аргумент командной строки. При разборе командной строки, если встречена строка параметра без следующего за ней аргумента командной строки, будет использовано значение из `const`. Примеры см. в описании [nargs](https://python-all.ru/3.15/library/argparse.html#nargs).742743Изменено в версии 3.11: `const=None` по умолчанию, в том числе когда `action='append_const'` или `action='store_const'`.744745### default746747Все необязательные аргументы и некоторые позиционные аргументы могут быть опущены в командной строке. Именованный аргумент `default` функции [`add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument), значение которого по умолчанию равно `None`, указывает, какое значение следует использовать, если аргумент командной строки отсутствует. Для необязательных аргументов значение `default` используется, когда строка параметра отсутствовала в командной строке:748749```python750>>> parser = argparse.ArgumentParser()751>>> parser.add_argument('--foo', default=42)752>>> parser.parse_args(['--foo', '2'])753Namespace(foo='2')754>>> parser.parse_args([])755Namespace(foo=42)756```757758Если в целевом пространстве имён уже установлен атрибут, действие *default* не перезапишет его:759760```python761>>> parser = argparse.ArgumentParser()762>>> parser.add_argument('--foo', default=42)763>>> parser.parse_args([], namespace=argparse.Namespace(foo=101))764Namespace(foo=101)765```766767Если значение `default` является строкой, анализатор разбирает его так, как если бы это был аргумент командной строки. В частности, анализатор применяет любой аргумент преобразования [type](https://python-all.ru/3.15/library/argparse.html#type), если он указан, перед установкой атрибута в возвращаемом значении [`Namespace`](https://python-all.ru/3.15/library/argparse.html#argparse.Namespace). В противном случае анализатор использует значение как есть:768769```python770>>> parser = argparse.ArgumentParser()771>>> parser.add_argument('--length', default='10', type=int)772>>> parser.add_argument('--width', default=10.5, type=int)773>>> parser.parse_args()774Namespace(length=10, width=10.5)775```776777Для позиционных аргументов с [nargs](https://python-all.ru/3.15/library/argparse.html#nargs), равным `?` или `*`, значение `default` используется, когда аргумент командной строки отсутствовал:778779```python780>>> parser = argparse.ArgumentParser()781>>> parser.add_argument('foo', nargs='?', default=42)782>>> parser.parse_args(['a'])783Namespace(foo='a')784>>> parser.parse_args([])785Namespace(foo=42)786```787788Поскольку `nargs='*'` собирает все предоставленные значения в список, отсутствующий позиционный аргумент даёт пустой список (`[]`). Только значение *default*, не равное `None`, переопределяет это (поэтому `default=None` по-прежнему даёт `[]`).789790Для аргументов [required](https://python-all.ru/3.15/library/argparse.html#required) значение `default` игнорируется. Например, это относится к позиционным аргументам со значениями [nargs](https://python-all.ru/3.15/library/argparse.html#nargs), отличными от `?` или `*`, или к необязательным аргументам, помеченным как `required=True`.791792Указание `default=argparse.SUPPRESS` приводит к тому, что атрибут не добавляется, если аргумент командной строки отсутствовал:793794```python795>>> parser = argparse.ArgumentParser()796>>> parser.add_argument('--foo', default=argparse.SUPPRESS)797>>> parser.parse_args([])798Namespace()799>>> parser.parse_args(['--foo', '1'])800Namespace(foo='1')801```802803### тип804805По умолчанию анализатор считывает аргументы командной строки как простые строки. Однако довольно часто строку командной строки следует интерпретировать как другой тип, например [`float`](https://python-all.ru/3.15/library/functions.html#float) или [`int`](https://python-all.ru/3.15/library/functions.html#int). Именованный аргумент `type` функции [`add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument) позволяет выполнять любые необходимые проверки и преобразования типов.806807Если именованный аргумент [type](https://python-all.ru/3.15/library/argparse.html#type) используется вместе с [default](https://python-all.ru/3.15/library/argparse.html#default), преобразователь типа применяется только в том случае, если значение по умолчанию является строкой.808809Аргумент `type` может быть вызываемым объектом, принимающим одну строку, или именем зарегистрированного типа (см. [`register()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.register)). Если функция вызывает исключение [`ArgumentTypeError`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentTypeError), [`TypeError`](https://python-all.ru/3.15/library/exceptions.html#TypeError) или [`ValueError`](https://python-all.ru/3.15/library/exceptions.html#ValueError), исключение перехватывается и выводится хорошо оформленное сообщение об ошибке. Другие типы исключений не обрабатываются.810811Распространённые встроенные типы и функции можно использовать в качестве преобразователей типов:812813```python814import argparse815import pathlib816817parser = argparse.ArgumentParser()818parser.add_argument('count', type=int)819parser.add_argument('distance', type=float)820parser.add_argument('street', type=ascii)821parser.add_argument('code_point', type=ord)822parser.add_argument('datapath', type=pathlib.Path)823```824825Пользовательские функции также можно использовать:826827```pycon828>>> def hyphenated(string):829... return '-'.join([word[:4] for word in string.casefold().split()])830...831>>> parser = argparse.ArgumentParser()832>>> _ = parser.add_argument('short_title', type=hyphenated)833>>> parser.parse_args(['"The Tale of Two Cities"'])834Namespace(short_title='"the-tale-of-two-citi')835```836837Функция [`bool()`](https://python-all.ru/3.15/library/functions.html#bool) не рекомендуется в качестве преобразователя типа. Всё, что она делает – преобразует пустые строки в `False`, а непустые в `True`. Обычно это не то, что нужно:838839```python840>>> parser = argparse.ArgumentParser()841>>> _ = parser.add_argument('--verbose', type=bool)842>>> parser.parse_args(['--verbose', 'False'])843Namespace(verbose=True)844```845846См. [`BooleanOptionalAction`](https://python-all.ru/3.15/library/argparse.html#argparse.BooleanOptionalAction) или `action='store_true'` для распространённых альтернатив.847848В целом, ключевое слово `type` – это удобство, которое следует использовать только для простых преобразований, способных вызывать лишь одно из трёх поддерживаемых исключений. Всё, что связано с более сложной обработкой ошибок или управлением ресурсами, должно выполняться ниже по потоку после разбора аргументов.849850Например, преобразования JSON или YAML содержат сложные случаи ошибок, которые требуют более детального отчёта, чем может дать ключевое слово `type`. Сообщение [`JSONDecodeError`](https://python-all.ru/3.15/library/json.html#json.JSONDecodeError) не будет хорошо отформатировано, а исключение [`FileNotFoundError`](https://python-all.ru/3.15/library/exceptions.html#FileNotFoundError) вообще не будет обработано.851852Даже [`FileType`](https://python-all.ru/3.15/library/argparse.html#argparse.FileType) имеет ограничения при использовании с ключевым словом `type`. Если один аргумент использует `FileType`, а затем следующий аргумент завершается ошибкой, сообщается об ошибке, но файл не закрывается автоматически. В этом случае лучше подождать, пока завершит работу парсер, а затем использовать оператор [`with`](https://python-all.ru/3.15/reference/compound_stmts.html#with) для управления файлами.853854Для проверок типов, которые просто сравнивают с фиксированным набором значений, рассмотрите вместо этого использование ключевого слова [choices](https://python-all.ru/3.15/library/argparse.html#choices).855856### choices857858Некоторые аргументы командной строки должны выбираться из ограниченного набора значений. Это можно обработать, передав объект-последовательность в качестве ключевого аргумента *choices* в [`add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument). При разборе командной строки значения аргументов будут проверены, и если аргумент не окажется среди допустимых значений, будет выведено сообщение об ошибке:859860```python861>>> parser = argparse.ArgumentParser(prog='game.py')862>>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])863>>> parser.parse_args(['rock'])864Namespace(move='rock')865>>> parser.parse_args(['fire'])866usage: game.py [-h] {rock,paper,scissors}867game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',868'paper', 'scissors')869```870871В качестве значения *choices* можно передать любую последовательность, поэтому поддерживаются объекты [`list`](https://python-all.ru/3.15/library/stdtypes.html#list), объекты [`tuple`](https://python-all.ru/3.15/library/stdtypes.html#tuple) и пользовательские последовательности.872873Использование [`enum.Enum`](https://python-all.ru/3.15/library/enum.html#enum.Enum) не рекомендуется, поскольку сложно контролировать его отображение в сообщениях об использовании, справке и ошибках.874875Обратите внимание, что *choices* проверяются после применения любых преобразований [type](https://python-all.ru/3.15/library/argparse.html#type), поэтому объекты в *choices* должны соответствовать указанному [type](https://python-all.ru/3.15/library/argparse.html#type). Из-за этого *choices* могут выглядеть непривычно в сообщениях об использовании, справке или ошибках.876877Чтобы *choices* оставались удобными для пользователя, рассмотрите пользовательскую обёртку типа, которая преобразует и форматирует значения, либо опустите [type](https://python-all.ru/3.15/library/argparse.html#type) и обрабатывайте преобразование в коде приложения.878879Форматированные choices переопределяют значение *metavar* по умолчанию, которое обычно выводится из *dest*. Обычно это именно то, что нужно, поскольку пользователь никогда не видит параметр *dest*. Если такое отображение нежелательно (например, из-за большого количества вариантов), просто укажите явный [metavar](https://python-all.ru/3.15/library/argparse.html#metavar).880881### required882883В целом, модуль `argparse` предполагает, что флаги вида `-f` и `--bar` обозначают *необязательные* аргументы, которые всегда можно опустить в командной строке. Чтобы сделать опцию *обязательной*, для ключевого аргумента `required=` функции [`add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument) можно указать `True`:884885```python886>>> parser = argparse.ArgumentParser()887>>> parser.add_argument('--foo', required=True)888>>> parser.parse_args(['--foo', 'BAR'])889Namespace(foo='BAR')890>>> parser.parse_args([])891usage: [-h] --foo FOO892: error: the following arguments are required: --foo893```894895Как показано в примере, если опция помечена как `required`, [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args) сообщит об ошибке, если эта опция отсутствует в командной строке.896897> **Примечание**898>899> Обязательные опции обычно считаются дурным тоном, поскольку пользователи ожидают, что *опции* будут *необязательными*, поэтому их следует по возможности избегать.900901### help902903Значение `help` – это строка с кратким описанием аргумента. Когда пользователь запрашивает справку (обычно с помощью `-h` или `--help` в командной строке), эти описания `help` отображаются для каждого аргумента.904905Строки `help` могут содержать различные спецификаторы формата, чтобы избежать повторения таких элементов, как имя программы или [значение по умолчанию](https://python-all.ru/3.15/library/argparse.html#default) аргумента. Доступные спецификаторы включают имя программы, `%(prog)s` и большинство ключевых аргументов функции [`add_argument()`](https://python-all.ru/3.15/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)916917options:918 -h, --help show this help message and exit919```920921Поскольку строка справки поддерживает %-форматирование, если требуется, чтобы в ней отображался литерал `%`, его нужно экранировать как `%%`.922923`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]930931options:932 -h, --help show this help message and exit933```934935### metavar936937Когда [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) генерирует сообщения справки, ему нужен способ ссылаться на каждый ожидаемый аргумент. По умолчанию объекты `ArgumentParser` используют значение [dest](https://python-all.ru/3.15/library/argparse.html#dest) в качестве «имени» каждого объекта. Для действий с позиционными аргументами значение [dest](https://python-all.ru/3.15/library/argparse.html#dest) используется напрямую, а для действий с необязательными аргументами значение [dest](https://python-all.ru/3.15/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 bar950951options: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 XXX969970options:971 -h, --help show this help message and exit972 --foo YYY973```974975Обратите внимание, что `metavar` изменяет только *отображаемое* имя – имя атрибута объекта [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args) по-прежнему определяется значением [dest](https://python-all.ru/3.15/library/argparse.html#dest).976977Разные значения `nargs` могут привести к тому, что метапеременная будет использована несколько раз. Передача кортежа в `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]985986options:987 -h, --help show this help message and exit988 -x X X989 --foo bar baz990```991992### dest993994Большинство действий [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) добавляют некоторое значение как атрибут объекта, возвращаемого [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args). Имя этого атрибута определяется ключевым аргументом `dest` функции [`add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument). Для действий с позиционными аргументами `dest` обычно передаётся первым аргументом в `add_argument()`:995996```python997>>> parser = argparse.ArgumentParser()998>>> parser.add_argument('bar')999>>> parser.parse_args(['XXX'])1000Namespace(bar='XXX')1001```10021003Для действий с необязательными аргументами значение `dest` обычно выводится из строк опций. [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) формирует значение `dest`, взяв первую длинную опцию с двойным дефисом и удалив начальные символы `-`. Если строки длинных опций с двойным дефисом не были указаны, `dest` выводится из первой длинной опции с одинарным дефисом путём удаления начального символа `-`. Если строки длинных опций не были указаны, `dest` выводится из первой короткой опции путём удаления начального символа `-`. Любые внутренние символы `-` преобразуются в символы `_`, чтобы строка была допустимым именем атрибута. Примеры ниже иллюстрируют это поведение:10041005```python1006>>> parser = argparse.ArgumentParser()1007>>> parser.add_argument('-f', '--foo-bar', '--foo')1008>>> parser.add_argument('-q', '-quz')1009>>> parser.add_argument('-x', '-y')1010>>> parser.parse_args('-f 1 -q 2 -x 3'.split())1011Namespace(foo_bar='1', quz='2', x='3')1012>>> parser.parse_args('--foo 1 -quz 2 -y 3'.split())1013Namespace(foo_bar='1', quz='2', x='2')1014```10151016`dest` позволяет указать пользовательское имя атрибута:10171018```python1019>>> parser = argparse.ArgumentParser()1020>>> parser.add_argument('--foo', dest='bar')1021>>> parser.parse_args('--foo XXX'.split())1022Namespace(bar='XXX')1023```10241025Несколько аргументов могут ссылаться на один и тот же `dest`. По умолчанию используется значение из последнего такого аргумента, переданного в командной строке. Используйте `action='append'`, чтобы собирать значения от всех таких аргументов в список. Для конфликтующих *строк параметров*, а не`dest` имён, см. [conflict\_handler](https://python-all.ru/3.15/library/argparse.html#conflict-handler).10261027Изменено в версии 3.15: Длинный параметр с одним дефисом теперь имеет приоритет над короткими параметрами.10281029### устарело10301031В течение жизненного цикла проекта некоторые аргументы могут потребовать удаления из командной строки. Перед удалением следует сообщить пользователям, что эти аргументы устарели и будут удалены. Ключевой аргумент `deprecated` метода [`add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument), который по умолчанию равен `False`, указывает, что аргумент устарел и будет удалён в будущем. Для аргументов, если `deprecated` равно `True`, то при использовании аргумента будет выведено предупреждение в [`sys.stderr`](https://python-all.ru/3.15/library/sys.html#sys.stderr):10321033```python1034>>> import argparse1035>>> parser = argparse.ArgumentParser(prog='snake.py')1036>>> parser.add_argument('--legs', default=0, type=int, deprecated=True)1037>>> parser.parse_args([])1038Namespace(legs=0)1039>>> parser.parse_args(['--legs', '4'])1040snake.py: warning: option '--legs' is deprecated1041Namespace(legs=4)1042```10431044Добавлено в версии 3.13.10451046### Классы действий10471048`Action` классы реализуют Action API – вызываемый объект, который возвращает вызываемый объект, обрабатывающий аргументы из командной строки. Любой объект, соответствующий этому API, может быть передан в качестве параметра `action` в [`add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument).10491050#### `class argparse.Action(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)`10511052`Action` объекты используются [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) для представления информации, необходимой для разбора одного аргумента из одной или нескольких строк командной строки. Класс `Action` должен принимать два позиционных аргумента и любые ключевые аргументы, переданные в [`ArgumentParser.add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument), кроме самого `action`.10531054Экземпляры `Action` (или возвращаемое значение любого вызываемого объекта для параметра `action`) должны иметь атрибуты `dest`, `option_strings`, `default`, `type`, `required`, `help` и т.д. Проще всего гарантировать наличие этих атрибутов – вызвать `Action.__init__()`.10551056#### `__call__(parser, namespace, values, option_string=None)`10571058Экземпляры `Action` должны быть вызываемыми, поэтому подклассы должны переопределять метод `__call__()`, который принимает четыре параметра:10591060- *parser* – объект [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser), содержащий это действие.1061- *namespace* – объект [`Namespace`](https://python-all.ru/3.15/library/argparse.html#argparse.Namespace), который будет возвращён [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args). Обычно действия добавляют атрибут к этому объекту с помощью [`setattr()`](https://python-all.ru/3.15/library/functions.html#setattr).1062- *values* – связанные аргументы командной строки с применёнными преобразованиями типов. Преобразования типов задаются ключевым аргументом [type](https://python-all.ru/3.15/library/argparse.html#type) в [`add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument).1063- *option\_string* – строка параметра, которая использовалась для вызова этого действия. Аргумент `option_string` необязателен и будет отсутствовать, если действие связано с позиционным аргументом.10641065Метод `__call__()` может выполнять произвольные действия, но обычно устанавливает атрибуты объекта `namespace` на основе `dest` и `values`.10661067#### `format_usage()`10681069Подклассы `Action` могут определить метод `format_usage()` без аргументов, возвращающий строку, которая будет использоваться при выводе справки об использовании программы. Если такой метод не предоставлен, используется разумное значение по умолчанию.10701071#### `class argparse.BooleanOptionalAction`10721073Подкласс [`Action`](https://python-all.ru/3.15/library/argparse.html#argparse.Action) для обработки булевых флагов с положительными и отрицательными параметрами. Добавление одного аргумента, например `--foo`, автоматически создаёт оба параметра `--foo` и `--no-foo`, сохраняя `True` и `False` соответственно:10741075```python1076>>> import argparse1077>>> parser = argparse.ArgumentParser()1078>>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)1079>>> parser.parse_args(['--no-foo'])1080Namespace(foo=False)1081```10821083Также поддерживаются длинные параметры с одним дефисом. Например, отрицательный параметр `-nofoo` автоматически добавляется для положительного параметра `-foo`. Но дополнительные параметры для коротких параметров, таких как `-f`, не добавляются.10841085Добавлено в версии 3.9.10861087Изменено в версии 3.15: Добавлена поддержка параметров с одним дефисом.10881089Добавлена поддержка альтернативных [prefix\_chars](https://python-all.ru/3.15/library/argparse.html#prefix-chars).10901091## Метод parse\_args()10921093#### `ArgumentParser.parse_args(args=None, namespace=None)`10941095Преобразует строки аргументов в объекты и назначает их в качестве атрибутов пространства имён. Возвращает заполненное пространство имён.10961097Предыдущие вызовы [`add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument) определяют, какие объекты создаются и как они назначаются. Подробнее см. документацию `add_argument()`.10981099- [args](https://python-all.ru/3.15/library/argparse.html#args) – список строк для разбора. По умолчанию берётся из [`sys.argv`](https://python-all.ru/3.15/library/sys.html#sys.argv).1100- [namespace](https://python-all.ru/3.15/library/argparse.html#namespace) – объект, в который будут помещены атрибуты. По умолчанию – новый пустой объект [`Namespace`](https://python-all.ru/3.15/library/argparse.html#argparse.Namespace).11011102### Синтаксис значений параметров11031104Метод [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args) поддерживает несколько способов указания значения параметра (если он принимает значение). В простейшем случае параметр и его значение передаются как два отдельных аргумента:11051106```python1107>>> parser = argparse.ArgumentParser(prog='PROG')1108>>> parser.add_argument('-x')1109>>> parser.add_argument('--foo')1110>>> parser.parse_args(['-x', 'X'])1111Namespace(foo=None, x='X')1112>>> parser.parse_args(['--foo', 'FOO'])1113Namespace(foo='FOO', x=None)1114```11151116Для длинных параметров (с именами длиннее одного символа) параметр и значение могут быть переданы как один аргумент командной строки, используя `=` для их разделения:11171118```python1119>>> parser.parse_args(['--foo=FOO'])1120Namespace(foo='FOO', x=None)1121```11221123Для коротких опций (опции длиной в один символ) опция и её значение могут быть объединены:11241125```python1126>>> parser.parse_args(['-xX'])1127Namespace(foo=None, x='X')1128```11291130Несколько коротких опций можно объединить, используя только один префикс `-`, при условии, что только последняя опция (или ни одна из них) требует значения:11311132```python1133>>> parser = argparse.ArgumentParser(prog='PROG')1134>>> parser.add_argument('-x', action='store_true')1135>>> parser.add_argument('-y', action='store_true')1136>>> parser.add_argument('-z')1137>>> parser.parse_args(['-xyzZ'])1138Namespace(x=True, y=True, z='Z')1139```11401141### Недопустимые аргументы11421143При разборе командной строки [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args) проверяет различные ошибки, включая неоднозначные опции, некорректные типы, неверные опции, неправильное количество позиционных аргументов и т.д. При обнаружении такой ошибки программа завершается и выводит сообщение об ошибке вместе со справкой по использованию:11441145```python1146>>> parser = argparse.ArgumentParser(prog='PROG')1147>>> parser.add_argument('--foo', type=int)1148>>> parser.add_argument('bar', nargs='?')11491150>>> # недопустимый тип1151>>> parser.parse_args(['--foo', 'spam'])1152usage: PROG [-h] [--foo FOO] [bar]1153PROG: error: argument --foo: invalid int value: 'spam'11541155>>> # недопустимая опция1156>>> parser.parse_args(['--bar'])1157usage: PROG [-h] [--foo FOO] [bar]1158PROG: error: no such option: --bar11591160>>> # неверное количество аргументов1161>>> parser.parse_args(['spam', 'badger'])1162usage: PROG [-h] [--foo FOO] [bar]1163PROG: error: extra arguments found: badger1164```11651166### Аргументы, содержащие `-`11671168Метод [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args) старается выдавать ошибки всякий раз, когда пользователь явно ошибся, но некоторые ситуации по своей природе неоднозначны. Например, аргумент командной строки `-1` может быть как попыткой указать опцию, так и попыткой передать позиционный аргумент. Метод `parse_args()` здесь действует осторожно: позиционные аргументы могут начинаться с `-` только если они похожи на отрицательные числа, и в анализаторе нет опций, которые выглядят как отрицательные числа:11691170```python1171>>> parser = argparse.ArgumentParser(prog='PROG')1172>>> parser.add_argument('-x')1173>>> parser.add_argument('foo', nargs='?')11741175>>> # нет опций с отрицательными числами, поэтому -1 – позиционный аргумент1176>>> parser.parse_args(['-x', '-1'])1177Namespace(foo=None, x='-1')11781179>>> # нет опций с отрицательными числами, поэтому -1 и -5 – позиционные аргументы1180>>> parser.parse_args(['-x', '-1', '-5'])1181Namespace(foo='-5', x='-1')11821183>>> parser = argparse.ArgumentParser(prog='PROG')1184>>> parser.add_argument('-1', dest='one')1185>>> parser.add_argument('foo', nargs='?')11861187>>> # опции с отрицательными числами присутствуют, поэтому -1 – это опция1188>>> parser.parse_args(['-1', 'X'])1189Namespace(foo=None, one='X')11901191>>> # опции с отрицательными числами присутствуют, поэтому -2 – это опция1192>>> parser.parse_args(['-2'])1193usage: PROG [-h] [-1 ONE] [foo]1194PROG: error: no such option: -211951196>>> # опции с отрицательными числами присутствуют, поэтому обе -1 – это опции1197>>> parser.parse_args(['-1', '-1'])1198usage: PROG [-h] [-1 ONE] [foo]1199PROG: error: argument -1: expected one argument1200```12011202Если позиционные аргументы должны начинаться с `-` и не похожи на отрицательные числа, можно вставить псевдоаргумент `'--'`, который сообщает [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args), что всё после него является позиционным аргументом:12031204```python1205>>> parser.parse_args(['--', '-f'])1206Namespace(foo='-f', one=None)1207```12081209См. также [руководство по argparse о неоднозначных аргументах](https://python-all.ru/3.15/howto/argparse.html#specifying-ambiguous-arguments) для получения дополнительных сведений.12101211### Сокращения аргументов (совпадение по префиксу)12121213Метод [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args) [по умолчанию](https://python-all.ru/3.15/library/argparse.html#allow-abbrev) позволяет сокращать длинные опции до префикса, если сокращение является однозначным (префикс соответствует уникальной опции):12141215```python1216>>> parser = argparse.ArgumentParser(prog='PROG')1217>>> parser.add_argument('-bacon')1218>>> parser.add_argument('-badger')1219>>> parser.parse_args('-bac MMM'.split())1220Namespace(bacon='MMM', badger=None)1221>>> parser.parse_args('-bad WOOD'.split())1222Namespace(bacon=None, badger='WOOD')1223>>> parser.parse_args('-ba BA'.split())1224usage: PROG [-h] [-bacon BACON] [-badger BADGER]1225PROG: error: ambiguous option: -ba could match -badger, -bacon1226```12271228Выдаётся ошибка для аргументов, которые могут соответствовать нескольким опциям. Эту возможность можно отключить, установив [allow\_abbrev](https://python-all.ru/3.15/library/argparse.html#allow-abbrev) в `False`.12291230### За пределами `sys.argv`12311232Иногда бывает полезно, чтобы [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) разбирал аргументы, отличные от аргументов [`sys.argv`](https://python-all.ru/3.15/library/sys.html#sys.argv). Это можно сделать, передав список строк в [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args). Это удобно для тестирования в интерактивной оболочке:12331234```python1235>>> parser = argparse.ArgumentParser()1236>>> parser.add_argument(1237... 'integers', metavar='int', type=int, choices=range(10),1238... nargs='+', help='an integer in the range 0..9')1239>>> parser.add_argument(1240... '--sum', dest='accumulate', action='store_const', const=sum,1241... default=max, help='sum the integers (default: find the max)')1242>>> parser.parse_args(['1', '2', '3', '4'])1243Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])1244>>> parser.parse_args(['1', '2', '3', '4', '--sum'])1245Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])1246```12471248### Объект Namespace12491250#### `class argparse.Namespace`12511252Простой класс, используемый по умолчанию в [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args) для создания объекта, содержащего атрибуты, и его возврата.12531254Этот класс намеренно прост, всего лишь подкласс [`object`](https://python-all.ru/3.15/library/functions.html#object) с читаемым строковым представлением. Если нужно dict-подобное представление атрибутов, можно воспользоваться стандартной идиомой Python, [`vars()`](https://python-all.ru/3.15/library/functions.html#vars):12551256```python1257>>> parser = argparse.ArgumentParser()1258>>> parser.add_argument('--foo')1259>>> args = parser.parse_args(['--foo', 'BAR'])1260>>> vars(args)1261{'foo': 'BAR'}1262```12631264Также может быть полезно, чтобы [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) присваивал атрибуты уже существующему объекту, а не новому объекту `Namespace`. Этого можно достичь, указав именованный аргумент `namespace=`:12651266```python1267>>> class C:1268... pass1269...1270>>> c = C()1271>>> parser = argparse.ArgumentParser()1272>>> parser.add_argument('--foo')1273>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)1274>>> c.foo1275'BAR'1276```12771278## Другие утилиты12791280### Подкоманды12811282#### `ArgumentParser.add_subparsers(*[, title][, description][, prog][, parser_class][, action][, dest][, required][, help][, metavar])`12831284Многие программы разделяют свою функциональность на несколько подкоманд; например, программа `svn` может вызывать подкоманды `svn checkout`, `svn update` и `svn commit`. Такое разделение функциональности может быть особенно удачной идеей, когда программа выполняет несколько различных функций, требующих разных видов аргументов командной строки. [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) поддерживает создание таких подкоманд с помощью метода `add_subparsers()`. Метод `add_subparsers()` обычно вызывается без аргументов и возвращает специальный объект действия. Этот объект имеет единственный метод, [`add_parser()`](https://python-all.ru/3.15/library/argparse.html#argparse._SubParsersAction.add_parser), который принимает имя команды и любые аргументы конструктора `ArgumentParser`, и возвращает объект `ArgumentParser`, который можно изменять обычным образом.12851286Описание параметров:12871288- *title* – заголовок для группы подпарсеров в выводе справки; по умолчанию «subcommands», если указано описание, в противном случае используется заголовок для позиционных аргументов1289- *description* – описание для группы подпарсеров в выводе справки; по умолчанию `None`1290- *prog* – информация об использовании, которая будет отображаться в справке подкоманды; по умолчанию – имя программы и любые позиционные аргументы перед аргументом подпарсера1291- *parser\_class* – класс, который будет использоваться для создания экземпляров подпарсеров; по умолчанию – класс текущего парсера (например, [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser))1292- [action](https://python-all.ru/3.15/library/argparse.html#action) – базовый тип действия, которое будет выполнено при обнаружении этого аргумента в командной строке1293- [dest](https://python-all.ru/3.15/library/argparse.html#dest) – имя атрибута, в котором будет сохранено имя подкоманды; по умолчанию `None` и значение не сохраняется1294- [required](https://python-all.ru/3.15/library/argparse.html#required) – указывает, обязательно ли должна быть указана подкоманда; по умолчанию `False` (добавлено в версии 3.7)1295- [help](https://python-all.ru/3.15/library/argparse.html#help) – справка для группы подпарсеров в выводе справки; по умолчанию `None`1296- [metavar](https://python-all.ru/3.15/library/argparse.html#metavar) – строка, представляющая доступные подкоманды в справке; по умолчанию `None`, и подкоманды отображаются в виде {cmd1, cmd2, ..}12971298Пример использования:12991300```python1301>>> # создать парсер верхнего уровня1302>>> parser = argparse.ArgumentParser(prog='PROG')1303>>> parser.add_argument('--foo', action='store_true', help='foo help')1304>>> subparsers = parser.add_subparsers(help='subcommand help')1305>>>1306>>> # создать парсер для команды "a"1307>>> parser_a = subparsers.add_parser('a', help='a help')1308>>> parser_a.add_argument('bar', type=int, help='bar help')1309>>>1310>>> # создать парсер для команды "b"1311>>> parser_b = subparsers.add_parser('b', help='b help')1312>>> parser_b.add_argument('--baz', choices=('X', 'Y', 'Z'), help='baz help')1313>>>1314>>> # разобрать некоторые списки аргументов1315>>> parser.parse_args(['a', '12'])1316Namespace(bar=12, foo=False)1317>>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])1318Namespace(baz='Z', foo=True)1319```13201321Обратите внимание, что объект, возвращаемый [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args), будет содержать только атрибуты главного парсера и того подпарсера, который был выбран из командной строки (а не любых других подпарсеров). Так, в приведённом выше примере, когда указана команда `a`, присутствуют только атрибуты `foo` и `bar`, а когда указана команда `b` – только атрибуты `foo` и `baz`.13221323Если подпарсер определяет аргумент с тем же `dest`, что и родительский парсер, они разделяют один атрибут пространства имён, поэтому значение родителя не будет сохранено. Пользователям следует задать им разные значения `dest`, чтобы сохранить оба.13241325Аналогично, при запросе справки от подпарсера выводится только справка этого конкретного парсера. Сообщение справки не включает сообщения родительского парсера или соседних парсеров. (Однако справку для каждой команды подпарсера можно задать, передав аргумент `help=` функции [`add_parser()`](https://python-all.ru/3.15/library/argparse.html#argparse._SubParsersAction.add_parser), как показано выше.)13261327```python1328>>> parser.parse_args(['--help'])1329usage: PROG [-h] [--foo] {a,b} ...13301331positional arguments:1332 {a,b} subcommand help1333 a a help1334 b b help13351336options:1337 -h, --help show this help message and exit1338 --foo foo help13391340>>> parser.parse_args(['a', '--help'])1341usage: PROG a [-h] bar13421343positional arguments:1344 bar bar help13451346options:1347 -h, --help show this help message and exit13481349>>> parser.parse_args(['b', '--help'])1350usage: PROG b [-h] [--baz {X,Y,Z}]13511352options:1353 -h, --help show this help message and exit1354 --baz {X,Y,Z} baz help1355```13561357Метод `add_subparsers()` также поддерживает именованные аргументы `title` и `description`. Когда любой из них присутствует, команды подпарсера отображаются в собственной группе в выводе справки. Например:13581359```python1360>>> parser = argparse.ArgumentParser()1361>>> subparsers = parser.add_subparsers(title='subcommands',1362... description='valid subcommands',1363... help='additional help')1364>>> subparsers.add_parser('foo')1365>>> subparsers.add_parser('bar')1366>>> parser.parse_args(['-h'])1367usage: [-h] {foo,bar} ...13681369options:1370 -h, --help show this help message and exit13711372subcommands:1373 valid subcommands13741375 {foo,bar} additional help1376```13771378Один из особенно эффективных способов обработки подкоманд – комбинировать использование метода `add_subparsers()` с вызовами [`set_defaults()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.set_defaults), чтобы каждый подпарсер знал, какую функцию Python он должен выполнить. Например:13791380```python1381>>> # функции подкоманд1382>>> def foo(args):1383... print(args.x * args.y)1384...1385>>> def bar(args):1386... print('((%s))' % args.z)1387...1388>>> # создать парсер верхнего уровня1389>>> parser = argparse.ArgumentParser()1390>>> subparsers = parser.add_subparsers(required=True)1391>>>1392>>> # создать парсер для команды "foo"1393>>> parser_foo = subparsers.add_parser('foo')1394>>> parser_foo.add_argument('-x', type=int, default=1)1395>>> parser_foo.add_argument('y', type=float)1396>>> parser_foo.set_defaults(func=foo)1397>>>1398>>> # создать парсер для команды "bar"1399>>> parser_bar = subparsers.add_parser('bar')1400>>> parser_bar.add_argument('z')1401>>> parser_bar.set_defaults(func=bar)1402>>>1403>>> # разобрать аргументы и вызвать выбранную функцию1404>>> args = parser.parse_args('foo 1 -x 2'.split())1405>>> args.func(args)14062.01407>>>1408>>> # разобрать аргументы и вызвать выбранную функцию1409>>> args = parser.parse_args('bar XYZYX'.split())1410>>> args.func(args)1411((XYZYX))1412```14131414Таким образом, можно поручить [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args) задачу вызова соответствующей функции после завершения разбора аргументов. Связывание функций с действиями таким образом – обычно самый простой способ обработать разные действия для каждого из ваших подпарсеров. Однако, если необходимо проверить имя вызванного подпарсера, сработает именованный аргумент `dest` при вызове `add_subparsers()`:14151416```python1417>>> parser = argparse.ArgumentParser()1418>>> subparsers = parser.add_subparsers(dest='subparser_name')1419>>> subparser1 = subparsers.add_parser('1')1420>>> subparser1.add_argument('-x')1421>>> subparser2 = subparsers.add_parser('2')1422>>> subparser2.add_argument('y')1423>>> parser.parse_args(['2', 'frobble'])1424Namespace(subparser_name='2', y='frobble')1425```14261427Изменено в версии 3.7: Новый именованный параметр *required*.14281429Изменено в версии 3.14: На *prog* подпарсера больше не влияет пользовательское сообщение об использовании в главном парсере.14301431#### `_SubParsersAction.add_parser(name, *, help=None, aliases=None, deprecated=False, **kwargs)`14321433Создаёт и возвращает новый объект [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) для подкоманды *name*.14341435Аргумент *name* – это имя подкоманды.14361437Аргумент *help* предоставляет краткое описание этой подкоманды.14381439Аргумент *aliases* позволяет задать альтернативные имена для этой подкоманды. Например:14401441```python1442>>> parser = argparse.ArgumentParser()1443>>> subparsers = parser.add_subparsers()1444>>> checkout = subparsers.add_parser('checkout', aliases=['co'])1445>>> checkout.add_argument('foo')1446>>> parser.parse_args(['co', 'bar'])1447Namespace(foo='bar')1448```14491450Аргумент *устарело*, если `True`, помечает подкоманду как устаревшую и выдаёт предупреждение при использовании. Например:14511452```python1453>>> parser = argparse.ArgumentParser(prog='chicken.py')1454>>> subparsers = parser.add_subparsers()1455>>> fly = subparsers.add_parser('fly', deprecated=True)1456>>> args = parser.parse_args(['fly'])1457chicken.py: warning: command 'fly' is deprecated1458Namespace()1459```14601461Все остальные именованные аргументы передаются напрямую конструктору `ArgumentParser`.14621463Добавлено в версии 3.13: Добавлен параметр *устарело*.14641465### Объекты FileType14661467#### `class argparse.FileType(mode='r', bufsize=-1, encoding=None, errors=None)`14681469Фабрика `FileType` создаёт объекты, которые можно передать в аргумент type функции [`ArgumentParser.add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument). Аргументы, имеющие объекты `FileType` в качестве типа, будут открывать аргументы командной строки как файлы с указанными режимами, размерами буфера, кодировками и обработкой ошибок (см. функцию [`open()`](https://python-all.ru/3.15/library/functions.html#open) для подробностей):14701471```python1472>>> parser = argparse.ArgumentParser()1473>>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))1474>>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8'))1475>>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])1476Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)1477```14781479Объекты FileType понимают псевдоаргумент `'-'` и автоматически преобразуют его в [`sys.stdin`](https://python-all.ru/3.15/library/sys.html#sys.stdin) для читаемых объектов `FileType` и в [`sys.stdout`](https://python-all.ru/3.15/library/sys.html#sys.stdout) для записываемых объектов `FileType`:14801481```python1482>>> parser = argparse.ArgumentParser()1483>>> parser.add_argument('infile', type=argparse.FileType('r'))1484>>> parser.parse_args(['-'])1485Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)1486```14871488> **Примечание**1489>1490> Если один аргумент использует *FileType*, а затем последующий аргумент завершается ошибкой, сообщается об ошибке, но файл не закрывается автоматически. Это также может повредить выходные файлы. В этом случае лучше дождаться завершения работы парсера, а затем использовать оператор [`with`](https://python-all.ru/3.15/reference/compound_stmts.html#with) для управления файлами.14911492Изменено в версии 3.4: Добавлены параметры *encoding* и *errors*.14931494Устарело с версии 3.14.14951496### Группы аргументов14971498#### `ArgumentParser.add_argument_group(title=None, description=None, *[, argument_default][, conflict_handler])`14991500По умолчанию [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) группирует аргументы командной строки на «позиционные аргументы» и «опции» при отображении сообщений справки. Если существует более осмысленная концептуальная группировка аргументов, чем эта, можно создать соответствующие группы с помощью метода `add_argument_group()`:15011502```python1503>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)1504>>> group = parser.add_argument_group('group')1505>>> group.add_argument('--foo', help='foo help')1506>>> group.add_argument('bar', help='bar help')1507>>> parser.print_help()1508usage: PROG [--foo FOO] bar15091510group:1511 bar bar help1512 --foo FOO foo help1513```15141515Метод `add_argument_group()` возвращает объект группы аргументов, у которого есть метод [`add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument), как и у обычного [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser). Когда аргумент добавляется в группу, парсер обрабатывает его как обычный аргумент, но при выводе справки отображает его в отдельной группе. Метод `add_argument_group()` принимает аргументы *title* и *description*, которые можно использовать для настройки этого отображения:15161517```python1518>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)1519>>> group1 = parser.add_argument_group('group1', 'group1 description')1520>>> group1.add_argument('foo', help='foo help')1521>>> group2 = parser.add_argument_group('group2', 'group2 description')1522>>> group2.add_argument('--bar', help='bar help')1523>>> parser.print_help()1524usage: PROG [--bar BAR] foo15251526group1:1527 group1 description15281529 foo foo help15301531group2:1532 group2 description15331534 --bar BAR bar help1535```15361537Необязательные именованные параметры [argument\_default](https://python-all.ru/3.15/library/argparse.html#argument-default) и [conflict\_handler](https://python-all.ru/3.15/library/argparse.html#conflict-handler) позволяют более детально управлять поведением группы аргументов. Эти параметры имеют тот же смысл, что и в конструкторе [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser), но применяются именно к группе аргументов, а не ко всему парсеру.15381539Обратите внимание, что любые аргументы, не входящие в ваши пользовательские группы, окажутся обратно в обычных разделах «позиционные аргументы» и «опциональные аргументы».15401541Внутри каждой группы аргументов они отображаются в выводе справки в порядке их добавления.15421543Устарело с версии 3.11, удалено в версии 3.14: Вызов `add_argument_group()` для группы аргументов теперь вызывает исключение. Это вложение никогда не поддерживалось, часто работало некорректно и было случайно доступно через наследование.15441545Устарело с версии 3.14: Передача [prefix\_chars](https://python-all.ru/3.15/library/argparse.html#prefix-chars) в `add_argument_group()` теперь устарела.15461547### Взаимное исключение15481549#### `ArgumentParser.add_mutually_exclusive_group(required=False)`15501551Создаёт взаимоисключающую группу. `argparse` гарантирует, что в командной строке присутствовал только один из аргументов взаимоисключающей группы:15521553```python1554>>> parser = argparse.ArgumentParser(prog='PROG')1555>>> group = parser.add_mutually_exclusive_group()1556>>> group.add_argument('--foo', action='store_true')1557>>> group.add_argument('--bar', action='store_false')1558>>> parser.parse_args(['--foo'])1559Namespace(bar=True, foo=True)1560>>> parser.parse_args(['--bar'])1561Namespace(bar=False, foo=False)1562>>> parser.parse_args(['--foo', '--bar'])1563usage: PROG [-h] [--foo | --bar]1564PROG: error: argument --bar: not allowed with argument --foo1565```15661567Метод `add_mutually_exclusive_group()` также принимает аргумент *required*, чтобы указать, что требуется хотя бы один из взаимоисключающих аргументов:15681569```python1570>>> parser = argparse.ArgumentParser(prog='PROG')1571>>> group = parser.add_mutually_exclusive_group(required=True)1572>>> group.add_argument('--foo', action='store_true')1573>>> group.add_argument('--bar', action='store_false')1574>>> parser.parse_args([])1575usage: PROG [-h] (--foo | --bar)1576PROG: error: one of the arguments --foo --bar is required1577```15781579Обратите внимание: в настоящее время взаимоисключающие группы аргументов не поддерживают аргументы *title* и *description* метода [`add_argument_group()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument_group). Однако взаимоисключающую группу можно добавить к группе аргументов, у которой есть заголовок и описание. Например:15801581```python1582>>> parser = argparse.ArgumentParser(prog='PROG')1583>>> group = parser.add_argument_group('Group title', 'Group description')1584>>> exclusive_group = group.add_mutually_exclusive_group(required=True)1585>>> exclusive_group.add_argument('--foo', help='foo help')1586>>> exclusive_group.add_argument('--bar', help='bar help')1587>>> parser.print_help()1588usage: PROG [-h] (--foo FOO | --bar BAR)15891590options:1591 -h, --help show this help message and exit15921593Group title:1594 Group description15951596 --foo FOO foo help1597 --bar BAR bar help1598```15991600Устарело с версии 3.11, удалено в версии 3.14: Вызов [`add_argument_group()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument_group) или `add_mutually_exclusive_group()` для взаимоисключающей группы теперь вызывает исключение. Такая вложенность никогда не поддерживалась, часто работала некорректно и была случайно раскрыта через наследование.16011602### Умолчания парсера16031604#### `ArgumentParser.set_defaults(**kwargs)`16051606В большинстве случаев атрибуты объекта, возвращаемого [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args), полностью определяются путём анализа аргументов командной строки и действий аргументов. `set_defaults()` позволяет добавить некоторые дополнительные атрибуты, которые определяются без какого-либо анализа командной строки:16071608```python1609>>> parser = argparse.ArgumentParser()1610>>> parser.add_argument('foo', type=int)1611>>> parser.set_defaults(bar=42, baz='badger')1612>>> parser.parse_args(['736'])1613Namespace(bar=42, baz='badger', foo=736)1614```16151616Обратите внимание: умолчания можно задать как на уровне парсера с помощью `set_defaults()`, так и на уровне аргумента с помощью [`add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument). Если оба метода вызываются для одного и того же аргумента, используется последнее установленное умолчание:16171618```python1619>>> parser = argparse.ArgumentParser()1620>>> parser.add_argument('--foo', default='bar')1621>>> parser.set_defaults(foo='spam')1622>>> parser.parse_args([])1623Namespace(foo='spam')1624```16251626Умолчания на уровне парсера могут быть особенно полезны при работе с несколькими парсерами. См. пример этого типа в методе [`add_subparsers()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_subparsers).16271628#### `ArgumentParser.get_default(dest)`16291630Возвращает значение по умолчанию для атрибута пространства имён, заданное либо [`add_argument()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.add_argument), либо [`set_defaults()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.set_defaults):16311632```python1633>>> parser = argparse.ArgumentParser()1634>>> parser.add_argument('--foo', default='badger')1635>>> parser.get_default('foo')1636'badger'1637```16381639### Вывод справки16401641В большинстве типичных приложений [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args) берёт на себя форматирование и вывод всех сообщений об использовании и ошибок. Однако доступно несколько методов форматирования:16421643#### `ArgumentParser.print_usage(file=None)`16441645Выводит краткое описание того, как [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) должен вызываться в командной строке. Если *file* равен `None`, предполагается [`sys.stdout`](https://python-all.ru/3.15/library/sys.html#sys.stdout).16461647#### `ArgumentParser.print_help(file=None)`16481649Выводит справочное сообщение, включая использование программы и информацию об аргументах, зарегистрированных в [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser). Если *file* равен `None`, предполагается [`sys.stdout`](https://python-all.ru/3.15/library/sys.html#sys.stdout).16501651Существуют также варианты этих методов, которые просто возвращают строку вместо её вывода:16521653#### `ArgumentParser.format_usage()`16541655Возвращает строку с кратким описанием того, как [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser) должен вызываться в командной строке.16561657#### `ArgumentParser.format_help()`16581659Возвращает строку со справочным сообщением, включая использование программы и информацию об аргументах, зарегистрированных в [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser).16601661### Частичный разбор16621663#### `ArgumentParser.parse_known_args(args=None, namespace=None)`16641665Иногда скрипту нужно обрабатывать только определённый набор аргументов командной строки, оставляя нераспознанные аргументы для другого скрипта или программы. В таких случаях может быть полезен метод `parse_known_args()`.16661667Этот метод работает аналогично [`parse_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_args), но не вызывает ошибку для лишних нераспознанных аргументов. Вместо этого он разбирает известные аргументы и возвращает кортеж из двух элементов, содержащий заполненное пространство имён и список всех нераспознанных аргументов.16681669```python1670>>> parser = argparse.ArgumentParser()1671>>> parser.add_argument('--foo', action='store_true')1672>>> parser.add_argument('bar')1673>>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])1674(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])1675```16761677> **Предупреждение**1678>1679> Правила [совпадения по префиксу](https://python-all.ru/3.15/library/argparse.html#prefix-matching) применяются к [`parse_known_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_known_args). Парсер может поглотить параметр, даже если он является всего лишь префиксом одного из известных параметров, вместо того чтобы оставить его в списке оставшихся аргументов.16801681### Настройка разбора файлов16821683#### `ArgumentParser.convert_arg_line_to_args(arg_line)`16841685Аргументы, читаемые из файла (см. именованный аргумент *fromfile\_prefix\_chars* конструктора [`ArgumentParser`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser)), читаются по одному аргументу на строку. `convert_arg_line_to_args()` можно переопределить для более сложного чтения.16861687Этот метод принимает один аргумент *arg\_line* – строку, прочитанную из файла аргументов. Он возвращает список аргументов, разобранных из этой строки. Метод вызывается по одному разу для каждой строки из файла аргументов, по порядку.16881689Полезным переопределением этого метода будет то, которое рассматривает каждое отделённое пробелом слово как аргумент. Следующий пример показывает, как это сделать:16901691```python1692class MyArgumentParser(argparse.ArgumentParser):1693 def convert_arg_line_to_args(self, arg_line):1694 return arg_line.split()1695```16961697Обратите внимание: при таком переопределении аргумент больше не может содержать пробелы, поскольку каждое отделённое пробелом слово становится отдельным аргументом.16981699### Методы завершения17001701#### `ArgumentParser.exit(status=0, message=None)`17021703Этот метод завершает программу с указанным *status* и, если задано, выводит *message* в [`sys.stderr`](https://python-all.ru/3.15/library/sys.html#sys.stderr) перед этим. Пользователь может переопределить этот метод, чтобы выполнять эти действия иначе:17041705```python1706class ErrorCatchingArgumentParser(argparse.ArgumentParser):1707 def exit(self, status=0, message=None):1708 if status:1709 raise Exception(f'Exiting because of an error: {message}')1710 exit(status)1711```17121713#### `ArgumentParser.error(message)`17141715Этот метод выводит сообщение об использовании, включая *message*, в [`sys.stderr`](https://python-all.ru/3.15/library/sys.html#sys.stderr) и завершает программу с кодом возврата 2.17161717### Смешанный разбор17181719#### `ArgumentParser.parse_intermixed_args(args=None, namespace=None)`17201721#### `ArgumentParser.parse_known_intermixed_args(args=None, namespace=None)`17221723Многие команды Unix позволяют пользователю смешивать опциональные аргументы с позиционными. Методы [`parse_intermixed_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_intermixed_args) и `parse_known_intermixed_args()` поддерживают такой стиль разбора.17241725Эти анализаторы не поддерживают все возможности `argparse` и будут вызывать исключения при использовании неподдерживаемых возможностей. В частности, не поддерживаются подпарсеры и взаимоисключающие группы, содержащие как опциональные, так и позиционные аргументы.17261727Следующий пример показывает разницу между [`parse_known_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_known_args) и [`parse_intermixed_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_intermixed_args): первый возвращает `['2', '3']` как неразобранные аргументы, в то время как второй собирает все позиционные аргументы в `rest`.17281729```python1730>>> parser = argparse.ArgumentParser()1731>>> parser.add_argument('--foo')1732>>> parser.add_argument('cmd')1733>>> parser.add_argument('rest', nargs='*', type=int)1734>>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())1735(Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])1736>>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())1737Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])1738```17391740`parse_known_intermixed_args()` возвращает кортеж из двух элементов, содержащий заполненное пространство имён и список оставшихся строк аргументов. [`parse_intermixed_args()`](https://python-all.ru/3.15/library/argparse.html#argparse.ArgumentParser.parse_intermixed_args) вызывает ошибку, если остаются какие-либо неразобранные строки аргументов.17411742Добавлено в версии 3.7.17431744### Регистрация пользовательских типов или действий17451746#### `ArgumentParser.register(registry_name, value, object)`17471748Иногда бывает удобно использовать произвольную строку в сообщениях об ошибках, чтобы сделать вывод более понятным для пользователя. В таких случаях `register()` можно использовать для регистрации пользовательских действий или типов в анализаторе и ссылаться на тип по его зарегистрированному имени, а не по имени вызываемого объекта.17491750Метод `register()` принимает три аргумента: *registry\_name*, указывающий внутренний реестр, в котором будет сохранён объект (например, `action`, `type`); *value* – ключ, под которым объект будет зарегистрирован; и object – вызываемый объект, который нужно зарегистрировать.17511752Следующий пример показывает, как зарегистрировать пользовательский тип в анализаторе:17531754```python1755>>> import argparse1756>>> parser = argparse.ArgumentParser()1757>>> parser.register('type', 'hexadecimal integer', lambda s: int(s, 16))1758>>> parser.add_argument('--foo', type='hexadecimal integer')1759_StoreAction(option_strings=['--foo'], dest='foo', nargs=None, const=None, default=None, type='hexadecimal integer', choices=None, required=False, help=None, metavar=None, deprecated=False)1760>>> parser.parse_args(['--foo', '0xFA'])1761Namespace(foo=250)1762>>> parser.parse_args(['--foo', '1.2'])1763usage: PROG [-h] [--foo FOO]1764PROG: error: argument --foo: invalid 'hexadecimal integer' value: '1.2'1765```17661767## Исключения17681769#### `exception argparse.ArgumentError`17701771Ошибка при создании или использовании аргумента (опционального или позиционного).17721773Строковое значение этого исключения – это сообщение, дополненное информацией об аргументе, который его вызвал.17741775#### `exception argparse.ArgumentTypeError`17761777Вызывается, когда что-то идёт не так при преобразовании строки командной строки в тип.17781779Руководства и учебные пособия17801781- [Учебное пособие по argparse](https://python-all.ru/3.15/howto/argparse.html)1782- [Перенос кода `optparse` на `argparse`](https://python-all.ru/3.15/howto/argparse-optparse.html)1783