argparse
— Parser for command-line options, arguments and sub-commands¶
Нове в версії 3.2.
Вихідний код: Lib/argparse.py
The argparse
module makes it easy to write user-friendly command-line
interfaces. The program defines what arguments it requires, and argparse
will figure out how to parse those out of sys.argv
. The argparse
module also automatically generates help and usage messages and issues errors
when users give the program invalid arguments.
приклад¶
Наступний код є програмою на Python, яка отримує список цілих чисел і створює або суму, або максимум:
import argparse
parser = argparse.ArgumentParser(description='Process some integers.')
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)')
args = parser.parse_args()
print(args.accumulate(args.integers))
Assuming the Python code above is saved into a file called prog.py
, it can
be run at the command line and provides useful help messages:
$ python prog.py -h
usage: prog.py [-h] [--sum] N [N ...]
Process some integers.
positional arguments:
N an integer for the accumulator
optional arguments:
-h, --help show this help message and exit
--sum sum the integers (default: find the max)
При запуску з відповідними аргументами він друкує або суму, або максимальне значення цілих чисел командного рядка:
$ python prog.py 1 2 3 4
4
$ python prog.py 1 2 3 4 --sum
10
If invalid arguments are passed in, it will issue an error:
$ python prog.py a b c
usage: prog.py [-h] [--sum] N [N ...]
prog.py: error: argument N: invalid int value: 'a'
У наступних розділах ви ознайомитеся з цим прикладом.
Створення синтаксичного аналізатора¶
Першим кроком у використанні 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)')
Later, calling parse_args()
will return an object with
two attributes, integers
and accumulate
. The integers
attribute
will be a list of one or more ints, and the accumulate
attribute will be
either the sum()
function, if --sum
was specified at the command line,
or the max()
function if it was not.
Розбір аргументів¶
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¶
-
class
argparse.
ArgumentParser
(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True)¶ Створіть новий об’єкт
ArgumentParser
. Усі параметри слід передати як аргументи ключового слова. Кожен параметр має власний більш детальний опис нижче, але коротко вони:prog - The name of the program (default:
sys.argv[0]
)usage - рядок, що описує використання програми (за замовчуванням: генерується з аргументів, доданих до аналізатора)
description - Text to display before the argument help (default: none)
epilog - Text to display after the argument help (default: none)
Parents - список об’єктів
ArgumentParser
, аргументи яких також мають бути включеніformatter_class - клас для налаштування виведення довідки
prefix_chars - набір символів, які є префіксом необов’язкових аргументів (за замовчуванням: „-„)
fromfile_prefix_chars - набір символів, які є префіксами файлів, з яких слід читати додаткові аргументи (за замовчуванням:
None
)argument_default - глобальне значення за замовчуванням для аргументів (за замовчуванням:
None
)конфлікт_обробник - стратегія вирішення конфліктних опцій (зазвичай непотрібних)
add_help - додає опцію
-h/--help
до аналізатора (за замовчуванням:True
)allow_abbrev - Дозволяє скорочувати довгі параметри, якщо скорочення є однозначним. (за замовчуванням:
True
)
Змінено в версії 3.5: Додано параметр allow_abbrev.
Змінено в версії 3.8: У попередніх версіях allow_abbrev також вимикав групування коротких прапорців, таких як
-vv
, щоб означати-v -v
.
У наступних розділах описано, як використовується кожен із них.
прог¶
За замовчуванням об’єкти 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]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help
Щоб змінити цю типову поведінку, можна надати інше значення за допомогою аргументу prog=
до ArgumentParser
:
>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help()
usage: myprogram [-h]
optional arguments:
-h, --help show this help message and exit
Зауважте, що ім’я програми, незалежно від того, чи визначається з sys.argv[0]
або з prog=
аргументу, доступне для довідкових повідомлень за допомогою специфікатора формату %(prog)s
.
>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.add_argument('--foo', help='foo of the %(prog)s program')
>>> parser.print_help()
usage: myprogram [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo of the myprogram program
використання¶
За замовчуванням ArgumentParser
обчислює повідомлення про використання з аргументів, які він містить:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [-h] [--foo [FOO]] bar [bar ...]
positional arguments:
bar bar help
optional arguments:
-h, --help show this help message and exit
--foo [FOO] foo help
Повідомлення за замовчуванням можна замінити аргументом ключового слова usage=
:
>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [options]
positional arguments:
bar bar help
optional arguments:
-h, --help show this help message and exit
--foo [FOO] foo help
Специфікатор формату %(prog)s
доступний для заповнення назви програми у ваших повідомленнях про використання.
опис¶
Більшість викликів конструктора ArgumentParser
використовуватимуть аргумент ключового слова description=
. Цей аргумент дає короткий опис того, що програма робить і як вона працює. У довідкових повідомленнях опис відображається між рядком використання командного рядка та довідковими повідомленнями для різних аргументів:
>>> parser = argparse.ArgumentParser(description='A foo that bars')
>>> parser.print_help()
usage: argparse.py [-h]
A foo that bars
optional arguments:
-h, --help show this help message and exit
За замовчуванням опис буде перенесено на рядок, щоб він поміщався в заданий простір. Щоб змінити цю поведінку, перегляньте аргумент formatter_class.
епілог¶
Деякі програми люблять відображати додатковий опис програми після опису аргументів. Такий текст можна вказати за допомогою аргументу epilog=
для 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
optional arguments:
-h, --help show this help message and exit
And that's how you'd foo a bar
Як і в випадку з аргументом description, текст epilog=
за замовчуванням переносить рядки, але цю поведінку можна налаштувати за допомогою аргументу formatter_class на ArgumentParser
.
батьки¶
Іноді кілька аналізаторів використовують загальний набір аргументів. Замість того, щоб повторювати визначення цих аргументів, можна використати єдиний синтаксичний аналізатор із усіма спільними аргументами та переданим аргументом parents=
для 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
(один у батьківському і один у дочірньому) і викличе помилку.
Примітка
Ви повинні повністю ініціалізувати аналізатори перед тим, як передавати їх через parents=
. Якщо ви змінюєте батьківські аналізатори після дочірнього, ці зміни не відображатимуться в дочірньому.
formatter_class¶
Об’єкти ArgumentParser
дозволяють налаштувати форматування довідки шляхом визначення альтернативного класу форматування. На даний момент існує чотири таких класи:
-
class
argparse.
RawDescriptionHelpFormatter
¶ -
class
argparse.
RawTextHelpFormatter
¶ -
class
argparse.
ArgumentDefaultsHelpFormatter
¶ -
class
argparse.
MetavarTypeHelpFormatter
¶
RawDescriptionHelpFormatter
і RawTextHelpFormatter
дають більше контролю над тим, як відображаються текстові описи. За замовчуванням об’єкти ArgumentParser
переносять тексти description і epilog у довідкові повідомлення командного рядка:
>>> parser = argparse.ArgumentParser(
... prog='PROG',
... description='''this description
... was indented weird
... but that is okay''',
... epilog='''
... likewise for this epilog whose whitespace will
... be cleaned up and whose words will be wrapped
... across a couple lines''')
>>> parser.print_help()
usage: PROG [-h]
this description was indented weird but that is okay
optional arguments:
-h, --help show this help message and exit
likewise for this epilog whose whitespace will be cleaned up and whose words
will be wrapped across a couple lines
Передача RawDescriptionHelpFormatter
як formatter_class=
вказує на те, що 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
optional arguments:
-h, --help show this help message and exit
RawTextHelpFormatter
зберігає пробіли для всіх видів довідкового тексту, включаючи описи аргументів. Однак кілька нових рядків замінено одним. Якщо ви бажаєте зберегти кілька порожніх рядків, додайте пробіли між новими рядками.
ArgumentDefaultsHelpFormatter
автоматично додає інформацію про значення за замовчуванням до кожного довідкового повідомлення аргументу:
>>> parser = argparse.ArgumentParser(
... prog='PROG',
... formatter_class=argparse.ArgumentDefaultsHelpFormatter)
>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
>>> parser.print_help()
usage: PROG [-h] [--foo FOO] [bar [bar ...]]
positional arguments:
bar BAR! (default: [1, 2, 3])
optional arguments:
-h, --help show this help message and exit
--foo FOO FOO! (default: 42)
MetavarTypeHelpFormatter
використовує ім’я аргументу 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
optional arguments:
-h, --help show this help message and exit
--foo int
prefix_chars¶
Більшість параметрів командного рядка використовуватимуть -
як префікс, напр. -f/--foo
. Парсери, які повинні підтримувати різні або додаткові префіксні символи, напр. для таких параметрів, як +f
або /foo
, можна вказати їх за допомогою аргументу prefix_chars=
конструктора ArgumentParser:
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
>>> parser.add_argument('+f')
>>> parser.add_argument('++bar')
>>> parser.parse_args('+f X ++bar Y'.split())
Namespace(bar='Y', f='X')
Аргумент prefix_chars=
за умовчанням має значення '-'
. Якщо вказати набір символів, який не містить -
, параметри -f/--foo
будуть заборонені.
fromfile_prefix_chars¶
Sometimes, for example when dealing with a particularly long argument lists, it
may make sense to keep the list of arguments in a file rather than typing it out
at the command line. If the fromfile_prefix_chars=
argument is given to the
ArgumentParser
constructor, then arguments that start with any of the
specified characters will be treated as files, and will be replaced by the
arguments they contain. For example:
>>> 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 ', 'бар']
.
Аргумент fromfile_prefix_chars=
за умовчанням має значення None
, що означає, що аргументи ніколи не розглядатимуться як посилання на файли.
аргумент_за замовчуванням¶
Як правило, параметри за замовчуванням вказуються або передачею значення за замовчуванням 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
, він розпізнає абревіатури довгих параметрів.
Цю функцію можна вимкнути, встановивши для параметра 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
Нове в версії 3.5.
обробник_конфлікту¶
Об’єкти 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
Іноді (наприклад, під час використання батьків) може бути корисним просто замінити будь-які старіші аргументи тим самим рядком параметрів. Щоб отримати таку поведінку, значення '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]
optional arguments:
-h, --help show this help message and exit
-f FOO old foo help
--foo FOO new foo help
Зауважте, що об’єкти ArgumentParser
видаляють дію лише в тому випадку, якщо перевизначено всі рядки параметрів. Отже, у наведеному вище прикладі стара дія -f/--foo
зберігається як дія -f
, тому що було замінено лише рядок опції --foo
.
add_help¶
За замовчуванням об’єкти 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]
optional arguments:
-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]
optional arguments:
--foo FOO foo help
Параметром довідки зазвичай є -h/--help
. Винятком є те, що prefix_chars=
указано і не містить -
, у цьому випадку -h
і --help
не є дійсними параметрами. У цьому випадку перший символ у prefix_chars
використовується для префіксу параметрів довідки:
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
>>> parser.print_help()
usage: PROG [+h]
optional arguments:
+h, ++help show this help message and exit
Метод add_argument().¶
-
ArgumentParser.
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 - The value produced if the argument is absent from the command line.
type – тип, до якого потрібно перетворити аргумент командного рядка.
choices - A container of the allowable values for the argument.
required – чи можна пропустити параметр командного рядка (тільки необов’язковий).
help - короткий опис того, що робить аргумент.
metavar – назва аргументу в повідомленнях про використання.
dest – ім’я атрибута, який буде додано до об’єкта, повернутого
parse_args()
.
У наступних розділах описано, як використовується кожен із них.
назву чи прапори¶
The add_argument()
method must know whether an optional
argument, like -f
or --foo
, or a positional argument, like a list of
filenames, is expected. The first arguments passed to
add_argument()
must therefore be either a series of
flags, or a simple argument name. For example, an optional argument could
be created like:
>>> 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'
- This stores the value specified by the const keyword argument. The'store_const'
action is most commonly used with optional arguments that specify some sort of flag. For example:>>> 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'
- This stores a list, and appends each argument value to the list. This is useful to allow an option to be specified multiple times. Example usage:>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', action='append') >>> parser.parse_args('--foo 1 --foo 2'.split()) Namespace(foo=['1', '2'])
'append_const'
- This stores a list, and appends the value specified by the const keyword argument to the list. (Note that the const keyword argument defaults toNone
.) The'append_const'
action is typically useful when multiple arguments need to store constants to the same list. For example:>>> 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.
You may also specify an arbitrary action by passing an Action subclass or
other object that implements the same interface. The recommended way to do
this is to extend Action
, overriding the __call__
method
and optionally the __init__
method.
Приклад спеціальної дії:
>>> 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 objects usually associate a single command-line argument with a
single action to be taken. The nargs
keyword argument associates a
different number of command-line arguments with a single action. The supported
values are:
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
argparse.REMAINDER
. All the remaining command-line arguments are gathered into a list. This is commonly useful for command line utilities that dispatch to other command line utilities:>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('--foo') >>> parser.add_argument('command') >>> parser.add_argument('args', nargs=argparse.REMAINDER) >>> print(parser.parse_args('--foo B cmd --arg1 XX ZZ'.split())) Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')
Якщо аргумент ключового слова nargs
не надано, кількість споживаних аргументів визначається дією. Загалом це означає, що один аргумент командного рядка буде використано, і буде створено один елемент (не список).
конст¶
Аргумент const
add_argument()
використовується для зберігання постійних значень, які не читаються з командного рядка, але потрібні для різних дій ArgumentParser
. Два найпоширеніші його використання:
When
add_argument()
is called withaction='store_const'
oraction='append_const'
. These actions add theconst
value to one of the attributes of the object returned byparse_args()
. See the action description for examples.When
add_argument()
is called with option strings (like-f
or--foo
) andnargs='?'
. This creates an optional argument that can be followed by zero or one command-line arguments. When parsing the command line, if the option string is encountered with no command-line argument following it, the value ofconst
will be assumed instead. See the nargs description for examples.
With the 'store_const'
and 'append_const'
actions, the const
keyword argument must be given. For other actions, it defaults to None
.
за замовчуванням¶
Усі додаткові аргументи та деякі позиційні аргументи можна пропустити в командному рядку. Аргумент ключового слова default
add_argument()
, значення якого за замовчуванням None
, визначає, яке значення слід використовувати, якщо аргумент командного рядка відсутній. Для необов’язкових аргументів використовується значення за замовчуванням
, якщо рядок параметрів відсутній у командному рядку:
>>> 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, якщо він надається, перед встановленням атрибута для значення, що повертається 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')
типу¶
By default, ArgumentParser
objects read command-line arguments in as simple
strings. However, quite often the command-line string should instead be
interpreted as another type, like a float
or int
. The
type
keyword argument of add_argument()
allows any
necessary type-checking and type conversions to be performed. Common built-in
types and functions can be used directly as the value of the type
argument:
>>> 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)
See the section on the default keyword argument for information on when the
type
argument is applied to default arguments.
To ease the use of various types of files, the argparse module provides the
factory FileType which takes the mode=
, bufsize=
, encoding=
and
errors=
arguments of the open()
function. For example,
FileType('w')
can be used to create a writable file:
>>> 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=
can take any callable that takes a single string argument and returns
the converted value:
>>> 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
The choices keyword argument may be more convenient for type checkers that simply check against a range of values:
>>> 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)
See the choices section for more details.
вибір¶
Some command-line arguments should be selected from a restricted set of values.
These can be handled by passing a container object as the choices keyword
argument to add_argument()
. When the command line is
parsed, argument values will be checked, and an error message will be displayed
if the argument was not one of the acceptable values:
>>> 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')
Note that inclusion in the choices container is checked after any type conversions have been performed, so the type of the objects in the choices container should match the type specified:
>>> 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)
Any container can be passed as the choices value, so list
objects,
set
objects, and custom containers are all supported.
вимагається¶
Загалом, модуль 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
optional arguments:
-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)
optional arguments:
-h, --help show this help message and exit
Оскільки рядок довідки підтримує %-formatting, якщо ви хочете, щоб літерал %
з’явився в рядку довідки, ви повинні екранувати його як %%
.
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
метавар¶
Коли 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
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
змінює лише відображене ім’я – ім’я атрибута об’єкта 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]
optional arguments:
-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 classes implement the Action API, a callable which returns a callable
which processes arguments from the command-line. Any object which follows
this API may be passed as the action
parameter to
add_argument()
.
-
class
argparse.
Action
(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)¶
Об’єкти дії використовуються ArgumentParser для представлення інформації, необхідної для аналізу одного аргументу з одного або кількох рядків із командного рядка. Клас Action повинен приймати два позиційні аргументи плюс будь-які ключові аргументи, передані в ArgumentParser.add_argument()
, крім самої action
.
Екземпляри Action (або значення, що повертається будь-яким викликом параметра action
) повинні мати визначені атрибути «dest», «option_strings», «default», «type», «required», «help» тощо. Найпростіший спосіб переконатися, що ці атрибути визначені, це викликати Action.__init__
.
Екземпляри дій мають бути викликаними, тому підкласи повинні перевизначати метод __call__
, який має приймати чотири параметри:
parser
– об’єкт ArgumentParser, який містить цю дію.простір імен
– об’єктNamespace
, який повертатимеparse_args()
. Більшість дій додають атрибут до цього об’єкта за допомогоюsetattr()
.значення
– пов’язані аргументи командного рядка з будь-якими застосованими перетвореннями типів. Перетворення типів вказуються аргументом ключового слова type дляadd_argument()
.option_string
- рядок параметра, який використовувався для виклику цієї дії. Аргументoption_string
необов’язковий і буде відсутній, якщо дію пов’язано з позиційним аргументом.
Метод __call__
може виконувати довільні дії, але зазвичай встановлює атрибути в простір імен
на основі dest
і values
.
Метод parse_args().¶
-
ArgumentParser.
parse_args
(args=None, namespace=None)¶ Перетворіть рядки аргументів на об’єкти та призначте їх як атрибути простору імен. Повернути заповнений простір імен.
Попередні виклики
add_argument()
точно визначають, які об’єкти створюються та як вони призначаються. Перегляньте документацію дляadd_argument()
для деталей.
Синтаксис значення опції¶
Метод 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()
за замовчуванням дозволяє скорочувати довгі параметри до префікса, якщо скорочення є однозначним (префікс відповідає унікальному параметру):
>>> 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_string][, dest][, required][, help][, metavar])¶ Many programs split up their functionality into a number of sub-commands, for example, the
svn
program can invoke sub-commands likesvn checkout
,svn update
, andsvn commit
. Splitting up functionality this way can be a particularly good idea when a program performs several different functions which require different kinds of command-line arguments.ArgumentParser
supports the creation of such sub-commands with theadd_subparsers()
method. Theadd_subparsers()
method is normally called with no arguments and returns a special action object. This object has a single method,add_parser()
, which takes a command name and anyArgumentParser
constructor arguments, and returns anArgumentParser
object that can be modified as usual.Опис параметрів:
title - заголовок для групи суб-парсера у виведенні довідки; за замовчуванням «підкоманди», якщо надається опис, інакше використовує заголовок для позиційних аргументів
description - опис для групи суб-парсера у виведенні довідки, за замовчуванням
None
prog - інформація про використання, яка відображатиметься з довідкою підкоманд, за замовчуванням назва програми та будь-які позиційні аргументи перед аргументом 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
іbaz
.Similarly, when a help message is requested from a subparser, only the help for that particular parser will be printed. The help message will not include parent parser or sibling parser messages. (A help message for each subparser command, however, can be given by supplying the
help=
argument toadd_parser()
as above.)>>> parser.parse_args(['--help']) usage: PROG [-h] [--foo] {a,b} ... positional arguments: {a,b} sub-command help a a help b b help optional arguments: -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 optional arguments: -h, --help show this help message and exit >>> parser.parse_args(['b', '--help']) usage: PROG b [-h] [--baz {X,Y,Z}] optional arguments: -h, --help show this help message and exit --baz {X,Y,Z} baz help
Метод
add_subparsers()
також підтримує ключові аргументиtitle
іdescription
. Якщо будь-який з них присутній, команди субпарсера відображатимуться у власній групі у виведенні довідки. Наприклад:>>> 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} ... optional arguments: -h, --help show this help message and exit subcommands: valid subcommands {foo,bar} additional help
Furthermore,
add_parser
supports an additionalaliases
argument, which allows multiple strings to refer to the same subparser. This example, likesvn
, aliasesco
as a shorthand forcheckout
:>>> 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() >>> >>> # 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: Новий обов’язковий аргумент ключового слова.
Об’єкти FileType¶
-
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 objects understand the pseudo-argument
'-'
and automatically convert this intosys.stdin
for readableFileType
objects andsys.stdout
for writableFileType
objects:>>> 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: The encodings and errors keyword arguments.
Групи аргументів¶
-
ArgumentParser.
add_argument_group
(title=None, description=None)¶ By default,
ArgumentParser
groups command-line arguments into «positional arguments» and «optional arguments» when displaying help messages. When there is a better conceptual grouping of arguments than this default one, appropriate groups can be created using theadd_argument_group()
method:>>> 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()
повертає об’єкт групи аргументів, який має метод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
Зверніть увагу, що будь-які аргументи, які не входять до визначених користувачем груп, повертаються до звичайних розділів «позиційні аргументи» та «необов’язкові аргументи».
Взаємне виключення¶
-
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()
також приймає обов’язковий аргумент, щоб вказати, що потрібен принаймні один із взаємовиключних аргументів:>>> 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
Note that currently mutually exclusive argument groups do not support the title and description arguments of
add_argument_group()
.
Параметри аналізатора за замовчуванням¶
-
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'])
Попередження
Prefix matching rules apply to
parse_known_args()
. The parser may consume an option even if it’s just
a prefix of one of its known options, instead of leaving it in the remaining
arguments list.
Налаштування аналізу файлів¶
-
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()
підтримують цей стиль аналізу.
These parsers do not support all the argparse features, and will raise
exceptions if unsupported features are used. In particular, subparsers,
argparse.REMAINDER
, and mutually exclusive groups that include both
optionals and positionals are not supported.
У наступному прикладі показано різницю між 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()
викликає помилку, якщо залишилися нерозібрані рядки аргументів.
Нове в версії 3.7.
Оновлення коду optparse¶
Спочатку модуль argparse
намагався підтримувати сумісність із optparse
. Однак optparse
було важко розширити прозоро, особливо зі змінами, необхідними для підтримки нових специфікаторів nargs=
і кращих повідомлень про використання. Коли майже все в optparse
було або скопійовано, або виправлено мавпами, більше не здавалося практичним намагатися підтримувати зворотну сумісність.
Модуль argparse
покращує модуль стандартної бібліотеки optparse
кількома способами, зокрема:
Обробка позиційних аргументів.
Допоміжні підкоманди.
Дозволяє альтернативні префікси параметрів, наприклад
+
і/
.Обробка нуля або більше та одного або кількох аргументів стилю.
Створення більш інформативних повідомлень про використання.
Забезпечення набагато простішого інтерфейсу для користувацького
типу
ідії
.
Шлях часткового оновлення з optparse
до argparse
:
Замініть усі виклики
optparse.OptionParser.add_option()
на викликиArgumentParser.add_argument()
.Замініть
(options, args) = parser.parse_args()
наargs = parser.parse_args()
і додайте додаткові викликиArgumentParser.add_argument()
для позиційних аргументів. Майте на увазі, що те, що раніше називалосяoptions
, тепер у контекстіargparse
називаєтьсяargs
.Замініть
optparse.OptionParser.disable_interspersed_args()
на використанняparse_intermixed_args()
замістьparse_args()
.Замініть дії зворотного виклику та аргументи ключового слова
callback_*
на аргументиtype
абоaction
.Замініть назви рядків для ключових аргументів
type
відповідними об’єктами типу (наприклад, int, float, complex тощо).Замініть
optparse.Values
наNamespace
іoptparse.OptionError
іoptparse.OptionValueError
наArgumentError
.Замініть рядки неявними аргументами, такими як
%default
або%prog
стандартним синтаксисом Python, щоб використовувати словники для форматування рядків, тобто%(default)s
і%(prog)s
.Замініть аргумент
version
конструктора OptionParser на викликparser.add_argument('--version', action='version', version=' <the version> ')
.