gh-109812: Fix phrasing for collections.Counter

[JacobCoffee]

This changes the wording for an incorrect collections.Counter piece.

• Issue: Tricky phrasing in the collections.Counter docs #109812

---

📚 Documentation preview 📚: https://cpython-previews--109813.org.readthedocs.build/

[ghost]

All commit authors signed the Contributor License Agreement.

[sobolevn]

Thanks! It is up to @rhettinger to decide on the wording, but the bug in the docs is clear! 👍

Congrats on your first CPython PR!
It is always nice to see familiar people 😉

[sobolevn]

Maybe just

Suggested change

	c.items() # convert to a view object of the dictionary’s items (elem, cnt) pairs
	c.items() # convert to a iterator of (elem, cnt) pairs

?

[pochmann]

It's not an iterator.

I'd just change "list" to "view". And "convert to" to "create", since the view doesn't really contain the data, so "convert to" seems wrong to me.

[sobolevn]

Yes, it is just an iterable 👍

>>> {}.items().__iter__
<method-wrapper '__iter__' of dict_items object at 0x102cd1250>
>>> {}.items().__next__
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'dict_items' object has no attribute '__next__'. Did you mean: '__ne__'?

[JacobCoffee]

Maybe this is more in line with the rest of the examples

Suggested change

	c.items() # create a view of the dictionary’s items (elem, cnt) pairs
	list(c.items()) # convert to a list of (elem, cnt) pairs

[terryjreedy]

I disagree. The doc for c.items() should say what c.items returns.

[rhettinger]

but the bug in the docs is clear!

Nitpick. The docs were correct when they were written (Python 2.7). It is the parent class that changed.

You all are welcome to change this to iterable which is correct but less accessible, or to view which is also correct and makes more specific promises, or to dict_items which is the exact type but meaningless to a reader, or to a set-like object providing a view on D's items which matches the inherited docstring. But ideally, you should focus on the communication goal for that section which is just a quick reference for common patterns for working with Counter objects. That section isn't a spec, it is a cheatsheet. So don't venture too far from what a newcomer would understand (i.e. 'view' and 'iterable' aren't accessible except for people are who already strong with Python).

This spirit of the section is about how we use counters, so I would opt for:

c.items() # access the (elem, cnt) pairs

[JacobCoffee]

I agree on view being less accessible.. had to look up what that even was 🙃