import argparse parser = 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)
prog=None - имя программы (по умолчанию: sys.argv[0]),usage=None - строка, описывающая использование программы,description=None - текст для отображения перед аргументом справка,epilog=None - текст для отображения после аргумента справка,parents=[] - список объектов ArgumentParser, аргументы которых также должны быть включены,formatter_class=argparse.HelpFormatter - класс для настройки вывода справки,prefix_chars='-' - префиксы необязательных параметров командной строки,fromfile_prefix_chars=None - префиксы файлов, из которых должны быть прочитаны дополнительные параметры,argument_default=None - глобальное значение для параметров командной строки по умолчанию,conflict_handler='error' - стратегия разрешения конфликтов опций,add_help=True - добавляет опцию a -h/--help в синтаксический анализатор,allow_abbrev=True - сокращает длинные варианты, если аббревиатура однозначна,exit_on_error=True - определяет, завершает ли ArgumentParser работу с информацией об ошибке при возникновении ошибки.ArgumentParser (описание методов смотрите далее, в других разделах)Класс ArgumentParser() модуля argparse создает новый объект ArgumentParser. Все параметры должны передаваться в качестве ключевых аргументов. Каждый параметр имеет свое собственное более подробное описание ниже.
prog=None.По умолчанию объекты ArgumentParser используют sys.argv[0] для определения способа отображения имени программы в справочных сообщениях. Это значение по умолчанию почти всегда корректно, потому что оно заставляет справочные сообщения соответствовать тому, как программа была вызвана из командной строки. Например, рассмотрим файл myprogram.py со следующим кодом:
# myprogram.py import argparse parser = argparse.ArgumentParser() parser.add_argument('--foo', help='foo help') args = parser.parse_args()
На экране появится справка, в качестве имени программы будет myprogram.py (независимо от того, откуда была вызвана программа):
$ python myprogram.py --help usage: myprogram.py [-h] [--foo FOO] optional arguments: -h, --help show this help message and exit --foo FOO foo help $ cd .. $ python subdir/myprogram.py --help usage: myprogram.py [-h] [--foo FOO] optional arguments: -h, --help show this help message and exit --foo FOO foo help
Чтобы изменить это поведение по умолчанию, можно указать другое значение с помощью аргумента prog:
>>> parser = argparse.ArgumentParser(prog='myprogram') >>> parser.print_help() # usage: myprogram [-h] # # optional arguments: # -h, --help show this help message and exit
Обратите внимание, что имя программы, независимо от того, определено ли оно из sys.argv[0] или из аргумента prog, доступно для справочных сообщений с использованием спецификатора формата %(prog)s.
>>> parser = argparse.ArgumentParser(prog='myprogram') >>> parser.add_argument('--foo', help='foo of the %(prog)s program') >>> parser.print_help() # usage: myprogram [-h] [--foo FOO] # # optional arguments: # -h, --help show this help message and exit # --foo FOO foo of the myprogram program
usage=None.По умолчанию argparse.ArgumentParser() вычисляет сообщение об использовании на основе содержащихся в нем аргументов:
>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('--foo', nargs='?', help='foo help') >>> parser.add_argument('bar', nargs='+', help='bar help') >>> parser.print_help() # usage: PROG [-h] [--foo [FOO]] bar [bar ...] # # positional arguments: # bar bar help # # optional arguments: # -h, --help show this help message and exit # --foo [FOO] foo help
Сообщение по умолчанию можно изменить с помощью аргумента usage:
>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]') >>> parser.add_argument('--foo', nargs='?', help='foo help') >>> parser.add_argument('bar', nargs='+', help='bar help') >>> parser.print_help() # usage: PROG [options] # # positional arguments: # bar bar help # # optional arguments: # -h, --help show this help message and exit # --foo [FOO] foo help
Спецификатор формата %(prog)s доступен для вывода имени программы в сообщениях об использовании скрипта.
description=None.Большинство вызовов конструктора ArgumentParser() будут использовать аргумент description. Этот аргумент дает краткое описание того, что делает программа и как она работает. В справочных сообщениях описание отображается между строкой использования командной строки и справочными сообщениями для различных аргументов:
>>> parser = argparse.ArgumentParser(description='A foo that bars') >>> parser.print_help() # usage: argparse.py [-h] # # A foo that bars # # optional arguments: # -h, --help show this help message and exit
По умолчанию описание будет обернуто в строку так, чтобы оно помещалось в заданное пространство. Чтобы изменить это поведение, смотрите аргумент formatter_class.
epilog=None.Некоторые программы любят выводить дополнительное описание программы после описания аргументов. Такой текст может быть задан с помощью аргумента epilog:
>>> parser = argparse.ArgumentParser( ... description='A foo that bars', ... epilog="And that's how you'd foo a bar") >>> parser.print_help() # usage: argparse.py [-h] # # A foo that bars # # optional arguments: # -h, --help show this help message and exit # # And that's how you'd foo a bar
Как и в случае с аргументом description, epilog по умолчанию заключен в строку, но это поведение можно настроить с помощью аргумента formatter_class для ArgumentParser.
parents=[].Иногда несколько парсеров могут использовать общий набор опций командной строки. Вместо того чтобы повторять определения этих параметров, можно использовать один синтаксический анализатор со всеми общими параметрами и передать их в аргумент parents. Аргумент parents принимает список объектов из родительского ArgumentParser, собирает из него все позиционные и необязательные параметры и добавляет их действия в новый создаваемый объект ArgumentParser:
>>> parent_parser = argparse.ArgumentParser(add_help=False) >>> parent_parser.add_argument('--parent', type=int) >>> foo_parser = argparse.ArgumentParser(parents=[parent_parser]) >>> foo_parser.add_argument('foo') >>> foo_parser.parse_args(['--parent', '2', 'XXX']) # Namespace(foo='XXX', parent=2) >>> bar_parser = argparse.ArgumentParser(parents=[parent_parser]) >>> bar_parser.add_argument('--bar') >>> bar_parser.parse_args(['--bar', 'YYY']) # Namespace(bar='YYY', parent=None)
Обратите внимание, что в большинстве родительских парсеров аргумент add_help=False. В противном случае ArgumentParser увидит два параметра -h/--help (один в родительском и один в дочернем) и вызовет ошибку.
Примечание. Необходимо полностью инициализировать парсеры, прежде чем передавать их через аргумент parent. Если изменить родительские парсеры после дочернего парсера, то эти изменения не будут отражены в дочернем парсере.
formatter_class=argparse.HelpFormatter.Объекты ArgumentParser позволяют настроить форматирование справки, указав альтернативный класс форматирования. В настоящее время существует четыре таких класса:
argparse.RawDescriptionHelpFormatter,argparse.RawTextHelpFormatter,argparse.ArgumentDefaultsHelpFormatter,argparse.MetavarTypeHelpFormatter.Классы форматирования RawDescriptionHelpFormatter и RawTextHelpFormatter обеспечивают больший контроль над отображением текстовых описаний. По умолчанию объекты ArgumentParser переносят текст описания и эпилога в справочные сообщения командной строки:
>>> parser = argparse.ArgumentParser( ... prog='PROG', ... description='''this description ... was indented weird ... but that is okay''', ... epilog=''' ... likewise for this epilog whose whitespace will ... be cleaned up and whose words will be wrapped ... across a couple lines''') >>> parser.print_help() # usage: PROG [-h] # # this description was indented weird but that is okay # # optional arguments: # -h, --help show this help message and exit # # likewise for this epilog whose whitespace will be cleaned up and whose words # will be wrapped across a couple lines
Передача класса RawDescriptionHelpFormatter через аргумент formatter_class указывает на то, что описание и эпилог уже правильно отформатированы и не должны быть завернуты в строку:
>>> parser = argparse.ArgumentParser( ... prog='PROG', ... formatter_class=argparse.RawDescriptionHelpFormatter, ... description=textwrap.dedent('''\ ... Please do not mess up this text! ... -------------------------------- ... I have indented it ... exactly the way ... I want it ... ''')) >>> parser.print_help() # usage: PROG [-h] # # Please do not mess up this text! # -------------------------------- # I have indented it # exactly the way # I want it # # optional arguments: # -h, --help show this help message and exit
Класс форматирования RawTextHelpFormatter сохраняет пробелы для всех видов текста справки, включая описания аргументов. Однако несколько новых строк заменяются одной. Если необходимо сохранить несколько пустых строк, то добавьте пробелы между символами новой строки.
Класс форматирования ArgumentDefaultsHelpFormatter автоматически добавляет информацию о значениях по умолчанию в каждое из справочных сообщений аргумента:
>>> parser = argparse.ArgumentParser( ... prog='PROG', ... formatter_class=argparse.ArgumentDefaultsHelpFormatter) >>> parser.add_argument('--foo', type=int, default=42, help='FOO!') >>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!') >>> parser.print_help() # usage: PROG [-h] [--foo FOO] [bar ...] # # positional arguments: # bar BAR! (default: [1, 2, 3]) # # optional arguments: # -h, --help show this help message and exit # --foo FOO FOO! (default: 42)
Класс форматирования MetavarTypeHelpFormatter в качестве отображаемого имени для значений параметров использует тип параметра каждого аргумента, вместо использования аргумента метода dest, как это делает обычный форматер:
>>> parser = argparse.ArgumentParser( ... prog='PROG', ... formatter_class=argparse.MetavarTypeHelpFormatter) >>> parser.add_argument('--foo', type=int) >>> parser.add_argument('bar', type=float) >>> parser.print_help() # usage: PROG [-h] [--foo int] float # # positional arguments: # float # # optional arguments: # -h, --help show this help message and exit # --foo int
prefix_chars='-'.Большинство параметров командной строки будут использовать символ '-' в качестве префикса, например -f/--foo. Парсеры, которым необходимо поддерживать разные или дополнительные символы префикса, например для таких параметров, как +f или /foo, их можно указать с помощью аргумента prefix_chars конструктора ArgumentParser():
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+') >>> parser.add_argument('+f') >>> parser.add_argument('++bar') >>> parser.parse_args('+f X ++bar Y'.split()) # Namespace(bar='Y', f='X')
Аргумент prefix_chars по умолчанию равен '-'. Если указать набор символов, не включающий '-', то параметры -f/--foo будут запрещены.
fromfile_prefix_chars=None.Иногда, например, при работе с особенно длинными списками аргументов, может иметь смысл сохранить список аргументов в файле, а не вводить его в командной строке. Если аргумент fromfile_prefix_chars передан конструктору argparse.ArgumentParser, то аргументы, начинающиеся с любого из указанных символов, будут рассматриваться как файлы и будут заменены содержащимися в них аргументами. Например:
>>> with open('args.txt', 'w') as fp: ... fp.write('-f\nbar') >>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@') >>> parser.add_argument('-f') >>> parser.parse_args(['-f', 'foo', '@args.txt']) # Namespace(f='bar')
Аргументы, считываемые из файла, по умолчанию должны быть по одному в каждой строке (но смотрите также метод parser.convert_arg_line_to_args()) и обрабатываются так, как если бы они находились в командной строке в том же месте, что и исходный аргумент ссылки на файл. Так, в приведенном выше примере выражение ['-f', 'foo', '@args.txt'] считается эквивалентным выражению ['-f', 'foo', '-f', 'bar'].
Аргумент fromfile_prefix_chars по умолчанию равен None и означает, что аргументы никогда не будут рассматриваться как ссылки на файлы.
Класс ArgumentParser использует кодировку файловой системы и обработчик ошибок для чтения файла, содержащего аргументы.
Изменено в Python 3.12: Класс
ArgumentParserизменил кодировку и ошибки для чтения файлов аргументов со стандартных (например,locale.getpreferredencoding(False)и"strict") на кодировку файловой системы и обработчик ошибок. Файл аргументов должен быть закодирован в UTF-8 вместо кодовой страницы ANSI в Windows.
argument_default=None.Как правило, значения аргументов по умолчанию задаются либо путем передачи значения по умолчанию в метод parser.add_argument(), либо путем вызова методов parser.set_defaults() с определенным набором пар имя-значение. Но иногда может быть полезно указать для аргументов единственное значение по умолчанию для всего парсера. Это можно сделать, передав аргумент argument_default. Например, чтобы глобально подавить создание атрибутов при вызовах parser.parse_args(), мы присвоим argument_default=SUPPRESS:
>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS) >>> parser.add_argument('--foo') >>> parser.add_argument('bar', nargs='?') >>> parser.parse_args(['--foo', '1', 'BAR']) # Namespace(bar='BAR', foo='1') >>> parser.parse_args([]) # Namespace()
conflict_handler='error'.Объекты ArgumentParser не допускают двух действий с одной и той же строкой параметров. По умолчанию, если предпринимается попытка создать аргумент с уже используемой строкой параметров, то объекты ArgumentParser вызывают исключение ArgumentError:
>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('-f', '--foo', help='old foo help') >>> parser.add_argument('--foo', help='new foo help') # Traceback (most recent call last): # .. # ArgumentError: argument --foo: conflicting option string(s): --foo
Иногда, при использовании параметров родительских парсеров может быть полезно просто переопределить некоторые родительские аргументы с той же строкой опций. Чтобы получить такое поведение, передайте в аргумент conflict_handler значение 'resolve':
>>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve') >>> parser.add_argument('-f', '--foo', help='old foo help') >>> parser.add_argument('--foo', help='new foo help') >>> parser.print_help() # usage: PROG [-h] [-f FOO] [--foo FOO] # # optional arguments: # -h, --help show this help message and exit # -f FOO old foo help # --foo FOO new foo help
Обратите внимание, что объекты ArgumentParser удаляют действие только в том случае, если все его строки параметров переопределены. Итак, в приведенном выше примере старое действие -f/--foo сохраняется как действие -f, потому что была переопределена только строка параметра --foo.
add_help=True.По умолчанию объекты ArgumentParser добавляют опцию, которая просто отображает справочное сообщение синтаксического анализатора. Например, рассмотрим файл с именем myprogram.py содержащий следующий код:
# myprogram.py import argparse parser = argparse.ArgumentParser() parser.add_argument('--foo', help='foo help') args = parser.parse_args()
Если в командной строке задано значение -h или --help, то будет напечатана справка:
$ python myprogram.py --help usage: myprogram.py [-h] [--foo FOO] optional arguments: -h, --help show this help message and exit --foo FOO foo help
Иногда может оказаться полезным отключить добавление опции справки. Это может быть достигнуто путем передачи add_help=False:
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False) >>> parser.add_argument('--foo', help='foo help') >>> parser.print_help() # usage: PROG [--foo FOO] # # optional arguments: # --foo FOO foo help
Параметр справки обычно имеет вид -h/--help. Исключением из этого правила является то, что prefix_chars указан и не включает символ '-', тогда -h и --help не являются допустимыми опциями. В этом случае первый символ в prefix_chars используется для префикса параметров справки:
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/') >>> parser.print_help() # usage: PROG [+h] # # optional arguments: # +h, ++help show this help message and exit
allow_abbrev=True.Обычно, при передаче списка аргументов методу parser.parse_args(), он распознает сокращения длинных параметров.
Эту функцию можно отключить, установив для allow_abbrev значение False:
>>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False) >>> parser.add_argument('--foobar', action='store_true') >>> parser.add_argument('--foonley', action='store_false') >>> parser.parse_args(['--foon']) # usage: PROG [-h] [--foobar] [--foonley] # PROG: error: unrecognized arguments: --foon
exit_on_error=True.Новое в Python 3.9.
Обычно, когда методу parser.parse_args() передается недопустимый список параметров командной строки, то вызов завершается с информацией об ошибке.
Если пользователь хочет отлавливать ошибки вручную, то эту функцию можно включить, установив для exit_on_error значение False:
>>> parser = argparse.ArgumentParser(exit_on_error=False) >>> parser.add_argument('--integers', type=int) # _StoreAction(option_strings=['--integers'], dest='integers', nargs=None, # const=None, default=None, type=<class 'int'>, # choices=None, help=None, metavar=None) >>> try: ... parser.parse_args('--integers a'.split()) ... except argparse.ArgumentError: ... print('Catching an argumentError') ... # Catching an argumentError