How to work with long literal lines in docstring? (backslash-newline not supported)

[glennmatthews]

If I have have long lines in a docstring that need to remain so (e.g., a doctest that produces long output), it gets flagged by pycodestyle for exceeding the 79-character line limit (E501). However, if I use backslash-newlines to wrap the doctest, then pydocstyle flags it with D207 and D301. Short of using # noqa, is there some other workaround? If not, can D207/D301 be enhanced to permit backslash-newline wrapping as valid?

example.py:

"""Module docstring."""


def foo():
    """Docstring not liked by pycodestyle.

    >>> print("this is a doctest which produces some long unwrapped output, sorry about that!")
    this is a doctest which produces some long unwrapped output, sorry about that!
    """
    pass


def bar():
    """Docstring not liked by pydocstyle.

    >>> print("this is a doctest which produces some long unwrapped output,\
sorry about that!")
    this is a doctest which produces some long unwrapped output,\
sorry about that!
    """
    pass


if __name__ == "__main__":
    import doctest
    doctest.testmod()

GLMATTHE-M-33R4:cot glmatthe$ pycodestyle example.py
example.py:7:80: E501 line too long (95 > 79 characters)
example.py:8:80: E501 line too long (82 > 79 characters)
GLMATTHE-M-33R4:cot glmatthe$ pydocstyle example.py
example.py:13 in public function `bar`:
        D301: Use r""" if any backslashes in a docstring
example.py:13 in public function `bar`:
        D207: Docstring is under-indented

[Nurdok]

I'm actually not sure what would be the best way to solve this. A "# noqa: D301" might be a reasonable solution as it looks pretty rare to me. @farmersez Any thoughts?

[glennmatthews]

Is it possible to have D301 ignore backslash-newline and have D207 not check indentation of lines preceded by backslash-newline?

[shacharoo]

IMO, if the docstring already looks badly-formatted (not your fault, of course 😄 ), a # noqa should suffice. I don't think this should be a special case in the D301 check.

[Nurdok]

Agreed. Closing this issue - # noqa: D301 (or # noqa: E501 for pycodestyle) is a reasonable solution.

[anntzer]

Kindly requesting the issue be reopened. The proposed solution does not work: where would you put the #noqa? -- it can't go after the backslash...

[Nurdok]

The # noqa statement goes in the same line as the def's colon. Here are examples from our tests:

def docstring_bad_ignore_all():  # noqa
    """Runs something"""
    pass


def docstring_bad_ignore_one():  # noqa: D400,D401
    """Runs something"""
    pass


def docstring_ignore_violations_of_pydocstyle_D400_and_PEP8_E501_but_catch_D401():  # noqa: E501,D400
    """Runs something"""
    pass

[jclerman]

It took me a long time to figure this out; hopefully it'll help someone else: As of flake8 (which uses pydocstyle) version 3.8.4 (and still, apparently, in 3.9.1), the noqa: D301 now has to go at the end of the multi-line docstring; it appears to be ignored if it's placed on the function-definition line.

So this works for flake8 version 3.8.4, and 3.9.1:

@click.command()
def my_func(my_input: str):
    """Do something.

    More details.
    \f
    These details are hidden from click help output.
    """  # noqa: D301
    pass

But this is what you need for flake8 version 3.7.9:

@click.command()
def my_func(my_input: str):  # noqa: D301
    """Do something.

    More details.
    \f
    These details are hidden from click help output.
    """
    pass