Ознакомьтесь с видеороликом https://youtu.be/pXhcPJK5cMc
docopt поможет вам:
docopt основан на соглашениях, которые десятилетиями использовались в справочных сообщениях и страницах помощи для описания интерфейса программ. Описание интерфейса в docopt - это формализованное справочное сообщение. Например:
Пример описывает интерфейс исполняемого файла naval_fate, который может быть вызван различными комбинациями команд (ship, new, move и др.).), параметры (-h, --help, --speed=kn и др.) и позиционные аргументы (name, x, y).
Пример использует квадратные скобки "[ ]", круглые скобки "( )", знак вертикальной черты "|" и многоточие "..." для описания соответственно необязательных, обязательных, взаимоисключающих и повторяющихся элементов. Вместе эти элементы образуют допустимые шаблоны использования, каждый из которых начинается с имени программы naval_fate.
Ниже шаблонов помещен список опций с описаниями. Они описывают, имеет ли опция короткую/длинную форму (-h, --help), имеет ли опция аргумент (--speed=kn), и имеет ли этот аргумент значение по умолчанию ([default: 10]).
Реализация docopt извлекает всю эту информацию и генерирует синтаксический анализатор аргументов командной строки с текстом описания интерфейса в качестве справочного сообщения, которое выводится при вызове программы с параметрами -h или --help.
Текст, находящийся между ключевым словом usage: (без учета регистра) и явной (видимой) пустой строкой, интерпретируется как список шаблонов использования (usage patterns). Первое слово после usage: интерпретируется как имя программы.
Это минимальный пример программы, которая не принимает аргументы командной строки:
Программа может иметь несколько шаблонов, перечисленных с различными элементами, используемыми для описания шаблона:
Все элементы и конструкции описаны ниже. Мы будем использовать слово "слово" для описания последовательности символов, разделенных или пробелами, или одним из символов из списка" [] () |", или "...".
<argument> ARGUMENTСлова, начинающиеся с "<", и заканчивающиеся ">" и находящиеся в верхнем регистре, интерпретируются как позиционные аргументы.
Слова, начинающиеся с одного или двух тире (за исключением самих-по-себе "-", "--") интерпретируются как соответственно короткие (one-letter) или длинные опции.
Короткие опции могут быть "сложены" ("stacked"), что означает, что -abc эквивалентно -a-b-c. Длинные опции могут иметь аргументы, указанные после пробела или равные знаку "=", например: --input=ARG эквивалентно --input ARG.
Короткие параметры могут иметь аргументы, указанные после необязательного пробела: -f FILE эквивалентно -fFILE.
Обратите внимание, что запись --input ARG (в отличие от --input=ARG) неоднозначна, то есть невозможно определить, является ли ARG аргументом опции или позиционным аргументом. В применяемых шаблонах это будет интерпретироваться как параметр с аргументом только в том случае, если приведено описание (приведенное ниже) для этого параметра. В противном случае он будет интерпретироваться как опция и отдельный позиционный аргумент.
Существует такая же двусмысленность с нотацией -f FILE и -fFILE. В последнем случае невозможно сказать, является ли это ряд сложенных (stacked) коротких вариантов или вариант с аргументом. Эти обозначения будут интерпретироваться как параметр с аргументом только в том случае, если будет предоставлено описание для параметра.
Все другие слова, которые не следуют вышеуказанным соглашениям --options или arguments, интерпретируются как (под)команды.
Элементы (параметры (опции), аргументы, команды), заключенные в квадратные скобки "[ ]", помечаются как необязательные. Не имеет значения, заключены ли элементы в одну или несколько пар скобок, например:
Эквивалентно
Все элементы обязательны по умолчанию, если они не заключены в скобки "[ ]". Однако, иногда необходимо пометить элементы как обязательные явно с помощью круглых скобок "()". Например, когда необходимо сгруппировать взаимоисключающие элементы (см. Следующий раздел):
Другой случай использования - когда вам нужно указать, что если один элемент присутствует, то и другой является обязательным, и это вы можете сделать следующим образом:
В этом случае, допустимый вызов программы может быть либо без аргументов, либо с двумя аргументами.
Взаимоисключающие элементы могут быть разделены вертикальной чертой (pipe) "|" как ниже:
Используйте круглые скобки "()" для группировки элементов, когда требуется один из взаимоисключающих случаев. Используйте квадратные скобки "[ ]" для группировки элементов, когда ни один из взаимоисключающих случаев не требуется:
Обратите внимание, что указание нескольких шаблонов работает точно так же, как вертикальная черта "|", то есть:
Эквивалентно
Используйте многоточие "..." чтобы указать, что аргумент (или группа аргументов) слева может быть продублирован один или несколько раз:
Вы можете гибко указать количество необходимых аргументов. Например, ниже приведено три разных способа указать, что требуется от ноля аргументов и более:
Один или больше аргументов
Два или больше аргументов (и т.д.)
"[options]" - это ярлык, который позволяет избежать перечисления всех опций (из списка опций с описаниями) в шаблоне. Например:
Эквивалентно:
Это может быть полезно, если у вас много вариантов, и все они применимы к одному из шаблонов. Кроме того, если у вас есть как короткие, так и длинные версии опций (указанные в описании опций), вы можете любую из них использовать в шаблоне:
Более подробная информация о том, как делать описания опций, будет приведена ниже.
В тех случаях когда не является частью опции, двойное тире "--" часто используется по соглашению для разделения опций и позиционных аргументов, чтобы обрабатывать случаи, когда, например, имена файлов могут быть ошибочно приняты за опции. Чтобы поддержать это соглашение, добавьте "[--]" в свои шаблоны перед позиционными аргументами.
Помимо этого особого значения, "--" - это просто обычная команда, поэтому вы можете применить любые ранее описанные операции, например, сделать ее необходимой (отбросив скобки "[ ]")
Одиночное тире "-", в тех случаях когда не является частью опции, часто используется по соглашению для обозначения того, что программа должна обрабатывать stdin, а не файл. Если вы хотите следовать этому соглашению, добавьте "[-]" в свой шаблон. "-" сама по себе это просто обычная команда, которую можно использовать с любым смыслом.
Описания опций состоят из списка опций, которые вы помещаете под своими шаблонами использования (usage patterns). Необязательно указывать их, если нет двусмысленности в шаблонах использования (описанных в разделе --option выше).
Описание опции позволяет указать:
Правила следующие:
Каждая строка, которая начинается с "-" или "--" (не считая пробелов), рассматривается как описание опции, например:
Чтобы указать, что параметр (опция) имеет аргумент, поместите слово, описывающее этот аргумент, после пробела (или знака равно "=") как показано ниже. Для обозначения аргументов опций используйте либо <угловые скобки>, либо соглашение верхнего регистра (UPPER-CASE). Вы можете использовать запятую, если хотите разделить параметры. В приведенном ниже примере обе строки допустимы, однако рекомендуется придерживаться одного стиля.
Используйте два пробела для отделения параметров от неформального описания.
Если вы хотите установить значение по умолчанию для параметра с аргументом, поместите его в описание параметра в форме [default: <the-default-value>].
Поупражняйтесь с docopt в браузере https://try.docopt.org/
docopt доступен на многих языках программирования. Официальные реализации перечислены в аккаунте организации docopt на GitHub.
Адаптированный перевод материала с сайта docopt.org, подготовил Константин Жаринов.