Python: модуль argparse – опции командной строки в примерах

Автор: | 08/05/2014
Нет комментариев

Pythonargparse – модуль Python, заменивший более старую версию похожего по функциональности модуля optparse.

Назначение модуля – обработка опций и аргументов командной строки, с которой вызывается скрипт.

Модуль может не быть установлен вместе с Python:

# pydoc argparse
no Python documentation found for 'argparse'

Поэтому его придётся установить вручную. Например, на CentOS:

# yum search argparse
...
python-argparse.noarch : Optparse inspired command line parser for Python
# yum -y install python-argparse

Для FreeBSD:

# cd /usr/ports/ && make search name="argparse"
Port:   py27-argparse-1.2.1
Path:   /usr/ports/devel/py-argparse
Info:   Optparse-inspired command-line parsing library
Maint:  [email protected]
B-deps: gettext-0.18.3.1 libiconv-1.14_3 py27-setuptools27-2.0.1 python27-2.7.6_4 readline-6.3.3_1
R-deps: gettext-0.18.3.1 libiconv-1.14_3 py27-setuptools27-2.0.1 python27-2.7.6_4 readline-6.3.3_1
WWW:    http://code.google.com/p/argparse/
# cd /usr/ports/devel/py-argparse && make install clean

Либо – установить с помощью pip или вручную.

Файл модуля во FreeBSD расположен в /usr/local/lib/python2.7/argparse.py, в CentOS – /usr/lib/python2.6/site-packages/argparse.py.

Для BASH есть аналогичный модуль getopts.

Для первого примера возьмём скрипт с таким содержимым:

#!/usr/bin/env python

import argparse

parser = argparse.ArgumentParser()

parser.add_argument('-1', '--one' , help='This will be option One')

parser.parse_args()

Результат его запуска:

$ ./args.py -h
usage: args.py [-h] [-1 ONE]
optional arguments:
-h, --help         show this help message and exit
-1 ONE, --one ONE  This will be option One

Заметьте, что опция -h (или --help) в нём не задаётся вручную, она обрабатывается модулем “автоматически” (хотя это можно переназначить).

Основные действия будут выполнятся классом ArgumentParser модуля argparse.

Список методов класса можно получить так:

>>> for i in dir(argparse.ArgumentParser):
...   if not i.startswith('_'):
...     print i
...
add_argument
add_argument_group
add_mutually_exclusive_group
add_subparsers
convert_arg_line_to_args
error
exit
format_help
format_usage
format_version
get_default
parse_args
parse_known_args
print_help
print_usage
print_version
register
set_defaults

Мы рассмотрим использование двух – add_argument и parse_args.

Python argparse – добавление опций с помощью add_argument

Ситаксис add_argument:

add_argument(name or flags...[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest])

name или flags – имя опции, например foo или -f, –foo
action – тип действия, которое будет выполнятся при вызове опции (см. ниже action='store');
nargs – количество аргументов к опции, которые могут (должны) быть использованы;
const – константа, может потребовать некоторым типам действий или аргументам;
default – действие по-умолчанию, если опция пропущена (не вызвана), прмиеняется ко всем опциям, которым не назначен отдельный ключ default;
type – тип данных, в котором должен быть сохранён объект (данные), переданные аргументом к опции, например – str или int;
choices – контейнер допустимых значений для аргумента;
required – указатель, является ли опция обязательной;
help – краткое описание опции, используется в --help;
metavar – имя аргумента для опции, которое будет выводится в --help;
dest – имя опции, которое будет передано методу parse_args().

Тут отдельно надо остановиться на ключе “action“.

Ключ action может принимать такие значения:

  • 'store' – просто сохраняет в переменной “имя_опции” значение, переданное опции (действие по-умолчанию);
  • 'store_const' – сохраняет значение, заданное ключём const;
  • 'store_true' или 'store_false' – сохраняет значение True или False;
  • 'count' – счётчик количества экземпляров опции.

Больше значений смотрите тут>>>.

Рассмотрим несколько примеров добавления обрабатываемых опций.

add_argument – name или flags

Опции, задаваемые со знаком “-” будут считаться опциональными, тогда как заданные просто в виде "имя" – обязательными.

Например:

#!/usr/bin/env python

import argparse

parser = argparse.ArgumentParser()

parser.add_argument('-1', '--one', help='This will be option One')
parser.add_argument('two', help='This will be option two')
parser.add_argument('three', help='This will be option three')

print parser.parse_args()

Обратите внимание – тут мы добавили функцию print(), для вывода “пространства имён” опций.

Вызовем скрипт с опцией --help:

$ ./args.py -h
usage: args.py [-h] [-1 ONE] two three

positional arguments:
  two                This will be option two
  three              This will be option three

