98

I have a Python script with a docstring. When the parsing of the command-line arguments does not succeed, I want to print the docstring for the user's information.

Is there any way to do this?

Minimal example

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

This describes the script.
"""

import sys


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

5 Answers 5

118

The docstring is stored in the module's __doc__ global.

print(__doc__)

By the way, this goes for any module: import sys; print(sys.__doc__). Docstrings of functions and classes are also in their __doc__ attribute.

3
  • 2
    That definitely works, but there is another way that shows a more native looking module help interface:: help(module_name) after you import that module.
    – danbgray
    May 3, 2016 at 14:33
  • 2
    @danbgray I think what you are getting at is what argparse is used for
    – james-see
    Mar 18, 2019 at 16:29
  • 1
    WEIRD PYTHON 2 WRINKLE: If you put, e.g. "from __future__ import print_function" before the docstring, it's not a docstring anymore. But you can put "from __future__" import... just after the docstring, and the "from __future__ imports must occur at the beginning of the file" rule is still satisfied. Jun 24, 2021 at 17:59
17

Argument parsing should always be done with argparse.

You can display the __doc__ string by passing it to the description parameter of 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)

If you call this mysuperscript.py and execute it you get:

$ ./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
14

Here is an alternative that does not hardcode the script's filename, but instead uses sys.argv[0] to print it. Using %(scriptName)s instead of %s improves readability of the code.

#!/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)
4
  • thanks. I usually have a usage() function that uses sys.argv[0] which is called before printing the docstring.
    – thias
    Feb 25, 2013 at 9:59
  • @wint3rschlaefer, could you explain how Usage: %(scriptName)s get the script name? What is this mechanism called in python?
    – olala
    Jan 24, 2016 at 16:40
  • 1
    @wint3rschlaefer Maybe it's worth updating with a python3 version, like """Usage: {scriptName}""".format(scriptName = sys.argv[0])
    – Cimbali
    Aug 9, 2016 at 10:38
  • 1
    How about using _name ?
    – Otzen
    Feb 5, 2021 at 22:16
1

This will print the __doc__ string when --help is the only argument.

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

Works for both:

  • ./yourscriptname.py --help
  • python3 yourscriptname.py --help
1

An enhancement of @MartinThoma's answer so it prints multi-line docstrings inspired by Python argparse: How to insert newline in the help text?.

Argument parsing should always be done with argparse.

You can display the doc string by passing it to the description parameter of 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) 

If you call this mysuperscript.py and execute it you get:

$ ./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

Without the addition of the formatter_class the output would not have the line break in the docstring.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.