getopt — Парсер в стиле C для опций командной строки

Источник: Lib/getopt.py

Не рекомендуется, начиная с версии 3.13: Модуль getopt является soft deprecated и не будет развиваться дальше; разработка будет продолжена для модуля argparse.

Примечание

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

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

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

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

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

Примечание

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

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

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

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

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

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

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']

В сценарии обычно используется примерно следующее:

import getopt, sys

def main():
    try:
        opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="])
    except getopt.GetoptError as err:
        # print help information and exit:
        print(err)  # will print something like "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"
    # ...

if __name__ == "__main__":
    main()

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

import argparse

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument('-o', '--output')
    parser.add_argument('-v', dest='verbose', action='store_true')
    args = parser.parse_args()
    # ... do something with args.output ...
    # ... do something with args.verbose ..

См.также

Модуль argparse

Альтернативная библиотека разбора опций и аргументов командной строки.