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:

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:
-- --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>)

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 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

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:

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:
-- --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>)

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 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
participants (6)
-
Bruce Leban
-
Ethan Furman
-
Guido van Rossum
-
Robert Kern
-
Terry Reedy
-
Ziad Sawalha