GNU bug report logs - #29003
[python.el] Docstring from PEP 257 is filled incorrectly by Emacs

Message received at submit <at> debbugs.gnu.org:

Received: (at submit) by debbugs.gnu.org; 26 Oct 2017 02:09:39 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed Oct 25 22:09:39 2017
Received: from localhost ([127.0.0.1]:33770 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1e7Xc3-0003qf-5C
	for submit <at> debbugs.gnu.org; Wed, 25 Oct 2017 22:09:39 -0400
Received: from eggs.gnu.org ([208.118.235.92]:34184)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <radon.neon@HIDDEN>) id 1e7Xc1-0003qQ-7v
 for submit <at> debbugs.gnu.org; Wed, 25 Oct 2017 22:09:37 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
 (envelope-from <radon.neon@HIDDEN>) id 1e7Xbv-0006Bh-9I
 for submit <at> debbugs.gnu.org; Wed, 25 Oct 2017 22:09:31 -0400
X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org
X-Spam-Level: 
X-Spam-Status: No, score=0.0 required=5.0 tests=BAYES_20,FREEMAIL_FROM,
 T_DKIM_INVALID autolearn=disabled version=3.3.2
Received: from lists.gnu.org ([2001:4830:134:3::11]:58482)
 by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32)
 (Exim 4.71) (envelope-from <radon.neon@HIDDEN>)
 id 1e7Xbv-0006Bc-5m
 for submit <at> debbugs.gnu.org; Wed, 25 Oct 2017 22:09:31 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:53388)
 by lists.gnu.org with esmtp (Exim 4.71)
 (envelope-from <radon.neon@HIDDEN>) id 1e7Xbu-0001Y3-9X
 for bug-gnu-emacs@HIDDEN; Wed, 25 Oct 2017 22:09:31 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
 (envelope-from <radon.neon@HIDDEN>) id 1e7Xbt-0006Au-Go
 for bug-gnu-emacs@HIDDEN; Wed, 25 Oct 2017 22:09:30 -0400
Received: from mail-lf0-x22b.google.com ([2a00:1450:4010:c07::22b]:45002)
 by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16)
 (Exim 4.71) (envelope-from <radon.neon@HIDDEN>)
 id 1e7Xbt-0006Ae-8Z
 for bug-gnu-emacs@HIDDEN; Wed, 25 Oct 2017 22:09:29 -0400
Received: by mail-lf0-x22b.google.com with SMTP id 75so2031820lfx.1
 for <bug-gnu-emacs@HIDDEN>; Wed, 25 Oct 2017 19:09:29 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025;
 h=mime-version:from:date:message-id:subject:to;
 bh=a4ds1HGfnm2QNTJGn71O6Ohv7+EUQFzxjooq1qBJeUQ=;
 b=TXDz8qltRhnLHuGUwcBAeZKSmF38jOhaCdvfHpiwQOohtg5CKGWpo/PKEvBmtKW8Pn
 cU3q3PsJMBGNeD+5w0fKUAI4PLBKxtVNeNgG2yUa32/n1AKTfkaW0wzKpt/L8klJTEO8
 NPiMryKkYhjtMEvjV1WmUDo4kqYan2GIsx/k3mGyLVfZXW3ontjipru2e5Jvf++6NQob
 7sXpP99t6U+/XwQZIxl1zn3wua/shwOet3rofWT9OzTeg5PvTaDxmQoNVJa+b+y6W8EB
 iVdFshT6a/MuOGLEh5Zho4daUYpxn9ehwGsTcrgGgSi/yVdje7x3odyxCShWK3I/xyRr
 FmvQ==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20161025;
 h=x-gm-message-state:mime-version:from:date:message-id:subject:to;
 bh=a4ds1HGfnm2QNTJGn71O6Ohv7+EUQFzxjooq1qBJeUQ=;
 b=fAaVjcIARYXPi4vWUbpFUxkQf3ox2ORrnVsJ/CJpwxLaxRB9bWWbdCK/ppmA8FeTnj
 EJNKd3v1Kv+d94dS51mlcSZcPlIWupUWaU5YPHhxhzX6onRNFkesTWcJlxvL6X5/kKyF
 IYwap5OsAr/KhDs1ykrd5Ulx+JjrpYAXdHdIOcXELd5zfuXk+lfFfTC7k7NebE4dPE9j
 HSrxCGpoMPLATcuGHBEKxsS4OHzGkQOBMMC4Mktw6v/8LJImWGES+KpUdJ54IglUgylm
 U/VVuCcMdWrjwdnZuK59DdYxuIPv+6eemrwQ4XW0YUe/aqU9imG4qsDfPfOnd3xsm3Pa
 Dw6A==
X-Gm-Message-State: AMCzsaUk2olmp5M1x7uTvMkRSw6IJHI2CnNqQq8UMwmyyEzHpkexgeYm
 0/TIQEY3PFPHH7WYy9is5litgi0Dsn3+ZFl2ySnabQ==
X-Google-Smtp-Source: ABhQp+QHwWD0OPS52Z+3ByrYal7Zgiao34LELkWG7hmw5DUILpFRT6PZ8fIqHElQ838R+MhoGO7G3oneLYnusElT6Rk=
X-Received: by 10.46.25.132 with SMTP id 4mr8864111ljz.145.1508983767658; Wed,
 25 Oct 2017 19:09:27 -0700 (PDT)
MIME-Version: 1.0
Received: by 10.25.208.10 with HTTP; Wed, 25 Oct 2017 19:08:47 -0700 (PDT)
From: Radon Rosborough <radon.neon@HIDDEN>
Date: Wed, 25 Oct 2017 19:08:47 -0700
Message-ID: <CADB4rJGsp0dnK59ngewtvMndzRm2eNBB==auC4niccztBQ2_cA@HIDDEN>
Subject: 25.3; Docstring from PEP 257 is filled incorrectly by Emacs
To: bug-gnu-emacs@HIDDEN
Content-Type: text/plain; charset="UTF-8"
X-detected-operating-system: by eggs.gnu.org: Genre and OS details not
 recognized.
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x
X-Received-From: 2001:4830:134:3::11
X-Spam-Score: -4.0 (----)
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -4.0 (----)

I recently noticed that Emacs fills an example docstring given [1] in
PEP 257 incorrectly. With `python-fill-docstring-style' at its default
value of `pep-257', the following code sample:

    def complex(real=0.0, imag=0.0):
        """Form a complex number.

        Keyword arguments:
        real -- the real part (default 0.0)
        imag -- the imaginary part (default 0.0)
        """
        if imag == 0.0 and real == 0.0:
            return complex_zero
        ...

is filled to:

    def complex(real=0.0, imag=0.0):
        """Form a complex number.

        Keyword arguments: real -- the real part (default 0.0) imag -- the
        imaginary part (default 0.0)

        """
        if imag == 0.0 and real == 0.0:
            return complex_zero
        ...

There are two issues here: the extra newline added, and the unwrapping
of the keyword arguments. The extra newline can be suppressed by
changing the value of `python-fill-docstring-style', but the keyword
argument unwrapping does not appear to be suppressible. This seems
erroneous to me since the value of `python-fill-docstring' would suggest
PEP 257 compliance, i.e. the examples given in PEP 257 should not be a
affected by wrapping. (I also checked out the third-party package
`python-docstring' [2], and it has the same behavior.)