Hello all, I'm sure this will be shot down [1], but it annoys me often enough that I'm going to suggest it anyway. :-) A recent tweet of Raymond's reminded me how useful textwrap.dedent() is for dedenting triple quoted strings in code blocks: def function(): this_string = textwrap.dedent("""\ Here is some indented text. that dedent will handle for us.""" ) Unfortunately that doesn't work for docstrings as they must be string literals. It is compounded by the fact that you can't even create the docstring for a class and manually assign it later. (Why not? But that's another issue...) How about *another* string prefix for dedented strings: class Thing(object): d""" This text will be, nicely dedented, thank you very much. """" All the best, Michael Foord [1] Because of the -100 rule as much as anything else, which applies doubly to features requiring new syntax https://blogs.msdn.com/b/ericgu/archive/2004/01/12/57985.aspx -- http://www.voidspace.org.uk/ May you do good and not evil May you find forgiveness for yourself and forgive others May you share freely, never taking more than you give. -- the sqlite blessing http://www.sqlite.org/different.html
This has been discussed a few times in the past. http://mail.python.org/pipermail/python-ideas/2011-May/010207.html triple-quoted strings and indendation http://mail.python.org/pipermail/python-ideas/2010-November/008589.html Multi-line strings that respect indentation --- Bruce Follow me: http://www.twitter.com/Vroo http://www.vroospeak.com On Tue, Aug 16, 2011 at 2:33 PM, Michael Foord <fuzzyman@gmail.com> wrote:
Michael Foord <fuzzyman@gmail.com> writes:
class Thing(object): """ This literal string contains leading and trailing whitespace. It also is indented. But none of that will show up when the docstring is processed and presented to the user. Because it is a docstring that conforms to PEP 257, the indentation will be handled properly by PEP-257 conformant docstring processors. <http://www.python.org/dev/peps/pep-0257/#handling-docstring-indentation>_ gives the specification for how indentation shall be handled by code that processes Python docstrings. The programmer inspecting the value of ‘__doc__’ will still see the leading, trailing, and indenting whitespace; but the programmer doing so isn't the recipient of the docstring as a docstring. So I don't see what problem there is to be solved. """ pass -- \ “Guaranteed to work throughout its useful life.” —packaging for | `\ clockwork toy, Hong Kong | _o__) | Ben Finney
On 16 August 2011 22:58, Ben Finney <ben+python@benfinney.id.au> wrote:
The place I'm concerned about is the interactive interpreter, virtually the only place I look at docstrings that isn't directly in the source code (or pre-processed by a doc tool - but I don't care about that). Michael
-- http://www.voidspace.org.uk/ May you do good and not evil May you find forgiveness for yourself and forgive others May you share freely, never taking more than you give. -- the sqlite blessing http://www.sqlite.org/different.html
Michael Foord <fuzzyman@gmail.com> writes:
Right, and the interactive interpreter's ‘help’ follows the PEP 257 specification for handling whitespace in docstrings. If it doesn't, I'd consider that a bug to be fixed. On the other hand, if you're doing things like ‘print foo.__doc__’, I don't think we need to do anything special to support that. You have ‘help’ available in the interpreter to nicely format an object's docstrings, right? -- \ “Let others praise ancient times; I am glad I was born in | `\ these.” —Ovid (43 BCE–18 CE) | _o__) | Ben Finney
On Tue, 2011-08-16 at 23:43 +0100, Michael Foord wrote:
Why don't you use bpython? It shows the docstring automatically as you're typing a class, without all the methods, and properly formatted. Also if you're working with docstrings yourself there's inspect.getdoc which handles whitespace/indentation. (But I still consider your proposal useful.)
Michael Foord wrote:
I think you need to explain the problem being solved, and your requirements, in a bit more detail here. As I understand it, the above is equivalent to this: class Thing(object): """ This text will be, nicely dedented, thank you very much. """ except that it looks indented in the source file. Compare that to the usual practice: class Thing(object): """ This text will be, nicely dedented, thank you very much. """ and the only difference is a bunch of leading spaces. If all you do with the docstrings is read them with help() in the interactive interpreter, why do you care about saving a few spaces? help() calls pydoc, which does its own reformatting of the docstring. Unless you regularly inspect instance.__doc__ by hand (not via help), I'm not sure what you hope to accomplish here. -- Steven
On Wed, Aug 17, 2011 at 9:36 AM, Steven D'Aprano <steve@pearwood.info> wrote:
Unless you regularly inspect instance.__doc__ by hand (not via help), I'm not sure what you hope to accomplish here.
One trick I did discover thanks to this thread: 'pydoc.pager = pydoc.plainpager' Eliminates the potentially annoying behaviour where help() takes over the entire terminal window and doesn't appear in the scrollback history. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On 17 August 2011 04:33, Nick Coghlan <ncoghlan@gmail.com> wrote:
Thanks Nick, that does make help substantially less annoying. I'll add it to my python startup. All the best, Michael
-- http://www.voidspace.org.uk/ May you do good and not evil May you find forgiveness for yourself and forgive others May you share freely, never taking more than you give. -- the sqlite blessing http://www.sqlite.org/different.html
On 17 August 2011 13:58, Michael Foord <fuzzyman@gmail.com> wrote:
Although `help(klass)` is still (often) way too verbose if I *just* want to see the class docstring (help shows all methods and their docstrings too). And as you can't modify a class docstring there's no way to fix indented text there. All the best, Michael
-- http://www.voidspace.org.uk/ May you do good and not evil May you find forgiveness for yourself and forgive others May you share freely, never taking more than you give. -- the sqlite blessing http://www.sqlite.org/different.html
On Wed, Aug 17, 2011 at 7:31 AM, Michael Foord <fuzzyman@gmail.com> wrote:
See http://bugs.python.org/issue12773. -eric
This has been discussed a few times in the past. http://mail.python.org/pipermail/python-ideas/2011-May/010207.html triple-quoted strings and indendation http://mail.python.org/pipermail/python-ideas/2010-November/008589.html Multi-line strings that respect indentation --- Bruce Follow me: http://www.twitter.com/Vroo http://www.vroospeak.com On Tue, Aug 16, 2011 at 2:33 PM, Michael Foord <fuzzyman@gmail.com> wrote:
Michael Foord <fuzzyman@gmail.com> writes:
class Thing(object): """ This literal string contains leading and trailing whitespace. It also is indented. But none of that will show up when the docstring is processed and presented to the user. Because it is a docstring that conforms to PEP 257, the indentation will be handled properly by PEP-257 conformant docstring processors. <http://www.python.org/dev/peps/pep-0257/#handling-docstring-indentation>_ gives the specification for how indentation shall be handled by code that processes Python docstrings. The programmer inspecting the value of ‘__doc__’ will still see the leading, trailing, and indenting whitespace; but the programmer doing so isn't the recipient of the docstring as a docstring. So I don't see what problem there is to be solved. """ pass -- \ “Guaranteed to work throughout its useful life.” —packaging for | `\ clockwork toy, Hong Kong | _o__) | Ben Finney
On 16 August 2011 22:58, Ben Finney <ben+python@benfinney.id.au> wrote:
The place I'm concerned about is the interactive interpreter, virtually the only place I look at docstrings that isn't directly in the source code (or pre-processed by a doc tool - but I don't care about that). Michael
-- http://www.voidspace.org.uk/ May you do good and not evil May you find forgiveness for yourself and forgive others May you share freely, never taking more than you give. -- the sqlite blessing http://www.sqlite.org/different.html
Michael Foord <fuzzyman@gmail.com> writes:
Right, and the interactive interpreter's ‘help’ follows the PEP 257 specification for handling whitespace in docstrings. If it doesn't, I'd consider that a bug to be fixed. On the other hand, if you're doing things like ‘print foo.__doc__’, I don't think we need to do anything special to support that. You have ‘help’ available in the interpreter to nicely format an object's docstrings, right? -- \ “Let others praise ancient times; I am glad I was born in | `\ these.” —Ovid (43 BCE–18 CE) | _o__) | Ben Finney
On Tue, 2011-08-16 at 23:43 +0100, Michael Foord wrote:
Why don't you use bpython? It shows the docstring automatically as you're typing a class, without all the methods, and properly formatted. Also if you're working with docstrings yourself there's inspect.getdoc which handles whitespace/indentation. (But I still consider your proposal useful.)
Michael Foord wrote:
I think you need to explain the problem being solved, and your requirements, in a bit more detail here. As I understand it, the above is equivalent to this: class Thing(object): """ This text will be, nicely dedented, thank you very much. """ except that it looks indented in the source file. Compare that to the usual practice: class Thing(object): """ This text will be, nicely dedented, thank you very much. """ and the only difference is a bunch of leading spaces. If all you do with the docstrings is read them with help() in the interactive interpreter, why do you care about saving a few spaces? help() calls pydoc, which does its own reformatting of the docstring. Unless you regularly inspect instance.__doc__ by hand (not via help), I'm not sure what you hope to accomplish here. -- Steven
On Wed, Aug 17, 2011 at 9:36 AM, Steven D'Aprano <steve@pearwood.info> wrote:
Unless you regularly inspect instance.__doc__ by hand (not via help), I'm not sure what you hope to accomplish here.
One trick I did discover thanks to this thread: 'pydoc.pager = pydoc.plainpager' Eliminates the potentially annoying behaviour where help() takes over the entire terminal window and doesn't appear in the scrollback history. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On 17 August 2011 04:33, Nick Coghlan <ncoghlan@gmail.com> wrote:
Thanks Nick, that does make help substantially less annoying. I'll add it to my python startup. All the best, Michael
-- http://www.voidspace.org.uk/ May you do good and not evil May you find forgiveness for yourself and forgive others May you share freely, never taking more than you give. -- the sqlite blessing http://www.sqlite.org/different.html
On 17 August 2011 13:58, Michael Foord <fuzzyman@gmail.com> wrote:
Although `help(klass)` is still (often) way too verbose if I *just* want to see the class docstring (help shows all methods and their docstrings too). And as you can't modify a class docstring there's no way to fix indented text there. All the best, Michael
-- http://www.voidspace.org.uk/ May you do good and not evil May you find forgiveness for yourself and forgive others May you share freely, never taking more than you give. -- the sqlite blessing http://www.sqlite.org/different.html
On Wed, Aug 17, 2011 at 7:31 AM, Michael Foord <fuzzyman@gmail.com> wrote:
See http://bugs.python.org/issue12773. -eric
participants (7)
-
Ben Finney -
Bruce Leban -
Dag Odenhall -
Eric Snow -
Michael Foord -
Nick Coghlan -
Steven D'Aprano