bug#18819: 24.3.93; python-mode: fill-paragraph breaks comments in a way that annoys "flake8"

bug#18819: 24.3.93; python-mode: fill-paragraph breaks comments in a way that annoys "flake8"

[Eric Hanchrow]

Some background: "flake8" (http://flake8.readthedocs.org/en/2.2.3/) is a
tool that examines a Python program, and complains about bad style.  I
use it frequently to ensure that my Python code conforms to the standard
conventions.

Anyhoo ... I noticed that filling a comment paragraph, in a way that
seems natural to me, leaves me with code that flake8 complains about.
Here's how to see what I saw:

* start `emacs -q`
* type C-x C-f /tmp/frotz.py RET
* enter the below two lines of Python code, including the
absurdly-long comment, into the python-mode buffer:
====8-<=======8-<=======8-<=======8-<=======8-<=======8-<=======8-<=======8-<===
def yow():
    when = time.time() # hey you hey you hey you hey you hey you hey you hey you
====8-<=======8-<=======8-<=======8-<=======8-<=======8-<=======8-<=======8-<===
* put point at the end of the second line, then type M-q, and then
save with C-x Cs

You'll see
====8-<=======8-<=======8-<=======8-<=======8-<=======8-<=======8-<=======8-<===
def yow():
    when = time.time() # hey you hey you hey you hey you hey you hey
                       # you hey you
====8-<=======8-<=======8-<=======8-<=======8-<=======8-<=======8-<=======8-<===

... to be honest, that looks good to me; but (assuming you've got flake8
installed -- "pip install flake8" is the easiest way) if you then do M-x
compile RET flake8 frotz.py RET, you'll see (along with a few other
lines that aren't relevant here)

    frotz.py:3:24: E111 indentation is not a multiple of four
    frotz.py:3:24: E113 unexpected indentation

So, in a perfect world, M-q would have ... somehow ... fiddled the
indentation so that flake8 was happy.  I can't offhand think of a way to
do that that wouldn't perplex the naïve user, but there you go :-)

In GNU Emacs 24.3.93.1 (x86_64-apple-darwin13.4.0, NS apple-appkit-1265.21)
 of 2014-10-06 on Eric-Hanchrows-iMac.local
Repository revision: eliz@gnu.org-20140929191028-lti2lybtzzrnjppc
Windowing system distributor `Apple', version 10.3.1343
Configured using:
 `configure --with-ns'

Important settings:
  locale-coding-system: utf-8-unix

Major mode: Python

Minor modes in effect:
  shell-dirtrack-mode: t
  tooltip-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  column-number-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
C-x C-f / t m p / f r o t z . p y C-j C-y C-p C-p C-p
C-p C-o d e f SPC y o w M-( C-e : C-M-p M-\ C-n <tab>
C-n C-n C-n M-m C-SPC C-p C-p C-f C-f C-x r d C-n C-n
M-^ M-^ M-^ M-; M-> C-x C-s C-p C-p C-e M-q C-x C-s
M-x c o m p i l e <return> C-a C-k f l a k e 8 7 <backspace>
SPC f r <tab> <return> M-x c o l u m n <tab> <return>
M-m C-h c M-q C-d C-p C-d C-n M-^ M-^ M-> C-p C-p M-f
M-f M-f M-f M-b C-k h e y SPC y o u SPC M-b M-b C-k
C-y C-y C-y C-y C-y C-y C-y C-x C-s M-q C-x C-s C-x
o g C-x o M-m C-d M-^ C-x C-s M-x r e p o e <backspace>
r t - e m <tab> <return>

Recent messages:
M-q runs the command fill-paragraph
Mark set [8 times]
Saving file /tmp/frotz.py...
Wrote /tmp/frotz.py
Saving file /tmp/frotz.py...
Wrote /tmp/frotz.py
(No files need saving)
Compilation exited abnormally with code 1
Saving file /tmp/frotz.py...
Wrote /tmp/frotz.py

Load-path shadows:
None found.

Features:
(shadow sort gnus-util mail-extr emacsbug message format-spec rfc822 mml
mml-sec mm-decode mm-bodies mm-encode mail-parse rfc2231 mailabbrev
gmm-utils mailheader sendmail rfc2047 rfc2045 ietf-drums mm-util
help-fns mail-prsvr mail-utils cus-start cus-load shell pcomplete
compile rect python easymenu json comint ring cl-loaddefs cl-lib
ansi-color time-date tooltip electric uniquify ediff-hook vc-hooks
lisp-float-type mwheel ns-win tool-bar dnd fontset image regexp-opt
fringe tabulated-list newcomment lisp-mode prog-mode register page
menu-bar rfn-eshadow timer select scroll-bar mouse jit-lock font-lock
syntax facemenu font-core frame cham georgian utf-8-lang misc-lang
vietnamese tibetan thai tai-viet lao korean japanese hebrew greek
romanian slovak czech european ethiopic indian cyrillic chinese
case-table epa-hook jka-cmpr-hook help simple abbrev minibuffer nadvice
loaddefs button faces cus-face macroexp files text-properties overlay
sha1 md5 base64 format env code-pages mule custom widget
hashtable-print-readable backquote make-network-process cocoa ns
multi-tty emacs)

Memory information:
((conses 16 109477 8810)
 (symbols 48 28490 0)
 (miscs 40 62 307)
 (strings 32 32817 4135)
 (string-bytes 1 594338)
 (vectors 16 11023)
 (vector-slots 8 401785 5355)
 (floats 8 62 391)
 (intervals 56 330 8)
 (buffers 960 13))

bug#18819: 24.3.93; python-mode: fill-paragraph breaks comments in a way that annoys "flake8"

[Fabián Ezequiel Gallina]

Hello Eric,

Note that inline comments are pretty much discouraged[0].

Leaving that aside, the problem is that inline comments should fit in
their own line.  In the example you provided, you are trying to make an
inline comment that's too large to fit the line and in that case the
recommendation would be to turn it into a normal comment just before the
statement.

So, surprisingly, it seems in this case both flake8 and python.el are
right :)

[0] https://www.python.org/dev/peps/pep-0008#inline-comments



Thanks,
Fabián