- Python Shortcuts, Commands, and Packages
- 4.2 Twenty-Two Programming Shortcuts
- 4.3 Running Python from the Command Line
- 4.4 Writing and Using Doc Strings
- 4.5 Importing Packages
- 4.6 A Guided Tour of Python Packages
- 4.7 Functions as First-Class Objects
- 4.8 Variable-Length Argument Lists
- 4.9 Decorators and Function Profilers
- 4.10 Generators
- 4.11 Accessing Command-Line Arguments
- Chapter 4 Summary
- Chapter 4 Questions for Review
- Chapter 4 Suggested Problems
This chapter is from the book
This chapter is from the book
This chapter is from the book
4.4 Writing and Using Doc Strings
Python doc strings enable you to leverage the work you do writing comments to get free online help. That help is then available to you while running IDLE, as well as from the command line, when you use the pydoc utility.
You can write doc strings for both functions and classes. Although this book has not yet introduced how to write classes, the principles are the same. Here’s an example with a function, showcasing a doc string.
def quad(a, b, c):
'''Quadratic Formula function.
This function applies the Quadratic Formula
to determine the roots of x in a quadratic
equation of the form ax^2 + bx + c = 0.
'''
determin = (b * b - 4 * a * c) ** .5
x1 = (-b + determin) / (2 * a)
x2 = (-b - determin) / (2 * a)
return x1, x2
When this doc string is entered in a function definition, you can get help from within IDLE:
>>> help(quad)
Help on function quad in module _ _main_ _:
quad(a, b, c)
Quadratic Formula function.
This function applies the Quadratic Formula
to determine the roots of x in a quadratic
equation of the form ax^2 + bx + c = 0.
The mechanics of writing a doc string follow a number of rules.
The doc string itself must immediately follow the heading of the function.
It must be a literal string utilizing the triple-quote feature. (You can actually use any style quote, but you need a literal quotation if you want to span multiple lines.)
The doc string must also be aligned with the “level-1” indentation under the function heading: For example, if the statements immediately under the function heading are indented four spaces, then the beginning of the doc string must also be indented four spaces.
Subsequent lines of the doc string may be indented as you choose, because the string is a literal string. You can place the subsequent lines flush left or continue the indentation you began with the doc string. In either case, Python online help will line up the text in a helpful way.
This last point needs some clarification. The doc string shown in the previous example could have been written this way:
def quad(a, b, c):
'''Quadratic Formula function.
This function applies the Quadratic Formula
to determine the roots of x in a quadratic
equation of the form ax^2 + bx + c = 0.
'''
determin = (b * b - 4 * a * c) ** .5
x1 = (-b + determin) / (2 * a)
x2 = (-b - determin) / (2 * a)
return x1, x2
You might expect this doc string to produce the desired behavior—to print help text that lines up—and you’d be right. But you can also put in extra spaces so that the lines also align within program code. It might seem this shouldn’t work, but it does.
For stylistic reasons, programmers are encouraged to write the doc string this way, in which the subsequent lines in the quote line up with the beginning of the quoted string instead of starting flush left in column 1:
def quad(a, b, c):
'''Quadratic Formula function.
This function applies the Quadratic Formula
to determine the roots of x in a quadratic
equation of the form ax^2 + bx + c = 0.
'''
As part of the stylistic guidelines, it’s recommended that you put in a brief summary of the function, followed by a blank line, followed by more detailed description.
When running Python from the command line, you can use the pydoc utility to get this same online help shown earlier. For example, you could get help on the module named queens.py. The pydoc utility responds by printing a help summary for every function. Note that “py” is not entered as part of the module name in this case.
python -m pydoc queens