https://github.com/python/cpython/commit/665b7dfcfa240e02760f58bed5ca29ec01d028e6
commit: 665b7dfcfa240e02760f58bed5ca29ec01d028e6
branch: main
author: Gregory P. Smith <[email protected]>
committer: gpshead <[email protected]>
date: 2026-04-24T16:36:46Z
summary:
Improve `hash()` builtin docstring with caveats. (GH-125229)
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)`.
files:
M Python/bltinmodule.c
M Python/clinic/bltinmodule.c.h
diff --git a/Python/bltinmodule.c b/Python/bltinmodule.c
index fec64e1ff9d25f..16413d784cc87c 100644
--- a/Python/bltinmodule.c
+++ b/Python/bltinmodule.c
@@ -1840,15 +1840,17 @@ hash as builtin_hash
obj: object
/
-Return the hash value for the given object.
+Return the integer hash value for the given object.
-Two objects that compare equal must also have the same hash value, but the
-reverse is not necessarily true.
+Two objects that compare equal must also have the same hash value, but
+the reverse is not necessarily true. Hash values may differ between
+Python processes. Not all objects are hashable; calling hash() on an
+unhashable object raises TypeError.
[clinic start generated code]*/
static PyObject *
builtin_hash(PyObject *module, PyObject *obj)
-/*[clinic end generated code: output=237668e9d7688db7 input=58c48be822bf9c54]*/
+/*[clinic end generated code: output=237668e9d7688db7 input=70a242ff65f6717c]*/
{
Py_hash_t x;
diff --git a/Python/clinic/bltinmodule.c.h b/Python/clinic/bltinmodule.c.h
index c8c141f863d26a..e6b845cd375d73 100644
--- a/Python/clinic/bltinmodule.c.h
+++ b/Python/clinic/bltinmodule.c.h
@@ -826,10 +826,12 @@ PyDoc_STRVAR(builtin_hash__doc__,
"hash($module, obj, /)\n"
"--\n"
"\n"
-"Return the hash value for the given object.\n"
+"Return the integer hash value for the given object.\n"
"\n"
-"Two objects that compare equal must also have the same hash value, but the\n"
-"reverse is not necessarily true.");
+"Two objects that compare equal must also have the same hash value, but\n"
+"the reverse is not necessarily true. Hash values may differ between\n"
+"Python processes. Not all objects are hashable; calling hash() on an\n"
+"unhashable object raises TypeError.");
#define BUILTIN_HASH_METHODDEF \
{"hash", (PyCFunction)builtin_hash, METH_O, builtin_hash__doc__},
@@ -1380,4 +1382,4 @@ builtin_issubclass(PyObject *module, PyObject *const
*args, Py_ssize_t nargs)
exit:
return return_value;
}
-/*[clinic end generated code: output=1c3327da8885bb8e input=a9049054013a1b77]*/
+/*[clinic end generated code: output=f1fc836a63d89826 input=a9049054013a1b77]*/
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
