New docs for set elements/dictionary keys (Was: Why is dictionary.keys() a list and not a set?)

[Mike Meyer]

"Martin v. Löwis" <martin at v.loewis.de> writes:
> Mike Meyer wrote:
>>>This is not true. The second definition of __hash__ does not meet
>>>the specifications:
>> The specification isn't on the __hash__ method, but on objects.
> What does it mean for a specification to be "on" something? The
> specification I quoted is listed "under" the __hash__ heading
> of the reference manual.

"applies to"

>> That's pretty flaky. The same docs say:
>> Should return a 32-bit integer usable as a hash value for dictionary
>> operations.
> What is flaky about this?

What's flaky is the claim in the docs that "the *only* requirement is
...". There are clearly other requirements, and they're listed in the
same paragraph as that requirement.

>> the dictionary implementation requires that a key's hash value is
>> immutable
> Indeed, the question here is: what does "an object is immutable"
> mean in this context? You appear to read it as "an object whose
> state does not change", however, what it really means is "an object
> which will always use the same state in __hash__ and __eq__".

I've given up on trying to say what "immutable" means, because common
usage in the CS and Python communities is ambiguous when it comes to
container objects. You give an unambiguous definition, but it's
specific to python, and clashes with common usage in the CS and Python
communities. Every old-style class that doesn't define __hash__,
__eq__ or __cmp__ is immutable by that definition, even if it has
mutator methods. Similar comments apply to new-style classes, but
require more work to pin down.

That's the reason this thread went the direction it did - because I
started discussing fixing the docs to not use "immutable" as the
defining property.

>> Maybe those are only "recommended" properties, but any class that
>> doesn't meet them is going to have instances with interesting
>> behaviors in sets and as dictionary keys.
> Indeed, you can anything return you want in __hash__, or always
> raise an exception. What precisely the result of dictionary
> operations is when you do so is undefined in Python.

I certainly hope that if __hash__ raises an exception, dictionary
operations pass the exception on to their caller. For the other cases,
undefined behavior is perfectly reasonable.

Back onto topic:

If you want to use your definition of "immutable" in the docs for
dictionary keys and set elements, I think that the docs should
explicitly include that definition. We can probably come up with a
less ambiguous (does "same state" mean "same state variables" or
"variables that don't change value"?) wording as well.

Personally, I think we'd be better off to come up with a term for this
property that doesn't have a commonly understood meaning that has such
broad areas of disagreement with the property. I've been using
"hashable", which I would currently define as "has a __hash__ method
with the properties described in the __hash__ documentation, or does
not have either a __cmp__ or a __eq__ method." Listing which builtin
types are hashable and which aren't (and which vary on an
instance-by-instance basis) would seem to be worthwhile as well.

        <mike
-- 
Mike Meyer <mwm at mired.org>			http://www.mired.org/home/mwm/
Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.