bpo-46209: add documentation for decoding newlines in the io module

[guoci]

https://bugs.python.org/issue46209

[merwok]

The types are not clear here. Are you saying this is a tuple of strings or one string?

[guoci]

the type is either a string or tuple of strings

cpython/Lib/_pyio.py

Lines 1971 to 1980 in e18d815

	def newlines(self):
	return (None,
	"\n",
	"\r",
	("\r", "\n"),
	"\r\n",
	("\n", "\r\n"),
	("\r", "\r\n"),
	("\r", "\n", "\r\n")
	)[self.seennl]

[merwok]

ok! I wouldn’t say types of newlines, unless that phrase is used elsewhere in the docs, it could be confusing.

[guoci]

how about changing to representations of newlines?

cpython/Lib/_pyio.py

Line 1901 in e18d815

records the types of newlines encountered. When used with

[merwok]

That sounds a bit abstract to me. These are newlines, meaning strings.
Isn’t there an existing phrase in io docs or dosctrings that can be reused?

[guoci]

I can't find any in the io docs, The docstring of that class says types of newlines.

[JelleZijlstra]

It might be worth just giving some examples.

[guoci]

Listed all the possible values.

[guoci]

@merwok Also, may I request you to look at #30276 too? It is very related to this.

[MaxwellDupre]

Docs complied on my machine. Looks ok.