optional arguments:
  -h, --help         show this help message and exit
  -1 ONE, --one ONE  This will be option One

Теперь – попробуем запустить скрипт с указанием всех опций:

$ ./args.py  -1 first one two
Namespace(one='first', three='two', two='one')

Т.к. для опции -1 не указано действие – будет выполнено действие по-умолчанию action='store'. Для позиционных опций не требуется указание аргументов, т.к. его значение само по себе будет явятся аргументом.

Например – вызов опции --one (или -1) без указания аргумента вызовет ошибку:

$ ./args.py one two -1
usage: args.py [-h] [-1 ONE] two three
args.py: error: argument -1/--one: expected one argument

При этом – к вызову обязательны все позиционные опции, иначе будет ошибка:

$ ./args.py one -1 first
usage: args.py [-h] [-1 ONE] two three
args.py: error: too few arguments

add_argument – action

Рассмотрим допустимые действия для опций.

‘store’ – сохраняет значение, переданное опции (действие по-умолчанию)

Т.е., опции обязательно передать аргумент, который будет сохранён как её значение.

Например:

#!/usr/bin/env python

import argparse

parser = argparse.ArgumentParser()

parser.add_argument('-1', '--one', help='This will be option One')

print parser.parse_args()

Будет аналогичен такому коду:

parser.add_argument('-1', '--one', action='store', help='This will be option One')

Результат выполнения:

$ ./args.py --one first_argument
Namespace(one='first_argument')
‘store_const’ – сохраняет значение, заданное ключём const;

Изменим наш код:

parser.add_argument(‘-1’, ‘–one’, action=’store_const’, const=’1′, help=’This will be option One’)

$ ./args.py --one
Namespace(one='1')

Удобно использовать для передачи различных флагов.

Например:

#!/usr/bin/env python

import argparse

parser = argparse.ArgumentParser()

parser.add_argument('-1', '--one', action='store_const', const='1', help='This will be option One')

print parser.parse_args()

if parser.parse_args().one == '1':
        print 'That's it!'
else:
        print 'Here is nothing :-('

Вызовем скрипт с опцией --one:

$ ./args.py --one
Namespace(one='1')
That's it!

И без неё:

