Parsing Strings in Enclosed in Curly Braces

[John Machin]

On May 17, 1:28 am, a... at pythoncraft.com (Aahz) wrote:
> In article <180531ca-33aa-47b9-9c69-5b5973f6b... at v35g2000pro.googlegroups.com>,
> John Machin  <sjmac... at lexicon.net> wrote:
> >Neat trick. However, from 2.6.2:
>
> >>>> help(sum)
> >Help on built-in function sum in module __builtin__:
>
> >sum(...)
> >    sum(sequence[, start]) -> value
>
> >    Returns the sum of a sequence of numbers (NOT strings) plus the
> >value
> >    of parameter 'start' (which defaults to 0).  When the sequence is
> >    empty, returns start.
>
> >Since when is a list a number? Perhaps the help needs clarification,
> >in line with the docs.
>
> The primary use-case for sum() is numbers, with a special exception to
> prohibit using strings.  Only strings are prohibited to allow using sum()
> with user-defined classes.  That makes it a little difficult to document

Non sequitur.

> precisely in a summary; unless you can come up with a specific better
> wording, the docs will probably stay as-is.  If you do come up with
> something better, please file it on bugs.python.org.

OK let's start with getting the docs right and then summarise that for
the help.
URI: http://docs.python.org/library/functions.html#sum
Contents:
"""
sum(iterable[, start])¶

    Sums start and the items of an iterable from left to right and
returns the total. start defaults to 0. The iterable‘s items are
normally numbers, and are not allowed to be strings. The fast, correct
way to concatenate a sequence of strings is by calling ''.join
(sequence). Note that sum(range(n), m) is equivalent to reduce
(operator.add, range(n), m) To add floating point values with extended
precision, see math.fsum().

    New in version 2.3
"""
Suggestions:
(1) fix what should be an apostrophe in "iterable's"
(2) s/sequence/iterable/g
(3) Either replace the sentence about "reduce" by "Note that sum
(iterable, start) is equivalent to reduce(operator.add, iterable,
start) except for the prohibition of strings" or explain why not or
what's so special about range(n).
(4) Add a full stop after the sentence about "reduce".

Help from 2.6.2:
"""
    sum(sequence[, start]) -> value

    Returns the sum of a sequence of numbers (NOT strings) plus the
value
    of parameter 'start' (which defaults to 0).  When the sequence is
    empty, returns start.
"""
Suggested replacement:
"""
    sum(iterable[, start]) -> value

    Returns the sum of the contents of the iterable plus the value
    of parameter 'start' (which defaults to 0).  When the iterable is
    empty, returns start. Strings are disallowed; use
    ''.join(iterable) to concatenate strings efficiently.
"""

Cheers,
John