argparse — Анализатор параметров командной строки, аргументов и вложенных команд¶

Создание синтаксического анализатора¶

Первым шагом в использовании argparse является создание объекта ArgumentParser:

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

Объект ArgumentParser будет содержать всю информацию, необходимую для разбора командной строки на типы данных Python.

Добавление аргументов¶

Заполнение ArgumentParser информацией об аргументах программы выполняется путем вызова метода add_argument(). Как правило, эти вызовы сообщают ArgumentParser, как использовать строки командной строки и преобразовать их в объекты. Эта информация сохраняется и используется при вызове parse_args(). Например:

>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
...                     help='an integer for the accumulator')
>>> parser.add_argument('--sum', dest='accumulate', action='store_const',
...                     const=sum, default=max,
...                     help='sum the integers (default: find the max)')

Позже вызов parse_args() вернет объект с двумя атрибутами: integers и accumulate. Атрибутом integers будет список из одного или нескольких целых чисел, а атрибутом accumulate будет либо функция sum(), если в командной строке было указано --sum, либо max() функционируйте, если этого не было.

Разбор аргументов¶

ArgumentParser анализирует аргументы с помощью метода parse_args(). Это проверит командную строку, преобразует каждый аргумент в соответствующий тип и затем вызовет соответствующее действие. В большинстве случаев это означает, что простой объект Namespace будет создан из атрибутов, проанализированных из командной строки:

>>> parser.parse_args(['--sum', '7', '-1', '42'])
Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])

В сценарии parse_args() обычно вызывается без аргументов, а ArgumentParser автоматически определяет аргументы командной строки из sys.argv.

программа¶

По умолчанию ArgumentParser объекты используют sys.argv[0] для определения способа отображения названия программы в справочных сообщениях. Это значение по умолчанию почти всегда желательно, поскольку оно позволяет привести справочные сообщения в соответствие с тем, как программа была вызвана в командной строке. Например, рассмотрим файл с именем 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]

options:
 -h, --help  show this help message and exit
 --foo FOO   foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

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

Чтобы изменить это поведение по умолчанию, можно указать другое значение, используя аргумент prog= вместо ArgumentParser:

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

options:
 -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]

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

использование¶

По умолчанию 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

options:
 -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

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

Спецификатор формата %(prog)s доступен для заполнения названия программы в сообщениях об использовании.

описание¶

В большинстве вызовов конструктора ArgumentParser используется аргумент ключевого слова description=. Этот аргумент содержит краткое описание того, что делает программа и как она работает. В справочных сообщениях описание различных аргументов отображается между строкой использования командной строки и справочными сообщениями:

>>> parser = argparse.ArgumentParser(description='A foo that bars')
>>> parser.print_help()
usage: argparse.py [-h]

A foo that bars

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

По умолчанию описание будет заключено в строку таким образом, чтобы оно помещалось в пределах заданного пространства. Чтобы изменить это поведение, обратитесь к аргументу formatter_class.

эпилог¶

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

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

A foo that bars

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

And that's how you'd foo a bar

Как и в случае с аргументом description, текст epilog= по умолчанию заключен в строку, но это поведение можно изменить с помощью аргумента formatter_class на ArgumentParser.

родители¶

Иногда несколько синтаксических анализаторов используют общий набор аргументов. Вместо того, чтобы повторять определения этих аргументов, можно использовать один синтаксический анализатор со всеми общими аргументами и переданным в parents= аргументом в ArgumentParser. Аргумент parents= принимает список объектов ArgumentParser, собирает из них все позиционные и необязательные действия и добавляет эти действия к создаваемому объекту ArgumentParser:

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

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

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

Обратите внимание, что большинство родительских синтаксических анализаторов будут указывать add_help=False. В противном случае ArgumentParser будет отображаться два параметра -h/--help (один в родительском и один в дочернем параметрах) и выдаст ошибку.

форматировщик_класс¶

ArgumentParser объекты позволяют настраивать форматирование справки, указывая альтернативный класс форматирования. В настоящее время существует четыре таких класса:

class argparse.RawDescriptionHelpFormatter¶

class argparse.RawTextHelpFormatter¶

class argparse.ArgumentDefaultsHelpFormatter¶

class 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

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

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

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

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

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

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

RawTextHelpFormatter содержит пробелы для всех видов справочного текста, включая описания аргументов. Однако несколько новых строк заменяются одной. Если вы хотите сохранить несколько пустых строк, добавьте пробелы между новыми строками.

ArgumentDefaultsHelpFormatter автоматически добавляет информацию о значениях по умолчанию к каждому из справочных сообщений по аргументам:

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

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

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

