Hashable documentation improvement needed

e8a9866f-bcc9-4cea-a6ef-b70ac84d2902 commented 8 years ago

BPO	26947
Nosy	@orsenthil, @ericvsmith, @stevendaprano, @vadmium, @zhangyangyu
PRs	python/cpython#948 python/cpython#957 python/cpython#958

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = None closed_at = created_at = labels = ['type-bug', 'docs'] title = 'Hashable documentation improvement needed' updated_at = user = 'https://bugs.python.org/mPython' ``` bugs.python.org fields: ```python activity = actor = 'orsenthil' assignee = 'docs@python' closed = True closed_date = closer = 'orsenthil' components = ['Documentation'] creation = creator = 'mPython' dependencies = [] files = [] hgrepos = [] issue_num = 26947 keywords = [] message_count = 12.0 messages = ['264805', '264813', '264820', '264822', '264876', '264901', '291007', '291011', '291012', '291013', '291015', '291016'] nosy_count = 7.0 nosy_names = ['orsenthil', 'eric.smith', 'steven.daprano', 'docs@python', 'martin.panter', 'xiang.zhang', 'mPython'] pr_nums = ['948', '957', '958'] priority = 'normal' resolution = 'fixed' stage = 'resolved' status = 'closed' superseder = None type = 'behavior' url = 'https://bugs.python.org/issue26947' versions = ['Python 3.5'] ```

e8a9866f-bcc9-4cea-a6ef-b70ac84d2902 commented 8 years ago

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.

zhangyangyu commented 8 years ago

I think the original is OK. Adding "not" means the opposite.

stevendaprano commented 8 years ago

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.

ericvsmith commented 8 years ago

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.

zhangyangyu commented 8 years ago

As a non-native speaker, actually I prefer the original one. But both versions lead to no confusion for me.

e8a9866f-bcc9-4cea-a6ef-b70ac84d2902 commented 8 years ago

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.

vadmium commented 7 years ago

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.”