Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to limit first line in Python docstrings to maximum line length during fill-paragraph in Emacs?

Tags:

python

emacs

My setup is Emacs 24.4.1, Linux, Python source code open in a buffer, Python mode 0.24.4 (comes with Emacs), fill-column set to 70, python-fill-docstring-style set to nil. I call fill-paragraph (M-q) from within a class method docstring to re-format the docstring such that no line is longer than 70 characters. But the first line of the docstring is always longer. Looks like the indentation (8 spaces) is not included in the line length calculation. What can I do to limit the line length to 70? Should I use python-mode.el instead?

Example:

class MyClass(object):
    def my_method(self):
        """Some long line with more than 70 characters in the docstring.  Some more text."""

After M-q in the docstring it looks like this. The first method docstring line ends at column 78 (and the second line is not indented, but that's a different issue):

class MyClass(object):
    def my_method(self):
        """Some long line with more than 70 characters in the docstring.  Some
more text."""

But with a line length of 70 it should be like this:

class MyClass(object):
    def my_method(self):
        """Some long line with more than 70 characters in the
        docstring.  Some more text."""
like image 397
holger Avatar asked Jul 20 '15 11:07

holger


2 Answers

With with current trunk of python-mode.el, r1993, and default style pep-257-nn it M-q yields

class MyClass(object):
    def my_method(self):
        """Some long line with more than 70 characters in the docstring.

        Some more text.
        """
like image 43
Andreas Röhler Avatar answered Nov 17 '22 14:11

Andreas Röhler


My answer consists of two parts:

  1. It is a bug in python.el that ships with Emacs. See GNU tickets #20860 and #21254. The workaround is to format the docstring manually.
  2. The first line should be a single sentence that is not longer than the maximum line length, followed by an empty line. All implemented docstring styles (django, onetwo, pep-257, pep-257-nn, symmetric) follow that rule. The first sentence doesn't need to be wrapped in that case and the first line can not be too long by definition.
like image 159
holger Avatar answered Nov 17 '22 13:11

holger