import argparse parser = argparse.ArgumentParser() parser.add_argument(name or flags...[, action][, nargs][, const] [, default][, type][, choices][, required] [, help][, metavar][, dest])
name or flags - или имя, или список строк опций, например foo или -f, --foo,action - основной тип действия, которое необходимо выполнить,nargs - количество параметров командной строки, которые следует использовать,const - постоянное значение, требуемое некоторыми action и nargs,default - значение, полученное, если опция отсутствует в командной строке,type - тип, в который должен быть преобразован параметр/опция командной строки,choices - контейнер допустимых значений для параметра/опции,required - можно ли опустить параметр командной строки (только для опций),help - краткое описание того, что делает параметр/опция,metavar - имя параметра/опции в сообщениях об использовании,dest - имя параметра/опции, которое будет добавлено к объекту.Метод add_argument() объекта ArgumentParser определяет, как следует анализировать один аргумент командной строки. Каждый параметр имеет свое собственное более подробное описание ниже.
name or flags.Метод parser.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
action.Объекты ArgumentParser связывают аргументы командной строки с действиями. Эти действия могут делать практически все что угодно со связанными с ними аргументами командной строки, хотя большинство действий просто добавляют атрибут к объекту, который будет возвращать метод parser.parse_args(). Ключевой аргумент action определяет, как следует обрабатывать переданные параметры в командную строку.
Предлагаемые действия:
'store' - просто сохраняет значение аргумента. Это действие по умолчанию. Например:
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo') >>> parser.parse_args('--foo 1'.split()) # Namespace(foo='1')
'store_const' - сохраняет значение, указанное ключевым аргументом const. Действие 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 в вызове метода parser.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' - сохраняет список и расширяет значение каждого параметра командной строки до списка. Пример использования:
Новое в Python 3.8.
>>> 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'])
Также можно указать произвольное действие, передав подкласс argparse.Action или другой объект, реализующий тот же интерфейс. Класс argparse.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)
Аргументы
type,choices, иmetavarв классеargparse.BooleanOptionalActionустарели и будут удалены в версии Python 3.14
Рекомендуемый способ создания настраиваемого действия это расширить подкласс argparse.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(FooAction, self).__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')
nargs.Объекты 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='*', но имеет смысл присваивать несколько дополнительных значений одному параметру командной строки. Например:
>>> 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 не указан, то количество используемых аргументов определяется действием. Это означает, что будет использован одно значение параметра командной строки и будет создан один элемент (не список).
const.Аргумент const метода parser.add_argument() используется для хранения постоянных значений, которые не считываются из командной строки, но требуются для различных действий объекту ArgumentParser.
Два наиболее распространенных его использования:
Когда метод add_argument() вызывается с действием action='store_const' или action='append_const'. Эти действия добавляют значение const к одному из атрибутов объекта, возвращаемого методом parse_args(). Примеры смотрите в описании action.
Когда метод add_argument() вызывается со строками параметров (например -f или --foo) и nargs='?'. Это создает необязательный параметр командной строки, за которым может следовать ноль или одно значение этого параметра. Если при синтаксическом анализе командной строки встречается этот параметр командной строки без значения, следующего за ним, то вместо него будет принято значение const. Примеры смотрите в описании nargs.
Для действий store_const и append_const необходимо указать ключевой аргумент const. Для других действий по умолчанию установлено значение None.
default.Все необязательные параметры и некоторые позиционные параметры командной строки могут быть опущены. Если какой либо параметр отсутствует в командной строке, то его значение по умолчанию будет равно None.
Аргумент default для метода parser.add_argument() указывает, какое значение следует использовать, если данный параметр командной строки отсутствует. Если в командной строке отсутствует строка параметра, то для необязательных параметров используется значение из аргумента default:
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', default=42) >>> parser.parse_args(['--foo', '2']) # Namespace(foo='2') >>> parser.parse_args([]) # Namespace(foo=42)
Если значением по умолчанию default является строка, то синтаксический анализатор обрабатывает это значение, как если бы оно передавалось из командной строки. В частности, перед установкой атрибута в возвращаемое значение пространства имен, синтаксический анализатор применяет аргумент преобразования типа type, если он предоставлен. В противном случае парсер использует значение как есть:
>>> 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')
type.По умолчанию объекты ArgumentParser считывают значения параметров командной строки как простые строки. Довольно часто считанное значение параметра командной строки следует интерпретировать как другой тип, например float или int. Аргумент type метода add_argument() позволяет выполнять любую необходимую проверку и преобразование типов. Значением аргумента type могут быть как встроенные типы и так и встроенные функции:
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('foo', type=int) >>> parser.add_argument('bar', type=open) >>> parser.parse_args('2 temp.txt'.split()) # Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)
Информацию о том, когда аргумент type применяется к значениям default смотрите в описании ключевого аргумента default.
Чтобы упростить использование различных типов файлов, модуль argparse предоставляет фабричный argparse.FileType, который принимает аргументы mode, bufsize, encoding и errors функции open(). Например argparse.FileType('w') можно использовать для создания файла с возможностью записи:
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('bar', type=argparse.FileType('w')) >>> parser.parse_args(['out.txt']) # Namespace(bar=<_io.TextIOWrapper name='out.txt' encoding='UTF-8'>)
Аргумент type может принимать любой вызываемый объект, который принимает единственный строковый аргумент и возвращает преобразованное значение:
>>> def perfect_square(string): ... value = int(string) ... sqrt = math.sqrt(value) ... if sqrt != int(sqrt): ... msg = "%r is not a perfect square" % string ... raise argparse.ArgumentTypeError(msg) ... return value ... >>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('foo', type=perfect_square) >>> parser.parse_args(['9']) # Namespace(foo=9) >>> parser.parse_args(['7']) # usage: PROG [-h] foo # PROG: error: argument foo: '7' is not a perfect square
Ключевой аргумент choices, который просто проверяет диапазон значений, может быть более удобен, чем проверка типа:
>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('foo', type=int, choices=range(5, 10)) >>> parser.parse_args(['7']) Namespace(foo=7) >>> parser.parse_args(['11']) usage: PROG [-h] {5,6,7,8,9} PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)
choices.Некоторые параметры командной строки необходимо выбирать из ограниченного набора значений. С этой задачей можно справиться, передав объект-контейнер в ключевому аргументу choices метода parser.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 должен соответствовать указанному в аргументе type:
>>> 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)
В качестве контейнера можно использовать все объекты списков, объекты множеств и настраиваемые контейнеры. Сюда входит enum.Enum, который можно использовать для ограничения выбора значений.
>>> from enum import Enum >>> class GameMove(Enum): ... ROCK = 'rock' ... PAPER = 'paper' ... SCISSORS = 'scissors' ... >>> parser = argparse.ArgumentParser(prog='game.py') >>> parser.add_argument('move', type=GameMove, choices=GameMove) >>> parser.parse_args(['rock']) # Namespace(move=<GameMove.ROCK: 'rock'>)
required.Как правило, модуль 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
Как показывает пример, если опция отсутствует в командной строке и отмечена как обязательная, то метод parse_args() сообщит об ошибке.
Примечание. Обязательные параметры обычно считаются плохим тоном и поэтому их следует по возможности избегать.
help.Значение аргумента help - это строка, содержащая краткое описание параметра командной строки. Когда пользователь запрашивает помощь (обычно с помощью -h или --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 # # optional arguments: # -h, --help show this help message and exit # --foo foo the bars before frobbling
Строки справки могут включать в себя различные описатели формата, чтобы избежать повторения таких вещей, как имя программы или значение 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) # # optional arguments: # -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] # # optional arguments: # -h, --help show this help message and exit
metavar.Когда объект argparse.ArgumentParser генерирует справочные сообщения, то ему нужно каким-то образом ссылаться на каждый ожидаемый аргумент. По умолчанию объекты argparse.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 # # optional arguments: # -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 # # optional arguments: # -h, --help show this help message and exit # --foo YYY
Обратите внимание, что metavar изменяет только отображаемое имя, а имя атрибута в объекте parser.parse_args() по-прежнему определяется значением dest.
Различные значения аргумента nargs могут привести к тому, что аргумент metavar будет использоваться несколько раз. Предоставление кортежа для 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] # # optional arguments: # -h, --help show this help message and exit # -x X X # --foo bar baz
dest.Большинство действий 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')