From 35e3696071e7dfcd6fdb6385b158ee815fb4137a Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Tue, 22 Jan 2019 20:45:59 +1000 Subject: [PATCH 1/5] Clarify U-mode deprecation in open() 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. --- Doc/library/functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index b49d752b16a390..99f5a478c03c9c 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1004,7 +1004,7 @@ 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) + ``'U'`` equivalent to `newline=None` (deprecated, use *newline* option) ========= =============================================================== The default mode is ``'r'`` (open for reading text, synonym of ``'rt'``). From 229b18ae571ad582db925b07bb8bf13a6f1326ba Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Tue, 22 Jan 2019 20:48:53 +1000 Subject: [PATCH 2/5] Too much Markdown lately :) --- Doc/library/functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 99f5a478c03c9c..03d31cf0360a31 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1004,7 +1004,7 @@ 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'`` equivalent to `newline=None` (deprecated, use *newline* option) + ``'U'`` equivalent to ``newline=None`` (deprecated, use *newline* option) ========= =============================================================== The default mode is ``'r'`` (open for reading text, synonym of ``'rt'``). From 9e42d75f1b6e5c0b0036074e14775a5fec856814 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Sun, 27 Jan 2019 22:02:43 +1000 Subject: [PATCH 3/5] Further adjustments to deprecation notice - add cross-reference to newline parameter description - move deprecation warning to the start of the paragraph - explain why the mode is deprecated (i.e. it's the default for test mode now, so specifying it explicitly is redundant) --- Doc/library/functions.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 03d31cf0360a31..204615ab9b2c97 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1004,7 +1004,9 @@ 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'`` equivalent to ``newline=None`` (deprecated, use *newline* option) + ``'U'`` :deprecated: :term:`universal newlines` is enabled by default + in text mode. See the :ref:` *newline* ` + parameter documentation for more details. ========= =============================================================== The default mode is ``'r'`` (open for reading text, synonym of ``'rt'``). @@ -1085,6 +1087,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: From e49f3ba214e395df1ac009fa86cda6826994e00a Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Sun, 27 Jan 2019 23:52:50 +1000 Subject: [PATCH 4/5] Fix table markup --- Doc/library/functions.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 204615ab9b2c97..f1971537d06499 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1005,8 +1005,6 @@ are always available. They are listed here in alphabetical order. ``'t'`` text mode (default) ``'+'`` open a disk file for updating (reading and writing) ``'U'`` :deprecated: :term:`universal newlines` is enabled by default - in text mode. See the :ref:` *newline* ` - parameter documentation for more details. ========= =============================================================== The default mode is ``'r'`` (open for reading text, synonym of ``'rt'``). @@ -1021,6 +1019,9 @@ are always available. They are listed here in alphabetical order. first decoded using a platform-dependent encoding or using the specified *encoding* if given. + :term:`universal newlines` is enabled by default in text mode, but can + be switched off with the :ref:`*newline* ` parameter. + .. note:: Python doesn't depend on the underlying operating system's notion of text From 0ad2ba929ae3e1f7026cf2ec557341dc8ad54b69 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Mon, 28 Jan 2019 01:19:02 +1000 Subject: [PATCH 5/5] Move 'U' entirely out of file mode table I couldn't get the longer entry to look any good inside the table, so I moved it out to a separate paragraph after the description of the actually useful file modes. --- Doc/library/functions.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index f1971537d06499..cca28ff5fb3b66 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'`` :deprecated: :term:`universal newlines` is enabled by default ========= =============================================================== The default mode is ``'r'`` (open for reading text, synonym of ``'rt'``). @@ -1019,8 +1018,11 @@ are always available. They are listed here in alphabetical order. first decoded using a platform-dependent encoding or using the specified *encoding* if given. - :term:`universal newlines` is enabled by default in text mode, but can - be switched off with the :ref:`*newline* ` parameter. + 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 ` parameter for further details. .. note::