Title: Additions to function docs: reduce and itertools.
Type: enhancement Stage:
Components: Documentation Versions: Python 3.3, Python 3.4
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: Esa.Peuha, docs@python, georg.brandl, python-dev, rhettinger, terry.reedy
Priority: normal Keywords: patch

Created on 2013-10-09 10:09 by Esa.Peuha, last changed 2013-10-12 23:05 by rhettinger. This issue is now closed.

File name Uploaded Description Edit
doc.diff Esa.Peuha, 2013-10-09 10:09 review
reduce_equiv.diff georg.brandl, 2013-10-12 16:55 review
Messages (11)
msg199281 - (view) Author: Esa Peuha (Esa.Peuha) Date: 2013-10-09 10:09
Here are some additions to documentation of a few functions:

all, any: alternative definitions using functools.reduce
enumerate: alternative definition using zip and itertools.count
sum: equivalent definition using functools.reduce and operator.add
functools.reduce: equivalent definitions, use operator.add in example
itertools.accumulate: point to functools.reduce
itertools.filterfalse: point to filter
msg199282 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-10-09 10:29
Most of these changes should not be applied: the "alternate" equivalents in terms of reduce() will not help understanding,  Equivalents for reduce() may be useful, but I would limit them to one per case, possibly even just one function that covers both cases.

I'm deferring to Raymond for the changes to the itertools docs.
msg199313 - (view) Author: Esa Peuha (Esa.Peuha) Date: 2013-10-09 16:58
How would you give a single definition of reduce() that helps people to understand both 2-arg and 3-arg variants? The way it is implemented in C is impossible to duplicate in pure Python; the best you could do is a hack that works unless someone *tries* to break it, but that would just be confusing.
msg199315 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-10-09 17:13
What about

def reduce(function, iterable, initializer=None):
    it = iter(iterable)
    if initializer is None:
        value = next(it)
        value = initializer
    for element in it:
        value = function(value, element)
    return value

Remember, an equivalent doesn't have to be 100% compatible, it is a way for the user to quickly get an idea what the function does.
msg199527 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-10-12 00:14
I think the reduce equivalent given by Georg would be excellent.

I think the enumerate equivalent already given is fine because I think equivalents should use basic syntax (for loops), not something that might be more obscure.
msg199541 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2013-10-12 07:20
Almost all of these make the docs worse and should not be applied.  The purpose of the "equivalent" code is simply to make the documentation clearer, not to show all the ways it could have been done.

I do think Georg's reduce() equivalent should be added because it is clearer than the current prose description.
msg199589 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-10-12 16:20
What do you think of the two references added to the itertools docs?
msg199597 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2013-10-12 16:44
The reference from accumulate() to reduce() may be useful.

I'm opposed to most of the other equivalents and cross-references.  They bloat the docs without adding value.  Terry is right in saying that the equivalent for enumerate() is better as a basic loop than as a composition of functional tools.   I think the OP has missed what the purpose of the code equivalents was trying to do.
msg199599 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-10-12 16:51
I agree. Will prepare a patch to the reduce() doc.
msg199639 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-10-12 23:05
New changeset 3b6401c27e39 by Raymond Hettinger in branch '3.3':
Issue #19202:  Add cross-reference and a rough code equivalent
msg199640 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2013-10-12 23:05
Thanks Georg.
Date User Action Args
2013-10-12 23:05:51rhettingersetstatus: open -> closed
resolution: fixed
messages: + msg199640
2013-10-12 23:05:09python-devsetnosy: + python-dev
messages: + msg199639
2013-10-12 16:55:14georg.brandlsetfiles: + reduce_equiv.diff
2013-10-12 16:51:52georg.brandlsetmessages: + msg199599
2013-10-12 16:44:14rhettingersetmessages: + msg199597
2013-10-12 16:20:50georg.brandlsetmessages: + msg199589
2013-10-12 07:20:14rhettingersetmessages: + msg199541
2013-10-12 07:15:50rhettingersetassignee: docs@python -> rhettinger
2013-10-12 00:14:02terry.reedysetnosy: + terry.reedy
title: Additions to docs -> Additions to function docs: reduce and itertools.
messages: + msg199527

versions: + Python 3.3
2013-10-09 17:13:17georg.brandlsetmessages: + msg199315
2013-10-09 16:58:09Esa.Peuhasetmessages: + msg199313
2013-10-09 10:29:57georg.brandlsetnosy: + georg.brandl, rhettinger
messages: + msg199282
2013-10-09 10:09:16Esa.Peuhacreate