Clarify U-mode deprecation in open() #11646
Conversation
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.
|
I stumbled across https://softwareengineering.stackexchange.com/questions/298677/why-is-universal-newlines-mode-deprecated-in-python today and realised that the poster's confusion was completely understandable given the way this deprecation was expressed. |
|
Too bad this doesn't link to the place in the text where |
Doc/library/functions.rst
Outdated
| @@ -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) | |||
There was a problem hiding this comment.
For me is a good improved. How say @csabella, it would be great have a link to newline definition
There was a problem hiding this comment.
Perhaps it would be clearer to put :deprecated: before the rest of the text
``'U'`` :deprecated: Use ``newline`` option instead. Equivalent to ``newline=None``
Having a link as suggested by @csabella would be great.
Doc/library/functions.rst
Outdated
| @@ -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) | |||
There was a problem hiding this comment.
Perhaps it would be clearer to put :deprecated: before the rest of the text
``'U'`` :deprecated: Use ``newline`` option instead. Equivalent to ``newline=None``
Having a link as suggested by @csabella would be great.
- 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)
|
I'm not sure bold mark-up inside a cross-reference actually works correctly, so I'm going to pull the branch locally and check that it actually works the way I want rather than continuing solely in the browser. |
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.
|
After rendering the docs locally, I came to the conclusion that there simply wasn't room inside the table to explain why the So I moved it down into its own paragraph after the explanation of the actually useful mode characters - that way the info is still there if someone is trying to understand existing code that uses it, but folks writing new code shouldn't ever need to care about it. |
|
Thanks @ncoghlan for the PR 🌮🎉.. I'm working now to backport this PR to: 3.7. |
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. (cherry picked from commit 3171df3) Co-authored-by: Nick Coghlan <ncoghlan@gmail.com>
|
GH-11687 is a backport of this pull request to the 3.7 branch. |
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. (cherry picked from commit 3171df3) Co-authored-by: Nick Coghlan <ncoghlan@gmail.com>
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.