[issue27043] Describe what ‘inspect.cleandoc’ does to synopsis line.

[Senthil Kumaran]

Senthil Kumaran added the comment:

Thanks for the patch, Nathan.

--
nosy: +orsenthil
resolution:  -> fixed
stage: commit review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27043] Describe what ‘inspect.cleandoc’ does to synopsis line.

[Roundup Robot]

Roundup Robot added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27043] Describe what ‘inspect.cleandoc’ does to synopsis line.

[Roundup Robot]

Roundup Robot added the comment:

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

--
nosy: +python-dev

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27043] Describe what ‘inspect.cleandoc’ does to synopsis line.

[R. David Murray]

Changes by R. David Murray :


--
stage: patch review -> commit review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27043] Describe what ‘inspect.cleandoc’ does to synopsis line.

[Ben Finney]

Ben Finney added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27043] Describe what ‘inspect.cleandoc’ does to synopsis line.

[Nathan Harold]

Nathan Harold added the comment:

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.

--
Added file: http://bugs.python.org/file43030/cleandoc2.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27043] Describe what ‘inspect.cleandoc’ does to synopsis line.

[Ben Finney]

Ben Finney added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27043] Describe what ‘inspect.cleandoc’ does to synopsis line.

[Martin Panter]

Martin Panter added the comment:

Patch looks good to me, thanks Nathan

--
nosy: +martin.panter
stage:  -> patch review
versions: +Python 3.5

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27043] Describe what ‘inspect.cleandoc’ does to synopsis line.

[Nathan Harold]

Nathan Harold added the comment:

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.

--
keywords: +patch
nosy: +nharold
Added file: http://bugs.python.org/file43018/cleandoc.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27043] Describe what ‘inspect.cleandoc’ does to synopsis line.

[Ben Finney]

New submission from Ben Finney:

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

--
assignee: docs@python
components: Documentation
messages: 265741
nosy: bignose, docs@python
priority: normal
severity: normal
status: open
title: Describe what ‘inspect.cleandoc’ does to synopsis line.
type: enhancement
versions: Python 2.7, Python 3.6

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com