On Thu, 16 Aug 2018 at 14:26, Rhodri James firstname.lastname@example.org wrote:
On 16/08/18 14:04, Jonathan Fine wrote:
And I think there's more. The page says
None This type has a single value. There is a single object with this value. [...]
I think it better to write
NoneType This type has a single value, `None`. The keyword `None` always gives the value `None`.
I disagree. That original text looks like it has been very carefully written to be (almost) true. What you are proposing to replace it with is less true and confusing to boot.
I agree that the original is better. I think the important thing (which doesn't come across when quoting text in email) is the typography.
``` None This type has a single value. There is a single object with this value. This object is accessed through the built-in name None. [...] ```
The initial "None" is on a line by itself, and is in "normal text" font, outdented from the following text. As it's in a section called "The standard type hierarchy", this reads to me as referring to a type, informally named as "None". It's not referring to the Python keyword None, which is formatted differently (monospace with a grey background). Conversely, the "None" in the phrase "the built-in name None" *is* formatted to indicate that it's the Python keyword. The typography makes it quite clear (to me) that there are two different *concepts* being discussed here, and furthermore, the wording clearly implies that neither of these concepts is precisely equivalent to the "single value" of the None type.
It's easy when discussion wording in a plain-text medium like email to ignore the impact of formatting on how the meaning of a piece of text is conveyed. In this case, I think that the details are subtle enough that the typography is critical to getting the message across.
One thing that *isn't* conveyed by the description here is the distinction between `None` and `Ellipsis`. The two relevant sections say
This object is accessed through the built-in name None This object is accessed through the literal ... or the built-in name Ellipsis
But you can't assign to (the name) None, and yet you can to (the name) Ellipsis. It might be better to say "the keyword None" in the section on None, to make that distinction. But that's the only change I'd make.
PS I should say that I would not expect any of the fine distinctions I've drawn in the above to be obvious to non-native speakers of English. That's a very different problem to handle, and one that is orders of magnitude harder than the comparatively simple task of trying to distinguish between None the type, the keyword and the value :-)