CODEWITHSUNDEEP
pythoncoding-style
Bram
Bram

Reputation: 825

Where can I find proper examples of the PEP 257 Docstring Conventions?

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

Upvotes: 17

Views: 15004

Answers (3)

Shahzaib Ali
Shahzaib Ali

Reputation: 412

here is some pep(Python Enhancement Proposal) python sample examples First we choose the version to go with like this sample is most similar to pep-8. So we have to provide the function description, parm and return type... 

def foo(bar, spam, eggs):
        """
        Some function

        :param bar: parameter that requires description
        :param spam: parameter that requires description
        :param eggs:
        :return xyz: parameter description
        """

According google style contains an excellent guide for python styling. That offers better guidance than PEP-257 here is the link for reference: google style guide

def sample_fun(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass

Upvotes: 0

Berislav Lopac
Berislav Lopac

Reputation: 17243

As far as I can see, the document you linked to says:

Insert a blank line 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.

(emphasis mine)

So, the examples you give are all correct as they have a blank line after the docstring, thus separating the next method declaration with a blank line.

Upvotes: 0

Vladimir Keleshev
Vladimir Keleshev

Reputation: 14245

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.

Upvotes: 11

Related Questions