MetavarTypeHelpFormatter использует имя аргумента type для каждого аргумента в качестве отображаемого имени для его значений (вместо использования dest, как это делает обычный форматировщик):

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

positional arguments:
  float

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

префикс_чары¶

Большинство параметров командной строки будут использовать - в качестве префикса, например -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 из файла с префиксом¶

Иногда, когда имеешь дело с особенно длинным списком аргументов, может иметь смысл сохранить список аргументов в файле, а не вводить его в командной строке. Если аргумент fromfile_prefix_chars= задан конструктору 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')

Аргументы, считываемые из файла, по умолчанию должны быть по одному в строке (но смотрите также convert_arg_line_to_args()) и обрабатываться так, как если бы они находились в том же месте, что и исходный аргумент, ссылающийся на файл, в командной строке. Таким образом, в приведенном выше примере выражение ['-f', 'foo', '@args.txt'] считается эквивалентным выражению ['-f', 'foo', '-f', 'bar'].

Значение аргумента fromfile_prefix_chars= по умолчанию равно None, что означает, что аргументы никогда не будут рассматриваться как ссылки на файлы.

аргумент_default¶

Как правило, значения аргументов по умолчанию задаются либо путем передачи значения по умолчанию в add_argument(), либо путем вызова методов set_defaults() с определенным набором пар имя-значение. Однако иногда может быть полезно указать одно значение по умолчанию для аргументов в рамках всего синтаксического анализатора. Этого можно добиться, передав argument_default= аргумент ключевого слова в ArgumentParser. Например, чтобы глобально запретить создание атрибутов при вызовах parse_args(), мы задаем argument_default=SUPPRESS:

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

разрешить_аббрев¶

Обычно, когда вы передаете список аргументов методу parse_args() из ArgumentParser, он содержит recognizes abbreviations длинных параметра.

Эту функцию можно отключить, установив для 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

обработчик конфликтов¶

ArgumentParser объекты не допускают выполнения двух действий с одной и той же строкой параметров. По умолчанию ArgumentParser объекты генерируют исключение, если предпринимается попытка создать аргумент со строкой параметров, которая уже используется:

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

Иногда (например, при использовании parents) может быть полезно просто переопределить все более старые аргументы с помощью той же строки параметров. Чтобы добиться такого поведения, значение 'resolve' может быть передано в аргумент conflict_handler= параметра ArgumentParser:

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

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

Обратите внимание, что объекты ArgumentParser удаляют действие только в том случае, если все его строки параметров переопределены. Итак, в приведенном выше примере старое действие -f/--foo сохраняется как действие -f, поскольку была переопределена только строка параметров --foo.

добавить_помощь¶

По умолчанию объекты ArgumentParser добавляют опцию, которая просто отображает справочное сообщение синтаксического анализатора. Например, рассмотрим файл с именем myprogram.py, содержащий следующий код:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()

Если в командной строке указано значение -h или --help, то будет выведена справка ArgumentParser:

$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

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

Иногда может оказаться полезным отключить добавление этой опции справки. Этого можно добиться, передав False в качестве аргумента add_help= в ArgumentParser:

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

options:
 --foo FOO  foo help

Опция справки обычно имеет значение -h/--help. Исключением из этого правила является случай, когда prefix_chars= указан и не включает -, и в этом случае -h и --help являются недопустимыми параметрами. В этом случае первый символ в prefix_chars используется для префикса параметров справки:

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

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

выход_на_ошибку¶

Обычно, когда вы передаете список недопустимых аргументов методу parse_args() из ArgumentParser, он завершает работу с информацией об ошибке.

Если пользователь хочет отслеживать ошибки вручную, эту функцию можно включить, установив для 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

название или флаги¶

Метод add_argument() должен знать, ожидается ли необязательный аргумент, например -f или --foo, или позиционный аргумент, например список имен файлов. Поэтому первые аргументы, передаваемые в add_argument(), должны быть либо набором флагов, либо простым именем аргумента.

Например, необязательный аргумент может быть создан следующим образом:

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

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

>>> parser.add_argument('bar')

При вызове parse_args() необязательные аргументы будут идентифицированы префиксом -, а остальные аргументы будут считаться позиционными:

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

действие¶

ArgumentParser объекты связывают аргументы командной строки с действиями. Эти действия могут выполнять практически все действия с аргументами командной строки, связанными с ними, хотя большинство действий просто добавляют атрибут к объекту, возвращаемому с помощью parse_args(). Аргумент ключевого слова action указывает, как следует обрабатывать аргументы командной строки. Предлагаемые действия следующие:

