Iterator Protocol - Python 描述符协议

 Iterator Protocol - Python 描述符协议

 先看几个有关概念,
     iterator 迭代器,
         一个实现了无参数的 __next__ 方法, 并返回 '序列'中下一个元素,在没有更多的元素可返回的时候 raises StopIteration 的对象,
         被称为 iterator(迭代器).
         在 python 中, 迭代器 'iterator' 同时也实现了 __iter__ 方法, 故 iterators are iterable.
         经典迭代器 'classic iterators' 从一个集合'collection'中返回元素.
         生成器 'generator' 也是迭代器, 但可能灵活些, 请参考 generator 一文。
             例,
                 >>> A = iter('Ads')
                 >>> A
                 <iterator object at 0x00000000036D7320>
                 >>> type(A)
                 <type 'iterator'>
                 >>> dir(A)
                 ['__class__', ... ..., '__iter__', ... ..., 'next']
                 >>> A.next()
                 'A'
                 >>> A.next()
                 'd'
                 >>> A.next()
                 's'
                 >>> A.next()
                 Traceback (most recent call last):
                   File "<input>", line 1, in <module>
                 StopIteration

         iterator
             Any object that implements the __next__
             no-argument method which returns the
             next item in a series, or raises StopItera
             tion when there are no more items. Python
             iterators also implement the __iter__
             method so they are also iterable. Classic
             iterators, according to the original design
             pattern, return items from a collection. A
             generator is also an iterator, but it’s more
             flexible. See generator

     iterable 可迭代,
         一个对象，如果该对象可以通过内置方法 'iter' 获得可以个 'iterator',则称该对象是可迭代对象 'iterable'
             如,
                 >>> A = iter('ABCCcvsds')
                 >>> A
                 <iterator object at 0x00000000036D7320>
                 >>> type(A)
                 <type 'iterator'>

         一个可迭代对象 'iterable object' 可以用于 循环'loops', 列表推导'comprehensions', 元祖拆包'tuple unpacking'.
         实现了 __iter__ 方法, 返回迭代器'iterator'的对象是可迭代的对象'iterable'. 序列'sequences' 是可迭代对象.
         实现了 __getitem__ 方法的对象也有可能是可迭代对象.

         iterable
             Any object from which the iter built-in
             function can obtain an iterator. An iterable
             object works as the source of items in for
             loops, comprehensions and tuple unpack‐
             ing. Objects implementing an __iter__
             method returning an iterator are iterable.
             Sequences are always iterable; other objects
             implementing a __getitem__ method may
             also be iterable.

     iterable unpacking 可迭代对象拆包
         与元祖拆白 'tuple unpacking' 同义. 应用于 'parallel assignment'.
             例,
                 >>> a = (1,2)
                 >>> b,c = a
                 >>> a
                 (1, 2)
                 >>> b
                 1
                 >>> c
                 2
                 >>> c,b = b,c
                 >>> a
                 (1, 2)
                 >>> b
                 2
                 >>> c
                 1

         parallel assignment
             Assigning to several variables from items in
             an iterable, using syntax like a, b = [c,
             d] — also known as destructuring assign‐
             ment. This is a common application of tuple
             unpacking.

 进一步了解一下儿迭代器对象 'Iterator Objects' 和 'Iterator Protocol',
     Iterator Objects
         python 中有两种 迭代器对象 'iterator objects'.

         一种是 序列迭代器 'sequence iterator', 用于对'序列对象' __getitem__ 方法的支持.

         另一种是,上例子中常见的迭代器: 一个可调用对象'callable object', 在其上调用 next()
         方法, 依次放回序列中的元素, 迭代结束的时候返回 StopIteration error(sentinel value).

         迭代器相关源码,
             与'第一种'迭代器相关,
                 PyTypeObject PySeqIter_Type
                     python 类型对象-'PySeqIter_Type' 为迭代器对象的'类型对象', 由 PySeqIter_New() 函数产生.
                     也是通过 iter(iterable) 内建函数所得到'序列'的类型对象.

                 int PySeqIter_Check(op)
                     当 op 是 PySeqIter_Type 类型的时候, 函数返回 true

                 PyObject* PySeqIter_New(PyObject *seq)
                     创建一个迭代器对象, 迭代结束后 raises IndexError

             与'另一种'迭代器相关,
             　　PyTypeObject PyCallIter_Type
                 　　由 PyCallIter_New() 创建的可'指定' sentinel value 的迭代器的类型对象.  iter(callable, sentinel value)

             　　int PyCallIter_Check(op)
                 　　当 op 是 PyCallIter_Type 类型的时候, 函数返回 true

             　　PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel)
                 　　创建一个迭代器对象, 迭代返回 sentinel value 结束, 并 raises IndexError
                 　　第一个参数是任何 python callable 的对象.

             　例子,
                 第一种'迭代器
                     >>> abc = [1,2,3,"S",4,5]
                     >>> a = iter(abc)
                     >>> a
                     <listiterator object at 0x00000000037E0668>
                     >>> a.next()
                     1
                     >> a.next()
                     2
                     >>> a.next()
                     3
                     >>> a.next()
                     'S'
                     >>> a.next()
                     4
                     >>> a.next()         # 当迭代器中没有新的数据的时候 StopIteration
                     Traceback (most recent call last):
                       File "<input>", line 1, in <module>
                     StopIteration
                     >>> a                # StopIteration 后迭代器对象还存在
                     <listiterator object at 0x00000000037E0668>
                     >>> a.next()         # 迭代器返回最后一个数据后，如果想再获取其中的元素, 需要再次生成新的迭代器对象
                     Traceback (most recent call last):
                       File "<input>", line 1, in <module>
                     StopIteration

                 另外一种'迭代器
                     >>> b = iter(abc.pop, "S")       # abc.pop 是一个 callable 的对象,  指定 StopIteration 的值'S'
                     >>> b
                     <callable-iterator object at 0x00000000037E0668>
                     >>> b.next()
                     4
                     >>> b.next()                     # next 方法得到元素 'S', raises StopIteration
                     Traceback (most recent call last):
                       File "<input>", line 1, in <module>
                     StopIteration

     Iterator Protocol
         python 在 C 层面有2个函数跟 迭代器 'iterator' 相关,

             int PyIter_Check(PyObject *o)
                 如果 对象 o 支持 迭代器协议 interator protocol 返回 true.

             PyObject* PyIter_Next(PyObject *o)
                 返回迭代 'iteration' 的下一个元素.
                 o 必须是一个迭代器(*** 注意,该函数本身并不对这一点做验证; 有使用者保证传入的是 iterator),
                 如果没有可以返回的元素, 返回 return NULL (没有exception 描述);
                 如果在获取元素的时候发生了任何的错误 errors, 返回 return NULL 即相应的 exception 描述.

             python 官方示例,
                 PyObject *iterator = PyObject_GetIter(obj);
                 PyObject *item;

                 if (iterator == NULL) {
                     /* propagate error */
                 }

                 while (item = PyIter_Next(iterator)) {
                     /* do something with item */
                     ...
                     /* release reference when done */
                     Py_DECREF(item);
                 }

                 Py_DECREF(iterator);

                 if (PyErr_Occurred()) {
                     /* propagate error */
                 }
                 else {
                     /* continue doing useful work */
                 }

　　iterator 应用的经典示例,
    　　with open('mydata.txt') as fp:
        　　for line in iter(fp.readline, ''):
            　　process_line(line)