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.
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
collections.counter examples are misleading #76951
Comments
The first example given for collections.Counter is misleading - the documentation ideally should show the 'best' (one and only one) way to do something and the example is this : >>> # Tally occurrences of words in a list
>>> cnt = Counter()
>>> for word in ['red', 'blue', 'red', 'green', 'blue', 'blue']:
... cnt[word] += 1
>>> cnt
Counter({'blue': 3, 'red': 2, 'green': 1}) clearly this could simply be : >>> # Tally occurrences of words in a list
>>> cnt = Counter(['red', 'blue', 'red', 'green', 'blue', 'blue'])
>>> cnt
Counter({'blue': 3, 'red': 2, 'green': 1}) (i.e. the iteration through the array is unneeded in this example). The 2nd example is better in showing the 'entry-level' use of the Counter class. There possibly does need to be a simple example of when you might manually increment the Counter class - but I don't think that the examples given illustrate that in a useful way; and I personally haven't come across a use-case for manually incrementing the Counter class entires that couldn't be accomplished with a comprehension or generator expression passed directly to the Counter constructor. |
Thanks for the suggestion. I respectfully disagree. The "core" functionality of Counter is the ability to write c['x'] += 1 without risking a KeyError. The add-on capability is to process an entire iterable all at once. This is analogous to the list() builtin- where the core ability is to write s.append(e) and there is a convenience of calling list(iterable). Another reason the first example goes first because it is simple. It shows counting in isolation with no other distractions (an in-vitro example). The second example is in a more complex environment incorporating file access and regular expressions (an in-vivo example). FWIW, there are plenty of examples of using the += style. Here's one I use in my Python courses:
import collections, re, pprint
visited = collections.Counter()
with open('notes/nasa_19950801.log') as f:
for line in f:
mo = re.search(r'GET\s+(\S+)\s+200', line)
if mo is not None:
url = mo.group(1)
visited[url] += 1
pprint.pprint(visited.most_common(20)) I've had good luck with people understanding the docs as-is, so I'm going to decline the suggestion. I do appreciate you taking the time to share your thoughts. |
Raymond, My view would be that the documentation of the stdlib should document the entry level use cases. I think the examples in the documentation should at least demonstrate something important on the class being documented - and the first example doesn't. I am very tempted to re-open - but I wont - no benefit in bouncing the status as we discuss this. |
You know, I'm not sure if I had ever seen that example before. When you click Counter at the top of the page, it goes right to the class definition, which is past the example. Having said that, I really like the example. Until now, I didn't realize what Raymond said above about Counters (that the core ability is to write c['x'] += 1 without a KeyError). So, thanks to this report, I learned that today! One thing that did surprise me in the example is that I expected the repr to be in insertion order in 3.7. The class description says 'It is an unordered collection where elements are stored as dictionary keys' and I was wondering if that was still true since dicts now have a guaranteed order. I tried it on the example, which still printed Counter({'blue': 3, 'red': 2, 'green': 1})! Of course it makes sense after looking at the code because it calls Anyway, writing this here to ask about the wording regarding 'unordered collection'. Thanks! |
Cheryl : |
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:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: