[issue32770] collections.counter examples are misleading

[Anthony Flury]

Anthony Flury  added the comment:

Cheryl : 
When you iterate around a counter instance it does return keys in the order 
they are first encountered/inserted - so I agree with you that it is an ordered 
collection from Python 3.7 onwards (although the iteration and the repr are 
ordered in different orders.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32770] collections.counter examples are misleading

[Cheryl Sabella]

Cheryl Sabella  added the comment:

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 `most_common` 
in the repr, but I hadn't realized that before.  So, two things learned about 
Counter today.   :-)

Anyway, writing this here to ask about the wording regarding 'unordered 
collection'.

Thanks!

--
nosy: +csabella

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32770] collections.counter examples are misleading

[Anthony Flury]

Anthony Flury  added the comment:

Raymond, 
I completely understand your comment but I do disagree.

My view would be that the documentation of the stdlib should document the entry 
level use cases.
The first example given uses nothing special from the Counter class - you could 
implement exactly the same with a defaultdict(int) - the only difference would 
be that output will read defaultdict(,{'blue': 3, 'red': 2, 
'green': 1}).

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32770] collections.counter examples are misleading

[Raymond Hettinger]

Raymond Hettinger  added the comment:

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:

'Scan a log file from a NASA server'

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.

--
assignee: docs@python -> rhettinger
nosy: +rhettinger
resolution:  -> not a bug
stage:  -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue32770] collections.counter examples are misleading

[Anthony Flury]

New submission from Anthony Flury :

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.

--
assignee: docs@python
components: Documentation
messages: 311630
nosy: anthony-flury, docs@python
priority: normal
severity: normal
status: open
title: collections.counter examples are misleading
versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com