• 'store' - При этом просто сохраняется значение аргумента. Это действие по умолчанию. Например:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--foo')
  >>> parser.parse_args('--foo 1'.split())
  Namespace(foo='1')
  

• 'store_const' - Здесь хранится значение, указанное в аргументе ключевого слова const; обратите внимание, что значение ключевого слова const по умолчанию равно None. Действие 'store_const' чаще всего используется с необязательными аргументами, которые задают какой-либо флаг. Например:

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

• 'store_true' и 'store_false' - это частные случаи 'store_const', используемые для хранения значений True и False соответственно. Кроме того, они создают значения по умолчанию False и True соответственно. Например:

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

• 'append' - При этом сохраняется список и к нему добавляется значение каждого аргумента. Полезно разрешить указывать параметр несколько раз. Если значение по умолчанию непустое, в анализируемом значении параметра будут присутствовать элементы по умолчанию, а после этих значений по умолчанию будут добавлены любые значения из командной строки. Пример использования:

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

• 'append_const' - При этом сохраняется список и к списку добавляется значение, указанное в аргументе ключевого слова const; обратите внимание, что значение ключевого слова const по умолчанию равно None. Действие 'append_const' обычно полезно, когда нескольким аргументам необходимо сохранить константы в одном списке. Например:

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

• 'count' - Подсчитывается количество раз, когда встречается ключевое слово-аргумент. Например, это полезно для повышения уровня детализации:

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

  Обратите внимание, что значением по умолчанию будет None, если явно не задано значение 0.

• 'help' - При этом выводится полное справочное сообщение для всех параметров текущего синтаксического анализатора, а затем завершается работа. По умолчанию в синтаксический анализатор автоматически добавляется действие справки. Подробнее о том, как создаются выходные данные, смотрите в ArgumentParser.

• 'version' - Это ожидает version= аргумент ключевого слова в вызове add_argument() и выводит информацию о версии и завершает работу при вызове:

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

• 'extend' - При этом сохраняется список и каждое значение аргумента добавляется к списку. Пример использования:

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

  Добавлено в версии 3.8.

Вы также можете указать произвольное действие, передав подкласс Action или другой объект, реализующий тот же интерфейс. Параметр BooleanOptionalAction доступен в argparse и добавляет поддержку логических действий, таких как --foo и --no-foo:

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

Рекомендуемый способ создания пользовательского действия - расширить Action, переопределив метод __call__ и, при необходимости, методы __init__ и format_usage.

Пример пользовательского действия:

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

Для получения более подробной информации смотрите Action.

нарги¶

Объекты ArgumentParser обычно связывают один аргумент командной строки с одним действием, которое необходимо выполнить. Аргумент ключевого слова nargs связывает различное количество аргументов командной строки с одним действием. Поддерживаемыми значениями являются:

• N (целое число). N аргументы из командной строки будут собраны в список. Например:

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

  Обратите внимание, что nargs=1 создает список из одного элемента. Это отличается от значения по умолчанию, при котором элемент создается сам по себе.

• '?'. По возможности, один аргумент будет использоваться из командной строки и выводиться как отдельный элемент. Если аргумент командной строки отсутствует, будет выводиться значение из default. Обратите внимание, что для необязательных аргументов существует дополнительный вариант - строка параметра присутствует, но за ней не следует аргумент командной строки. В этом случае будет получено значение из const. Несколько примеров, иллюстрирующих это:

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

  Одним из наиболее распространенных применений nargs='?' является разрешение дополнительных входных и выходных файлов:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
  ...                     default=sys.stdin)
  >>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
  ...                     default=sys.stdout)
  >>> parser.parse_args(['input.txt', 'output.txt'])
  Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,
            outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)
  >>> parser.parse_args([])
  Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,
            outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)
  

• '*'. Все имеющиеся аргументы командной строки собраны в список. Обратите внимание, что обычно не имеет особого смысла использовать более одного позиционного аргумента с nargs='*', но возможно использование нескольких необязательных аргументов с nargs='*'. Например:

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

• '+'. Как и в случае с '*', все имеющиеся аргументы командной строки собраны в список. Кроме того, если отсутствует хотя бы один аргумент командной строки, будет выдано сообщение об ошибке. Например:

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

Если аргумент ключевого слова nargs не указан, количество используемых аргументов определяется параметром action. Обычно это означает, что будет использован один аргумент командной строки и будет создан один элемент (не список).

постоянный¶

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

• Когда add_argument() вызывается с помощью action='store_const' или action='append_const'. Эти действия добавляют значение const к одному из атрибутов объекта, возвращаемых с помощью parse_args(). Примеры приведены в описании действия. Если const не указано в add_argument(), оно получит значение по умолчанию None.

