No wrapping when there is a paragraph break

[tekumara]

example:

def func():
    """My awesome function.

    This line is quite long. In fact is it longer than one hundred and twenty characters so it should be wrapped but it is not.

    It doesn't wrap because of this line and the blank line in between! Delete them and it will wrap.
    """

When running docformatter it doesn't wrap, eg:

docformatter example.py --wrap-descriptions 120 --wrap-summaries 120

docformatter 1.5.0

[mcarans]

@weibullguy I just tried this (pip install git+ssh://[email protected]/PyCQA/docformatter@master#egg=docformatter then docformatter --in-place --wrap-descriptions=79 --wrap-summaries=79 downloader.py) with my multi-paragraph description below and the second paragraph (with blah blah...) didn't wrap. Is there something I'm meant to do to make it work?

        """Returns header of tabular file pointed to by url and an iterator
        where each row is returned as a list or dictionary depending on the
        dict_form argument. The headers argument is either a row number or list
        of row numbers (in case of multi-line headers) to be considered as
        headers (rows start counting at 1), or the actual headers defined as a
        list of strings. It defaults to 1 and cannot be None. The dict_form
        arguments specifies if each row should be returned as a dictionary or a
        list, defaulting to a list.

        Optionally, headers can be inserted at specific positions. This is achieved blah blah blah blah blah blah
        using the header_insertions argument. If supplied, it is a list of tuples of the
        form (position, header) to be inserted. A function is called for each row. If
        supplied, it takes as arguments: headers (prior to any insertions) and row
        (which will be in dict or list form depending upon the dict_rows argument) and
        outputs a modified row or None to ignore the row.

        Args:
            url (str): URL or path to read from
...
        """

[weibullguy]

@mcarans This is an example of the issue reported in #58. The Args: and following line causes docformatter to treat the entire docstring as a list and do nothing. If you remove those lines it will wrap. Support for conventions outside of PEP-257 such as rEST, numpy, google, etc. is in the works. The two offending lines fall into the outside PEP-257 category.

[mcarans]

@weibullguy It did correctly wrap the first paragraph, just not the second. Would it be possible for it to just ignore Args: and everything below, but wrap everything above?

[weibullguy]

@mcarans the first paragraph is the summary of a multi-line docstring (even if it's not PEP-257 compliant), it was wrapped because you passed the --wrap-summaries=79 argument. The remainder is the long description and wasn't wrapped for the reason discussed above. The plan is to have docformatter actually handle all the conventions and directives that are outside PEP-257. I don't know that having an intermediate step to accomplish what you're suggesting is any easier than just adding the functionality to handle the rEST directives.

[mcarans]

@weibullguy Perhaps it would be useful to have a feature to tell docformatter to leave part of the docstring alone? For example, someone may have manually set up part of the docstring exactly as they want it and don't want it to be touched. The user could supply a regex for what part is to be left alone (or what part is to be changed if that is more useful).

That general feature would also allow for my specific case of wanting to ignore Args: and what follows (the regex would be something like Args.*).

[weibullguy]

@mcarans Not a bad idea and would be at least a short-term solution for many of the reST, numpy, google, etc. related issues. I would suggest using comment directives to turn docformatter on and off such that:

• # docfmt: skip turns off docformatter in-line
• # docfmt: off and # docfmt: on turn docformatter off for a chunk of docstring and back on.

For example:

"""Short summary for the docstring that's actually really long and would be wrapped. # docfmt: skip

This is a long description.  It could be many paragraphs long.  Following
this long description, is non PEP-257 stuff like reST directives that we 
don't want docformatter to touch.

# docfmt: off
Args:
            url (str): URL or path to read from
# docfmt: on
"""

The only problem I encounter with the quick example is pydocstyle raising a D400: First line should end with a period (not 'p') warning. There could be others.

If that seems to address your suggestion, why don't you raise a new issue requesting the functionality? If you do, please reference this comment.