This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Describe what ‘inspect.cleandoc’ does to synopsis line.
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: bignose, docs@python, martin.panter, nharold, orsenthil, python-dev
Priority: normal Keywords: patch

Created on 2016-05-17 00:42 by bignose, last changed 2022-04-11 14:58 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
cleandoc.patch nharold, 2016-05-26 16:58 Revise inspect.cleandoc documentation review
cleandoc2.patch nharold, 2016-05-27 16:18 Split paragraphs review
Messages (9)
msg265741 - (view) Author: Ben Finney (bignose) Date: 2016-05-17 00:42
The library documentation for ‘inspect.cleandoc’ describes the transformation that occurs to “the second line onwards”, but makes no mention of what processing occurs to the synopsis (first) line.

Please update the library documentation for this function, to explicitly describe how it processes each of the different parts of a docstring.

If possible, this should be guided by PEP 257's discussion of how indentation is transformed: https://www.python.org/dev/peps/pep-0257/#handling-docstring-indentation
msg266444 - (view) Author: Nathan Harold (nharold) * Date: 2016-05-26 16:58
Here's my shot at a revision (corresponding patch attached):

   Clean up indentation from docstrings that are indented to line up with blocks
   of code.  All leading whitespace is removed from the first line.  Any leading
   whitespace that can be uniformly removed from the second line onwards is
   removed.  Empty lines at the beginning and end are subsequently removed.  Also,
   all tabs are expanded to spaces.

This version also makes it explicit that nothing happens to trailing whitespace, should a line happen to have any.  This actually seems to be a difference between this function and the sample implementation in the PEP.

One odd side effect of that difference is that a line consisting only of whitespace may actually not be removed from the beginning or end of the string, if the preceding whitespace removals aren't sufficient to leave the line completely empty.  For instance:

>>> inspect.cleandoc('   A \n  B \n   \n  ')
'A \nB \n '

Two spaces are removed from each of the second, third, and fourth lines.  The fourth line is then empty and is removed; the third line still contains one space and is kept.

On the other hand, as defined in the PEP, the extra space on the third line is removed as trailing whitespace, so that the third line is then removed entirely:

>>> trim('   A \n  B \n   \n  ')
'A\nB'

Most likely this difference rarely affects anything.  In any case, mentioning it here because it influenced exactly how I revised the docs.
msg266462 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-05-27 00:09
Patch looks good to me, thanks Nathan
msg266463 - (view) Author: Ben Finney (bignose) Date: 2016-05-27 01:11
On Fri, May 27, 2016, at 02:58, Nathan Harold wrote:
> Here's my shot at a revision (corresponding patch attached):

Thanks for that. The only improvement I'd ask for is to more clearly
separate
the description into two paragraphs: overall description of the effect
of the
function; then, detailed description of the specific transformations.
msg266502 - (view) Author: Nathan Harold (nharold) * Date: 2016-05-27 16:18
Split version (cleandoc2.patch):

   Clean up indentation from docstrings that are indented to line up with blocks
   of code.
   
   All leading whitespace is removed from the first line.  Any leading whitespace
   that can be uniformly removed from the second line onwards is removed.  Empty
   lines at the beginning and end are subsequently removed.  Also, all tabs are
   expanded to spaces.
msg266531 - (view) Author: Ben Finney (bignose) Date: 2016-05-28 03:53
On 27-May-2016, Nathan Harold wrote:
> 
> Split version (cleandoc2.patch):
> 
>    Clean up indentation from docstrings that are indented to line up
>    with blocks of code.
>    
>    All leading whitespace is removed from the first line. Any
>    leading whitespace that can be uniformly removed from the second
>    line onwards is removed. Empty lines at the beginning and end are
>    subsequently removed. Also, all tabs are expanded to spaces.

That looks good to me.
msg266669 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-05-30 03:38
New changeset c1eb32e183fd by Senthil Kumaran in branch '3.5':
issue27043 - Explain the inspect.cleandoc behavior on synopsis line and other lines.
https://hg.python.org/cpython/rev/c1eb32e183fd

New changeset 4d5a5d4e731d by Senthil Kumaran in branch 'default':
[merge from 3.5] issue27043 - Explain the inspect.cleandoc behavior on synopsis line and other lines.
https://hg.python.org/cpython/rev/4d5a5d4e731d
msg266670 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-05-30 03:39
New changeset 8f841baa0e06 by Senthil Kumaran in branch '2.7':
issue27043 - Explain the inspect.cleandoc behavior on synopsis line and other lines.
https://hg.python.org/cpython/rev/8f841baa0e06
msg266671 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2016-05-30 03:39
Thanks for the patch, Nathan.
History
Date User Action Args
2022-04-11 14:58:31adminsetgithub: 71230
2016-05-30 03:39:47orsenthilsetstatus: open -> closed

nosy: + orsenthil
messages: + msg266671

resolution: fixed
stage: commit review -> resolved
2016-05-30 03:39:02python-devsetmessages: + msg266670
2016-05-30 03:38:04python-devsetnosy: + python-dev
messages: + msg266669
2016-05-30 00:32:10r.david.murraysetstage: patch review -> commit review
2016-05-28 03:53:32bignosesetmessages: + msg266531
2016-05-27 16:18:27nharoldsetfiles: + cleandoc2.patch

messages: + msg266502
2016-05-27 01:11:44bignosesetmessages: + msg266463
2016-05-27 00:09:31martin.pantersetversions: + Python 3.5
nosy: + martin.panter

messages: + msg266462

stage: patch review
2016-05-26 16:58:30nharoldsetfiles: + cleandoc.patch

nosy: + nharold
messages: + msg266444

keywords: + patch
2016-05-17 00:42:37bignosecreate