From bb8d6a0863e7bf2cac519ee41ec8fa966eee08b7 Mon Sep 17 00:00:00 2001
From: "Gregory P. Smith" <68491+gpshead@users.noreply.github.com>
Date: Mon, 27 Apr 2026 09:17:30 -0700
Subject: [PATCH] [3.14] Improve  `hash()` builtin docstring with caveats.
 (GH-125229) (#149054)

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)`.
(cherry picked from commit 665b7dfcfa240e02760f58bed5ca29ec01d028e6)
---
 Python/bltinmodule.c          | 10 ++++++----
 Python/clinic/bltinmodule.c.h | 10 ++++++----
 2 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/Python/bltinmodule.c b/Python/bltinmodule.c
index 603d9646ce58..fe54919c6657 100644
--- a/Python/bltinmodule.c
+++ b/Python/bltinmodule.c
@@ -1763,15 +1763,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 b44a8d1e2972..578e852ce9eb 100644
--- a/Python/clinic/bltinmodule.c.h
+++ b/Python/clinic/bltinmodule.c.h
@@ -723,10 +723,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__},
@@ -1277,4 +1279,4 @@ builtin_issubclass(PyObject *module, PyObject *const *args, Py_ssize_t nargs)
 exit:
     return return_value;
 }
-/*[clinic end generated code: output=b5d2231033c7591c input=a9049054013a1b77]*/
+/*[clinic end generated code: output=4eb1d06e7e74d91c input=a9049054013a1b77]*/
-- 
2.47.3