$ ./args.py
Namespace(one=None)
Here is nothing :-(
‘store_true’ или ‘store_false’ – сохраняет значение True или False

Похож по действию на store_const, с той разницей что хранит только True или False.

Изменим код:

parser.add_argument('-1', '--one', action='store_true', help='This will be option One')

Результат:

$ ./args.py -1
Namespace(one=True)

Тогда как вызов без опции --one задаст значение False:

$ ./args.py
Namespace(one=False)

И наоборот:

parser.add_argument('-1', '--one', action='store_false', help='This will be option One')

$ ./args.py -1
Namespace(one=False)

И без опции:

$ ./args.py
Namespace(one=True)

Соответственно – можем использовать код:

#!/usr/bin/env python

import argparse

parser = argparse.ArgumentParser()

parser.add_argument('-1', '--one', action='store_true', help='This will be option One')

print parser.parse_args()

res = parser.parse_args()

if res.one:
        print 'First is True!'
else:
        print 'First is nothing :-('

Обратите внимание, что тут мы создали объект res, который является экземпляром класса argparse с вызовом метода ArgumentParser – просто, что бы не писать лишний текст.

Результат выполнения:

$ ./args.py -1
Namespace(one=True)
First is True!

И без опции:

$ ./args.py
Namespace(one=False)
First is nothing :-(
‘count’ – счётчик количества экземпляров опции

Изменим наш код:

parser.add_argument('-1', '--one', action='count', help='This will be option One')

И вызовем его с одним ключём:

$ ./args.py -1
Namespace(one=1)

Или двумя:

$ ./args.py -11
Namespace(one=2)

Пример использования – указать уровень “подробности” режима verbosity, когда можно указать -v, -vv или -vvv.

add_argument – nargs

Ключ nargs поддерживает такие значения:

  • N – количество аргументов к опции;
  • ? – если присутствует один аргумент – он будет сохранён, иначе – будет использовано значение из ключа default;
  • * – все переданные аргументы будут сохранены в один список;
  • + – то же, что и * – но если нет хотя бы одного аргумента – будет выдано сообщение об ошибке;
nargs с N-аргументов:

Пример кода:

parser.add_argument('-1', '--one', nargs=2, help='This will be option One')

Обратите внимание, что тут 2 указывается без кавычек – иначе интерпретатор будет рассматривать значение как string (строку), что вызовет ошибку.

Если вызвать без указания аргументов к опции -1 – будет выдано сообщение об ошибке:

$ ./args.py -1
usage: args.py [-h] [-1 ONE ONE]
args.py: error: argument -1/--one: expected 2 argument(s)

Вызываем с двумя аргументами – и получаем список:

$ ./args.py -1 one two
Namespace(one=['one', 'two'])
nargs с “?” аргументов:
parser.add_argument('-1', '--one', nargs='?', help='This will be option One')
$ ./args.py -1 first
Namespace(one='first')

Или передать имя файла:

$ ./args.py -1 file.txt
Namespace(one='file.txt')

При вызове без аргумента – значение переменной будет задано как None:

$ ./args.py -1
Namespace(one=None)

Изменить это можно с помощью ключей const и default.

Немного изменим наш код:

parser.add_argument('-1', '--one', nargs='?', const='const-one', default='default-one', help='This will be option One')
parser.add_argument('-2', '--two', nargs='?', const='const-two', default='default-two', help='This will be option Two')

И результаты:

$ ./args.py -1 -2
Namespace(one='const-one', two='const-two')
$ ./args.py -1 first -2
Namespace(one='first', two='const-two')
$ ./args.py -1 first -2 second
Namespace(one='first', two='second')
nargs с “*” аргументов:

Изменим пример:

parser.add_argument('-1', '--one', nargs='*', help='This will be option One')

При вызове без аргументов опции – создаст пустой список:

$ ./args.py -1 one two three
Namespace(one=['one', 'two', 'three'])

При вызове с любым количеством аргументов – добавит их все в один список:

$ ./args.py -1 one two three
Namespace(one=['one', 'two', 'three'])

Далее со списком можно выполнять любые стандартные операции:

#!/usr/bin/env python

import argparse

parser = argparse.ArgumentParser()

parser.add_argument('-1', '--one', nargs='*', help='This will be option One')

print parser.parse_args()

res = parser.parse_args()

for i in res.one:
        print i

И результат:

$ ./args.py -1 one two three
Namespace(one=['one', 'two', 'three'])
one
two
three
nargs с “+” аргументов:

Требуется наличие хотя бы одного аргумента к опции.

Напрмиер:

parser.add_argument('-1', '--one', nargs='+', help='This will be option One')

Вызов без аргумента:

$ ./args.py -1
usage: args.py [-h] [-1 ONE [ONE ...]]
args.py: error: argument -1/--one: expected at least one argument

С одним аргументом:

$ ./args.py -1 one
Namespace(one=['one'])

Несколькими:

$ ./args.py -1 one two three
Namespace(one=['one', 'two', 'three'])

add_argument – choices

Т.к. мы кратко рассмотрели const  и default  выше – то пропустим их, и перейдём к слудющему ключу – choices.

Изменим пример:

parser.add_argument('-1', '--one', choices=['1', '2', '3'], help='This will be option One')

В результате – аргумент к опции должен быть только из предложенного списка:

$ ./args.py -1 one two three
usage: args.py [-h] [-1 {1,2,3}]
args.py: error: argument -1/--one: invalid choice: 'one' (choose from 1, 2, 3)

Правильный выбор:

$ ./args.py -1 1
Namespace(one='1')
1

add_argument – required

Указание является ли опция обязательной:

parser.add_argument('-1', '--one', required=True, help='This will be option One')
$ ./args.py
usage: args.py [-h] -1 ONE
args.py: error: argument -1/--one is required
$ ./args.py -1 1
Namespace(one='1')
1

add_argument – dest

Замена имени переменной. По-умолчанию – имя переменной формируется из “длинного имени” опции (если есть, в нашем примере это --one), или из “короткого” (если нет “длинного”, в нашем примере это -1):

parser.add_argument('-1', '--one', help='This will be option One')
$ ./args.py -1 one
Namespace(one='one')
parser.add_argument('-1', help='This will be option One')
$ ./args.py -1 one
Namespace(1='one')

Зададим другое имя:

parser.add_argument('-1', '--one', dest='firstvar', help='This will be option One')

Результат:

$ ./args.py -1 one
Namespace(firstvar='one')

Что бы проверить, что скрипт вызван хотя бы с одной опцией – можно использовать такой способ:

#!/usr/bin/env python

import argparse
import sys

parser = argparse.ArgumentParser()

parser.add_argument('-1', '--one', dest='firstvar', help='This will be option One')

if len(sys.argv) == 1:
        print 'nERROR! You must specify at least one option.n'
        parser.print_help()

И вызовем скрипт без опций:

$ ./args.py

ERROR! You must specify at least one option.

usage: args.py [-h] [-1 FIRSTVAR]

optional arguments:
  -h, --help            show this help message and exit
  -1 FIRSTVAR, --one FIRSTVAR
                        This will be option One

На этом, пожалуй, всё.

Ссылки по теме:

https://docs.python.org
https://docs.python.org
http://habrahabr.ru/post/144416/
http://sakalr.blogspot.com