Skip to content

Improve hash() builtin docstring with caveats. #125229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Improve hash() builtin docstring with caveats. #125229

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e8b5949
Improve `hash()` builtin docstring with caveats.
gpshead Oct 9, 2024
027cc3a
make clinic
gpshead Oct 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions Python/bltinmodule.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1623,15 +1623,18 @@ 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.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I struggled on which way to word this. do people, especially newbies, understand what a process is? i've also seen linter wording around this say "between runs" but that is less technical, what even is a run? people come at interactive python use from so many environments that I don't know if the concept of a run or process makes sense. but process is at least technically accurate. as hash randomization, for example, is process based. and hashes of things like object() are the pointer values and thus process specific.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @JelleZijlstra - given the addition to the next paragraph, I don't think you need this addition here.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure the "within this process" part adds value; why did you add it?


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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Worth mentioning that mutable objects aren't hashable, and that hash() on them raises a TypeError?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Something like "Equivalent objects will always give the same hash value within a single Python process, but a different Python process may report a different hash value. Not all objects are hashable."?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or, "The same object can have different hash values in different processes. Use hash() only within a single process."


This hash value is used internally by Python dict and set hash tables.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if this sentence adds value.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe remove the "hash tables" part.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or say "the dict and set builtin types".

[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=587834cbab541b99]*/
{
Py_hash_t x;

Expand Down
9 changes: 6 additions & 3 deletions Python/clinic/bltinmodule.c.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading