Skip to content

Commit

Permalink
Improve hash() builtin docstring with caveats.
Browse files Browse the repository at this point in the history
Mention its return type and that the value can be expected to change between
processes (hash randomization).

Why? The `hash` builtin gets reached for and used by a lot of people whether it
is the right tool or not. IDEs surface docstrings and people use pydoc and
`help(hash)`.

There are more possible caveats we could go into here such as classes
implementing their own dunder methods like `__eq__` or `__hash__` naturally
being able to violate the constraint stated in this docstring. But _that_ feels
like too much for a beginner friendly docstring.
  • Loading branch information
gpshead committed Oct 9, 2024
1 parent c7d5d1d commit e8b5949
Showing 1 changed file with 5 additions and 2 deletions.
7 changes: 5 additions & 2 deletions Python/bltinmodule.c
Original file line number Diff line number Diff line change
Expand Up @@ -1623,10 +1623,13 @@ hash as builtin_hash
obj: object
/
Return the hash value for the given object.
Return the integer hash value for the given object within this process.
Two objects that compare equal must also have the same hash value, but the
reverse is not necessarily true.
reverse is not necessarily true. Hash values may vary between Python
processes.
This hash value is used internally by Python dict and set hash tables.
[clinic start generated code]*/

static PyObject *
Expand Down

0 comments on commit e8b5949

Please sign in to comment.