newline is (partially) independent of universal newlines; needs to be made more clear in docs

[ssbr]

BPO	20722
Nosy	@Yhg1s, @ssbr

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2014-02-21.13:24:07.454>
labels = ['type-feature', '3.8', 'docs']
title = 'newline is (partially) independent of universal newlines; needs to be made more clear in docs'
updated_at = <Date 2018-05-03.14:16:13.018>
user = 'https://github.com/ssbr'

bugs.python.org fields:

activity = <Date 2018-05-03.14:16:13.018>
actor = 'cheryl.sabella'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2014-02-21.13:24:07.454>
creator = 'Devin Jeanpierre'
dependencies = []
files = []
hgrepos = []
issue_num = 20722
keywords = []
message_count = 2.0
messages = ['211854', '211857']
nosy_count = 3.0
nosy_names = ['twouters', 'Devin Jeanpierre', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue20722'
versions = ['Python 3.8']

[ssbr]

http://docs.python.org/3.4/library/functions.html#open says "newline controls how universal newlines mode works (it only applies to text mode)."

My reading of this when I saw it was that newline= doesn't do anything unless universal newlines mode is enabled. This is untrue, and you can infer it's untrue from the following lines, but then the docs appear to contradict themselves. Please fix to say something more along the lines of "newline controls how newlines are read and written. It only applies to text mode."

The interactions with universal newlines mode are explained in the following text, so they don't need to be called out upfront. newline does more than just that.

[Yhg1s]

Additionally, the deprecation notice for 'U' in the table of modules should mention that the 'U' mode, not universal newlines, is deprecated because it is unnecessary. Or 'controlled by the newline argument' perhaps.

[JelleZijlstra]

@Yhg1s's comment no longer applies to the docs versions we're still maintaining; U was removed in 3.11 and the 3.10 docs (https://docs.python.org/3.10/library/functions.html#open) have non-misleading wording about U.