From e8b5949dd10be5dd3b1d4bb6c44d12dccbaeb82a Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith [Google LLC]" Date: Wed, 9 Oct 2024 23:00:06 +0000 Subject: [PATCH 1/2] 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. --- Python/bltinmodule.c | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/Python/bltinmodule.c b/Python/bltinmodule.c index f87f942cc76258..c7bec720172551 100644 --- a/Python/bltinmodule.c +++ b/Python/bltinmodule.c @@ -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 * From 027cc3a0df692dcbee8d98930015d8abd07e2ec1 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith [Google LLC]" Date: Wed, 9 Oct 2024 23:05:22 +0000 Subject: [PATCH 2/2] make clinic --- Python/bltinmodule.c | 2 +- Python/clinic/bltinmodule.c.h | 9 ++++++--- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/Python/bltinmodule.c b/Python/bltinmodule.c index c7bec720172551..673314c19db512 100644 --- a/Python/bltinmodule.c +++ b/Python/bltinmodule.c @@ -1634,7 +1634,7 @@ This hash value is used internally by Python dict and set hash tables. static PyObject * builtin_hash(PyObject *module, PyObject *obj) -/*[clinic end generated code: output=237668e9d7688db7 input=58c48be822bf9c54]*/ +/*[clinic end generated code: output=237668e9d7688db7 input=587834cbab541b99]*/ { Py_hash_t x; diff --git a/Python/clinic/bltinmodule.c.h b/Python/clinic/bltinmodule.c.h index f75a8d4ac0ccd4..86bf88bd7f38de 100644 --- a/Python/clinic/bltinmodule.c.h +++ b/Python/clinic/bltinmodule.c.h @@ -695,10 +695,13 @@ 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 within this process.\n" "\n" "Two objects that compare equal must also have the same hash value, but the\n" -"reverse is not necessarily true."); +"reverse is not necessarily true. Hash values may vary between Python\n" +"processes.\n" +"\n" +"This hash value is used internally by Python dict and set hash tables."); #define BUILTIN_HASH_METHODDEF \ {"hash", (PyCFunction)builtin_hash, METH_O, builtin_hash__doc__}, @@ -1228,4 +1231,4 @@ builtin_issubclass(PyObject *module, PyObject *const *args, Py_ssize_t nargs) exit: return return_value; } -/*[clinic end generated code: output=435d3f286a863c49 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=8743b427edc26536 input=a9049054013a1b77]*/