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

Примечание

Модуль 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

Вызывается, когда в списке аргументов обнаруживается нераспознанный параметр или когда требующему аргумента параметру, не задано значение none. Аргументом исключения является строка, указывающая причину ошибки. Для длинных опций необязательный переданный аргумент, также вызовет исключение. Атрибуты 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(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"
    # ...

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()
    # ... сделать что-нибудь с args.output ...
    # ... сделать что-нибудь с args.verbose ..

См.также

Модуль argparse
Альтернативный вариант командной строки и библиотека парсинга аргументов.