On 4/19/2012 6:16 PM, Cameron Simpson wrote:
On 19Apr2012 18:07, Terry Reedy<tjre...@udel.edu> wrote:
| On 4/19/2012 5:32 PM, Cameron Simpson wrote:
|> On 19Apr2012 14:32, Terry Reedy<tjre...@udel.edu> wrote:
|> | On 4/19/2012 11:51 AM, Jacob MacDonald wrote:
|> |> When I talk about an iterable, I say "iterable".
|> |
|> | Ditto.
|>
|> I used to, but find myself saying "sequence" these days. It reads
|> better, but is it the same thing?
|
| A Python 'sequence' is a collection that has a length and can be indexed
| by counts 0, 1, ... . In other words, len(s) and s[n] work. This
| definition is in the library manual somewhere.
7.4.1. Collections Abstract Base Classes defines a Sequence as a Sized,
Iterable, Container.
The glossary entry for 'sequence' leaves out the container part:
"An iterable which supports efficient element access using integer
indices via the __getitem__() special method and defines a len() method
that returns the length of the sequence. ... Note that dict also
supports __getitem__() and __len__(), but is considered a mapping rather
than a sequence because the lookups use arbitrary immutable keys rather
than integers."
Then there is this: "iter(object[, sentinel])
... object must be ... or it must support the sequence protocol (the
__getitem__() method with integer arguments starting at 0)."
On the same topic, when I write a generator my docstring tends to come
in one of two forms:
foo() yields values ...
or
foo() returns an iterable ...
'Generator' is another area of confusion. Here is what the
implementation says
>>> def gf(): yield 1
>>> type(gf)
<class 'function'>
>>> g = gf()
>>> type(g)
<class 'generator'>
I and as far as I know, most people, call gf a generator function
(function that returns a generator) and g a generator, as in instance of
class 'generator', just as 'a list' is an instance of class 'list'.
Unfortunately, whoever wrote the glossary contradicted the language and
called gf a 'generator' and g merely an 'iterator'. It is, but
generators are an important subcategory of iterator with extra api and
currently unique suspend-resume behavior. Actually, the entry
contradicts itself and later uses 'generator' as I have, to refer to the
class 'generator' instance whose .__next__ method suspends and resumes.
I will have to propose a patch.
I find the first clumsy, but tend not to think of generators as "returning"
an iterable as a single action. But of course they do, don't
they:
A generator function returns a generator, which is a sub-category of
iterator, which is a sub-category of iterable. A generator function is
not an iterable itself, because it does not have a .__iter__ method.
Since there are minor api differences between generators and other
iterators, I think the docstring should be specific. For gf above, I
would say "Return a generator that yields 1."
Note that the Python docs are intended to consistently say 'return'
rather than 'returns'. If the return is the default None, they use some
other imperative verb such as 'convert' or 'invoke'. I try to do the
same so I will have that habit when I work on them.
As far as I know, generators are only constructed from Python-coded
generator functions and expressions, so that there are no built-in
generators. Still, generators are the easiest to write Python
equivalents of the various built-in iterator types, such as those in
itertools. So there are no trivially found generator doc examples that I
know of, though there must be some in some Python-coded module.
---
Terry Jan Reedy
--
http://mail.python.org/mailman/listinfo/python-list
