classification
Title: dictionary keys described incorrectly in tutorial
Type: Stage:
Components: Documentation Versions: Python 3.7, Python 3.6, Python 2.7
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Xezlec, docs@python, methane, r.david.murray, rhettinger
Priority: normal Keywords:

Created on 2016-12-27 21:27 by Xezlec, last changed 2016-12-30 05:32 by rhettinger. This issue is now closed.

Messages (10)
msg284135 - (view) Author: Xezlec (Xezlec) Date: 2016-12-27 21:27
In section 5.5 on the page https://docs.python.org/2/tutorial/datastructures.html#dictionaries the requirements given for dictionary keys are not correct.

Specifically, it is claimed that only immutable objects (and tuples containing only immutable objects) may be used as keys.  This is false, as user-defined mutable objects may be used as keys.  I suggest rewording along these lines:

"Only user-defined objects and immutable built-in types may be used as keys.  Although allowed, it is bad practice to use a mutable user-defined object as a key when equality is determined in any way other than identity (the default)."
msg284136 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-12-27 21:36
It could say 'hashable object' instead of immutable object.  I don't know if hash has been introduced by that point, though.

It's the tutorial.  Probably better to just leave it alone.  Precise understanding can come later.
msg284137 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-12-27 21:38
Note that this applies equally well to python3.
msg284143 - (view) Author: Inada Naoki (methane) * (Python committer) Date: 2016-12-28 01:11
> It's the tutorial.  Probably better to just leave it alone.  Precise understanding can come later.

I agree.
Beginner should start using dict with builtin immutable type as key.
hashable is too complex at this point.
msg284144 - (view) Author: Xezlec (Xezlec) Date: 2016-12-28 01:45
> It's the tutorial.  Probably better to just leave it alone.  Precise understanding can come later.

But the problem isn't that it's imprecise.  It's flat-out wrong.  My opinion would be that it's always a bad idea to put wrong information in the documentation, especially when it's the first Google hit.  It can lead to all sorts of confusion and frustration (as it did for me).  Users are likely to assume documentation from any official source is the final word.

If precision is the problem, could it be reworded to be more vague?
msg284147 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-12-28 02:27
It is not wrong.  It does not say that keys are limited to immutables, only that immutables can be keys.  Perhaps the sentence about a tuple pointing to a mutable could be tightened up, though, by saying that if a tuple points to something that can not itself be a dictionary key, then that tuple can not be a dictionary key.
msg284149 - (view) Author: Inada Naoki (methane) * (Python committer) Date: 2016-12-28 02:41
> If precision is the problem, could it be reworded to be more vague?

"can be any immutable" seems vague enough to me.  It doesn't say "cannot be any mutable type.".

>  Users are likely to assume documentation from any official source is the final word.

But tutorial should use less words as possible.  This section is before introducing "class" statement.  Only strings, numbers, list and set are introduced before section.

I feel assuming early part of tutorial as final word bad practice.
msg284152 - (view) Author: Xezlec (Xezlec) Date: 2016-12-28 04:11
> Perhaps the sentence about a tuple pointing to a mutable could be tightened up, though, by saying that if a tuple points to something that can not itself be a dictionary key, then that tuple can not be a dictionary key.

That would be great.  Thank you.

> I feel assuming early part of tutorial as final word bad practice.

Alright.  If that's how both of you feel, then it can't be helped.

But if that's how it is, then maybe it would be a good idea to make the tutorial more distinct?  Right now, the only way I can tell Google has landed me on a tutorial page as opposed to a reference page is the word "tutorial" in the URL and in small print at the very top of the page.  They're styled similarly.  I never even realized they were separate things until today (let alone that one of them must be read skeptically).

Sorry to take up your time.  Thanks for listening.
msg284174 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-12-28 14:33
You know, it might actually not be a bad idea to use a slightly different color scheme for the tutorial.  We'll see if that idea generates any interest :)
msg284310 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-12-30 05:32
I'm going to concur with the other respondents on this.  As a Python teacher, this is how I teach what should be used as a dictionary key.

While immutability and hashability aren't equivalent, it is a good first approximation.  Also, even though it is true that you could make a hashable object that is mutable, it is generally a bad practice that leads to regrets.

I'm going to close this.  If someone wants to change the styling of the tutorial, that can reasonably be discussed in another patch.

Thank you for your ideas, but we're going to pass on this one.  The tutorial is a place where it can be counter-productive to 1) make discussions too long, 2) go into atypical practices, 3) add too many caveats in a effort to be overly precise, etc.   Also, this part of the tutorial has been around for many years and has done a reasonably good job at educating its readers.
History
Date User Action Args
2016-12-30 05:32:30rhettingersetstatus: open -> closed

nosy: + rhettinger
messages: + msg284310

resolution: rejected
2016-12-28 14:33:52r.david.murraysetmessages: + msg284174
2016-12-28 04:11:51Xezlecsetmessages: + msg284152
2016-12-28 02:41:49methanesetmessages: + msg284149
2016-12-28 02:27:30r.david.murraysetmessages: + msg284147
2016-12-28 01:45:58Xezlecsetmessages: + msg284144
2016-12-28 01:11:31methanesetnosy: + methane
messages: + msg284143
2016-12-27 21:38:07r.david.murraysettitle: Python 2 dictionary keys described incorrectly -> dictionary keys described incorrectly in tutorial
messages: + msg284137
versions: + Python 3.6, Python 3.7
2016-12-27 21:36:47r.david.murraysetnosy: + r.david.murray
messages: + msg284136
2016-12-27 21:27:05Xezleccreate