[issue23787] sum() function docstring lists arguments incorrectly

[Raymond Hettinger]

Raymond Hettinger added the comment:

[Serhiy]
> Raymond, could you open a pull request?

Perhaps you could do it for me.  I still haven't had time to wrestle with the github switchover, so I'm effectively crippled for a while.

[Valentine]
> Seems like mentioning string was really a bad idea .... that's
> why I considered the docstring [subtly] wrong.

Not really wrong in a way that confuses typical users.  That docstring has been successfully communicating the basic API for over a decade.

Over time, the docs have slowly converted the old "sequence" references to "iterable".  The docs were never really wrong; instead, we just got more precise by what we meant by sequence versus iterable (i.e. before the ABCs were introduced, the term "sequence" was used in a somewhat generic way to mean "a succession of data values"). 

Also note, it is an interesting paradox that docstrings that are the most helpful to most people most of the time are brief and little loose with terminology.  In general, they reward those who are doing quick lookups for API reminders, but do not reward pedantic close readings.

We'll go ahead and change "sequence" to "iterable" for sum(), but I think that is only a minor win.  The change makes it more technically correct but less friendly to some users (i.e. people need to be taught what "iterable" means while they tend to get the notion of "sequence of values" without any training).

As far as the exclusion of string goes, there were plenty of debate about whether to allow them or to more broadly disallow many data types where summing works quadratically.  The final decision was made by the BDFL and it seems to have been the right decision for just about everyone.  You can take issue with his decision, but that would be pointless.

----------
nosy: +rhettinger
status: pending -> open

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue23787>
_______________________________________