• Когда add_argument() вызывается со строками параметров (например, -f или --foo) и nargs='?'. Это создает необязательный аргумент, за которым могут следовать ноль или один аргумент командной строки. При анализе командной строки, если встречается строка параметров, за которой не следует аргумент командной строки, значение const будет приниматься за None. Примеры смотрите в описании nargs.

по умолчанию¶

Все необязательные аргументы и некоторые позиционные аргументы могут быть опущены в командной строке. Аргумент ключевого слова default в add_argument(), значение которого по умолчанию равно None, указывает, какое значение следует использовать, если аргумент командной строки отсутствует. В качестве необязательных аргументов используется значение default, если строка параметра отсутствовала в командной строке:

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

Если для целевого пространства имен уже установлен атрибут, действие по умолчанию не перезапишет его:

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

Если значение default является строкой, синтаксический анализатор анализирует значение так, как если бы оно было аргументом командной строки. В частности, синтаксический анализатор применяет любой аргумент преобразования type, если он указан, перед установкой атрибута для возвращаемого значения Namespace. В противном случае синтаксический анализатор использует значение как есть:

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

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

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

Указание default=argparse.SUPPRESS не приводит к добавлению атрибута, если аргумент командной строки отсутствовал:

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

тип¶

По умолчанию синтаксический анализатор считывает аргументы командной строки в виде простых строк. Однако довольно часто вместо этого строку командной строки следует интерпретировать как другой тип, например float или int. Ключевое слово type для add_argument() позволяет выполнять любую необходимую проверку типов и преобразования типов.

Если ключевое слово type используется с ключевым словом default, то преобразователь типов применяется только в том случае, если по умолчанию используется строка.

Аргументом type может быть любой вызываемый объект, который принимает одну строку. Если функция вызывает ArgumentTypeError, TypeError, или ValueError, исключение перехватывается и отображается сообщение об ошибке в удобном формате. Другие типы исключений не обрабатываются.

В качестве преобразователей типов можно использовать обычные встроенные типы и функции:

import argparse
import pathlib

parser = argparse.ArgumentParser()
parser.add_argument('count', type=int)
parser.add_argument('distance', type=float)
parser.add_argument('street', type=ascii)
parser.add_argument('code_point', type=ord)
parser.add_argument('source_file', type=open)
parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
parser.add_argument('datapath', type=pathlib.Path)

Также можно использовать пользовательские функции:

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

Функция bool() не рекомендуется в качестве преобразователя типов. Все, что она делает, - это преобразует пустые строки в False, а непустые строки в True. Обычно это не то, что требуется.

В общем, ключевое слово type является удобным и должно использоваться только для простых преобразований, которые могут вызвать только одно из трех поддерживаемых исключений. Все, что связано с более интересной обработкой ошибок или управлением ресурсами, должно выполняться ниже по потоку после анализа аргументов.

Например, преобразования в JSON или YAML содержат сложные случаи ошибок, которые требуют более подробной отчетности, чем та, которую можно получить с помощью ключевого слова type. JSONDecodeError было бы неправильно отформатировано, а исключение FileNotFoundError вообще не обрабатывалось бы.

Даже FileType имеет свои ограничения для использования с ключевым словом type. Если в одном из аргументов используется FileType, а затем последующий аргумент не выполняется, выводится сообщение об ошибке, но файл не закрывается автоматически. В этом случае было бы лучше дождаться завершения работы синтаксического анализатора, а затем использовать инструкцию with для управления файлами.

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

выбор¶

Некоторые аргументы командной строки следует выбирать из ограниченного набора значений. Их можно обработать, передав объект sequence в качестве ключевого слова choices в add_argument(). При анализе командной строки будут проверены значения аргументов, и будет выведено сообщение об ошибке, если аргумент не был одним из допустимых значений:

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

Обратите внимание, что включение в последовательность choices проверяется после выполнения любых преобразований типов, поэтому тип объектов в последовательности choices должен соответствовать указанному типу:

>>> parser = argparse.ArgumentParser(prog='doors.py')
>>> parser.add_argument('door', type=int, choices=range(1, 4))
>>> print(parser.parse_args(['3']))
Namespace(door=3)
>>> parser.parse_args(['4'])
usage: doors.py [-h] {1,2,3}
doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)

В качестве значения choices может быть передана любая последовательность, поэтому поддерживаются объекты list, объекты tuple и пользовательские последовательности.

