getopt – анализатор параметров командной строки в стиле C¶getopt – C-style parser for command line options

Исходный код: Lib/getopt.py

Этот модуль помогает скриптам разбирать аргументы командной строки в sys.argv. Он поддерживает те же соглашения, что и функция Unix getopt() (включая особые значения аргументов вида '-' и '--'). Длинные опции, подобные поддерживаемым программным обеспечением GNU, также могут использоваться через необязательный третий аргумент.

Пользователям, не знакомым с функцией Unix getopt(), следует рассмотреть использование модуля argparse. Пользователи, знакомые с функцией Unix getopt(), но желающие получить эквивалентное поведение, написав меньше кода и получая более качественные справку и сообщения об ошибках, должны рассмотреть использование модуля optparse. Подробнее см. Выбор библиотеки разбора аргументов.

Этот модуль предоставляет две функции и одно исключение:

getopt.getopt(args, shortopts, longopts=[])¶

Разбирает параметры командной строки и список аргументов. args – это список аргументов для разбора, без ссылки на выполняемую программу. Обычно это означает sys.argv[1:]. shortopts – это строка букв опций, которые скрипт хочет распознавать, где опции, требующие аргумента, сопровождаются двоеточием (':'), а опции, принимающие необязательный аргумент, сопровождаются двумя двоеточиями ('::'); то есть тот же формат, который использует Unix getopt().

Примечание

В отличие от GNU getopt(), после неопционного аргумента все последующие аргументы также считаются неопционными. Это аналогично тому, как работают не-GNU Unix-системы.

longopts, если указан, должен быть списком строк с именами длинных опций, которые должны поддерживаться. Начальные символы '--' не должны включаться в имя опции. Длинные опции, требующие аргумента, должны сопровождаться знаком равенства ('='). Длинные опции, принимающие необязательный аргумент, должны сопровождаться знаком равенства и вопросительным знаком ('=?'). Чтобы принимать только длинные опции, shortopts должна быть пустой строкой. Длинные опции в командной строке могут распознаваться, если они предоставляют префикс имени опции, который точно совпадает с одной из принятых опций. Например, если longopts равен ['foo', 'frob'], опция --fo будет соответствовать --foo, но --f не будет соответствовать однозначно, поэтому будет возбуждено GetoptError.

Возвращаемое значение состоит из двух элементов: первый – список пар (option, value); второй – список аргументов программы, оставшихся после удаления списка опций (это конечный срез args). Каждая возвращаемая пара «опция-значение» содержит опцию в качестве первого элемента, с префиксом дефис для коротких опций (например, '-x') или двух дефисов для длинных опций (например, '--long-option'), и аргумент опции в качестве второго элемента, или пустую строку, если у опции нет аргумента. Опции располагаются в списке в том же порядке, в котором они были найдены, что допускает повторения. Длинные и короткие опции могут смешиваться.

Изменено в версии 3.14: Поддерживаются необязательные аргументы.

getopt.gnu_getopt(args, shortopts, longopts=[])¶

Эта функция работает как getopt(), за исключением того, что по умолчанию используется режим сканирования в стиле GNU. Это означает, что опционные и неопционные аргументы могут перемешиваться. Функция getopt() прекращает обработку опций, как только встречается неопционный аргумент.

Если первый символ строки опций – '+', или установлена переменная окружения POSIXLY_CORRECT, то обработка опций прекращается, как только встречается неопционный аргумент.

Если первый символ строки опций – '-', неопционные аргументы, за которыми следуют опции, добавляются в список пар опция-значение как пара, первым элементом которой является None, а вторым – список неопционных аргументов. Второй элемент результата gnu_getopt() – это список аргументов программы после последней опции.

Изменено в версии 3.14: Поддержка возврата перемешанных опций и неопционных аргументов по порядку.

exception getopt.GetoptError¶

Это исключение возбуждается, когда в списке аргументов обнаружена нераспознанная опция или когда опции, требующей аргумента, не передано ни одного. Аргумент исключения – строка, указывающая причину ошибки. Для длинных опций передача аргумента опции, которая его не требует, также вызовет это исключение. Атрибуты msg и opt содержат сообщение об ошибке и соответствующую опцию; если нет конкретной опции, к которой относится исключение, opt является пустой строкой.

exception getopt.error¶

Псевдоним для GetoptError; для обратной совместимости.

Пример использования только опций в стиле Unix:

>>> import getopt
>>> args = '-a -b -cfoo -d bar a1 a2'.split()
>>> args
['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'abc:d:')
>>> optlist
[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
>>> args
['a1', 'a2']

Использование длинных имён опций так же просто:

>>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
>>> args = s.split()
>>> args
['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'x', [
...     'condition=', 'output-file=', 'testing'])
>>> optlist
[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x', '')]
>>> args
['a1', 'a2']

Необязательные аргументы должны указываться явно:

>>> s = '-Con -C --color=off --color a1 a2'
>>> args = s.split()
>>> args
['-Con', '-C', '--color=off', '--color', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'C::', ['color=?'])
>>> optlist
[('-C', 'on'), ('-C', ''), ('--color', 'off'), ('--color', '')]
>>> args
['a1', 'a2']

Порядок опций и неопционных аргументов может быть сохранён:

>>> s = 'a1 -x a2 a3 a4 --long a5 a6'
>>> args = s.split()
>>> args
['a1', '-x', 'a2', 'a3', 'a4', '--long', 'a5', 'a6']
>>> optlist, args = getopt.gnu_getopt(args, '-x:', ['long='])
>>> optlist
[(None, ['a1']), ('-x', 'a2'), (None, ['a3', 'a4']), ('--long', 'a5')]
>>> args
['a6']

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

import getopt, sys

def main():
    try:
        opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="])
    except getopt.GetoptError as err:
        # вывести справочную информацию и завершить работу:
        print(err)  # выведет что-то вроде "option -a not recognized"
        usage()
        sys.exit(2)
    output = None
    verbose = False
    for o, a in opts:
        if o == "-v":
            verbose = True
        elif o in ("-h", "--help"):
            usage()
            sys.exit()
        elif o in ("-o", "--output"):
            output = a
        else:
            assert False, "unhandled option"
    process(args, output=output, verbose=verbose)

if __name__ == "__main__":
    main()

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

import optparse

if __name__ == '__main__':
    parser = optparse.OptionParser()
    parser.add_option('-o', '--output')
    parser.add_option('-v', dest='verbose', action='store_true')
    opts, args = parser.parse_args()
    process(args, output=opts.output, verbose=opts.verbose)

Примерно эквивалентный интерфейс командной строки для этого случая также можно создать с помощью модуля argparse:

import argparse

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument('-o', '--output')
    parser.add_argument('-v', dest='verbose', action='store_true')
    parser.add_argument('rest', nargs='*')
    args = parser.parse_args()
    process(args.rest, output=args.output, verbose=args.verbose)

Подробнее о том, чем поведение версии argparse этого кода отличается от версии optparse (и getopt), см. Выбор библиотеки разбора аргументов.