getopt — C-style parser for command line options

Вихідний код: Lib/getopt.py

Примітка

Модуль 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(), після аргументу, що не є опцією, усі подальші аргументи також вважаються не опціями. Це схоже на те, як працюють не-GNU Unix системи.

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

Повернене значення складається з двох елементів: перший – це список пар (параметр, значення); другий — список аргументів програми, що залишився після видалення списку параметрів (це кінцевий фрагмент 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

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