[Python-checkins] Clarify U-mode deprecation in open() (GH-11646)

Nick Coghlan webhook-mailer at python.org
Sun Jan 27 11:21:17 EST 2019


https://github.com/python/cpython/commit/3171df34141c1f26ec16dccb4357184c0cf6c58f
commit: 3171df34141c1f26ec16dccb4357184c0cf6c58f
branch: master
author: Nick Coghlan <ncoghlan at gmail.com>
committer: GitHub <noreply at github.com>
date: 2019-01-28T02:21:11+10:00
summary:

Clarify U-mode deprecation in open() (GH-11646)

The previous wording could be read as saying that universal
newlines mode itself was deprecated, when it's only the 'U'
character in the mode field that should be avoided.

The update also moves the description of the 'U' mode character
out of the mode table, as the longer explanation was overly
intrusive as a table entry and overshadowed the actually useful
mode characters.

files:
M Doc/library/functions.rst

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index b49d752b16a3..cca28ff5fb3b 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1004,7 +1004,6 @@ are always available.  They are listed here in alphabetical order.
    ``'b'``   binary mode
    ``'t'``   text mode (default)
    ``'+'``   open a disk file for updating (reading and writing)
-   ``'U'``   :term:`universal newlines` mode (deprecated)
    ========= ===============================================================
 
    The default mode is ``'r'`` (open for reading text, synonym of ``'rt'``).
@@ -1019,6 +1018,12 @@ are always available.  They are listed here in alphabetical order.
    first decoded using a platform-dependent encoding or using the specified
    *encoding* if given.
 
+   There is an additional mode character permitted, ``'U'``, which no longer
+   has any effect, and is considered deprecated. It previously enabled
+   :term:`universal newlines` in text mode, which became the default behaviour
+   in Python 3.0. Refer to the documentation of the
+   :ref:`newline <open-newline-parameter>` parameter for further details.
+
    .. note::
 
       Python doesn't depend on the underlying operating system's notion of text
@@ -1085,6 +1090,8 @@ are always available.  They are listed here in alphabetical order.
    .. index::
       single: universal newlines; open() built-in function
 
+   .. _open-newline-parameter:
+
    *newline* controls how :term:`universal newlines` mode works (it only
    applies to text mode).  It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and
    ``'\r\n'``.  It works as follows:



More information about the Python-checkins mailing list