Как соответствовать строкам документации PEP 257 при использовании модуля Python optparse? - PullRequest
Новая
       8

Как соответствовать строкам документации PEP 257 при использовании модуля Python optparse?

5 голосов
/ 11 августа 2009

Согласно PEP 257 строкой сценария командной строки должно быть сообщение об использовании.

Строка документа сценария отдельная программа) должна использоваться как его сообщение об использовании, напечатанное, когда скрипт вызывается с неверным или пропущенные аргументы (или, возможно, с опция "-h", для "помощи"). Такой Документация должна документировать сценарий синтаксис функции и командной строки, переменные среды и файлы. Сообщения об использовании могут быть довольно сложными (несколько экранов заполнено) и должно быть достаточно для нового пользователя, чтобы использовать командовать должным образом, а также полная быстрая ссылка на все варианты и аргументы для искушенный пользователь.

Итак, моя строка документации будет выглядеть примерно так: 

<tool name> <copyright info>

Usage: <prog name> [options] [args]

some text explaining the usage...

Options:
  -h, --help  show this help message and exit
   ...

Теперь я хочу использовать модуль optparse. optparse генерирует разделы «Опции» и «использование», объясняющие синтаксис командной строки: 

from optparse import OptionParser

if __name__ == "__main__":
    parser = OptionParser()
    (options, args) = parser.parse_args()

При вызове скрипта с флагом -h выводится: 

Usage: script.py [options]

Options:
    -h, --help  show this help message and exit

Это можно изменить следующим образом: 

parser = OptionParser(usage="Usage: %prog [options] [args]",
                      description="some text explaining the usage...")

, что приводит к 

Usage: script.py [options] [args]

some text explaining the usage...

Options:
  -h, --help  show this help message and exit

Но как я могу использовать здесь строку документации? Передача строки документации в качестве сообщения об использовании имеет две проблемы.

  1. optparse добавляет «Использование:» в строку документации, если оно не начинается с «Использование:»
  2. Заполнитель '% prog' должен использоваться в строке документации

Результат

Судя по ответам, кажется, что нет способа повторно использовать строку документации, предназначенную для модуля optparse. Таким образом, оставшаяся опция - разобрать строку документации вручную и создать OptionParser. (Так что я приму ответ С. Лута)

Часть «Использование:» представлена ​​IndentedHelpFormatter, который можно заменить параметром форматирования в OptionParser .__ init __ ().

Ответы [ 3 ]

6 голосов
/ 08 апреля 2012

Я написал модуль docopt, чтобы делать именно то, что вы хотите - написать сообщение об использовании в docstring и оставаться сухим. Это также позволяет вообще избежать утомительного кода OptionParser, так как docopt генерирует парсер на основании сообщения об использовании.

Проверьте это: http://github.com/docopt/docopt

"""Naval Fate.

Usage:
  naval_fate.py ship new <name>...
  naval_fate.py ship [<name>] move <x> <y> [--speed=<kn>]
  naval_fate.py ship shoot <x> <y>
  naval_fate.py mine (set|remove) <x> <y> [--moored|--drifting]
  naval_fate.py -h | --help
  naval_fate.py --version

Options:
  -h --help     Show this screen.
  --version     Show version.
  --speed=<kn>  Speed in knots [default: 10].
  --moored      Moored (anchored) mine.
  --drifting    Drifting mine.

"""
from docopt import docopt


if __name__ == '__main__':
    arguments = docopt(__doc__, version='Naval Fate 2.0')
    print(arguments)
4 голосов
/ 11 августа 2009

Выбор 1: копировать и вставлять. Не СУХОЙ, но работоспособный.

Вариант 2: проанализируйте вашу собственную строку документации, чтобы вычеркнуть абзац описания. Это всегда второй абзац, так что вы можете разделить на \ n \ n. 

usage, description= __doc__.split('\n\n')[:2]

Поскольку optparse генерирует использование, вы, возможно, не захотите предоставлять ему предложение об использовании. Ваша версия использования может быть неправильной. Если вы настаиваете на предоставлении строки использования для optparse, я оставлю в качестве упражнения для читателя выяснить, как удалить "Usage: " из передней части строки usage, созданной выше.

1 голос
/ 11 августа 2009

Я думаю, что мы должны быть разумны в отношении этого совета PEP - я думаю, что было бы хорошо оставить модуль с __doc__, являющимся кратким описанием, которое суммирует длительное использование. Но если вы перфекционист: 

'''<tool name>

The full description and usage can be generated by optparse module.

Description: ...

'''

...

# Generate usage and options using optparse.
usage, options = ... 

# Modify the docstring on the fly.
docstring = __doc__.split('\n\n')
docstring[1:2] = [__license__, usage, options]
__doc__ = '\n\n'.join(docstring)
...