|
| 1 | +# Iterables and iterators |
| 2 | + |
| 3 | +So far we have used for loops with many different kinds of things. |
| 4 | + |
| 5 | +```py |
| 6 | +>>> for name in ['theelous3', 'RubyPinch', 'go|dfish']: |
| 7 | +... print(name) |
| 8 | +... |
| 9 | +theelous3 |
| 10 | +RubyPinch |
| 11 | +go|dfish |
| 12 | +>>> for letter in 'abc': |
| 13 | +... print(letter) |
| 14 | +... |
| 15 | +a |
| 16 | +b |
| 17 | +c |
| 18 | +>>> |
| 19 | +``` |
| 20 | + |
| 21 | +For looping over something is one way to **iterate** over it. Some other |
| 22 | +things also iterate, for example, `' '.join(['a', 'b', 'c'])` iterates |
| 23 | +over the list `['a', 'b', 'c']`. If we can for loop over something, then |
| 24 | +that something is **iterable**. For example, strings and lists are |
| 25 | +iterable, but integers and floats are not. |
| 26 | + |
| 27 | +```py |
| 28 | +>>> for thing in 123: |
| 29 | +... print(thing) |
| 30 | +... |
| 31 | +Traceback (most recent call last): |
| 32 | + File "<stdin>", line 1, in <module> |
| 33 | +TypeError: 'int' object is not iterable |
| 34 | +>>> |
| 35 | +``` |
| 36 | + |
| 37 | +## Iterators |
| 38 | + |
| 39 | +Lists and strings don't change when we iterate over them. |
| 40 | + |
| 41 | +```py |
| 42 | +>>> word = 'hi' |
| 43 | +>>> for character in word: |
| 44 | +... print(character) |
| 45 | +... |
| 46 | +h |
| 47 | +i |
| 48 | +>>> word |
| 49 | +'hello' |
| 50 | +>>> |
| 51 | +``` |
| 52 | + |
| 53 | +We can also iterate over [files](../basics/files.md), but they change |
| 54 | +when we do that. They remember their position, so if we iterate over |
| 55 | +them twice we get the content once only. |
| 56 | + |
| 57 | +```py |
| 58 | +>>> with open('test.txt', 'w') as f: |
| 59 | +... print("one", file=f) |
| 60 | +... print("two", file=f) |
| 61 | +... |
| 62 | +>>> a = [] |
| 63 | +>>> b = [] |
| 64 | +>>> with open('test.txt', 'r') as f: |
| 65 | +... for line in f: |
| 66 | +... a.append(line) |
| 67 | +... for line in f: |
| 68 | +... b.append(line) |
| 69 | +... |
| 70 | +>>> a |
| 71 | +['one\n', 'two\n'] |
| 72 | +>>> b |
| 73 | +[] |
| 74 | +>>> |
| 75 | +``` |
| 76 | + |
| 77 | +We have also used [enumerate](../basics/trey-hunner-zip-and-enumerate.md) |
| 78 | +before, and it actually remembers its position also: |
| 79 | + |
| 80 | +```py |
| 81 | +>>> e = enumerate('hello') |
| 82 | +>>> for pair in e: |
| 83 | +... print(pair) |
| 84 | +... |
| 85 | +(0, 'h') |
| 86 | +(1, 'e') |
| 87 | +(2, 'l') |
| 88 | +(3, 'l') |
| 89 | +(4, 'o') |
| 90 | +>>> for pair in e: |
| 91 | +... print(pair) |
| 92 | +... |
| 93 | +>>> |
| 94 | +``` |
| 95 | + |
| 96 | +Iterators are **iterables that remember their position**. For example, |
| 97 | +`open('test.txt', 'r')` and `enumerate('hello')` are iterators. |
| 98 | +Iterators can only be used once, so we need to create a new iterator if |
| 99 | +we want to do another for loop. |
| 100 | + |
| 101 | +Here's a picture that hopefully explains this better: |
| 102 | + |
| 103 | + |
| 104 | + |
| 105 | +## Iterating manually |
| 106 | + |
| 107 | +Iterators have a magic method called `__next__`, and there's a built-in |
| 108 | +function called `next()` for calling that. Calling `next()` on an |
| 109 | +iterator gets the next value and moves it forward. Like this: |
| 110 | + |
| 111 | +```py |
| 112 | +>>> e = enumerate('abc') |
| 113 | +>>> e.__next__() |
| 114 | +(0, 'a') |
| 115 | +>>> e.__next__() |
| 116 | +(1, 'b') |
| 117 | +>>> e.__next__() |
| 118 | +(2, 'c') |
| 119 | +>>> |
| 120 | +``` |
| 121 | + |
| 122 | +There's also a built-in `next()` function that does the same thing: |
| 123 | + |
| 124 | +```py |
| 125 | +>>> e = enumerate('abc') |
| 126 | +>>> next(e) |
| 127 | +(0, 'a') |
| 128 | +>>> next(e) |
| 129 | +(1, 'b') |
| 130 | +>>> next(e) |
| 131 | +(2, 'c') |
| 132 | +>>> |
| 133 | +``` |
| 134 | + |
| 135 | +Here `e` remembers its position, and every time we call `next(e)` it |
| 136 | +gives us the next element and moves forward. When it has no more values |
| 137 | +to give us, calling `next(e)` raises a StopIteration: |
| 138 | + |
| 139 | +```py |
| 140 | +>>> next(e) |
| 141 | +Traceback (most recent call last): |
| 142 | + File "<stdin>", line 1, in <module> |
| 143 | +StopIteration |
| 144 | +>>> |
| 145 | +``` |
| 146 | + |
| 147 | +There is usually not a good way to check if the iterator is at the end, |
| 148 | +and it's best to just try to get an value from it and catch |
| 149 | +StopIteration. |
| 150 | + |
| 151 | +This is actually what for looping over an iterator does. For example, |
| 152 | +this code... |
| 153 | + |
| 154 | +```py |
| 155 | +for pair in enumerate('hello'): |
| 156 | + print(pair) |
| 157 | +``` |
| 158 | + |
| 159 | +...does roughly the same thing as this code: |
| 160 | + |
| 161 | +```py |
| 162 | +e = enumerate('hello') |
| 163 | +while True: |
| 164 | + try: |
| 165 | + pair = next(e) |
| 166 | + except StopIteration: |
| 167 | + # it's at the end, time to stop |
| 168 | + break |
| 169 | + # we got a pair |
| 170 | + print(pair) |
| 171 | +``` |
| 172 | + |
| 173 | +The for loop version is much simpler to write and I wrote the while loop |
| 174 | +version just to explain what the for loop does. |
| 175 | + |
| 176 | +## Converting to iterators |
| 177 | + |
| 178 | +Now we know what iterating over an iterator does. But how about |
| 179 | +iterating over a list or a string? They are not iterators, so we can't |
| 180 | +call `next()` on them: |
| 181 | + |
| 182 | +```py |
| 183 | +>>> next('abc') |
| 184 | +Traceback (most recent call last): |
| 185 | + File "<stdin>", line 1, in <module> |
| 186 | +TypeError: 'str' object is not an iterator |
| 187 | +>>> |
| 188 | +``` |
| 189 | + |
| 190 | +There's a built-in function called `iter()` that converts anything |
| 191 | +iterable to an iterator. |
| 192 | + |
| 193 | +```py |
| 194 | +>>> i = iter('abc') |
| 195 | +>>> i |
| 196 | +<str_iterator object at 0x7f987b860160> |
| 197 | +>>> next(i) |
| 198 | +'a' |
| 199 | +>>> next(i) |
| 200 | +'b' |
| 201 | +>>> next(i) |
| 202 | +'c' |
| 203 | +>>> next(i) |
| 204 | +Traceback (most recent call last): |
| 205 | + File "<stdin>", line 1, in <module> |
| 206 | +StopIteration |
| 207 | +>>> |
| 208 | +``` |
| 209 | + |
| 210 | +Calling `iter()` on anything non-iterable gives us an error. |
| 211 | + |
| 212 | +```py |
| 213 | +>>> iter(123) |
| 214 | +Traceback (most recent call last): |
| 215 | + File "<stdin>", line 1, in <module> |
| 216 | +TypeError: 'int' object is not iterable |
| 217 | +>>> |
| 218 | +``` |
| 219 | + |
| 220 | +If we try to convert an iterator to an iterator using `iter()` we just |
| 221 | +get back the same iterator. |
| 222 | + |
| 223 | +```py |
| 224 | +>>> e = enumerate('abc') |
| 225 | +>>> iter(e) is e |
| 226 | +True |
| 227 | +>>> |
| 228 | +``` |
| 229 | + |
| 230 | +So code like this... |
| 231 | + |
| 232 | +```py |
| 233 | +for thing in stuff: |
| 234 | + print(thing) |
| 235 | +``` |
| 236 | + |
| 237 | +...works roughly like this: |
| 238 | + |
| 239 | +```py |
| 240 | +iterator = iter(stuff) |
| 241 | +while True: |
| 242 | + try: |
| 243 | + thing = next(iterator) |
| 244 | + except StopIteration: |
| 245 | + break |
| 246 | + print(thing) |
| 247 | +``` |
| 248 | + |
| 249 | +## Custom iterables |
| 250 | + |
| 251 | +Implementing a custom iterator is easy. All we need to do is to define a |
| 252 | +`__next__` method that gets the next element, and an `__iter__` method |
| 253 | +that returns the iterator itself. For example, here's an iterator that |
| 254 | +behaves like `iter([1, 2, 3])`: |
| 255 | + |
| 256 | + |
| 257 | + |
| 258 | +*** |
| 259 | + |
| 260 | +You may use this tutorial freely at your own risk. See |
| 261 | +[LICENSE](../LICENSE). |
| 262 | + |
| 263 | +[Previous](../basics/classes.md) | [Next](../README.md) | |
| 264 | +[List of contents](../README.md#advanced) |
0 commit comments