1 Iterator Protocol - Python 描述符協議
  2 
  3 先看幾個有關概念,
  4     iterator 叠代器,
  5         一個實現了無參數的 __next__ 方法, 並返回 ‘序列‘中下一個元素,在沒有更多的元素可返回的時候 raises StopIteration 的對象,
  6         被稱為 iterator(叠代器).
  7         在 python 中, 叠代器 ‘iterator‘ 同時也實現了 __iter__ 方法, 故 iterators are iterable.
  8         經典叠代器 ‘
 
classic iterators‘ 從一個集合‘collection‘中返回元素.
  9         生成器 ‘generator‘ 也是叠代器, 但可能靈活些, 請參考 generator 一文。
 10             例,
 11                 >>> A = iter(‘Ads‘)
 12                 >>> A
 13                 <iterator object at 0x00000000036D7320>
 14                 >>> type(A)
 
 15                 <type ‘iterator‘>
 16                 >>> dir(A)
 17                 [‘__class__‘, ... ..., ‘__iter__‘, ... ..., ‘next‘]
 18                 >>> A.next()
 19                 ‘A‘
 20                 >>> A.next()
 21                 ‘d‘
 22                 >>> A.next()
 
 23                 ‘s‘
 24                 >>> A.next()
 25                 Traceback (most recent call last):
 26                   File "<input>", line 1, in <module>
 27                 StopIteration
 28 
 29         iterator
 30             Any object that implements the __next__
 31             no-argument method which returns the
 32             next item in a series, or raises StopItera
 33             tion when there are no more items. Python
 34             iterators also implement the __iter__
 35             method so they are also iterable. Classic
 36             iterators, according to the original design
 37             pattern, return items from a collection. A
 38             generator is also an iterator, but it’s more
 39             flexible. See generator
 40 
 41     iterable 可叠代,
 42         一個對象，如果該對象可以通過內置方法 ‘iter‘ 獲得可以個 ‘iterator‘,則稱該對象是可叠代對象 ‘iterable‘
 43             如,
 44                 >>> A = iter(‘ABCCcvsds‘)
 45                 >>> A
 46                 <iterator object at 0x00000000036D7320>
 47                 >>> type(A)
 48                 <type ‘iterator‘>
 49 
 50         一個可叠代對象 ‘iterable object‘ 可以用於 循環‘loops‘, 列表推導‘comprehensions‘, 元祖拆包‘tuple unpacking‘.
 51         實現了 __iter__ 方法, 返回叠代器‘iterator‘的對象是可叠代的對象‘iterable‘. 序列‘sequences‘ 是可叠代對象.
 52         實現了 __getitem__ 方法的對象也有可能是可叠代對象.
 53 
 54         iterable
 55             Any object from which the iter built-in
 56             function can obtain an iterator. An iterable
 57             object works as the source of items in for
 58             loops, comprehensions and tuple unpack‐
 59             ing. Objects implementing an __iter__
 60             method returning an iterator are iterable.
 61             Sequences are always iterable; other objects
 62             implementing a __getitem__ method may
 63             also be iterable.
 64 
 65     iterable unpacking 可叠代對象拆包
 66         與元祖拆白 ‘tuple unpacking‘ 同義. 應用於 ‘parallel assignment‘.
 67             例,
 68                 >>> a = (1,2)
 69                 >>> b,c = a
 70                 >>> a
 71                 (1, 2)
 72                 >>> b
 73                 1
 74                 >>> c
 75                 2
 76                 >>> c,b = b,c
 77                 >>> a
 78                 (1, 2)
 79                 >>> b
 80                 2
 81                 >>> c
 82                 1
 83 
 84         parallel assignment
 85             Assigning to several variables from items in
 86             an iterable, using syntax like a, b = [c,
 87             d] — also known as destructuring assign‐
 88             ment. This is a common application of tuple
 89             unpacking.
 90 
 91 進一步了解一下兒叠代器對象 ‘Iterator Objects‘ 和 ‘Iterator Protocol‘,
 92     Iterator Objects
 93         python 中有兩種 叠代器對象 ‘iterator objects‘.
 94 
 95         一種是 序列叠代器 ‘sequence iterator‘, 用於對‘序列對象‘ __getitem__ 方法的支持.
 96 
 97         另一種是,上例子中常見的叠代器: 一個可調用對象‘callable object‘, 在其上調用 next()
 98         方法, 依次放回序列中的元素, 叠代結束的時候返回 StopIteration error(sentinel value).
 99 
