[issue15554] correct and clarify str.splitlines() documentation

[Chris Jerdonek]

New submission from Chris Jerdonek:

The documentation for str.splitlines()--

http://docs.python.org/dev/library/stdtypes.html#str.splitlines

includes a statement that is not quite correct:

"Unlike split(), if the string ends with line boundary characters the returned list does not have an empty last element."

For example,

>>> '\n'.splitlines()
['']
>>> '\n\n'.splitlines()
['', '']
>>> '\r\n'.splitlines()
['']
>>> '\n\r\n'.splitlines()
['', '']
>>> '\r'.splitlines()
['']
>>> 'a\n\n'.splitlines()
['a', '']

Also, the note about split() only applies when split() is passed a separator.  For example--

>>> 'a\n'.split('\n')
['a', '']
>>> 'a\n'.split()
['a']

Finally, the function's behavior on the empty string is another difference worth mentioning that is not covered by the existing note.

I am attaching a patch that addresses these points.  Notice also that the patch phrases it not as whether the list *has* an empty last element, but whether an *additional* last element should be added, which is the more important point.

----------
assignee: docs at python
components: Documentation
files: issue-splitlines-docs-1.patch
keywords: easy, patch
messages: 167394
nosy: cjerdonek, docs at python, jcea, pitrou
priority: normal
severity: normal
stage: patch review
status: open
title: correct and clarify str.splitlines() documentation
versions: Python 2.7, Python 3.2, Python 3.3
Added file: http://bugs.python.org/file26680/issue-splitlines-docs-1.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue15554>
_______________________________________