[Python-checkins] r70438 - python/trunk/Doc/library/functions.rst

[Raymond Hettinger]

FWIW, I think the examples need to be *very* short.
The functions.rst page is growing hard to read because
of all of the lengthy examples, caveats, warnings, and
saying verbosity.  We don't want to turn the main docs
into a tutorial.  It makes them harder to use.   If someone
just wants to scan what the builtin functions do, they now
face a very lengthy page of reading.  It's getting too fat.

I think the example below is way too long.


Raymond


----- Original Message ----- 
From: "benjamin.peterson" <python-checkins at python.org>
To: <python-checkins at python.org>
Sent: Tuesday, March 17, 2009 1:29 PM
Subject: [Python-checkins] r70438 - python/trunk/Doc/library/functions.rst


> Author: benjamin.peterson
> Date: Tue Mar 17 21:29:51 2009
> New Revision: 70438
> 
> Log:
> I thought this was begging for an example
> 
> Modified:
>   python/trunk/Doc/library/functions.rst
> 
> Modified: python/trunk/Doc/library/functions.rst
> ==============================================================================
> --- python/trunk/Doc/library/functions.rst (original)
> +++ python/trunk/Doc/library/functions.rst Tue Mar 17 21:29:51 2009
> @@ -596,6 +596,25 @@
>    its :meth:`next` method; if the value returned is equal to *sentinel*,
>    :exc:`StopIteration` will be raised, otherwise the value will be returned.
> 
> +   Example usage: ::
> +
> +      >>> iterator = iter(range(10))
> +      >>> iterator
> +      <listiterator object at 0x86b50>
> +      >>> iterator.next()
> +      0
> +      >>> iterator.next()
> +      1
> +      >>> def my_generator():
> +      ...     for i in range(10):
> +      ...             yield i
> +      ...
> +      >>> iterator = iter(my_generator().next, 7)
> +      >>> iterator
> +      <callable-iterator object at 0x86bb0>
> +      >>> list(iterator)
> +      [0, 1, 2, 3, 4, 5, 6]
> +
>    .. versionadded:: 2.2
> 
> 
> _______________________________________________
> Python-checkins mailing list
> Python-checkins at python.org
> http://mail.python.org/mailman/listinfo/python-checkins