[Python-checkins] cpython (3.4): document what exactly str.splitlines() splits on (closes #12855)

[benjamin.peterson]

https://hg.python.org/cpython/rev/6244a5dbaf84
changeset:   95337:6244a5dbaf84
branch:      3.4
parent:      95327:5c5eb374e296
user:        Benjamin Peterson <benjamin at python.org>
date:        Tue Mar 31 21:20:36 2015 -0400
summary:
  document what exactly str.splitlines() splits on (closes #12855)

Patch by Martin Panter.

files:
  Doc/library/stdtypes.rst |  40 +++++++++++++++++++++++++--
  1 files changed, 36 insertions(+), 4 deletions(-)


diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1855,10 +1855,42 @@
 
 .. method:: str.splitlines([keepends])
 
-   Return a list of the lines in the string, breaking at line boundaries.
-   This method uses the :term:`universal newlines` approach to splitting lines.
-   Line breaks are not included in the resulting list unless *keepends* is
-   given and true.
+   Return a list of the lines in the string, breaking at line boundaries.  Line
+   breaks are not included in the resulting list unless *keepends* is given and
+   true.
+
+   This method splits on the following line boundaries.  In particular, the
+   boundaries are a superset of :term:`universal newlines`.
+
+   +-----------------------+-----------------------------+
+   | Representation        | Description                 |
+   +=======================+=============================+
+   | ``\n``                | Line Feed                   |
+   +-----------------------+-----------------------------+
+   | ``\r``                | Carriage Return             |
+   +-----------------------+-----------------------------+
+   | ``\r\n``              | Carriage Return + Line Feed |
+   +-----------------------+-----------------------------+
+   | ``\v`` or ``\x0b``    | Line Tabulation             |
+   +-----------------------+-----------------------------+
+   | ``\f`` or ``\x0c``    | Form Feed                   |
+   +-----------------------+-----------------------------+
+   | ``\x1c``              | File Separator              |
+   +-----------------------+-----------------------------+
+   | ``\x1d``              | Group Separator             |
+   +-----------------------+-----------------------------+
+   | ``\x1e``              | Record Separator            |
+   +-----------------------+-----------------------------+
+   | ``\x85``              | Next Line (C1 Control Code) |
+   +-----------------------+-----------------------------+
+   | ``\u2028``            | Line Separator              |
+   +-----------------------+-----------------------------+
+   | ``\u2029``            | Paragraph Separator         |
+   +-----------------------+-----------------------------+
+
+   .. versionchanged:: 3.2
+
+      ``\v`` and ``\f`` added to list of line boundaries.
 
    For example::
 

-- 
Repository URL: https://hg.python.org/cpython