17

I'm trying to use pydocstyle to check the quality of my docstring and I'm getting this error:

D205: 1 blank line required between summary line and description (found 0)

This is how my code looks like 

def func(input):
    """

    Function that does something interesting.
        Args:
            -input- Input of the function

    Returns:
        output- Output of the function

    """
    data = words + sentences
    corpus= somefunction(data)

When I put a blank line between the docstring and the function statements like so;

def func(input):
    """

    Function that does something interesting.
        Args:
            -input- Input of the function

    Returns:
        output- Output of the function

    """

    data = words + sentences
    corpus= somefunction(data)

I get the this errror:

D202: No blank lines allowed after function docstring (found 1)

How do I resolve this? Thanks for you help.

Richard Ackon
  • 651
  • 1
  • 7
  • 11

3 Answers3

20

See PEP 257 -- Docstring Conventions

def func(input):
    """**summary line, max. 79 chars including period** Do something interesting.

    **description starts after blank line above**
    Args:
        -input- Input of the function

    Returns:
        output- Output of the function

    """
    # no blank line allowed here

    data = [words, sentences]
    corpus = somefunction(data)
AcK
  • 2,063
  • 2
  • 20
  • 27
4

To Solve this, add a blank line after the first line of the Docstring.

According to PEP 257 -- Docstring Conventions, a Multi-line docstring consists of a Summary line(1st line) just like a one-line docstring, followed by a blank line and then a more Elaborate description follows. It is important that the summary line fits on one line and is separated from the rest of the docstring by a blank line.

def func(input):
    """Function that does something interesting.

    Args:
        - input - Input of the function

    Returns:
        - output - Output of the function
    """
    data = words + sentences
    corpus = somefunction(data)

Note

  • The Summary line can begin on the same line as the opening quotes or on the next line, preferably, the former.
  • There should be no blank lines after the opening quotes or before the closing quotes.

Read More...

Wangwe
  • 171
  • 1
  • 6
0

Making a python script simultaneously adhere to pydocstyle and pycodestyle is a challenge. But one thing which greatly helps is that in your docstring write the first line as summary of the function or class within 79 characters including .. This way you adhere to both PEP 257 (as per pydocstyle) of having a period at the end of an unbroken line and 79 characters limit of PEP 8 (as per pycodestyle).

Then after leaving one blank line (for that using new line shortcut of your code editor is better than manually pressing enter) you can write whatever you want and at that time focusing only on pycodestyle which is slightly easier than pydocstyle and the main reason is that our understanding of line and indentation is quite different than what system understands due to indentation settings, tab settings, line settings in the various code editors we use.So in this way you will have TODO from pycodestyle which you can understand and rectify easily instead of banging your head against the wall on pydocstyle mysteriousTODOs of 1 blank line, which you see is there but the system doesn't recognize.

riskdoctor
  • 241
  • 3
  • 3