[Python-ideas] Python docs page: In what ways is None special

[Paul Moore]

On Thu, 16 Aug 2018 at 14:26, Rhodri James <rhodri at kynesim.co.uk> 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.

Paul

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
:-)