PEP-257: drop recommendation for extra line at end of multi-line docstring
PEP-257 includes this recommendation: “The BDFL [3] recommends inserting a blank line between the last paragraph in a multi-line docstring and its closing quotes, placing the closing quotes on a line by themselves. This way, Emacs' fill-paragraph command can be used on it.” I believe emacs no longer has this limitation. "If you do fill-paragraph in emacs in Python mode within a docstring, emacs already ignores the closing triple-quote. In fact, the most recent version of emacs supports several different docstring formatting styles and gives you the ability to switch between them.” - quoting Kevin L. Mitchell who is more familiar with emacs than I am. I’m considering removing that recommendation and updating some of the examples in PEP-257, but I’d like some thoughts from this group before I submit the patch. Any thoughts or references to conversations that may have already been had on this topic? Regards, Ziad
To clarify are you asking to delete the recommendation of a blank line or the entire recommendation? That is are you suggesting the recommendation change to "It is recommended to place the closing quotes on a line by themselves." I think deleting it completely is a bad idea as otherwise it's hard to see where the docstring ends and the code begins, especially when using doctest. --- Bruce Learn how hackers think: http://j.mp/gruyere-security https://www.linkedin.com/in/bruceleban On Thu, Feb 27, 2014 at 2:06 PM, Ziad Sawalha <ziad.sawalha@rackspace.com>wrote:
PEP-257 includes this recommendation:
"The BDFL [3] recommends inserting a blank line between the last paragraph in a multi-line docstring and its closing quotes, placing the closing quotes on a line by themselves. This way, Emacs' fill-paragraph command can be used on it."
I believe emacs no longer has this limitation. "If you do fill-paragraph in emacs in Python mode within a docstring, emacs already ignores the closing triple-quote. In fact, the most recent version of emacs supports several different docstring formatting styles and gives you the ability to switch between them." - quoting Kevin L. Mitchell who is more familiar with emacs than I am.
I'm considering removing that recommendation and updating some of the examples in PEP-257, but I'd like some thoughts from this group before I submit the patch. Any thoughts or references to conversations that may have already been had on this topic?
Regards, Ziad _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
On Thu, Feb 27, 2014 at 2:41 PM, Bruce Leban <bruce@leapyear.org> wrote:
To clarify are you asking to delete the recommendation of a blank line or the entire recommendation?
That is are you suggesting the recommendation change to
"It is recommended to place the closing quotes on a line by themselves."
This clause must stay.
I think deleting it completely is a bad idea as otherwise it's hard to see where the docstring ends and the code begins, especially when using doctest.
--- Bruce Learn how hackers think: http://j.mp/gruyere-security https://www.linkedin.com/in/bruceleban
On Thu, Feb 27, 2014 at 2:06 PM, Ziad Sawalha <ziad.sawalha@rackspace.com>wrote:
PEP-257 includes this recommendation:
"The BDFL [3] recommends inserting a blank line between the last paragraph in a multi-line docstring and its closing quotes, placing the closing quotes on a line by themselves. This way, Emacs' fill-paragraph command can be used on it."
I believe emacs no longer has this limitation. "If you do fill-paragraph in emacs in Python mode within a docstring, emacs already ignores the closing triple-quote. In fact, the most recent version of emacs supports several different docstring formatting styles and gives you the ability to switch between them." - quoting Kevin L. Mitchell who is more familiar with emacs than I am.
I'm considering removing that recommendation and updating some of the examples in PEP-257, but I'd like some thoughts from this group before I submit the patch. Any thoughts or references to conversations that may have already been had on this topic?
Regards, Ziad _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
_______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido van Rossum (python.org/~guido)
On Feb 27, 2014, at 4:42 PM, "Bruce Leban" <bruce@leapyear.org<mailto:bruce@leapyear.org>> wrote: To clarify are you asking to delete the recommendation of a blank line or the entire recommendation? That is are you suggesting the recommendation change to “It is recommended to place the closing quotes on a line by themselves." That's right. I just want to get rid of the recommendation for the blank line. I think deleting it completely is a bad idea as otherwise it's hard to see where the docstring ends and the code begins, especially when using doctest. --- Bruce Learn how hackers think: http://j.mp/gruyere-security https://www.linkedin.com/in/bruceleban On Thu, Feb 27, 2014 at 2:06 PM, Ziad Sawalha <ziad.sawalha@rackspace.com<mailto:ziad.sawalha@rackspace.com>> wrote: PEP-257 includes this recommendation: “The BDFL [3] recommends inserting a blank line between the last paragraph in a multi-line docstring and its closing quotes, placing the closing quotes on a line by themselves. This way, Emacs' fill-paragraph command can be used on it.” I believe emacs no longer has this limitation. "If you do fill-paragraph in emacs in Python mode within a docstring, emacs already ignores the closing triple-quote. In fact, the most recent version of emacs supports several different docstring formatting styles and gives you the ability to switch between them.” - quoting Kevin L. Mitchell who is more familiar with emacs than I am. I’m considering removing that recommendation and updating some of the examples in PEP-257, but I’d like some thoughts from this group before I submit the patch. Any thoughts or references to conversations that may have already been had on this topic? Regards, Ziad _______________________________________________ Python-ideas mailing list Python-ideas@python.org<mailto:Python-ideas@python.org> https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
How about this patch? http://codereview.appspot.com/69870043 On Thu, Feb 27, 2014 at 5:48 PM, Ziad Sawalha <ziad.sawalha@rackspace.com>wrote:
On Feb 27, 2014, at 4:42 PM, "Bruce Leban" <bruce@leapyear.org> wrote:
To clarify are you asking to delete the recommendation of a blank line or the entire recommendation?
That is are you suggesting the recommendation change to
"It is recommended to place the closing quotes on a line by themselves."
That's right. I just want to get rid of the recommendation for the blank line.
I think deleting it completely is a bad idea as otherwise it's hard to see where the docstring ends and the code begins, especially when using doctest.
--- Bruce Learn how hackers think: http://j.mp/gruyere-security https://www.linkedin.com/in/bruceleban
On Thu, Feb 27, 2014 at 2:06 PM, Ziad Sawalha <ziad.sawalha@rackspace.com>wrote:
PEP-257 includes this recommendation:
"The BDFL [3] recommends inserting a blank line between the last paragraph in a multi-line docstring and its closing quotes, placing the closing quotes on a line by themselves. This way, Emacs' fill-paragraph command can be used on it."
I believe emacs no longer has this limitation. "If you do fill-paragraph in emacs in Python mode within a docstring, emacs already ignores the closing triple-quote. In fact, the most recent version of emacs supports several different docstring formatting styles and gives you the ability to switch between them." - quoting Kevin L. Mitchell who is more familiar with emacs than I am.
I'm considering removing that recommendation and updating some of the examples in PEP-257, but I'd like some thoughts from this group before I submit the patch. Any thoughts or references to conversations that may have already been had on this topic?
Regards, Ziad _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
_______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido van Rossum (python.org/~guido)
Approved :-) On Feb 27, 2014, at 9:33 PM, "Guido van Rossum" <guido@python.org<mailto:guido@python.org>> wrote: How about this patch? http://codereview.appspot.com/69870043 On Thu, Feb 27, 2014 at 5:48 PM, Ziad Sawalha <ziad.sawalha@rackspace.com<mailto:ziad.sawalha@rackspace.com>> wrote: On Feb 27, 2014, at 4:42 PM, "Bruce Leban" <bruce@leapyear.org<mailto:bruce@leapyear.org>> wrote: To clarify are you asking to delete the recommendation of a blank line or the entire recommendation? That is are you suggesting the recommendation change to “It is recommended to place the closing quotes on a line by themselves." That's right. I just want to get rid of the recommendation for the blank line. I think deleting it completely is a bad idea as otherwise it's hard to see where the docstring ends and the code begins, especially when using doctest. --- Bruce Learn how hackers think: http://j.mp/gruyere-security https://www.linkedin.com/in/bruceleban On Thu, Feb 27, 2014 at 2:06 PM, Ziad Sawalha <ziad.sawalha@rackspace.com<mailto:ziad.sawalha@rackspace.com>> wrote: PEP-257 includes this recommendation: “The BDFL [3] recommends inserting a blank line between the last paragraph in a multi-line docstring and its closing quotes, placing the closing quotes on a line by themselves. This way, Emacs' fill-paragraph command can be used on it.” I believe emacs no longer has this limitation. "If you do fill-paragraph in emacs in Python mode within a docstring, emacs already ignores the closing triple-quote. In fact, the most recent version of emacs supports several different docstring formatting styles and gives you the ability to switch between them.” - quoting Kevin L. Mitchell who is more familiar with emacs than I am. I’m considering removing that recommendation and updating some of the examples in PEP-257, but I’d like some thoughts from this group before I submit the patch. Any thoughts or references to conversations that may have already been had on this topic? Regards, Ziad _______________________________________________ Python-ideas mailing list Python-ideas@python.org<mailto:Python-ideas@python.org> https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/ _______________________________________________ Python-ideas mailing list Python-ideas@python.org<mailto:Python-ideas@python.org> https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/ -- --Guido van Rossum (python.org/~guido<http://python.org/~guido>)
Updated! On Thu, Feb 27, 2014 at 8:58 PM, Ziad Sawalha <ziad.sawalha@rackspace.com>wrote:
Approved :-)
On Feb 27, 2014, at 9:33 PM, "Guido van Rossum" <guido@python.org> wrote:
How about this patch? http://codereview.appspot.com/69870043
On Thu, Feb 27, 2014 at 5:48 PM, Ziad Sawalha <ziad.sawalha@rackspace.com>wrote:
On Feb 27, 2014, at 4:42 PM, "Bruce Leban" <bruce@leapyear.org> wrote:
To clarify are you asking to delete the recommendation of a blank line or the entire recommendation?
That is are you suggesting the recommendation change to
"It is recommended to place the closing quotes on a line by themselves."
That's right. I just want to get rid of the recommendation for the blank line.
I think deleting it completely is a bad idea as otherwise it's hard to see where the docstring ends and the code begins, especially when using doctest.
--- Bruce Learn how hackers think: http://j.mp/gruyere-security https://www.linkedin.com/in/bruceleban
On Thu, Feb 27, 2014 at 2:06 PM, Ziad Sawalha <ziad.sawalha@rackspace.com
wrote:
PEP-257 includes this recommendation:
"The BDFL [3] recommends inserting a blank line between the last paragraph in a multi-line docstring and its closing quotes, placing the closing quotes on a line by themselves. This way, Emacs' fill-paragraph command can be used on it."
I believe emacs no longer has this limitation. "If you do fill-paragraph in emacs in Python mode within a docstring, emacs already ignores the closing triple-quote. In fact, the most recent version of emacs supports several different docstring formatting styles and gives you the ability to switch between them." - quoting Kevin L. Mitchell who is more familiar with emacs than I am.
I'm considering removing that recommendation and updating some of the examples in PEP-257, but I'd like some thoughts from this group before I submit the patch. Any thoughts or references to conversations that may have already been had on this topic?
Regards, Ziad _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
_______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido van Rossum (python.org/~guido)
-- --Guido van Rossum (python.org/~guido)
And there was great rejoicing across the land! On 02/28/2014 09:53 AM, Guido van Rossum wrote:
Updated!
On Thu, Feb 27, 2014 at 8:58 PM, Ziad Sawalha <ziad.sawalha@rackspace.com <mailto:ziad.sawalha@rackspace.com>> wrote:
Approved :-)
On Feb 27, 2014, at 9:33 PM, "Guido van Rossum" <guido@python.org <mailto:guido@python.org>> wrote:
How about this patch? http://codereview.appspot.com/69870043
On Thu, Feb 27, 2014 at 5:48 PM, Ziad Sawalha <ziad.sawalha@rackspace.com <mailto:ziad.sawalha@rackspace.com>> wrote:
On Feb 27, 2014, at 4:42 PM, "Bruce Leban" <bruce@leapyear.org <mailto:bruce@leapyear.org>> wrote:
To clarify are you asking to delete the recommendation of a blank line or the entire recommendation?
That is are you suggesting the recommendation change to
“It is recommended to place the closing quotes on a line by themselves."
That's right. I just want to get rid of the recommendation for the blank line.
I think deleting it completely is a bad idea as otherwise it's hard to see where the docstring ends and the code begins, especially when using doctest.
--- Bruce Learn how hackers think: http://j.mp/gruyere-security https://www.linkedin.com/in/bruceleban
On Thu, Feb 27, 2014 at 2:06 PM, Ziad Sawalha <ziad.sawalha@rackspace.com <mailto:ziad.sawalha@rackspace.com>> wrote:
PEP-257 includes this recommendation:
“The BDFL [3] recommends inserting a blank line between the last paragraph in a multi-line docstring and its closing quotes, placing the closing quotes on a line by themselves. This way, Emacs' fill-paragraph command can be used on it.”
I believe emacs no longer has this limitation. "If you do fill-paragraph in emacs in Python mode within a docstring, emacs already ignores the closing triple-quote. In fact, the most recent version of emacs supports several different docstring formatting styles and gives you the ability to switch between them.” - quoting Kevin L. Mitchell who is more familiar with emacs than I am.
I’m considering removing that recommendation and updating some of the examples in PEP-257, but I’d like some thoughts from this group before I submit the patch. Any thoughts or references to conversations that may have already been had on this topic?
Regards, Ziad
Thanks, Guido. I’ll follow up with updates to common tools as I come across them (ex. pep257: https://github.com/GreenSteam/pep257/pull/64). Ziad On Feb 28, 2014, at 11:53 AM, Guido van Rossum <guido@python.org<mailto:guido@python.org>> wrote: Updated! On Thu, Feb 27, 2014 at 8:58 PM, Ziad Sawalha <ziad.sawalha@rackspace.com<mailto:ziad.sawalha@rackspace.com>> wrote: Approved :-) On Feb 27, 2014, at 9:33 PM, "Guido van Rossum" <guido@python.org<mailto:guido@python.org>> wrote: How about this patch? http://codereview.appspot.com/69870043 On Thu, Feb 27, 2014 at 5:48 PM, Ziad Sawalha <ziad.sawalha@rackspace.com<mailto:ziad.sawalha@rackspace.com>> wrote: On Feb 27, 2014, at 4:42 PM, "Bruce Leban" <bruce@leapyear.org<mailto:bruce@leapyear.org>> wrote: To clarify are you asking to delete the recommendation of a blank line or the entire recommendation? That is are you suggesting the recommendation change to “It is recommended to place the closing quotes on a line by themselves." That's right. I just want to get rid of the recommendation for the blank line. I think deleting it completely is a bad idea as otherwise it's hard to see where the docstring ends and the code begins, especially when using doctest. --- Bruce Learn how hackers think: http://j.mp/gruyere-security https://www.linkedin.com/in/bruceleban On Thu, Feb 27, 2014 at 2:06 PM, Ziad Sawalha <ziad.sawalha@rackspace.com<mailto:ziad.sawalha@rackspace.com>> wrote: PEP-257 includes this recommendation: “The BDFL [3] recommends inserting a blank line between the last paragraph in a multi-line docstring and its closing quotes, placing the closing quotes on a line by themselves. This way, Emacs' fill-paragraph command can be used on it.” I believe emacs no longer has this limitation. "If you do fill-paragraph in emacs in Python mode within a docstring, emacs already ignores the closing triple-quote. In fact, the most recent version of emacs supports several different docstring formatting styles and gives you the ability to switch between them.” - quoting Kevin L. Mitchell who is more familiar with emacs than I am. I’m considering removing that recommendation and updating some of the examples in PEP-257, but I’d like some thoughts from this group before I submit the patch. Any thoughts or references to conversations that may have already been had on this topic? Regards, Ziad _______________________________________________ Python-ideas mailing list Python-ideas@python.org<mailto:Python-ideas@python.org> https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/ _______________________________________________ Python-ideas mailing list Python-ideas@python.org<mailto:Python-ideas@python.org> https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/ -- --Guido van Rossum (python.org/~guido<http://python.org/~guido>) -- --Guido van Rossum (python.org/~guido<http://python.org/~guido>)
On 3/3/2014 1:55 PM, Ziad Sawalha wrote:
Thanks, Guido.
I’ll follow up with updates to common tools as I come across them (ex. pep257: https://github.com/GreenSteam/pep257/pull/64).
Does pep8.py try to enforce the extra blank? -- Terry Jan Reedy
On Mon, Mar 3, 2014 at 11:27 AM, Terry Reedy <tjreedy@udel.edu> wrote:
On 3/3/2014 1:55 PM, Ziad Sawalha wrote:
Thanks, Guido.
I'll follow up with updates to common tools as I come across them (ex. pep257: https://github.com/GreenSteam/pep257/pull/64).
I already did that.
Does pep8.py try to enforce the extra blank?
I dunno; it shouldn't. (I use it regularly and it doesn't complain to me.) -- --Guido van Rossum (python.org/~guido)
I haven't followed this recommendation for years. :-) Good riddance! (However, the one about two spaces after a period stands. :-) On Thu, Feb 27, 2014 at 2:06 PM, Ziad Sawalha <ziad.sawalha@rackspace.com>wrote:
PEP-257 includes this recommendation:
"The BDFL [3] recommends inserting a blank line between the last paragraph in a multi-line docstring and its closing quotes, placing the closing quotes on a line by themselves. This way, Emacs' fill-paragraph command can be used on it."
I believe emacs no longer has this limitation. "If you do fill-paragraph in emacs in Python mode within a docstring, emacs already ignores the closing triple-quote. In fact, the most recent version of emacs supports several different docstring formatting styles and gives you the ability to switch between them." - quoting Kevin L. Mitchell who is more familiar with emacs than I am.
I'm considering removing that recommendation and updating some of the examples in PEP-257, but I'd like some thoughts from this group before I submit the patch. Any thoughts or references to conversations that may have already been had on this topic?
Regards, Ziad _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido van Rossum (python.org/~guido)
On 2014-02-27 22:41, Guido van Rossum wrote:
I haven't followed this recommendation for years. :-) Good riddance!
FWIW, PEP 8 still suggests the old form, though the example was fixed to conform to the new suggestion: http://hg.python.org/peps/file/272debef6b77/pep-0008.txt#l548 http://hg.python.org/peps/rev/5efe00002b3e
(However, the one about two spaces after a period stands. :-)
Alas! -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco
Fixed. Thanks for pointing this out! On Sun, Mar 2, 2014 at 7:05 AM, Robert Kern <robert.kern@gmail.com> wrote:
On 2014-02-27 22:41, Guido van Rossum wrote:
I haven't followed this recommendation for years. :-) Good riddance!
FWIW, PEP 8 still suggests the old form, though the example was fixed to conform to the new suggestion:
http://hg.python.org/peps/file/272debef6b77/pep-0008.txt#l548 http://hg.python.org/peps/rev/5efe00002b3e
(However, the one about two spaces after a period stands. :-)
Alas!
-- Robert Kern
"I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco
_______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido van Rossum (python.org/~guido)
participants (6)
-
Bruce Leban -
Ethan Furman -
Guido van Rossum -
Robert Kern -
Terry Reedy -
Ziad Sawalha