[Python-Dev] semantics of subclassing things from itertools

[Raymond Hettinger]

> On Sep 10, 2015, at 3:23 AM, Maciej Fijalkowski <fijall at gmail.com> wrote:
> 
> I would like to know what are the semantics if you subclass something
> from itertools (e.g. islice).
> 
> Right now it's allowed and people do it, which is why the
> documentation is incorrect. It states "equivalent to: a function-or a
> generator", but you can't subclass whatever it is equivalent to, which
> is why in PyPy we're unable to make it work in pure python.
> 
> I would like some clarification on that.

The docs should say "roughly equivalent to" not "exactly equivalent to".
The intended purpose of the examples in the itertools docs is to use
pure python code to help people better understand each tool.  It is not
is intended to dictate that tool x is a generator or is a function.

The intended semantics are that the itertools are classes (not functions
and not generators).  They are intended to be sub-classable (that is
why they have Py_TPFLAGS_BASETYPE defined).

The description as a function was perhaps used too loosely (in much the
same way that we tend to think of int(3.14) as being a function when int
is really a class).  I tend to think about mapping, filtering, accumulating,
as being functions while at the same time knowing that they are actually
classes that produce iterators.

The section called "itertools functions" is a misnomer but is also useful
because the patterns of documenting functions better fit the itertools
and because documenting them as classes suggest that they should
each have a list of methods on that class (which doesn't make send
because the itertools are each one trick ponies with no aspirations 
to grow a pool of methods).

When I get a chance, I'll go through those docs and make them more precise.
Sorry for the ambiguity.


Raymond