01-iterators-and-iterables-review.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Iterators"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In Python, an [``Iterator``][Iterator] is an instance of any class that defines the ``__iter__()`` and ``__next__()`` (``next()`` in Python 2) magic methods.\n",
    "\n",
    "``iter(iterator)`` is the same as ``iterator.__iter__()``, and should always return back ``iterator``, to indicate that the object is an iterator for itself.\n",
    "\n",
    "``next(iterator)`` is the same as ``iterator.__next__()``, and ``value = next(iterator, default)`` is the same as\n",
    "\n",
    "```python\n",
    "try:\n",
    "    value = iterator.__next__()\n",
    "except StopIteration:\n",
    "    value = default\n",
    "```\n",
    "\n",
    "``__next__()`` is a method that computes and returns the next element of the iterator. When no more elements are remaining, it must raise ``StopIteration``. Thus, ``__next__()`` mutates the internal state of the iterator, and by default and by convention, iterators are one-time use only. All rules for passing around mutable objects apply. If you pass an iterator to a function, then it might read some or all of the remaining elements, which will not be seen by the next function that tries to read from the iterator.\n",
    "\n",
    "[Iterator]: <https://docs.python.org/3.6/library/collections.abc.html#collections.abc.Iterator> \"Iterator\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Example iterator.\n",
    "\n",
    "import collections\n",
    "\n",
    "\n",
    "class RangeIterator(collections.Iterator):\n",
    "    \"\"\"Naive implementation of builtins.range() iterator.\"\"\"\n",
    "    def __init__(self, stop):\n",
    "        if not isinstance(stop, int):\n",
    "            raise TypeError('stop must be an int')\n",
    "        if stop < 0:\n",
    "            raise ValueError('stop must be >= 0')\n",
    "        super().__init__()\n",
    "        self.stop = stop\n",
    "        self.next_item = 0 if (stop > 0) else StopIteration()\n",
    "        \n",
    "    def __repr__(self):\n",
    "        return f\"<{self.__class__.__name__}({self.stop!r}): next_item={self.next_item!r}>\"\n",
    "    \n",
    "    # __iter__ is already defined in `collections.Iterator` as\n",
    "    #\n",
    "    # def __iter__(self):\n",
    "    #     return self\n",
    "    \n",
    "    def __next__(self):\n",
    "        item = self.next_item\n",
    "        if isinstance(item, StopIteration):\n",
    "            raise StopIteration\n",
    "        self.next_item += 1\n",
    "        if self.next_item >= self.stop:\n",
    "            self.next_item = StopIteration()\n",
    "        return item"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<RangeIterator(2): next_item=0>"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "range_iterator = RangeIterator(2)\n",
    "range_iterator"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(<RangeIterator(2): next_item=0>, True)"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "iter(range_iterator), iter(range_iterator) is range_iterator"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(0, <RangeIterator(2): next_item=1>)"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(range_iterator), range_iterator"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(1, <RangeIterator(2): next_item=StopIteration()>)"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(range_iterator), range_iterator"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Traceback (most recent call last):\n",
      "  File \"<ipython-input-6-e6a2b2ed7925>\", line 4, in <module>\n",
      "    next(range_iterator)\n",
      "  File \"<ipython-input-1-ea2a2b1cf1f9>\", line 28, in __next__\n",
      "    raise StopIteration\n",
      "StopIteration\n"
     ]
    }
   ],
   "source": [
    "import traceback\n",
    "\n",
    "try:\n",
    "    next(range_iterator)\n",
    "except StopIteration:\n",
    "    traceback.print_exc()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(range_iterator, 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Iterables"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In Python, an [``Iterable``][Iterable] is an instance of any class that defines the ``__iter__()`` magic method. ``Iterator`` is a subclass of ``Iterable``.\n",
    "\n",
    "``iter(iterable)`` is the same as ``iterable.__iter__()``, and should always return an iterator for the iterable. This iterator can then be iterated over, in order to retrieve the elements of the iterable.\n",
    "\n",
    "Iterables (including all iterators) can be one-time use only, but they can also be reusable. When they are reusable, ``__iter__()`` will return a brand-new iterator that starts at the first item, and advancing the iterator will have no effect on the original iterable.\n",
    "\n",
    "[Iterable]: <https://docs.python.org/3.6/library/collections.abc.html#collections.abc.Iterable> \"Iterable\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Example iterable.\n",
    "\n",
    "import collections\n",
    "\n",
    "\n",
    "class RangeIterable(collections.Iterable):\n",
    "    \"\"\"Naive implementation of an builtins.range() iterable.\"\"\"\n",
    "    def __init__(self, stop):\n",
    "        super().__init__()\n",
    "        self.stop = stop\n",
    "        \n",
    "    def __repr__(self):\n",
    "        return f\"{self.__class__.__name__}({self.stop!r})\"\n",
    "    \n",
    "    def __iter__(self):\n",
    "        return RangeIterator(stop=self.stop)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "RangeIterable(2)"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "range_iterable = RangeIterable(2)\n",
    "range_iterable"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Traceback (most recent call last):\n",
      "  File \"<ipython-input-10-4644b570951a>\", line 4, in <module>\n",
      "    next(range_iterable)\n",
      "TypeError: 'RangeIterable' object is not an iterator\n"
     ]
    }
   ],
   "source": [
    "import traceback\n",
    "\n",
    "try:\n",
    "    next(range_iterable)\n",
    "except TypeError:\n",
    "    traceback.print_exc()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<RangeIterator(2): next_item=0>"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "iter(range_iterable)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "iter(range_iterable) is range_iterable"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "iter(range_iterable) is iter(range_iterable)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(iter(range_iterable))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Syntax for iteration: for-loops"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Python code can, and often does, manually iterate through iterators and iterables, via ``iter()`` and ``next()``. However, the Python language syntax has built-in support for automatically iterating over the elements of an iterable. The for-loop, which is common in most modern programming languages (though Python's for-loop is really a for-each loop), runs through an iterable one element at a time, making use of the current element in a block of code.\n",
    "\n",
    "```python\n",
    "for item in iterable:\n",
    "    # do something with item, such as\n",
    "    print(item)\n",
    "```\n",
    "\n",
    "If we ignore the semantics of ``continue``, ``break``, and ``else``, a for-loop generally looks like\n",
    "\n",
    "```python\n",
    "for TARGET in ITER:\n",
    "    BLOCK\n",
    "```\n",
    "\n",
    "and is syntactic sugar for something like\n",
    "\n",
    "```python\n",
    "iterable = (ITER)\n",
    "iterator = iter(iterable)\n",
    "running = True\n",
    "while running:\n",
    "    try:\n",
    "        TARGET = next(iterator)\n",
    "    except StopIteration:\n",
    "        running = False\n",
    "    else:\n",
    "        BLOCK\n",
    "```\n",
    "\n",
    "Note that the for-loop construct has special handling for ``StopIteration``. The for-loop construct is intimately aware of the iterator protocol, and knows to catch ``StopIteration`` and interpret it as the end of iteration."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0\n",
      "1\n"
     ]
    }
   ],
   "source": [
    "for item in RangeIterable(2):\n",
    "    print(item)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "def manual_simplified_for_loop(iterable, function):\n",
    "    iterator = iter(iterable)\n",
    "    running = True\n",
    "    while running:\n",
    "        try:\n",
    "            item = next(iterator)\n",
    "        except StopIteration:\n",
    "            running = False\n",
    "        else:\n",
    "            function(item)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0\n",
      "1\n"
     ]
    }
   ],
   "source": [
    "manual_simplified_for_loop(RangeIterable(2), print)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Other uses of iterables"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Many functions accept iterables and then iterate over them, either manually or with for-loops."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[0, 1, 2, 3, 4]"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(RangeIterable(5))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1, 2, 3, 4]"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(filter(None, RangeIterable(5)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "# License"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "License: [Apache License, Version 2.0][Apache License]  \n",
    "[Jordan Moldow][], 2017\n",
    "\n",
    ">     Copyright 2017 Jordan Moldow\n",
    ">\n",
    ">     Licensed under the Apache License, Version 2.0 (the \"License\");\n",
    ">     you may not use this file except in compliance with the License.\n",
    ">     You may obtain a copy of the License at\n",
    ">\n",
    ">         http://www.apache.org/licenses/LICENSE-2.0\n",
    ">\n",
    ">     Unless required by applicable law or agreed to in writing, software\n",
    ">     distributed under the License is distributed on an \"AS IS\" BASIS,\n",
    ">     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
    ">     See the License for the specific language governing permissions and\n",
    ">     limitations under the License.\n",
    "\n",
    "[Jordan Moldow]: <https://github.com/jmoldow> \"Jordan Moldow\"\n",
    "[Apache License]: <http://www.apache.org/licenses/LICENSE-2.0> \"Apache License, Version 2.0\""
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}