[Python-checkins] r61761 - python/trunk/Doc/library/collections.rst

[Georg Brandl]

Raymond Hettinger schrieb:
>> -           def _make(cls, iterable):
>> +           def _make(cls, iterable, new=tuple.__new__, len=len):
>>                'Make a new Point object from a sequence or iterable'
>> -               result = tuple.__new__(cls, iterable)
>> +               result = new(cls, iterable)
> 
> It would be nice if there were some way to tell doctest to have an expected difference. In this case, I had intentionally simplified 
> the presentation.  The code is a bit clearer without the pre-binding optimization used by the real code.

Okay, I hadn't guessed this. I don't think there is a way for doctest to 
recognize this, so we can either skip this as a doctest, or omit the
simplification.

> The comment strings in the itertools docs take a similar approach with a simplified notation:
> 
>   def product(*args, **kwds):
>       # product('ABCD', 'xy') --> Ax Ay Bx By Cx Cy Dx Dy
>       # product(range(2), repeat=3) --> 000 001 010 011 100 101 110 111
>       pools = map(tuple, args) * kwds.get('repeat', 1)
>       result = [[]]
>       for pool in pools:
>           result = [x+[y] for x in result for y in pool]
>       for prod in result:
>           yield tuple(prod)
> 
> Also, it would be nice to have a general purpose way of suppressing arbitrary lines from the generated html.  In the changes to 
> operator.rst, we may be better off suppresing the first and last line in this example:
> 
>     >>> import operator
>     >>> d = {}
>     >>> keys = range(256)
>     >>> vals = map(chr, keys)
>     >>> vals = map(chr, keys)
>     >>> map(operator.setitem, [d]*len(keys), keys, vals)
> +   [None, None, ..., None]
> 
> The point of the map operation was the side-effect, not the list of Nones.
> 
> Likewise, brevity is served and narrative flow is better preserved if we can hide imports.   In docs about the operator module, the 
> examples don't gain anything from the "import operator" line which is necessary for the doctest to run.

The import is no problem, since there is the concept of "setup code" that runs
before all the doctests (see e.g. the decimal commit). I'll move the operator
import there.

The last line, however, is trickier. Of course, since there is no interesting 
output to compare, I'll remove the output and skip the test.

Georg

-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.