Как я могу распечатать строку документации файла Python при его выполнении?

У меня есть скрипт Python со строкой документации. Когда синтаксический анализ аргументов командной строки не удается, я хочу распечатать строку документации для информации пользователя.

Есть какой-либо способ сделать это?

Минимальный пример

#!/usr/bin/env python
"""
Usage: script.py

This describes the script.
"""

import sys


if len(sys.argv) < 2:
    print("<here comes the docstring>")

python docstring
person thias    schedule 17.10.2011    source источник
comment
Существуют библиотеки для разбора аргументов командной строки: argparse (›=2.7) и optparse. docs.python.org/dev/library/argparse.html docs.python.org/dev/library/optparse.html   -  person codeape    schedule 17.10.2011
comment
Я знаю это, но это не имеет отношения к вопросу   -  person thias    schedule 17.10.2011
comment
Я один человек, который иногда явно не хочет использовать argparse для действительно простого скрипта, поэтому я благодарен тем, кто ниже ответил на заданный вопрос.   -  person SteveWithamDuplicate    schedule 24.06.2021

Ответы (5)


arrow_upward
99
arrow_downward

Строка документации хранится в глобальном файле __doc__ модуля.

print(__doc__)

Кстати, это касается любого модуля: import sys; print(sys.__doc__). Строки документации функций и классов также находятся в их атрибуте __doc__.

person Petr Viktorin    schedule 17.10.2011
comment
Это определенно работает, но есть и другой способ показать более нативный интерфейс справки модуля: help(module_name) после того, как вы импортируете этот модуль. - person danbgray; 03.05.2016
comment
@danbgray Я думаю, вы имеете в виду, для чего используется argparse - person jamescampbell; 18.03.2019
comment
WEIRD PYTHON 2 WRINKLE: Если вы поместите, например. from __future__ import print_function перед строкой документации, это больше не строка документации. Но вы можете поставить from __future__ import... сразу после строки документации, а импорт from __future__ должен происходить в начале файла, правило все равно выполняется. - person SteveWithamDuplicate; 24.06.2021

arrow_upward
13
arrow_downward

Вот альтернатива, которая не жестко задает имя файла сценария, а вместо этого использует sys.argv[0] для его печати. Использование %(scriptName)s вместо %s улучшает читаемость кода.

#!/usr/bin/env python
"""
Usage: %(scriptName)s

This describes the script.
"""

import sys
if len(sys.argv) < 2:
   print __doc__ % {'scriptName' : sys.argv[0].split("/")[-1]}
   sys.exit(0)
person wint3rschlaefer    schedule 25.02.2013
comment
благодаря. Обычно у меня есть функция Usage(), которая использует sys.argv[0], которая вызывается перед печатью строки документации. - person thias; 25.02.2013
comment
@wint3rschlaefer, не могли бы вы объяснить, как Usage: %(scriptName)s получает имя сценария? Как этот механизм называется в питоне? - person olala; 24.01.2016
comment
@wint3rschlaefer Возможно, стоит обновить версию python3, например """Usage: {scriptName}""".format(scriptName = sys.argv[0]) - person Cimbali; 09.08.2016
comment
Как насчет использования _name ? - person Otzen; 06.02.2021

arrow_upward
13
arrow_downward

Разбор аргументов всегда должен выполняться с помощью argparse.

Вы можете отобразить строку __doc__, передав ее параметру description Argparse:

#!/usr/bin/env python
"""
This describes the script.
"""


if __name__ == '__main__':
    from argparse import ArgumentParser
    parser = ArgumentParser(description=__doc__)
    # Add your arguments here
    parser.add_argument("-f", "--file", dest="myFilenameVariable",
                        required=True,
                        help="write report to FILE", metavar="FILE")
    args = parser.parse_args()
    print(args.myFilenameVariable)

Если вы вызовете этот mysuperscript.py и выполните его, вы получите:

$ ./mysuperscript.py --help
usage: mysuperscript.py [-h] -f FILE

This describes the script.

optional arguments:
  -h, --help            show this help message and exit
  -f FILE, --file FILE  write report to FILE
person Martin Thoma    schedule 28.07.2014

arrow_upward
1
arrow_downward

Это напечатает строку __doc__, когда --help является единственным аргументом.

if __name__=='__main__':
 if len(sys.argv)==2 and sys.argv[1]=='--help':
    print(__doc__)

Работает для обоих:

  • ./yourscriptname.py --help
  • python3 yourscriptname.py --help
person Mr CaT    schedule 26.11.2017

arrow_upward
0
arrow_downward

Улучшение ответа @MartinThoma, поэтому он печатает многострочные строки документации, вдохновленные Python argparse: Как вставить новую строку в текст справки?.

Разбор аргументов всегда должен выполняться с помощью argparse.

Вы можете отобразить строку doc, передав ее в параметр описания Argparse:

#!/usr/bin/env python 
""" 
This summarizes the script.

Additional descriptive paragraph(s).
"""  # Edited this docstring


if __name__ == '__main__':
    from argparse import ArgumentParser, RawTextHelpFormatter  # Edited this line
    parser = ArgumentParser(description=__doc__
                            formatter_class=RawTextHelpFormatter)  # Added this line
    # Add your arguments here
    parser.add_argument("-f", "--file", dest="myFilenameVariable",
                        required=True,
                        help="write report to FILE", metavar="FILE")
    args = parser.parse_args()
    print(args.myFilenameVariable)

Если вы вызовете это mysuperscript.py и выполните его, вы получите:

$ ./mysuperscript.py --help
usage: mysuperscript.py [-h] -f FILE

This summarizes the script.

Additional descriptive paragraph(s).

optional arguments:
  -h, --help            show this help message and exit
  -f FILE, --file FILE  write report to FILE

Без добавления formatter_class вывод не будет иметь разрыва строки в строке документации.

person jhale1805    schedule 28.01.2021