Использование enum.Enum не рекомендуется, поскольку трудно контролировать его отображение в использовании, справке и сообщениях об ошибках.

Параметры форматирования переопределяют значение по умолчанию metavar, которое обычно выводится из dest. Обычно это то, что вам нужно, потому что пользователь никогда не видит параметр dest. Если такое отображение нежелательно (возможно, из-за большого количества вариантов), просто укажите явное метаданное.

требуемый¶

В общем, модуль argparse предполагает, что флаги типа -f и --bar указывают на необязательные аргументы, которые всегда можно опустить в командной строке. Чтобы сделать параметр обязательным, True можно указать в качестве ключевого слова required= в качестве аргумента add_argument().:

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

Как показано в примере, если параметр помечен как required, parse_args(), будет выдано сообщение об ошибке, если этот параметр отсутствует в командной строке.

помощь¶

Значение help представляет собой строку, содержащую краткое описание аргумента. Когда пользователь запрашивает помощь (обычно используя -h или --help в командной строке), эти help описания будут отображаться с каждым аргументом:

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', action='store_true',
...                     help='foo the bars before frobbling')
>>> parser.add_argument('bar', nargs='+',
...                     help='one of the bars to be frobbled')
>>> parser.parse_args(['-h'])
usage: frobble [-h] [--foo] bar [bar ...]

positional arguments:
 bar     one of the bars to be frobbled

options:
 -h, --help  show this help message and exit
 --foo   foo the bars before frobbling

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

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

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

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

Поскольку строка справки поддерживает %-форматирование, если вы хотите, чтобы в строке справки отображался литерал %, вы должны экранировать его как %%.

argparse поддерживает отключение записи справки для определенных параметров, установив значение help равным argparse.SUPPRESS:

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

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

метавар¶

Когда ArgumentParser генерирует справочные сообщения, ему нужно каким-то образом ссылаться на каждый ожидаемый аргумент. По умолчанию объекты ArgumentParser используют значение dest в качестве «имени» каждого объекта. По умолчанию для действий с позиционными аргументами напрямую используется значение dest, а для действий с необязательными аргументами значение dest указывается в верхнем регистре. Таким образом, единственный позиционный аргумент с dest='bar' будет называться bar. Единственный необязательный аргумент --foo, за которым должен следовать единственный аргумент командной строки, будет называться FOO. Пример:

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

positional arguments:
 bar

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

Альтернативное имя может быть указано с помощью metavar:

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

positional arguments:
 XXX

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

Обратите внимание, что metavar изменяет только отображаемое имя - имя атрибута для объекта parse_args() по-прежнему определяется значением dest.

Различные значения nargs могут привести к многократному использованию метаданных. При указании кортежа metavar для каждого из аргументов задается различное отображение:

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

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

дест¶

Большинство действий ArgumentParser добавляют некоторое значение в качестве атрибута объекта, возвращаемого parse_args(). Имя этого атрибута определяется ключевым словом dest в аргументе add_argument(). Для действий с позиционными аргументами dest обычно указывается в качестве первого аргумента для add_argument():

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

Для действий с необязательными аргументами значение dest обычно выводится из строк параметров. ArgumentParser генерирует значение dest, беря первую длинную строку параметра и удаляя начальную строку --. Если не было указано ни одной длинной строки параметров, dest будет получено из первой короткой строки параметров путем удаления начального символа -. Все внутренние символы - будут преобразованы в символы _, чтобы убедиться, что строка является допустимым именем атрибута. Приведенные ниже примеры иллюстрируют это поведение:

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

dest позволяет указать пользовательское имя атрибута:

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

Классы действий¶

Классы Action реализуют Action API, вызываемый объект, который возвращает вызываемый объект, обрабатывающий аргументы из командной строки. Любой объект, который следует этому API, может быть передан в качестве параметра action в add_argument().

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

Объекты Action используются ArgumentParser для представления информации, необходимой для анализа одного аргумента из одной или нескольких строк командной строки. Класс Action должен принимать два позиционных аргумента плюс любые аргументы ключевого слова, передаваемые в ArgumentParser.add_argument(), за исключением самого action.

Экземпляры Action (или возвращаемое значение любого вызываемого параметра action) должны иметь определенные атрибуты «dest», «option_strings», «default», «type», «required», «help» и т.д. Самый простой способ убедиться, что эти атрибуты определены, - это вызвать Action.__init__.

Экземпляры Action должны быть доступны для вызова, поэтому подклассы должны переопределять метод __call__, который должен принимать четыре параметра:

• parser - Объект ArgumentParser, который содержит это действие.

