Menu
PEP 257 says:
Insert a blank line before and after all docstrings (one-line or multi-line) that document a class -- generally speaking, the class's methods are separated from each other by a single blank line, and the docstring needs to be offset from the first method by a blank line; for symmetry, put a blank line between the class header and the docstring.
But I can't seem to find any code that actually implements this.
I've checked several standard modules delivered with Python 2.6, even searched specifically for ones where Guido's name is mentioned. But even the code of the rietveld code review tool does IMHO not comply (see e.g. http://code.google.com/p/rietveld/source/browse/upload.py):
class CondensedHelpFormatter(optparse.IndentedHelpFormatter):
"""Frees more horizontal space by removing indentation from group
options and collapsing arguments between short and long, e.g.
'-o ARG, --opt=ARG' to -o --opt ARG"""
def format_heading(self, heading):
return "%s:\n" % heading
This multi line docstring does not have a blank line in before and the blank line after is outside the closing quotes.
This class from /usr/lib64/python2.6/site.py does not have a blank line before but has a blank line before and after the closing quotes.
class _Helper(object):
"""Define the built-in 'help'.
This is a wrapper around pydoc.help (with a twist).
"""
def __repr__(self):
Are there examples available to demonstrate PEP 257?
Thanks in advance
414
One-line Docstrings This looks better for one-liners. For example: def power(a, b): """Returns arg1 raised to power arg2."""
Don't use whitespace to line up operators. Multiple statements on the same line are discouraged.
Docstrings are accessible from the doc attribute (__doc__) for any of the Python objects and also with the built-in help() function. An object's docstring is defined by including a string constant as the first statement in the object's definition.
The docstring for a module function should include the same items as a class method: A brief description of what the function is and what it's used for. Any arguments (both required and optional) that are passed including keyword arguments. Label any arguments that are considered optional.
Not a direct answer, but if you want to comply with PEP257 you can use a tool I wrote: https://github.com/halst/pep257
I too was shocked to see how much code (also in the standard library) does not even try to comply with PEP257.
Probably, most people think that their docstring-style makes sense, and I also thought there is something awkward to the PEP257 style, but after using it for some time I fell in love with it, and think that it is the most beautiful way to write docstrings. I always follow PEP257 in every aspect I can, and wrote the tool so that more people could see how they can improve their style.
As an example, I had a funny experience with PEP8 and pep8 tool: when I first read PEP8 I liked it and thought I follow it, but when I tried my code on pep8 I was shocked by how far from PEP8 I am, and how better my code looks after I fix those style-errors.
I hope people will have similar experience with pep257, and start to follow PEP257 happily ever after.
123
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
