[issue26947] Documentation improvement needed
New submission from mPython: On following page: https://docs.python.org/3/glossary.html#term-hashable sentence "All of Python’s immutable built-in objects are hashable, while no mutable containers (such as lists or dictionaries) are." is not complete - probably a word "not" is needed on the end. ---------- assignee: docs@python components: Documentation messages: 264805 nosy: docs@python, mPython priority: normal severity: normal status: open title: Documentation improvement needed versions: Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Xiang Zhang added the comment: I think the original is OK. Adding "not" means the opposite. ---------- nosy: +xiang.zhang _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Steven D'Aprano added the comment: Xiang Zhang is correct: the original is technically correct. If you read it like this: "All of Python’s immutable built-in objects are hashable, while no mutable containers (such as lists or dictionaries) are [hashable]." it should be clear. But if you have a suggestion for wording which is easier to understand (especially for those whose English is not so good) please say so. ---------- nosy: +steven.daprano _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Eric V. Smith added the comment: I'm a native speaker, and it's not the greatest sentence. How about: All of Python’s immutable built-in objects (such as numbers, strings and tuples) are hashable. None of its mutable containers (such as lists or dictionaries) are hashable. ---------- nosy: +eric.smith _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Xiang Zhang added the comment: As a non-native speaker, actually I prefer the original one. But both versions lead to no confusion for me. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
mPython added the comment: Just to mention that I'm not native speaker, and I'm Django (Python) beginner. I'm very good in C++, Java and in last 12 years read a lot IT documentation. Mentioned sentence was not clear enough for me so I created this ticket. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Changes by Cheryl Sabella <chekat2@gmail.com>: ---------- pull_requests: +1130 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Martin Panter added the comment: The pull request currently suggests “All of Python’s immutable built-in objects are hashable; mutable containers (such as lists or dictionaries) are not.” This seems better wording than the original. FWIW, I would have tried “Python’s built-in immutable objects are hashable, while mutable containers (such as lists and dictionaries) are not hashable.” ---------- nosy: +martin.panter title: Documentation improvement needed -> Hashable documentation improvement needed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Senthil Kumaran added the comment: New changeset 64c887ab3a400cf91bde4f0c5ef69eacc88bc5e1 by Senthil Kumaran (csabella) in branch 'master': bpo-26947: DOC: clarify wording on hashable in glossary (#948) https://github.com/python/cpython/commit/64c887ab3a400cf91bde4f0c5ef69eacc88... ---------- nosy: +orsenthil _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Changes by Senthil Kumaran <senthil@uthcode.com>: ---------- pull_requests: +1139 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Changes by Senthil Kumaran <senthil@uthcode.com>: ---------- pull_requests: +1140 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Senthil Kumaran added the comment: New changeset a71a3ad54d14483cfaebd8e0fb96c97c798d9e32 by Senthil Kumaran in branch '3.6': bpo-26947: DOC: clarify wording on hashable in glossary (#948) (#957) https://github.com/python/cpython/commit/a71a3ad54d14483cfaebd8e0fb96c97c798... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Senthil Kumaran added the comment: New changeset 51fc7e3d6a29de7b3142e51f8caf4d31f7ac72a0 by Senthil Kumaran in branch '3.5': bpo-26947: DOC: clarify wording on hashable in glossary (#948) (#958) https://github.com/python/cpython/commit/51fc7e3d6a29de7b3142e51f8caf4d31f7a... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Changes by Senthil Kumaran <senthil@uthcode.com>: ---------- resolution: -> fixed stage: -> resolved status: open -> closed type: -> behavior _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Senthil Kumaran added the comment: I reviewed in the pull request. I agree that the wording was slightly better than the original. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Senthil Kumaran added the comment: I have to admit, I did not see some of the negative votes in this ticket before merging the patch. If your is opposition is strong, please comment and suggest a better improvement over the patch. thank you! ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Xiang Zhang added the comment: I think the original is OK. Adding "not" means the opposite. ---------- nosy: +xiang.zhang _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Steven D'Aprano added the comment: Xiang Zhang is correct: the original is technically correct. If you read it like this: "All of Python’s immutable built-in objects are hashable, while no mutable containers (such as lists or dictionaries) are [hashable]." it should be clear. But if you have a suggestion for wording which is easier to understand (especially for those whose English is not so good) please say so. ---------- nosy: +steven.daprano _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Eric V. Smith added the comment: I'm a native speaker, and it's not the greatest sentence. How about: All of Python’s immutable built-in objects (such as numbers, strings and tuples) are hashable. None of its mutable containers (such as lists or dictionaries) are hashable. ---------- nosy: +eric.smith _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Xiang Zhang added the comment: As a non-native speaker, actually I prefer the original one. But both versions lead to no confusion for me. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
mPython added the comment: Just to mention that I'm not native speaker, and I'm Django (Python) beginner. I'm very good in C++, Java and in last 12 years read a lot IT documentation. Mentioned sentence was not clear enough for me so I created this ticket. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Changes by Cheryl Sabella <chekat2@gmail.com>: ---------- pull_requests: +1130 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Martin Panter added the comment: The pull request currently suggests “All of Python’s immutable built-in objects are hashable; mutable containers (such as lists or dictionaries) are not.” This seems better wording than the original. FWIW, I would have tried “Python’s built-in immutable objects are hashable, while mutable containers (such as lists and dictionaries) are not hashable.” ---------- nosy: +martin.panter title: Documentation improvement needed -> Hashable documentation improvement needed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Senthil Kumaran added the comment: New changeset 64c887ab3a400cf91bde4f0c5ef69eacc88bc5e1 by Senthil Kumaran (csabella) in branch 'master': bpo-26947: DOC: clarify wording on hashable in glossary (#948) https://github.com/python/cpython/commit/64c887ab3a400cf91bde4f0c5ef69eacc88... ---------- nosy: +orsenthil _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Changes by Senthil Kumaran <senthil@uthcode.com>: ---------- pull_requests: +1139 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Changes by Senthil Kumaran <senthil@uthcode.com>: ---------- pull_requests: +1140 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Senthil Kumaran added the comment: New changeset a71a3ad54d14483cfaebd8e0fb96c97c798d9e32 by Senthil Kumaran in branch '3.6': bpo-26947: DOC: clarify wording on hashable in glossary (#948) (#957) https://github.com/python/cpython/commit/a71a3ad54d14483cfaebd8e0fb96c97c798... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Senthil Kumaran added the comment: New changeset 51fc7e3d6a29de7b3142e51f8caf4d31f7ac72a0 by Senthil Kumaran in branch '3.5': bpo-26947: DOC: clarify wording on hashable in glossary (#948) (#958) https://github.com/python/cpython/commit/51fc7e3d6a29de7b3142e51f8caf4d31f7a... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Changes by Senthil Kumaran <senthil@uthcode.com>: ---------- resolution: -> fixed stage: -> resolved status: open -> closed type: -> behavior _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Senthil Kumaran added the comment: I reviewed in the pull request. I agree that the wording was slightly better than the original. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
Senthil Kumaran added the comment: I have to admit, I did not see some of the negative votes in this ticket before merging the patch. If your is opposition is strong, please comment and suggest a better improvement over the patch. thank you! ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26947> _______________________________________
participants (7)
-
Cheryl Sabella -
Eric V. Smith
-
Martin Panter
-
mPython
-
Senthil Kumaran
-
Steven D'Aprano
-
Xiang Zhang