• namespace - Объект Namespace, который будет возвращен с помощью parse_args(). Большинство действий добавляют атрибут к этому объекту с помощью setattr().

• values - Соответствующие аргументы командной строки, к которым применяются любые преобразования типов. Преобразования типов задаются с помощью аргумента ключевого слова type в add_argument().

• option_string - Строка параметров, которая использовалась для вызова этого действия. Аргумент option_string является необязательным и будет отсутствовать, если действие связано с позиционным аргументом.

Метод __call__ может выполнять произвольные действия, но обычно устанавливает атрибуты для namespace на основе dest и values.

Подклассы Action могут определять метод format_usage, который не принимает аргументов и возвращает строку, которая будет использоваться при выводе результатов использования программы. Если такой метод не предусмотрен, будет использоваться разумное значение по умолчанию.

Синтаксис значения параметра¶

Метод parse_args() поддерживает несколько способов указания значения параметра (если он используется). В простейшем случае параметр и его значение передаются как два отдельных аргумента:

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

Для длинных параметров (параметры с именами длиннее одного символа) параметр и значение также могут передаваться в качестве одного аргумента командной строки, используя = для их разделения:

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

Для коротких опций (длиной всего в один символ) параметр и его значение могут быть объединены:

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

Несколько коротких опций могут быть объединены вместе, используя только один префикс -, при условии, что значение требуется только для последней опции (или ни для одной из них):

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

Недопустимые аргументы¶

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

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

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

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

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

Аргументы, содержащие -¶

Метод parse_args() пытается выдавать ошибки всякий раз, когда пользователь явно допустил ошибку, но некоторые ситуации по своей сути неоднозначны. Например, аргумент командной строки -1 может быть либо попыткой указать параметр, либо попыткой предоставить позиционный аргумент. Метод parse_args() здесь осторожен: позиционные аргументы могут начинаться с - только в том случае, если они выглядят как отрицательные числа и в синтаксическом анализаторе нет параметров, которые выглядят как отрицательные числа:

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

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

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

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

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

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

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

Если у вас есть позиционные аргументы, которые должны начинаться с - и не выглядеть как отрицательные числа, вы можете вставить псевдоаргумент '--', который сообщает parse_args(), что все, что следует за ним, является позиционным аргументом:

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

Сокращения аргументов (сопоставление префиксов)¶

Метод parse_args() by default позволяет сокращать длинные варианты до префикса, если аббревиатура однозначна (префикс соответствует уникальному варианту).:

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

Для аргументов, которые могут содержать более одного параметра, выдается ошибка. Эту функцию можно отключить, установив для разрешить_аббрев значение False.

За пределами sys.argv¶

Иногда может быть полезно, чтобы ArgumentParser анализировал аргументы, отличные от sys.argv. Этого можно добиться, передав список строк в parse_args(). Это полезно для тестирования в интерактивном приглашении:

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

Объект пространства имен¶

class argparse.Namespace¶

Простой класс, используемый по умолчанию parse_args() для создания объекта, содержащего атрибуты, и его возврата.

Этот класс намеренно прост, это просто подкласс object с удобочитаемым строковым представлением. Если вы предпочитаете иметь представление атрибутов в виде dict, вы можете использовать стандартную идиому Python, vars():

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

Также может оказаться полезным, чтобы атрибуты ArgumentParser присваивались уже существующему объекту, а не новому объекту Namespace. Этого можно достичь, указав аргумент ключевого слова namespace=:

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

Подчиненные команды¶

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

Многие программы разделяют свои функциональные возможности на несколько подкоманд, например, программа svn может вызывать такие подкоманды, как svn checkout, svn update, и svn commit. Разделение функциональности таким образом может быть особенно хорошей идеей, когда программа выполняет несколько разных функций, для которых требуются разные типы аргументов командной строки. ArgumentParser поддерживает создание таких вложенных команд с помощью метода add_subparsers(). Метод add_subparsers() обычно вызывается без аргументов и возвращает специальный объект action. У этого объекта есть единственный метод, add_parser(), который принимает имя команды и любые аргументы конструктора ArgumentParser и возвращает объект ArgumentParser, который может быть изменен как обычно.

Описание параметров:

• title - заголовок для группы синтаксических анализаторов в выводе справки; по умолчанию «подкоманды», если указано описание, в противном случае используется title для позиционных аргументов

• описание - описание для группы вспомогательных анализаторов в выводе справки, по умолчанию None

• prog - информация об использовании, которая будет отображаться с помощью подкоманды help, по умолчанию это название программы и любые позиционные аргументы перед аргументом subparser

