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

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

Строка документации скрипта (автономной программы) должна быть пригодна для использования в качестве сообщения об использовании, которое выводится при вызове скрипта с неправильными или отсутствующими аргументами (или, возможно, с опцией "-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__().


python optparse
person wierob    schedule 11.08.2009    source источник

Ответы (3)


arrow_upward
4
arrow_downward

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

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

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

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

person S.Lott    schedule 11.08.2009
comment
Мне нравится второе решение. Не очень чистоплотный, но умный и прагматичный. - person e-satis; 11.08.2009
comment
Поскольку пустые строки между абзацами являются стандартом RST, это избавляет от выполнения полного синтаксического анализа Docutils в doc и дает ожидаемый результат — по определению. - person S.Lott; 11.08.2009
comment
Это может быть вариант для описания. Но я все еще не могу повторно использовать часть «использование», и optparse заставляет сообщение начинаться с Usage: . - person wierob; 11.08.2009

arrow_upward
6
arrow_downward

Я написал модуль docopt, чтобы делать именно то, что вы хотите — писать сообщение об использовании в строке документации и оставаться СУХИМ. Это также позволяет вообще избежать написания утомительного 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)
person Vladimir Keleshev    schedule 08.04.2012

arrow_upward
1
arrow_downward

Я думаю, что мы должны разумно относиться к совету этого 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)
person ilya n.    schedule 11.08.2009