Skip to content

Commit e8b5949

Browse files
committed
Improve hash() builtin docstring with caveats.
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.
1 parent c7d5d1d commit e8b5949

File tree

1 file changed

+5
-2
lines changed

1 file changed

+5
-2
lines changed

Python/bltinmodule.c

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1623,10 +1623,13 @@ hash as builtin_hash
16231623
obj: object
16241624
/
16251625
1626-
Return the hash value for the given object.
1626+
Return the integer hash value for the given object within this process.
16271627
16281628
Two objects that compare equal must also have the same hash value, but the
1629-
reverse is not necessarily true.
1629+
reverse is not necessarily true. Hash values may vary between Python
1630+
processes.
1631+
1632+
This hash value is used internally by Python dict and set hash tables.
16301633
[clinic start generated code]*/
16311634

16321635
static PyObject *

0 commit comments

Comments
 (0)