• parser_class - класс, который будет использоваться для создания экземпляров вспомогательного синтаксического анализатора, по умолчанию это класс текущего синтаксического анализатора (например, ArgumentParser).

• action - основной тип действия, которое необходимо выполнить при обнаружении этого аргумента в командной строке.

• dest - имя атрибута, под которым будет сохранено имя подкоманды; по умолчанию None и никакое значение не сохраняется.

• required - Должна ли быть указана подкоманда, по умолчанию False (добавлено в 3.7)

• help - справка для группы вспомогательных анализаторов в выводе справки, по умолчанию None

• metavar - строка, представляющая доступные подкоманды в справке; по умолчанию это None и представляет подкоманды в виде {cmd1, cmd2, ..}

Несколько примеров использования:

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

Обратите внимание, что объект, возвращаемый parse_args(), будет содержать атрибуты только для основного синтаксического анализатора и подпараметра, который был выбран в командной строке (и не для каких-либо других подпараметров). Таким образом, в приведенном выше примере, когда указана команда a, присутствуют только атрибуты foo и bar, а когда указана команда b, только foo атрибуты <<<5присутствуют атрибуты >>> и baz.

Аналогичным образом, когда у синтаксического анализатора запрашивается справочное сообщение, будет напечатана только справка для этого конкретного синтаксического анализатора. Справочное сообщение не будет содержать сообщений родительского или родственных синтаксических анализаторов. (Однако справочное сообщение для каждой команды синтаксического анализа можно получить, указав help= в качестве аргумента add_parser(), как указано выше.)

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

positional arguments:
  {a,b}   sub-command help
    a     a help
    b     b help

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

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

positional arguments:
  bar     bar help

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

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

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

Метод add_subparsers() также поддерживает аргументы ключевых слов title и description. При наличии любого из них команды subparsers будут отображаться в своей собственной группе в выводе справки. Например:

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

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

subcommands:
  valid subcommands

  {foo,bar}   additional help

Кроме того, add_parser поддерживает дополнительный аргумент aliases, который позволяет нескольким строкам ссылаться на один и тот же синтаксический анализатор. В этом примере, как и в svn, псевдонимы co используются как сокращение от checkout:

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

Одним из особенно эффективных способов обработки вложенных команд является сочетание использования метода add_subparsers() с вызовами set_defaults(), чтобы каждый синтаксический анализатор знал, какую функцию Python он должен выполнить. Например:

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

Таким образом, вы можете позволить parse_args() выполнять работу по вызову соответствующей функции после завершения разбора аргументов. Связывание функций с подобными действиями, как правило, является самым простым способом обработки различных действий для каждого из ваших анализаторов. Однако, если необходимо проверить имя вызываемого синтаксического анализатора, будет работать аргумент ключевого слова dest для вызова add_subparsers():

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

Изменено в версии 3.7: Новый обязательный аргумент ключевого слова.

Объекты типа файла¶

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

Фабрика FileType создает объекты, которые могут быть переданы в аргумент типа ArgumentParser.add_argument(). Аргументы, имеющие в качестве типа FileType объектов, будут открывать аргументы командной строки в виде файлов с запрошенными режимами, размерами буфера, кодировками и обработкой ошибок (более подробную информацию смотрите в функции open()).:

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

Объекты типа FileType понимают псевдоаргумент '-' и автоматически преобразуют его в sys.stdin для объектов, доступных для чтения FileType, и sys.stdout для объектов, доступных для записи FileType:

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

Изменено в версии 3.4: Добавлены параметры encodings и errors.

Группы аргументов¶

ArgumentParser.add_argument_group(title=None, description=None)¶

По умолчанию ArgumentParser при отображении справочных сообщений аргументы командной строки группируются в «позиционные аргументы» и «параметры». Если концептуальная группировка аргументов лучше, чем по умолчанию, можно создать соответствующие группы, используя метод add_argument_group():

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

group:
  bar    bar help
  --foo FOO  foo help

Метод add_argument_group() возвращает объект argument group, который имеет метод add_argument() точно такой же, как у обычного ArgumentParser. Когда аргумент добавляется в группу, синтаксический анализатор обрабатывает его как обычный аргумент, но отображает аргумент в отдельной группе для справочных сообщений. Метод add_argument_group() принимает аргументы title и description, которые можно использовать для настройки этого отображения:

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

group1:
  group1 description

  foo    foo help

group2:
  group2 description

  --bar BAR  bar help

Обратите внимание, что любые аргументы, которых нет в ваших пользовательских группах, будут возвращены в обычные разделы «позиционные аргументы» и «необязательные аргументы».