100         叠代器相關源碼,
101             與‘第一種‘叠代器相關,
102                 PyTypeObject PySeqIter_Type
103                     python 類型對象-‘PySeqIter_Type‘ 為叠代器對象的‘類型對象‘, 由 PySeqIter_New() 函數產生.
104                     也是通過 iter(iterable) 內建函數所得到‘序列‘的類型對象.
105 
106                 int PySeqIter_Check(op)
107                     當 op 是 PySeqIter_Type 類型的時候, 函數返回 true
108 
109                 PyObject* PySeqIter_New(PyObject *seq)
110                     創建一個叠代器對象, 叠代結束後 raises IndexError
111 
112             與‘另一種‘叠代器相關,
113             　　PyTypeObject PyCallIter_Type
114                 　　由 PyCallIter_New() 創建的可‘指定‘ sentinel value 的叠代器的類型對象.  iter(callable, sentinel value)
115 
116             　　int PyCallIter_Check(op)
117                 　　當 op 是 PyCallIter_Type 類型的時候, 函數返回 true
118 
119             　　PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel)
120                 　　創建一個叠代器對象, 叠代返回 sentinel value 結束, 並 raises IndexError
121                 　　第一個參數是任何 python callable 的對象.
122 
123             　例子,
124                 第一種‘叠代器
125                     >>> abc = [1,2,3,"S",4,5]
126                     >>> a = iter(abc)
127                     >>> a
128                     <listiterator object at 0x00000000037E0668>
129                     >>> a.next()
130                     1
131                     >> a.next()
132                     2
133                     >>> a.next()
134                     3
135                     >>> a.next()
136                     ‘S‘
137                     >>> a.next()
138                     4
139                     >>> a.next()         # 當叠代器中沒有新的數據的時候 StopIteration
140                     Traceback (most recent call last):
141                       File "<input>", line 1, in <module>
142                     StopIteration
143                     >>> a                # StopIteration 後叠代器對象還存在
144                     <listiterator object at 0x00000000037E0668>
145                     >>> a.next()         # 叠代器返回最後一個數據後，如果想再獲取其中的元素, 需要再次生成新的叠代器對象
146                     Traceback (most recent call last):
147                       File "<input>", line 1, in <module>
148                     StopIteration
149 
150                 另外一種‘叠代器
151                     >>> b = iter(abc.pop, "S")       # abc.pop 是一個 callable 的對象,  指定 StopIteration 的值‘S‘
152                     >>> b
153                     <callable-iterator object at 0x00000000037E0668>
154                     >>> b.next()
155                     4
156                     >>> b.next()                     # next 方法得到元素 ‘S‘, raises StopIteration
157                     Traceback (most recent call last):
158                       File "<input>", line 1, in <module>
159                     StopIteration
160 
161     Iterator Protocol
162         python 在 C 層面有2個函數跟 叠代器 ‘iterator‘ 相關,
163 
164             int PyIter_Check(PyObject *o)
165                 如果 對象 o 支持 叠代器協議 interator protocol 返回 true.
166 
167             PyObject* PyIter_Next(PyObject *o)
168                 返回叠代 ‘iteration‘ 的下一個元素.
169                 o 必須是一個叠代器(*** 註意,該函數本身並不對這一點做驗證; 有使用者保證傳入的是 iterator),
170                 如果沒有可以返回的元素, 返回 return NULL (沒有exception 描述);
171                 如果在獲取元素的時候發生了任何的錯誤 errors, 返回 return NULL 即相應的 exception 描述.
172 
173             python 官方示例,
174                 PyObject *iterator = PyObject_GetIter(obj);
175                 PyObject *item;
176 
177                 if (iterator == NULL) {
178                     /* propagate error */
179                 }
180 
181                 while (item = PyIter_Next(iterator)) {
182                     /* do something with item */
183                     ...
184                     /* release reference when done */
185                     Py_DECREF(item);
186                 }
187 
188                 Py_DECREF(iterator);
189 
190                 if (PyErr_Occurred()) {
191                     /* propagate error */
192                 }
193                 else {
194                     /* continue doing useful work */
195                 }

　　iterator 應用的經典示例,
    　　with open(‘mydata.txt‘) as fp:
        　　for line in iter(fp.readline, ‘‘):
            　　process_line(line)

Iterator Protocol - Python 描述符協議