Изменено в версии 3.11: Вызов add_argument_group() для группы аргументов не рекомендуется. Эта функция никогда не поддерживалась и не всегда работает корректно. Функция появилась в API случайно, в результате наследования, и в будущем будет удалена.

Взаимное исключение¶

ArgumentParser.add_mutually_exclusive_group(required=False)¶

Создайте взаимоисключающую группу. argparse проследит за тем, чтобы в командной строке присутствовал только один из аргументов во взаимоисключающей группе:

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

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

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

Обратите внимание, что в настоящее время взаимоисключающие группы аргументов не поддерживают аргументы title и description для add_argument_group().

Изменено в версии 3.11: Вызов add_argument_group() или add_mutually_exclusive_group() во взаимоисключающей группе не рекомендуется. Эти функции никогда не поддерживались и не всегда работают корректно. Эти функции появились в API случайно в результате наследования и будут удалены в будущем.

Значения синтаксического анализатора по умолчанию¶

ArgumentParser.set_defaults(**kwargs)¶

В большинстве случаев атрибуты объекта, возвращаемые с помощью parse_args(), будут полностью определены путем проверки аргументов командной строки и действий с аргументами. set_defaults() позволяет добавлять некоторые дополнительные атрибуты, которые определяются без какой-либо проверки командной строки:

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

Обратите внимание, что значения по умолчанию на уровне синтаксического анализатора всегда переопределяют значения по умолчанию на уровне аргументов:

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

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

ArgumentParser.get_default(dest)¶

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

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

Справка по печати¶

В большинстве обычных приложений parse_args() выполняет форматирование и вывод на печать любых сообщений об использовании или ошибках. Однако доступно несколько методов форматирования:

ArgumentParser.print_usage(file=None)¶

Выведите краткое описание того, как следует вызывать ArgumentParser в командной строке. Если предполагается, что file равен None, sys.stdout.

ArgumentParser.print_help(file=None)¶

Распечатайте справочное сообщение, включающее описание использования программы и информацию об аргументах, зарегистрированных с помощью ArgumentParser. Если предполагается, что file равен None, sys.stdout.

Существуют также варианты этих методов, которые просто возвращают строку вместо того, чтобы печатать ее:

ArgumentParser.format_usage()¶

Возвращает строку, содержащую краткое описание того, как следует вызывать ArgumentParser в командной строке.

ArgumentParser.format_help()¶

Возвращает строку, содержащую справочное сообщение, включая описание использования программы и информацию об аргументах, зарегистрированных с помощью ArgumentParser.

Частичный синтаксический анализ¶

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

Иногда скрипт может обрабатывать только несколько аргументов командной строки, передавая остальные аргументы другому скрипту или программе. В таких случаях может быть полезен метод parse_known_args(). Он работает почти так же, как parse_args(), за исключением того, что не выдает ошибку при наличии дополнительных аргументов. Вместо этого он возвращает кортеж из двух элементов, содержащий заполненное пространство имен и список оставшихся строк аргументов.

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

Настройка синтаксического анализа файлов¶

ArgumentParser.convert_arg_line_to_args(arg_line)¶

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

Этот метод принимает единственный аргумент arg_line, который представляет собой строку, считанную из файла аргументов. Он возвращает список аргументов, проанализированных из этой строки. Метод вызывается один раз для каждой строки, считанной из файла аргументов, по порядку.

Полезным вариантом переопределения этого метода является использование каждого слова, разделенного пробелом, в качестве аргумента. В следующем примере показано, как это сделать:

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

Существующие методы¶

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

Этот метод завершает работу программы, завершая ее с указанным статусом, и, если он указан, перед этим выводится сообщение. Пользователь может переопределить этот метод, чтобы выполнить эти действия по-другому:

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

ArgumentParser.error(message)¶

Этот метод выводит сообщение об использовании, включающее сообщение о стандартной ошибке, и завершает работу программы с кодом состояния, равным 2.

Смешанный синтаксический анализ¶

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

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

Ряд команд Unix позволяет пользователю смешивать необязательные аргументы с позиционными. Методы parse_intermixed_args() и parse_known_intermixed_args() поддерживают этот стиль синтаксического анализа.

Эти анализаторы не поддерживают все функции argparse и будут вызывать исключения, если будут использоваться неподдерживаемые функции. В частности, не поддерживаются подпараметры и взаимоисключающие группы, которые включают как параметры, так и позиционные значения.

В следующем примере показана разница между parse_known_args() и parse_intermixed_args(): первый возвращает ['2', '3'] в качестве нерасчлененных аргументов, в то время как второй собирает все позиционные значения в rest.

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

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