itertools_module/notebook.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# The Itertools Module"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```itertools``` module contains a number of additional iterators which supplement those found in ```builtins```."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Categorize_Identifiers Module"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook will use the following functions ```dir2```, ```variables``` and ```view``` in the custom module ```categorize_identifiers``` which is found in the same directory as this notebook file. ```dir2``` is a variant of ```dir``` that groups identifiers into a ```dict``` under categories and ```variables``` is an IPython based a variable inspector. ```view``` is used to view a ```Collection``` in more detail:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from categorize_identifiers import dir2, variables, view"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Iterable and Iterator"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A ```Collection``` is an iterable. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "archive = (1, True, 3.14, 'hello', 'hello', 'bye')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the directory of the iterable is examined, it has the ```__len__```, ```__repr__``` and ```__iter__``` datamodel methods available to an iterable:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'method': ['count', 'index'],\n",
      " 'datamodel_method': ['__add__',\n",
      "                      '__class_getitem__',\n",
      "                      '__contains__',\n",
      "                      '__getitem__',\n",
      "                      '__getnewargs__',\n",
      "                      '__iter__',\n",
      "                      '__len__',\n",
      "                      '__mul__',\n",
      "                      '__rmul__']}\n"
     ]
    }
   ],
   "source": [
    "dir2(archive, object, unique_only=True)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This means the length function ```len``` can be used:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "6"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "len(archive)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And all 6 items are displayed simultaneously:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(1, True, 3.14, 'hello', 'hello', 'bye')"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "archive"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The iterator function ```iter``` can be used to create an iterator instance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = iter(archive)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<tuple_iterator at 0x2b4ca6b1ea0>"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The iterator instance has its own datamodel methods. Notice the omission of the datamodel method ```__len__```. This datamodel method is not defined because an iterator displays only one value at a time and often has no concept of length:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'datamodel_method': ['__iter__',\n",
      "                      '__length_hint__',\n",
      "                      '__next__',\n",
      "                      '__setstate__']}\n"
     ]
    }
   ],
   "source": [
    "dir2(forward, object, unique_only=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Because this example is constructed from a fixed length ```tuple``` it has the ```__length_hint__``` datamodel method. This datamodel method isn't normally used directly, instead the ```length_hint``` function is used from the operator module:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "from operator import length_hint"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "6"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "length_hint(forward)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```next``` function can be used to read the next value and discard the previous value:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "5"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "length_hint(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "4"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "length_hint(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3.14"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "length_hint(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'hello'"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "length_hint(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'hello'"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "length_hint(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'bye'"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "length_hint(forward)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that using ```length_hint``` now returns ```0```. This means if ```next``` is used there will be a ```StopIterator``` error:\n",
    "\n",
    "```\n",
    "next(forward)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively if the iterator is cast into a ```tuple```, all the remaining elements in it are consumed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = iter(archive)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "6"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "length_hint(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "5"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "length_hint(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(True, 3.14, 'hello', 'hello', 'bye')"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(forward)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Python builtins"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before examining the ```itertools``` module, an overview of the iterator classes in ```builtins``` will be examined, these are the most commonly used iterator classes and the additional iterators in ```itertools``` typically supplement these."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Zip"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```zip``` class can be used to zip two or more collections together. Its initialisation signature can be viewed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mzip\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mself\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m*\u001b[0m\u001b[0margs\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m     \n",
       "zip(*iterables, strict=False) --> Yield tuples until an input is exhausted.\n",
       "\n",
       "   >>> list(zip('abcdefg', range(3), range(4)))\n",
       "   [('a', 0, 0), ('b', 1, 1), ('c', 2, 2)]\n",
       "\n",
       "The zip object yields n-length tuples, where n is the number of iterables\n",
       "passed as positional arguments to zip().  The i-th element in every tuple\n",
       "comes from the i-th iterable argument to zip().  This continues until the\n",
       "shortest argument is exhausted.\n",
       "\n",
       "If strict is true and one of the arguments is exhausted before the others,\n",
       "raise a ValueError.\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "zip?"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following keys and values can be zipped:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [],
   "source": [
    "keys = ('r', 'g', 'b')\n",
    "values = ('#FF0000', '#00FF00', '#0000FF')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = zip(keys, values)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<zip at 0x2b4ca788fc0>"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This ```zip``` instance is an iterator as it displays 1 zipped value at a time, which in this case is a 2 element ```tuple``` instance containing the ```key``` in keys and the ```value``` in values at the respective index. Each time next is called, the next ```tuple``` of ```key```, ```value``` pairs is shown:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('r', '#FF0000')"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('g', '#00FF00')"
      ]
     },
     "execution_count": 33,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('b', '#0000FF')"
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When two ```Collections``` are zipped, they can be cast into a ```tuple```, ```list```, ```set``` or ```dict``` and doing so consumes all the values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = zip(keys, values)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(('r', '#FF0000'), ('g', '#00FF00'), ('b', '#0000FF'))"
      ]
     },
     "execution_count": 36,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = zip(keys, values)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'r': '#FF0000', 'g': '#00FF00', 'b': '#0000FF'}"
      ]
     },
     "execution_count": 38,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "dict(forward)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If ```zip``` is used on two ```Collection``` instances of differing lengths, it stops zipping, once the shortest length ```Collection``` has been exhausted. ```names``` for example has an additional value ```'yellow'``` which is ignored:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [],
   "source": [
    "names = ('red', 'green', 'blue', 'yellow')\n",
    "keys = ('r', 'g', 'b')\n",
    "values = ('#FF0000', '#00FF00', '#0000FF')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = zip(names, keys, values)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(('red', 'r', '#FF0000'), ('green', 'g', '#00FF00'), ('blue', 'b', '#0000FF'))"
      ]
     },
     "execution_count": 41,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(forward)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Earlier a ```tuple``` and a ```tuple_iterator``` were examined. The ```range``` class is iterable like a tuple but often gets confused with an iterator because its common usage in ```for``` loops. It can be used to obtain an iterable of a numeric sequence. Its initialisation signature can be viewed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mrange\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mself\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m*\u001b[0m\u001b[0margs\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m     \n",
       "range(stop) -> range object\n",
       "range(start, stop[, step]) -> range object\n",
       "\n",
       "Return an object that produces a sequence of integers from start (inclusive)\n",
       "to stop (exclusive) by step.  range(i, j) produces i, i+1, i+2, ..., j-1.\n",
       "start defaults to 0, and stop is omitted!  range(4) produces 0, 1, 2, 3.\n",
       "These are exactly the valid indices for a list of 4 elements.\n",
       "When step is given, it specifies the increment (or decrement).\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "range?"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Its input arguments are of the type int:\n",
    "\n",
    "* It can take in a single ```stop``` input argument. \n",
    "\n",
    "* Alternatively it can take a ```start``` and ```stop``` input argument.\n",
    "\n",
    "* Alternatively it can take a ```start```, ```stop``` and ```step``` input argument."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The input arguments are followed by a ```/``` indicating they are to be provided positionally only. If ```start``` is not supplied it is assumed to be ```0``` and if ```step``` is not supplied it is assumed to be ```1```. Recall Python uses zero-order indexing and is therefore inclusive of the lower bound and exclusive of the upper bound:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = range(3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "range(0, 3)"
      ]
     },
     "execution_count": 44,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nums"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The datamodel identifiers of the ```range``` class include ```__len__``` and ```__iter__```. The ```range``` class does not include ```__next__``` because it is not an iterator: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'attribute': ['start', 'step', 'stop'],\n",
      " 'method': ['count', 'index'],\n",
      " 'datamodel_method': ['__bool__',\n",
      "                      '__contains__',\n",
      "                      '__getitem__',\n",
      "                      '__iter__',\n",
      "                      '__len__',\n",
      "                      '__reversed__']}\n"
     ]
    }
   ],
   "source": [
    "dir2(range, object, unique_only=True)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The range class always has a ```stop``` value, and therefore is always an iterable of finite length. It has a size that can readily be computed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 46,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nums.start"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 47,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nums.stop"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 48,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nums.step"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 49,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 49,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "len(nums)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```range``` instance is iterable and can be cast into an iterator using the ```iter``` function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 50,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = iter(nums)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 51,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<range_iterator at 0x2b4ca7303d0>"
      ]
     },
     "execution_count": 51,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```range_iterator``` instance is an iterator. Its identifiers can be examined using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 52,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'datamodel_method': ['__iter__',\n",
      "                      '__length_hint__',\n",
      "                      '__next__',\n",
      "                      '__setstate__']}\n"
     ]
    }
   ],
   "source": [
    "dir2(forward, object, unique_only=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 53,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 53,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "length_hint(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 54,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 54,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 55,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 55,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "length_hint(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 56,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(1, 2)"
      ]
     },
     "execution_count": 56,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A for loop is often used with a ```range``` instance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 57,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0\n",
      "1\n",
      "2\n"
     ]
    }
   ],
   "source": [
    "for num in range(3):\n",
    "    print(num)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Under the hood, this uses a ```range_iterator``` instance. \n",
    "\n",
    "It is worthwhile exploring the mechanics of the ```for``` loop using an infinite ```while``` loop: \n",
    "\n",
    "* An iterator is instantiated.\n",
    "* ```next``` is called on this iterator within a nested ```try``` code block and in this case the ```int``` value of the iterator is printed.\n",
    "* There is an associated ```except``` block which is used to ```break``` out the ```while``` loop when a ```StopIteration``` error is encountered."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 58,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0\n",
      "1\n",
      "2\n"
     ]
    }
   ],
   "source": [
    "forward = iter(range(3))\n",
    "while True:\n",
    "    try:\n",
    "        print(next(forward))\n",
    "    except StopIteration:\n",
    "        break"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This means all for ```loops``` are under the hood ```while``` loops which use nested ```try``` and ```except``` ```StopIteration``` code blocks. The former contains the code that would be placed in the ```for``` loop and the latter is designed for breaking out the ```while``` loop."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Map"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```map``` class can be used to map a function call to a sequence. Its initialisation signature can be viewed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 59,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mmap\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mself\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m*\u001b[0m\u001b[0margs\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m     \n",
       "map(func, *iterables) --> map object\n",
       "\n",
       "Make an iterator that computes the function using arguments from\n",
       "each of the iterables.  Stops when the shortest iterable is exhausted.\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "map?"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example the ```lambda``` expression:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 60,
   "metadata": {},
   "outputs": [],
   "source": [
    "squared = lambda num: num ** 2"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Can be mapped to the following ```tuple``` sequence:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 61,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = (0, 1, 2, 3, 4)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An iterator that maps this function to this sequence can be created using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 62,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = map(squared, nums)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 63,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<map at 0x2b4ca793970>"
      ]
     },
     "execution_count": 63,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The map instances identifiers can be examined. It is an iterator that once again has the datamodel identifier ```__next__```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 64,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'datamodel_method': ['__iter__', '__next__']}\n"
     ]
    }
   ],
   "source": [
    "dir2(forward, object, unique_only=True)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When ```next``` is called, the next value in ```nums``` becomes ```num``` and is used as the input argument in the ```squared``` function call:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 65,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 65,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The remaining function calls in the iterator can be consumed by casting to a ```tuple``` or ```list```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 66,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1, 4, 9, 16]"
      ]
     },
     "execution_count": 66,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can be done on a single line:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 67,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[0, 1, 4, 9, 16]"
      ]
     },
     "execution_count": 67,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(map(squared, nums))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Many of the use cases for ```map``` can also be carried out using a ```list``` comprehension:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 68,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[0, 1, 4, 9, 16]"
      ]
     },
     "execution_count": 68,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "[num ** 2 for num in (0, 1, 2, 3, 4)]"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Filter"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```filter``` class can be used to filter values from a sequence using a filter function call to a sequence. Its initialisation signature can be viewed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 69,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mfilter\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mself\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m*\u001b[0m\u001b[0margs\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m     \n",
       "filter(function or None, iterable) --> filter object\n",
       "\n",
       "Return an iterator yielding those items of iterable for which function(item)\n",
       "is true. If function is None, return the items that are true.\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "filter?"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example the ```lambda``` expression:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 70,
   "metadata": {},
   "outputs": [],
   "source": [
    "positive_filter = lambda num: num > 0"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Can be mapped to the following sequence:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 71,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = (-2, -1, 0, 1, 2)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 72,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = filter(positive_filter, nums)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This filter instances identifiers can be examined:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 73,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'datamodel_method': ['__iter__', '__next__']}\n"
     ]
    }
   ],
   "source": [
    "dir2(forward, object, unique_only=True)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once again it is an iterator and has the datamodel identifier ```__next__```. When ```next``` is called, the value is the next value in the sequence nums where the ```positive_filter``` function returns ```True```. Alternatively all the filtered values given by the iterator can be consumed by casting to a ```tuple``` or ```list```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 74,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(1, 2)"
      ]
     },
     "execution_count": 74,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(filter(positive_filter, nums))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Itertools Module"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```itertools``` module can be imported using:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 75,
   "metadata": {},
   "outputs": [],
   "source": [
    "import itertools"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The identifiers from the ```itertools``` module can be examined. They contains a number of useful iterator classes which supplement those from ```builtins```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 76,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'method': ['tee'],\n",
      " 'lower_class': ['accumulate',\n",
      "                 'batched',\n",
      "                 'chain',\n",
      "                 'combinations',\n",
      "                 'combinations_with_replacement',\n",
      "                 'compress',\n",
      "                 'count',\n",
      "                 'cycle',\n",
      "                 'dropwhile',\n",
      "                 'filterfalse',\n",
      "                 'groupby',\n",
      "                 'islice',\n",
      "                 'pairwise',\n",
      "                 'permutations',\n",
      "                 'product',\n",
      "                 'repeat',\n",
      "                 'starmap',\n",
      "                 'takewhile',\n",
      "                 'zip_longest'],\n",
      " 'datamodel_attribute': ['__doc__', '__name__', '__package__', '__spec__'],\n",
      " 'datamodel_method': ['__loader__'],\n",
      " 'internal_method': ['_grouper', '_tee', '_tee_dataobject']}\n"
     ]
    }
   ],
   "source": [
    "dir2(itertools)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A brief overview can be obtained using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 77,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mType:\u001b[0m        module\n",
       "\u001b[1;31mString form:\u001b[0m <module 'itertools' (built-in)>\n",
       "\u001b[1;31mDocstring:\u001b[0m  \n",
       "Functional tools for creating and using iterators.\n",
       "\n",
       "Infinite iterators:\n",
       "count(start=0, step=1) --> start, start+step, start+2*step, ...\n",
       "cycle(p) --> p0, p1, ... plast, p0, p1, ...\n",
       "repeat(elem [,n]) --> elem, elem, elem, ... endlessly or up to n times\n",
       "\n",
       "Iterators terminating on the shortest input sequence:\n",
       "accumulate(p[, func]) --> p0, p0+p1, p0+p1+p2\n",
       "batched(p, n) --> [p0, p1, ..., p_n-1], [p_n, p_n+1, ..., p_2n-1], ...\n",
       "chain(p, q, ...) --> p0, p1, ... plast, q0, q1, ...\n",
       "chain.from_iterable([p, q, ...]) --> p0, p1, ... plast, q0, q1, ...\n",
       "compress(data, selectors) --> (d[0] if s[0]), (d[1] if s[1]), ...\n",
       "dropwhile(pred, seq) --> seq[n], seq[n+1], starting when pred fails\n",
       "groupby(iterable[, keyfunc]) --> sub-iterators grouped by value of keyfunc(v)\n",
       "filterfalse(pred, seq) --> elements of seq where pred(elem) is False\n",
       "islice(seq, [start,] stop [, step]) --> elements from\n",
       "       seq[start:stop:step]\n",
       "pairwise(s) --> (s[0],s[1]), (s[1],s[2]), (s[2], s[3]), ...\n",
       "starmap(fun, seq) --> fun(*seq[0]), fun(*seq[1]), ...\n",
       "tee(it, n=2) --> (it1, it2 , ... itn) splits one iterator into n\n",
       "takewhile(pred, seq) --> seq[0], seq[1], until pred fails\n",
       "zip_longest(p, q, ...) --> (p[0], q[0]), (p[1], q[1]), ...\n",
       "\n",
       "Combinatoric generators:\n",
       "product(p, q, ... [repeat=1]) --> cartesian product\n",
       "permutations(p[, r])\n",
       "combinations(p, r)\n",
       "combinations_with_replacement(p, r)"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "itertools?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More details can be obtained using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 78,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on built-in module itertools:\n",
      "\n",
      "NAME\n",
      "    itertools - Functional tools for creating and using iterators.\n",
      "\n",
      "DESCRIPTION\n",
      "    Infinite iterators:\n",
      "    count(start=0, step=1) --> start, start+step, start+2*step, ...\n",
      "    cycle(p) --> p0, p1, ... plast, p0, p1, ...\n",
      "    repeat(elem [,n]) --> elem, elem, elem, ... endlessly or up to n times\n",
      "\n",
      "    Iterators terminating on the shortest input sequence:\n",
      "    accumulate(p[, func]) --> p0, p0+p1, p0+p1+p2\n",
      "    batched(p, n) --> [p0, p1, ..., p_n-1], [p_n, p_n+1, ..., p_2n-1], ...\n",
      "    chain(p, q, ...) --> p0, p1, ... plast, q0, q1, ...\n",
      "    chain.from_iterable([p, q, ...]) --> p0, p1, ... plast, q0, q1, ...\n",
      "    compress(data, selectors) --> (d[0] if s[0]), (d[1] if s[1]), ...\n",
      "    dropwhile(pred, seq) --> seq[n], seq[n+1], starting when pred fails\n",
      "    groupby(iterable[, keyfunc]) --> sub-iterators grouped by value of keyfunc(v)\n",
      "    filterfalse(pred, seq) --> elements of seq where pred(elem) is False\n",
      "    islice(seq, [start,] stop [, step]) --> elements from\n",
      "           seq[start:stop:step]\n",
      "    pairwise(s) --> (s[0],s[1]), (s[1],s[2]), (s[2], s[3]), ...\n",
      "    starmap(fun, seq) --> fun(*seq[0]), fun(*seq[1]), ...\n",
      "    tee(it, n=2) --> (it1, it2 , ... itn) splits one iterator into n\n",
      "    takewhile(pred, seq) --> seq[0], seq[1], until pred fails\n",
      "    zip_longest(p, q, ...) --> (p[0], q[0]), (p[1], q[1]), ...\n",
      "\n",
      "    Combinatoric generators:\n",
      "    product(p, q, ... [repeat=1]) --> cartesian product\n",
      "    permutations(p[, r])\n",
      "    combinations(p, r)\n",
      "    combinations_with_replacement(p, r)\n",
      "\n",
      "CLASSES\n",
      "    builtins.object\n",
      "        accumulate\n",
      "        batched\n",
      "        chain\n",
      "        combinations\n",
      "        combinations_with_replacement\n",
      "        compress\n",
      "        count\n",
      "        cycle\n",
      "        dropwhile\n",
      "        filterfalse\n",
      "        groupby\n",
      "        islice\n",
      "        pairwise\n",
      "        permutations\n",
      "        product\n",
      "        repeat\n",
      "        starmap\n",
      "        takewhile\n",
      "        zip_longest\n",
      "\n",
      "    class accumulate(builtins.object)\n",
      "     |  accumulate(iterable, func=None, *, initial=None)\n",
      "     |\n",
      "     |  Return series of accumulated sums (or other binary function results).\n",
      "     |\n",
      "     |  Methods defined here:\n",
      "     |\n",
      "     |  __getattribute__(self, name, /)\n",
      "     |      Return getattr(self, name).\n",
      "     |\n",
      "     |  __iter__(self, /)\n",
      "     |      Implement iter(self).\n",
      "     |\n",
      "     |  __next__(self, /)\n",
      "     |      Implement next(self).\n",
      "     |\n",
      "     |  __reduce__(...)\n",
      "     |      Return state information for pickling.\n",
      "     |\n",
      "     |  __setstate__(...)\n",
      "     |      Set state information for unpickling.\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Static methods defined here:\n",
      "     |\n",
      "     |  __new__(*args, **kwargs) from builtins.type\n",
      "     |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n",
      "    class batched(builtins.object)\n",
      "     |  batched(iterable, n)\n",
      "     |\n",
      "     |  Batch data into tuples of length n. The last batch may be shorter than n.\n",
      "     |\n",
      "     |  Loops over the input iterable and accumulates data into tuples\n",
      "     |  up to size n.  The input is consumed lazily, just enough to\n",
      "     |  fill a batch.  The result is yielded as soon as a batch is full\n",
      "     |  or when the input iterable is exhausted.\n",
      "     |\n",
      "     |      >>> for batch in batched('ABCDEFG', 3):\n",
      "     |      ...     print(batch)\n",
      "     |      ...\n",
      "     |      ('A', 'B', 'C')\n",
      "     |      ('D', 'E', 'F')\n",
      "     |      ('G',)\n",
      "     |\n",
      "     |  Methods defined here:\n",
      "     |\n",
      "     |  __getattribute__(self, name, /)\n",
      "     |      Return getattr(self, name).\n",
      "     |\n",
      "     |  __iter__(self, /)\n",
      "     |      Implement iter(self).\n",
      "     |\n",
      "     |  __next__(self, /)\n",
      "     |      Implement next(self).\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Static methods defined here:\n",
      "     |\n",
      "     |  __new__(*args, **kwargs) from builtins.type\n",
      "     |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n",
      "    class chain(builtins.object)\n",
      "     |  chain(*iterables) --> chain object\n",
      "     |\n",
      "     |  Return a chain object whose .__next__() method returns elements from the\n",
      "     |  first iterable until it is exhausted, then elements from the next\n",
      "     |  iterable, until all of the iterables are exhausted.\n",
      "     |\n",
      "     |  Methods defined here:\n",
      "     |\n",
      "     |  __getattribute__(self, name, /)\n",
      "     |      Return getattr(self, name).\n",
      "     |\n",
      "     |  __iter__(self, /)\n",
      "     |      Implement iter(self).\n",
      "     |\n",
      "     |  __next__(self, /)\n",
      "     |      Implement next(self).\n",
      "     |\n",
      "     |  __reduce__(...)\n",
      "     |      Return state information for pickling.\n",
      "     |\n",
      "     |  __setstate__(...)\n",
      "     |      Set state information for unpickling.\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Class methods defined here:\n",
      "     |\n",
      "     |  __class_getitem__(...) from builtins.type\n",
      "     |      See PEP 585\n",
      "     |\n",
      "     |  from_iterable(iterable, /) from builtins.type\n",
      "     |      Alternative chain() constructor taking a single iterable argument that evaluates lazily.\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Static methods defined here:\n",
      "     |\n",
      "     |  __new__(*args, **kwargs) from builtins.type\n",
      "     |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n",
      "    class combinations(builtins.object)\n",
      "     |  combinations(iterable, r)\n",
      "     |\n",
      "     |  Return successive r-length combinations of elements in the iterable.\n",
      "     |\n",
      "     |  combinations(range(4), 3) --> (0,1,2), (0,1,3), (0,2,3), (1,2,3)\n",
      "     |\n",
      "     |  Methods defined here:\n",
      "     |\n",
      "     |  __getattribute__(self, name, /)\n",
      "     |      Return getattr(self, name).\n",
      "     |\n",
      "     |  __iter__(self, /)\n",
      "     |      Implement iter(self).\n",
      "     |\n",
      "     |  __next__(self, /)\n",
      "     |      Implement next(self).\n",
      "     |\n",
      "     |  __reduce__(...)\n",
      "     |      Return state information for pickling.\n",
      "     |\n",
      "     |  __setstate__(...)\n",
      "     |      Set state information for unpickling.\n",
      "     |\n",
      "     |  __sizeof__(...)\n",
      "     |      Returns size in memory, in bytes.\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Static methods defined here:\n",
      "     |\n",
      "     |  __new__(*args, **kwargs) from builtins.type\n",
      "     |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n",
      "    class combinations_with_replacement(builtins.object)\n",
      "     |  combinations_with_replacement(iterable, r)\n",
      "     |\n",
      "     |  Return successive r-length combinations of elements in the iterable allowing individual elements to have successive repeats.\n",
      "     |\n",
      "     |  combinations_with_replacement('ABC', 2) --> ('A','A'), ('A','B'), ('A','C'), ('B','B'), ('B','C'), ('C','C')\n",
      "     |\n",
      "     |  Methods defined here:\n",
      "     |\n",
      "     |  __getattribute__(self, name, /)\n",
      "     |      Return getattr(self, name).\n",
      "     |\n",
      "     |  __iter__(self, /)\n",
      "     |      Implement iter(self).\n",
      "     |\n",
      "     |  __next__(self, /)\n",
      "     |      Implement next(self).\n",
      "     |\n",
      "     |  __reduce__(...)\n",
      "     |      Return state information for pickling.\n",
      "     |\n",
      "     |  __setstate__(...)\n",
      "     |      Set state information for unpickling.\n",
      "     |\n",
      "     |  __sizeof__(...)\n",
      "     |      Returns size in memory, in bytes.\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Static methods defined here:\n",
      "     |\n",
      "     |  __new__(*args, **kwargs) from builtins.type\n",
      "     |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n",
      "    class compress(builtins.object)\n",
      "     |  compress(data, selectors)\n",
      "     |\n",
      "     |  Return data elements corresponding to true selector elements.\n",
      "     |\n",
      "     |  Forms a shorter iterator from selected data elements using the selectors to\n",
      "     |  choose the data elements.\n",
      "     |\n",
      "     |  Methods defined here:\n",
      "     |\n",
      "     |  __getattribute__(self, name, /)\n",
      "     |      Return getattr(self, name).\n",
      "     |\n",
      "     |  __iter__(self, /)\n",
      "     |      Implement iter(self).\n",
      "     |\n",
      "     |  __next__(self, /)\n",
      "     |      Implement next(self).\n",
      "     |\n",
      "     |  __reduce__(...)\n",
      "     |      Return state information for pickling.\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Static methods defined here:\n",
      "     |\n",
      "     |  __new__(*args, **kwargs) from builtins.type\n",
      "     |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n",
      "    class count(builtins.object)\n",
      "     |  count(start=0, step=1)\n",
      "     |\n",
      "     |  Return a count object whose .__next__() method returns consecutive values.\n",
      "     |\n",
      "     |  Equivalent to:\n",
      "     |      def count(firstval=0, step=1):\n",
      "     |          x = firstval\n",
      "     |          while 1:\n",
      "     |              yield x\n",
      "     |              x += step\n",
      "     |\n",
      "     |  Methods defined here:\n",
      "     |\n",
      "     |  __getattribute__(self, name, /)\n",
      "     |      Return getattr(self, name).\n",
      "     |\n",
      "     |  __iter__(self, /)\n",
      "     |      Implement iter(self).\n",
      "     |\n",
      "     |  __next__(self, /)\n",
      "     |      Implement next(self).\n",
      "     |\n",
      "     |  __reduce__(...)\n",
      "     |      Return state information for pickling.\n",
      "     |\n",
      "     |  __repr__(self, /)\n",
      "     |      Return repr(self).\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Static methods defined here:\n",
      "     |\n",
      "     |  __new__(*args, **kwargs) from builtins.type\n",
      "     |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n",
      "    class cycle(builtins.object)\n",
      "     |  cycle(iterable, /)\n",
      "     |\n",
      "     |  Return elements from the iterable until it is exhausted. Then repeat the sequence indefinitely.\n",
      "     |\n",
      "     |  Methods defined here:\n",
      "     |\n",
      "     |  __getattribute__(self, name, /)\n",
      "     |      Return getattr(self, name).\n",
      "     |\n",
      "     |  __iter__(self, /)\n",
      "     |      Implement iter(self).\n",
      "     |\n",
      "     |  __next__(self, /)\n",
      "     |      Implement next(self).\n",
      "     |\n",
      "     |  __reduce__(...)\n",
      "     |      Return state information for pickling.\n",
      "     |\n",
      "     |  __setstate__(...)\n",
      "     |      Set state information for unpickling.\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Static methods defined here:\n",
      "     |\n",
      "     |  __new__(*args, **kwargs) from builtins.type\n",
      "     |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n",
      "    class dropwhile(builtins.object)\n",
      "     |  dropwhile(predicate, iterable, /)\n",
      "     |\n",
      "     |  Drop items from the iterable while predicate(item) is true.\n",
      "     |\n",
      "     |  Afterwards, return every element until the iterable is exhausted.\n",
      "     |\n",
      "     |  Methods defined here:\n",
      "     |\n",
      "     |  __getattribute__(self, name, /)\n",
      "     |      Return getattr(self, name).\n",
      "     |\n",
      "     |  __iter__(self, /)\n",
      "     |      Implement iter(self).\n",
      "     |\n",
      "     |  __next__(self, /)\n",
      "     |      Implement next(self).\n",
      "     |\n",
      "     |  __reduce__(...)\n",
      "     |      Return state information for pickling.\n",
      "     |\n",
      "     |  __setstate__(...)\n",
      "     |      Set state information for unpickling.\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Static methods defined here:\n",
      "     |\n",
      "     |  __new__(*args, **kwargs) from builtins.type\n",
      "     |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n",
      "    class filterfalse(builtins.object)\n",
      "     |  filterfalse(function, iterable, /)\n",
      "     |\n",
      "     |  Return those items of iterable for which function(item) is false.\n",
      "     |\n",
      "     |  If function is None, return the items that are false.\n",
      "     |\n",
      "     |  Methods defined here:\n",
      "     |\n",
      "     |  __getattribute__(self, name, /)\n",
      "     |      Return getattr(self, name).\n",
      "     |\n",
      "     |  __iter__(self, /)\n",
      "     |      Implement iter(self).\n",
      "     |\n",
      "     |  __next__(self, /)\n",
      "     |      Implement next(self).\n",
      "     |\n",
      "     |  __reduce__(...)\n",
      "     |      Return state information for pickling.\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Static methods defined here:\n",
      "     |\n",
      "     |  __new__(*args, **kwargs) from builtins.type\n",
      "     |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n",
      "    class groupby(builtins.object)\n",
      "     |  groupby(iterable, key=None)\n",
      "     |\n",
      "     |  make an iterator that returns consecutive keys and groups from the iterable\n",
      "     |\n",
      "     |  iterable\n",
      "     |    Elements to divide into groups according to the key function.\n",
      "     |  key\n",
      "     |    A function for computing the group category for each element.\n",
      "     |    If the key function is not specified or is None, the element itself\n",
      "     |    is used for grouping.\n",
      "     |\n",
      "     |  Methods defined here:\n",
      "     |\n",
      "     |  __getattribute__(self, name, /)\n",
      "     |      Return getattr(self, name).\n",
      "     |\n",
      "     |  __iter__(self, /)\n",
      "     |      Implement iter(self).\n",
      "     |\n",
      "     |  __next__(self, /)\n",
      "     |      Implement next(self).\n",
      "     |\n",
      "     |  __reduce__(...)\n",
      "     |      Return state information for pickling.\n",
      "     |\n",
      "     |  __setstate__(...)\n",
      "     |      Set state information for unpickling.\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Static methods defined here:\n",
      "     |\n",
      "     |  __new__(*args, **kwargs) from builtins.type\n",
      "     |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n",
      "    class islice(builtins.object)\n",
      "     |  islice(iterable, stop) --> islice object\n",
      "     |  islice(iterable, start, stop[, step]) --> islice object\n",
      "     |\n",
      "     |  Return an iterator whose next() method returns selected values from an\n",
      "     |  iterable.  If start is specified, will skip all preceding elements;\n",
      "     |  otherwise, start defaults to zero.  Step defaults to one.  If\n",
      "     |  specified as another value, step determines how many values are\n",
      "     |  skipped between successive calls.  Works like a slice() on a list\n",
      "     |  but returns an iterator.\n",
      "     |\n",
      "     |  Methods defined here:\n",
      "     |\n",
      "     |  __getattribute__(self, name, /)\n",
      "     |      Return getattr(self, name).\n",
      "     |\n",
      "     |  __iter__(self, /)\n",
      "     |      Implement iter(self).\n",
      "     |\n",
      "     |  __next__(self, /)\n",
      "     |      Implement next(self).\n",
      "     |\n",
      "     |  __reduce__(...)\n",
      "     |      Return state information for pickling.\n",
      "     |\n",
      "     |  __setstate__(...)\n",
      "     |      Set state information for unpickling.\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Static methods defined here:\n",
      "     |\n",
      "     |  __new__(*args, **kwargs) from builtins.type\n",
      "     |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n",
      "    class pairwise(builtins.object)\n",
      "     |  pairwise(iterable, /)\n",
      "     |\n",
      "     |  Return an iterator of overlapping pairs taken from the input iterator.\n",
      "     |\n",
      "     |  s -> (s0,s1), (s1,s2), (s2, s3), ...\n",
      "     |\n",
      "     |  Methods defined here:\n",
      "     |\n",
      "     |  __getattribute__(self, name, /)\n",
      "     |      Return getattr(self, name).\n",
      "     |\n",
      "     |  __iter__(self, /)\n",
      "     |      Implement iter(self).\n",
      "     |\n",
      "     |  __next__(self, /)\n",
      "     |      Implement next(self).\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Static methods defined here:\n",
      "     |\n",
      "     |  __new__(*args, **kwargs) from builtins.type\n",
      "     |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n",
      "    class permutations(builtins.object)\n",
      "     |  permutations(iterable, r=None)\n",
      "     |\n",
      "     |  Return successive r-length permutations of elements in the iterable.\n",
      "     |\n",
      "     |  permutations(range(3), 2) --> (0,1), (0,2), (1,0), (1,2), (2,0), (2,1)\n",
      "     |\n",
      "     |  Methods defined here:\n",
      "     |\n",
      "     |  __getattribute__(self, name, /)\n",
      "     |      Return getattr(self, name).\n",
      "     |\n",
      "     |  __iter__(self, /)\n",
      "     |      Implement iter(self).\n",
      "     |\n",
      "     |  __next__(self, /)\n",
      "     |      Implement next(self).\n",
      "     |\n",
      "     |  __reduce__(...)\n",
      "     |      Return state information for pickling.\n",
      "     |\n",
      "     |  __setstate__(...)\n",
      "     |      Set state information for unpickling.\n",
      "     |\n",
      "     |  __sizeof__(...)\n",
      "     |      Returns size in memory, in bytes.\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Static methods defined here:\n",
      "     |\n",
      "     |  __new__(*args, **kwargs) from builtins.type\n",
      "     |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n",
      "    class product(builtins.object)\n",
      "     |  product(*iterables, repeat=1) --> product object\n",
      "     |\n",
      "     |  Cartesian product of input iterables.  Equivalent to nested for-loops.\n",
      "     |\n",
      "     |  For example, product(A, B) returns the same as:  ((x,y) for x in A for y in B).\n",
      "     |  The leftmost iterators are in the outermost for-loop, so the output tuples\n",
      "     |  cycle in a manner similar to an odometer (with the rightmost element changing\n",
      "     |  on every iteration).\n",
      "     |\n",
      "     |  To compute the product of an iterable with itself, specify the number\n",
      "     |  of repetitions with the optional repeat keyword argument. For example,\n",
      "     |  product(A, repeat=4) means the same as product(A, A, A, A).\n",
      "     |\n",
      "     |  product('ab', range(3)) --> ('a',0) ('a',1) ('a',2) ('b',0) ('b',1) ('b',2)\n",
      "     |  product((0,1), (0,1), (0,1)) --> (0,0,0) (0,0,1) (0,1,0) (0,1,1) (1,0,0) ...\n",
      "     |\n",
      "     |  Methods defined here:\n",
      "     |\n",
      "     |  __getattribute__(self, name, /)\n",
      "     |      Return getattr(self, name).\n",
      "     |\n",
      "     |  __iter__(self, /)\n",
      "     |      Implement iter(self).\n",
      "     |\n",
      "     |  __next__(self, /)\n",
      "     |      Implement next(self).\n",
      "     |\n",
      "     |  __reduce__(...)\n",
      "     |      Return state information for pickling.\n",
      "     |\n",
      "     |  __setstate__(...)\n",
      "     |      Set state information for unpickling.\n",
      "     |\n",
      "     |  __sizeof__(...)\n",
      "     |      Returns size in memory, in bytes.\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Static methods defined here:\n",
      "     |\n",
      "     |  __new__(*args, **kwargs) from builtins.type\n",
      "     |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n",
      "    class repeat(builtins.object)\n",
      "     |  repeat(object [,times]) -> create an iterator which returns the object\n",
      "     |  for the specified number of times.  If not specified, returns the object\n",
      "     |  endlessly.\n",
      "     |\n",
      "     |  Methods defined here:\n",
      "     |\n",
      "     |  __getattribute__(self, name, /)\n",
      "     |      Return getattr(self, name).\n",
      "     |\n",
      "     |  __iter__(self, /)\n",
      "     |      Implement iter(self).\n",
      "     |\n",
      "     |  __length_hint__(...)\n",
      "     |      Private method returning an estimate of len(list(it)).\n",
      "     |\n",
      "     |  __next__(self, /)\n",
      "     |      Implement next(self).\n",
      "     |\n",
      "     |  __reduce__(...)\n",
      "     |      Return state information for pickling.\n",
      "     |\n",
      "     |  __repr__(self, /)\n",
      "     |      Return repr(self).\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Static methods defined here:\n",
      "     |\n",
      "     |  __new__(*args, **kwargs) from builtins.type\n",
      "     |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n",
      "    class starmap(builtins.object)\n",
      "     |  starmap(function, iterable, /)\n",
      "     |\n",
      "     |  Return an iterator whose values are returned from the function evaluated with an argument tuple taken from the given sequence.\n",
      "     |\n",
      "     |  Methods defined here:\n",
      "     |\n",
      "     |  __getattribute__(self, name, /)\n",
      "     |      Return getattr(self, name).\n",
      "     |\n",
      "     |  __iter__(self, /)\n",
      "     |      Implement iter(self).\n",
      "     |\n",
      "     |  __next__(self, /)\n",
      "     |      Implement next(self).\n",
      "     |\n",
      "     |  __reduce__(...)\n",
      "     |      Return state information for pickling.\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Static methods defined here:\n",
      "     |\n",
      "     |  __new__(*args, **kwargs) from builtins.type\n",
      "     |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n",
      "    class takewhile(builtins.object)\n",
      "     |  takewhile(predicate, iterable, /)\n",
      "     |\n",
      "     |  Return successive entries from an iterable as long as the predicate evaluates to true for each entry.\n",
      "     |\n",
      "     |  Methods defined here:\n",
      "     |\n",
      "     |  __getattribute__(self, name, /)\n",
      "     |      Return getattr(self, name).\n",
      "     |\n",
      "     |  __iter__(self, /)\n",
      "     |      Implement iter(self).\n",
      "     |\n",
      "     |  __next__(self, /)\n",
      "     |      Implement next(self).\n",
      "     |\n",
      "     |  __reduce__(...)\n",
      "     |      Return state information for pickling.\n",
      "     |\n",
      "     |  __setstate__(...)\n",
      "     |      Set state information for unpickling.\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Static methods defined here:\n",
      "     |\n",
      "     |  __new__(*args, **kwargs) from builtins.type\n",
      "     |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n",
      "    class zip_longest(builtins.object)\n",
      "     |  zip_longest(iter1 [,iter2 [...]], [fillvalue=None]) --> zip_longest object\n",
      "     |\n",
      "     |  Return a zip_longest object whose .__next__() method returns a tuple where\n",
      "     |  the i-th element comes from the i-th iterable argument.  The .__next__()\n",
      "     |  method continues until the longest iterable in the argument sequence\n",
      "     |  is exhausted and then it raises StopIteration.  When the shorter iterables\n",
      "     |  are exhausted, the fillvalue is substituted in their place.  The fillvalue\n",
      "     |  defaults to None or can be specified by a keyword argument.\n",
      "     |\n",
      "     |  Methods defined here:\n",
      "     |\n",
      "     |  __getattribute__(self, name, /)\n",
      "     |      Return getattr(self, name).\n",
      "     |\n",
      "     |  __iter__(self, /)\n",
      "     |      Implement iter(self).\n",
      "     |\n",
      "     |  __next__(self, /)\n",
      "     |      Implement next(self).\n",
      "     |\n",
      "     |  __reduce__(...)\n",
      "     |      Return state information for pickling.\n",
      "     |\n",
      "     |  __setstate__(...)\n",
      "     |      Set state information for unpickling.\n",
      "     |\n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Static methods defined here:\n",
      "     |\n",
      "     |  __new__(*args, **kwargs) from builtins.type\n",
      "     |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n",
      "FUNCTIONS\n",
      "    tee(iterable, n=2, /)\n",
      "        Returns a tuple of n independent iterators.\n",
      "\n",
      "FILE\n",
      "    (built-in)\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(itertools)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### ISlice"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Supposing the following ```tuple``` instance is instantiated:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 79,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = tuple(range(10))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 80,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Type</th>\n",
       "      <th>Size/Shape</th>\n",
       "      <th>Value</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Instance Name</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>nums</th>\n",
       "      <td>tuple</td>\n",
       "      <td>10</td>\n",
       "      <td>(0, 1, 2, 3, 4, 5, 6, 7, 8, 9)</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                Type Size/Shape                           Value\n",
       "Instance Name                                                  \n",
       "nums           tuple         10  (0, 1, 2, 3, 4, 5, 6, 7, 8, 9)"
      ]
     },
     "execution_count": 80,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "variables(['nums'])"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```tuple``` was cast from a ```range``` instance which had a default ```start``` of ```0``` and ```step``` of ```1``` so its index and values match. Indexing and slicing are typically carried out using square brackets:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 81,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Index \t Type                 \t Size   \t Value                         \n",
      "0 \t int                  \t 1      \t 0                              \t\n",
      "1 \t int                  \t 1      \t 1                              \t\n",
      "2 \t int                  \t 1      \t 2                              \t\n",
      "3 \t int                  \t 1      \t 3                              \t\n",
      "4 \t int                  \t 1      \t 4                              \t\n",
      "5 \t int                  \t 1      \t 5                              \t\n",
      "6 \t int                  \t 1      \t 6                              \t\n",
      "7 \t int                  \t 1      \t 7                              \t\n",
      "8 \t int                  \t 1      \t 8                              \t\n",
      "9 \t int                  \t 1      \t 9                              \t\n"
     ]
    }
   ],
   "source": [
    "view(nums)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 82,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 82,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nums[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 83,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(1, 2, 3, 4)"
      ]
     },
     "execution_count": 83,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nums[1:5]"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```slice``` function can also be explicitly used. The ```slice``` function has input arguments that are consistent with the ```range``` class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 84,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mslice\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mself\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m*\u001b[0m\u001b[0margs\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m     \n",
       "slice(stop)\n",
       "slice(start, stop[, step])\n",
       "\n",
       "Create a slice object.  This is used for extended slicing (e.g. a[0:10:2]).\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "slice?"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Its input arguments are ```int``` instances:\n",
    "\n",
    "* It can take in a single ```stop``` input argument. \n",
    "* Alternatively it can take a ```start``` and ```stop``` input argument.\n",
    "* Alternatively it can take a ```start```, ```stop``` and ```step``` input argument."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The input arguments are followed by a ```/``` indicating they are to be provided positionally only. If the ```start``` is not supplied it is assumed to be ```0``` and if the ```step``` is assumed to be ```1```. The same ```slice``` as before can be examined:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 85,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "slice(1, 5, None)"
      ]
     },
     "execution_count": 85,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "slice(1, 5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 86,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(1, 2, 3, 4)"
      ]
     },
     "execution_count": 86,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nums[slice(1, 5)]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notation is used when a ```slice``` is assigned to an instance name, for example ```SELECTION```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 87,
   "metadata": {},
   "outputs": [],
   "source": [
    "SELECTION = slice(1, 5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And this can make the code more readible:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 88,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(1, 2, 3, 4)"
      ]
     },
     "execution_count": 88,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nums[SELECTION]"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The iterator slice class ```islice``` returns an iterator instead of a slice that retains the same datatype as the original iterable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 89,
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import islice"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 90,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mislice\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mself\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m*\u001b[0m\u001b[0margs\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m     \n",
       "islice(iterable, stop) --> islice object\n",
       "islice(iterable, start, stop[, step]) --> islice object\n",
       "\n",
       "Return an iterator whose next() method returns selected values from an\n",
       "iterable.  If start is specified, will skip all preceding elements;\n",
       "otherwise, start defaults to zero.  Step defaults to one.  If\n",
       "specified as another value, step determines how many values are\n",
       "skipped between successive calls.  Works like a slice() on a list\n",
       "but returns an iterator.\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "islice?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It requires an iterable or iterator as the first positional input argument and the subsequent input arguments match that of slice:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 91,
   "metadata": {},
   "outputs": [],
   "source": [
    "i_slice = itertools.islice(nums, 1, 5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 92,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<itertools.islice at 0x2b4ca71c540>"
      ]
     },
     "execution_count": 92,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "i_slice"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The iterator slice ```islice``` class more commonly takes an iterator as a first input argument. When it does the iterator slice is linked to the iterator:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 93,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = tuple(range(10))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 94,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = iter(nums)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 95,
   "metadata": {},
   "outputs": [],
   "source": [
    "i_slice = itertools.islice(forward, 3, 5)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can be seen by casting ```forward_slice``` to a ```tuple``` instance, consuming all its values and then casting ```forward``` to a ```tuple``` instance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 96,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(3, 4)"
      ]
     },
     "execution_count": 96,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(i_slice)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When values are consumed using the iterator slice ```i_slice``` they and any values before them (as an iterator can only go forward) are also consumed in the iterator ```forward``` and therefore then ```forward``` is cast into a ```tuple```, consuming the remaining values, the first value is ```5```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 97,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(5, 6, 7, 8, 9)"
      ]
     },
     "execution_count": 97,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(forward)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the iterator ```forward``` and ```i_slice``` are reconstructed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 98,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = iter(range(10))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 99,
   "metadata": {},
   "outputs": [],
   "source": [
    "i_slice = itertools.islice(forward, 3, 5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If ```next``` is used on the iterator, the first value is observed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 100,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 100,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before the call ```next``` was used, this value was considered by the iterator slice ```i_slice``` to be at index ```0``` however it is now consumed and there is now the next value is considered to be at index ```0```. When the iterator slice ```i_slice``` is cast into a ```tuple``` consuming all the values notice the return value is ```(4, 5)``` opposed to ```(3, 4)```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 101,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(4, 5)"
      ]
     },
     "execution_count": 101,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(i_slice)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The remaining values in the ```iterator``` instance ```forward``` can be seen by casting to a ```tuple```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 102,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(6, 7, 8, 9)"
      ]
     },
     "execution_count": 102,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(forward)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Tee"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```tee``` function can be used to return a ```tuple``` of ```n``` independent iterators. Its name comes from the tee junction used for example in plumbing to split a water stream:"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![img_001](./images/img_001.png)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Its docstring can be examined:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 103,
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import tee"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 104,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mSignature:\u001b[0m \u001b[0mtee\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0miterable\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mn\u001b[0m\u001b[1;33m=\u001b[0m\u001b[1;36m2\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m Returns a tuple of n independent iterators.\n",
       "\u001b[1;31mType:\u001b[0m      builtin_function_or_method"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "tee?"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It takes in an ```iterable``` such as an iterator as an input argument, alongside the number of independent iterators ```n```. The input arguments are before ```/``` and therefore must be supplied positionally."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example the iterator forward can be split into two independent iterators and the two element ```tuple``` can be unpacked into 2 instance names ```forward1``` and ```forward2``` using ```tuple``` unpacking:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 105,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = iter(range(10))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 106,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward1, forward2 = itertools.tee(forward, 2)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "These can be shown to be independent by looking at the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 107,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 107,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 108,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 108,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 109,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 109,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward1)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Although ```forward1``` and ```forward2``` appear to be independent, they are still related to the original object ```forward```. Essentially ```forward``` becomes equivalent to the pipeline that is furthest along (most exhausted):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 110,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 110,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that because ```next``` has now been used on ```forward``` which had previously taken the value of the furthest pipeline ```forward1```, that this advances ```forward1```. In contrast this does not advance ```forward2``` which at this point is behind:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 111,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 111,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 112,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 112,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward2)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Casting the rest of the values in ```forward1``` to a ```tuple``` therefore exhausts ```forward```. ```forward2``` is still behind:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 113,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(4, 5, 6, 7, 8, 9)"
      ]
     },
     "execution_count": 113,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(forward1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 114,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "()"
      ]
     },
     "execution_count": 114,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 115,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 115,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward2)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Chain"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```itertools.chain``` class can be used to chain two or more iterables together. Its initialisation signature can be viewed by inputting:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 116,
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import chain"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 117,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mchain\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mself\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m*\u001b[0m\u001b[0margs\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m     \n",
       "chain(*iterables) --> chain object\n",
       "\n",
       "Return a chain object whose .__next__() method returns elements from the\n",
       "first iterable until it is exhausted, then elements from the next\n",
       "iterable, until all of the iterables are exhausted.\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "chain?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The input arguments ```*iterables``` indicates that a variable number of iterables or iterators can be chained. These proceed a ```/``` indicating that these must be provided positionally."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 118,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward1 = iter((1, 2, 3))\n",
    "forward2 = iter(('a', 'b', 'c'))\n",
    "forward = chain(forward1, forward2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```chain``` iterator essentially chains the iterators creating one larger iterator. This large iterator is still linked with the original iterators. Using ```next``` on one of the original iterators ```forward1``` or ```forward2``` will exhaust it from the chain ```forward```. Likewise using ```next``` on the chain ```forward``` will exhaust the value from the corresponding original iterator:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 119,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 119,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 120,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'a'"
      ]
     },
     "execution_count": 120,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 121,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 121,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 122,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 122,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 123,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'b'"
      ]
     },
     "execution_count": 123,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Repeat"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```itertools.repeat``` class can be used to repeat an ```object``` for a specified or unspecified number of times. Its initialisation signature can be viewed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 124,
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import repeat"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 125,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mrepeat\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mself\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m*\u001b[0m\u001b[0margs\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m     \n",
       "repeat(object [,times]) -> create an iterator which returns the object\n",
       "for the specified number of times.  If not specified, returns the object\n",
       "endlessly.\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "repeat?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The input arguments ```object``` is required. The input argument ```times``` is optional which is why it is displayed after a leading comma ```[,times]```. These are before ```/``` and must therefore be provided as positional input arguments."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 126,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = repeat('hello', 3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 127,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "repeat('hello', 3)"
      ]
     },
     "execution_count": 127,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When ```next``` is called on the iterator, the repeated object ```'hello'``` will display:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 128,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'hello'"
      ]
     },
     "execution_count": 128,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 129,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'hello'"
      ]
     },
     "execution_count": 129,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 130,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'hello'"
      ]
     },
     "execution_count": 130,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If this is recreated, it can be cast into a ```tuple``` or ``` list``` where the finite ```3``` values will be consumed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 131,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = repeat('hello', 3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 132,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('hello', 'hello', 'hello')"
      ]
     },
     "execution_count": 132,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "On the other hand, if the optional input argument ```times``` is not specified, an iterator of **infinite repeat values** will be created:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 133,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = repeat('hello')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 134,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "repeat('hello')"
      ]
     },
     "execution_count": 134,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Care should be taken when attempting to cast this **infinitely** repeating iterator to a sequence such as a ```tuple``` or ```'list'``` as a sequence of **infinite** values occupies **infinite** memory and crashes the program.\n",
    "\n",
    "```python\n",
    "tuple(repeat('hello'))\n",
    "```"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Likewise when a ```for``` loop is constructed using this **infinitely** repeating iterator, it will essentially carry out an **infinite** loop:\n",
    "\n",
    "```python\n",
    "forward = repeat('hello')\n",
    "for word in forward:\n",
    "    print(word)\n",
    "```"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Cycle"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```itertools.cycle``` class can be used to repeat a cycle of objects indefinitely. A common use case is the cycling of files in a folder in an application with a next button. Once the last file has been accessed, instead of the next button being greyed out, it can be cycled back to the first file. Its initialisation signature can be viewed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 135,
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import cycle"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 136,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mcycle\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0miterable\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m      Return elements from the iterable until it is exhausted. Then repeat the sequence indefinitely.\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "cycle?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And it can be used in the following example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 137,
   "metadata": {},
   "outputs": [],
   "source": [
    "colors = ('red', 'green', 'blue')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 138,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = cycle(colors)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 139,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<itertools.cycle at 0x2b4ca89c380>"
      ]
     },
     "execution_count": 139,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The iterator can be indefinitely cycled through:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 140,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'red'"
      ]
     },
     "execution_count": 140,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 141,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'green'"
      ]
     },
     "execution_count": 141,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 142,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'blue'"
      ]
     },
     "execution_count": 142,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 143,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'red'"
      ]
     },
     "execution_count": 143,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Care should once again be taken when attempting to cast this to a sequence or using it in a ```for``` loop as it will attempt to create a sequence that is infinite in length or result in an infinite loop respectively."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Count"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```itertools.count``` class can be used to create an iterator that is similar to a range iterator. Its initialisation signature can be viewed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 144,
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import count"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 145,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mcount\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mstart\u001b[0m\u001b[1;33m=\u001b[0m\u001b[1;36m0\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mstep\u001b[0m\u001b[1;33m=\u001b[0m\u001b[1;36m1\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m     \n",
       "Return a count object whose .__next__() method returns consecutive values.\n",
       "\n",
       "Equivalent to:\n",
       "    def count(firstval=0, step=1):\n",
       "        x = firstval\n",
       "        while 1:\n",
       "            yield x\n",
       "            x += step\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "count?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The input arguments are ```start``` and ```step``` which have the default values ```0``` and ```1``` respectively. Notice the emission of ```stop```, indicating that this iterator will count indefinitely:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 146,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = count()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 147,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "count(0)"
      ]
     },
     "execution_count": 147,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The iterator can be used to count upwards indefinitely:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 148,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 148,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 149,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 149,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 150,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 150,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 151,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 151,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Care should once again be taken when attempting to cast this to a sequence or using it in a ```for``` loop as it will attempt to create a sequence that is infinite in length or result in an infinite loop respectively. Sometimes a ```for``` loop is constructed that includes a condition with a ```break``` statement:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 152,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = count()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 153,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0\n",
      "1\n",
      "2\n",
      "3\n",
      "4\n",
      "5\n",
      "6\n",
      "7\n",
      "8\n",
      "9\n",
      "10\n",
      "11\n"
     ]
    }
   ],
   "source": [
    "for value in forward:\n",
    "    print(value)\n",
    "    if value > 10:\n",
    "        break"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Accumulate"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```itertools.accumulate``` class can be used to create an iterator that is similar to one created using ```map``` by default mapping the addition binary operator to the iterable returning the accumulation along the sequence. Its initialisation signature can be viewed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 154,
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import accumulate"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 155,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0maccumulate\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0miterable\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mfunc\u001b[0m\u001b[1;33m=\u001b[0m\u001b[1;32mNone\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m*\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0minitial\u001b[0m\u001b[1;33m=\u001b[0m\u001b[1;32mNone\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m      Return series of accumulated sums (or other binary function results).\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "accumulate?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The input arguments are the ```iterable```. There is an optional ```func``` which defaults to the addition operator and the ```initial``` input argument which specifies the original value and defaults to ```None```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 156,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = (0, 1, 2, 3, 4)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 157,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = accumulate(nums)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 158,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<itertools.accumulate at 0x2b4ca7b9710>"
      ]
     },
     "execution_count": 158,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When next is used, the first value in the sequence ```0``` is returned:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 159,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 159,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When ```next``` is used, the previous accumulation ```0``` is added with the second value in the iterator ```1```. Both of these are supplied to the binary operator ```add```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 160,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 160,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When ```next``` is used, the previous accumulation ```1``` is added with the third value in the iterator ```2```. Both of these are supplied to the binary operator ```add```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 161,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 161,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This continues until all the values in the sequence are exhausted. If the iterator is cast into a ```tuple```, it has the same length as the original sequence:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 162,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(0, 1, 3, 6, 10)"
      ]
     },
     "execution_count": 162,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(accumulate(nums))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If an initial value is specified, this increases the length by ```1```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 163,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(99, 99, 100, 102, 105, 109)"
      ]
     },
     "execution_count": 163,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(accumulate(nums, initial=99))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The operator module contains the binary functions which can be assigned to the ```func``` input argument of the ```accumulate``` class. It can be imported using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 164,
   "metadata": {},
   "outputs": [],
   "source": [
    "import operator"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Its identifiers can be viewed using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 165,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'method': ['abs',\n",
      "            'add',\n",
      "            'and_',\n",
      "            'call',\n",
      "            'concat',\n",
      "            'contains',\n",
      "            'countOf',\n",
      "            'delitem',\n",
      "            'eq',\n",
      "            'floordiv',\n",
      "            'ge',\n",
      "            'getitem',\n",
      "            'gt',\n",
      "            'iadd',\n",
      "            'iand',\n",
      "            'iconcat',\n",
      "            'ifloordiv',\n",
      "            'ilshift',\n",
      "            'imatmul',\n",
      "            'imod',\n",
      "            'imul',\n",
      "            'index',\n",
      "            'indexOf',\n",
      "            'inv',\n",
      "            'invert',\n",
      "            'ior',\n",
      "            'ipow',\n",
      "            'irshift',\n",
      "            'is_',\n",
      "            'is_not',\n",
      "            'isub',\n",
      "            'itruediv',\n",
      "            'ixor',\n",
      "            'le',\n",
      "            'length_hint',\n",
      "            'lshift',\n",
      "            'lt',\n",
      "            'matmul',\n",
      "            'mod',\n",
      "            'mul',\n",
      "            'ne',\n",
      "            'neg',\n",
      "            'not_',\n",
      "            'or_',\n",
      "            'pos',\n",
      "            'pow',\n",
      "            'rshift',\n",
      "            'setitem',\n",
      "            'sub',\n",
      "            'truediv',\n",
      "            'truth',\n",
      "            'xor'],\n",
      " 'lower_class': ['attrgetter', 'itemgetter', 'methodcaller'],\n",
      " 'datamodel_attribute': ['__all__',\n",
      "                         '__builtins__',\n",
      "                         '__cached__',\n",
      "                         '__doc__',\n",
      "                         '__file__',\n",
      "                         '__loader__',\n",
      "                         '__name__',\n",
      "                         '__package__',\n",
      "                         '__spec__'],\n",
      " 'datamodel_method': ['__abs__',\n",
      "                      '__add__',\n",
      "                      '__and__',\n",
      "                      '__call__',\n",
      "                      '__concat__',\n",
      "                      '__contains__',\n",
      "                      '__delitem__',\n",
      "                      '__eq__',\n",
      "                      '__floordiv__',\n",
      "                      '__ge__',\n",
      "                      '__getitem__',\n",
      "                      '__gt__',\n",
      "                      '__iadd__',\n",
      "                      '__iand__',\n",
      "                      '__iconcat__',\n",
      "                      '__ifloordiv__',\n",
      "                      '__ilshift__',\n",
      "                      '__imatmul__',\n",
      "                      '__imod__',\n",
      "                      '__imul__',\n",
      "                      '__index__',\n",
      "                      '__inv__',\n",
      "                      '__invert__',\n",
      "                      '__ior__',\n",
      "                      '__ipow__',\n",
      "                      '__irshift__',\n",
      "                      '__isub__',\n",
      "                      '__itruediv__',\n",
      "                      '__ixor__',\n",
      "                      '__le__',\n",
      "                      '__lshift__',\n",
      "                      '__lt__',\n",
      "                      '__matmul__',\n",
      "                      '__mod__',\n",
      "                      '__mul__',\n",
      "                      '__ne__',\n",
      "                      '__neg__',\n",
      "                      '__not__',\n",
      "                      '__or__',\n",
      "                      '__pos__',\n",
      "                      '__pow__',\n",
      "                      '__rshift__',\n",
      "                      '__setitem__',\n",
      "                      '__sub__',\n",
      "                      '__truediv__',\n",
      "                      '__xor__'],\n",
      " 'internal_method': ['_abs']}\n"
     ]
    }
   ],
   "source": [
    "dir2(operator)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```operator``` module has the ```__mul__``` datamodel method which gives details about the ```*```. For convenience this is also available under the alias ```mul```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 166,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 166,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "operator.__mul__ == operator.mul"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 167,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mSignature:\u001b[0m \u001b[0moperator\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mmul\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0ma\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mb\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m Same as a * b.\n",
       "\u001b[1;31mType:\u001b[0m      builtin_function_or_method"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "operator.mul?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A multiplication accumulation can for example be created using the multiplication operator:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 168,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = (1, 2, 3, 4, 5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 169,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(1, 2, 6, 24, 120)"
      ]
     },
     "execution_count": 169,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(accumulate(nums, func=operator.mul))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Starmap"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the function ```powered``` is assigned using a ```lambda``` expression:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 170,
   "metadata": {},
   "outputs": [],
   "source": [
    "powered = lambda num, power: num ** power"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are two input parameters and one return value. A ```tuple``` of arguments can be instantiated:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 171,
   "metadata": {},
   "outputs": [],
   "source": [
    "args = (2, 3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And can be unpacked to the input parameters in the function call:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 172,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "8"
      ]
     },
     "execution_count": 172,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "powered(*args)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```itertools.starmap``` class can be used to create an iterator that is similar to one created using ```map```. Instead of mapping a function to a sequence where each value in the sequence is supplied as a single input argument for the function call. The function is mapped to a sequence of equally length ```tuple``` instances and ```tuple``` unpacking is used for each ```tuple``` supplying multiple input parameters for each function call. The initialisation signature can be seen:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 173,
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import starmap"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 174,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mstarmap\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mfunction\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0miterable\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m      Return an iterator whose values are returned from the function evaluated with an argument tuple taken from the given sequence.\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "starmap?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The input parameter are the function and iterable of ```tuple``` instances. These are followed by a ```/``` indicating they must be supplied positionally only."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example ```args``` can be created using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 175,
   "metadata": {},
   "outputs": [],
   "source": [
    "args = tuple(zip(range(10), itertools.repeat(2)))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 176,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "((0, 2),\n",
       " (1, 2),\n",
       " (2, 2),\n",
       " (3, 2),\n",
       " (4, 2),\n",
       " (5, 2),\n",
       " (6, 2),\n",
       " (7, 2),\n",
       " (8, 2),\n",
       " (9, 2))"
      ]
     },
     "execution_count": 176,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "args"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For simplicity, the second value in each ```tuple``` is a constant ```2```. A ```starmap``` iterator can now be created:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 177,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = starmap(powered, args)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 178,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<itertools.starmap at 0x2b4ca81fdf0>"
      ]
     },
     "execution_count": 178,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using ```next``` will move onto the next ```tuple``` and use the values in this ```tuple``` for the input parameters in that iteration of the function call:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 179,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 179,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 180,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 180,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 181,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "4"
      ]
     },
     "execution_count": 181,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This iterator can be cast into a ```tuple``` to compute the following squared values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 182,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(0, 1, 4, 9, 16, 25, 36, 49, 64, 81)"
      ]
     },
     "execution_count": 182,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(starmap(powered, args))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Zip Longest"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```itertools.zip_longest``` class can be used to zip two or more collections together. Unlike ```zip``` which stops zipping once the shortest sequence has been exhausted, ```itertools.zip_longest``` will continue zipping until the longest sequence is exhaused. When one of the iterables being zipped is exhausted, ```None``` values will be zipped:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 183,
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import zip_longest"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 184,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mzip_longest\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mself\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m*\u001b[0m\u001b[0margs\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m     \n",
       "zip_longest(iter1 [,iter2 [...]], [fillvalue=None]) --> zip_longest object\n",
       "\n",
       "Return a zip_longest object whose .__next__() method returns a tuple where\n",
       "the i-th element comes from the i-th iterable argument.  The .__next__()\n",
       "method continues until the longest iterable in the argument sequence\n",
       "is exhausted and then it raises StopIteration.  When the shorter iterables\n",
       "are exhausted, the fillvalue is substituted in their place.  The fillvalue\n",
       "defaults to None or can be specified by a keyword argument.\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "zip_longest?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The example used with the ```zip``` class can be reused:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 185,
   "metadata": {},
   "outputs": [],
   "source": [
    "names = ('red', 'green', 'blue', 'yellow')\n",
    "keys = ('r', 'g', 'b')\n",
    "values = ('#FF0000', '#00FF00', '#0000FF')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An iterator can be created which zips these three collections:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 186,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = zip_longest(names, keys, values)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that the last value has two ```None``` values because ```names``` and ```values``` have been exhausted:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 187,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('red', 'r', '#FF0000'),\n",
       " ('green', 'g', '#00FF00'),\n",
       " ('blue', 'b', '#0000FF'),\n",
       " ('yellow', None, None)]"
      ]
     },
     "execution_count": 187,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Pairwise"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```itertools.pairwise``` class can be used to create ```tuple``` pairs from neighbouring values in a sequence. Its initialisation signature can be viewed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 188,
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import pairwise"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 189,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mpairwise\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0miterable\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m     \n",
       "Return an iterator of overlapping pairs taken from the input iterator.\n",
       "\n",
       "s -> (s0,s1), (s1,s2), (s2, s3), ...\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "pairwise?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It has a single input argument ```iterable``` which is followed by a ```/``` indicating that it must be supplied positionally."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The example ```letters``` can be used:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 190,
   "metadata": {},
   "outputs": [],
   "source": [
    "letters = ('a', 'b', 'c', 'd')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A pairwise iterator can be instantiated:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 191,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = pairwise(letters)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 192,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<itertools.pairwise at 0x2b4ca8ce890>"
      ]
     },
     "execution_count": 192,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Casting to a ```list``` will display all the pairs, the ```tuple``` will have the length one less that the original sequence, as 2 elements are required per pair:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 193,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('a', 'b'), ('b', 'c'), ('c', 'd')]"
      ]
     },
     "execution_count": 193,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(pairwise(letters))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Filter False"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```itertools.filterfalse``` class acts inversely to the ```filter``` class. Its initialisation signature can be viewed by:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 194,
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import filterfalse"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 195,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mfilterfalse\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mfunction\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0miterable\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m     \n",
       "Return those items of iterable for which function(item) is false.\n",
       "\n",
       "If function is None, return the items that are false.\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "filterfalse?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example if the same ```lambda``` expression is used as before:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 196,
   "metadata": {},
   "outputs": [],
   "source": [
    "positive_filter = lambda num: num > 0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Can be mapped to the following sequence:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 197,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = (-2, -1, 0, 1, 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 198,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = filterfalse(positive_filter, nums)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 199,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<itertools.filterfalse at 0x2b4ca8cfb50>"
      ]
     },
     "execution_count": 199,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All the filtered values given by the iterator can be consumed by casting to a ```tuple```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 200,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(-2, -1, 0)"
      ]
     },
     "execution_count": 200,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(filterfalse(positive_filter, nums))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 201,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(1, 2)"
      ]
     },
     "execution_count": 201,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(filter(positive_filter, nums))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Drop While"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```itertools.dropwhile``` class will drop each item in an iterable until a predicate is taken to be ```False```. i.e. the first ```False``` acts as a trigger point. Its initialisation signature can be viewed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 202,
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import dropwhile"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 203,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mdropwhile\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mpredicate\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0miterable\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m     \n",
       "Drop items from the iterable while predicate(item) is true.\n",
       "\n",
       "Afterwards, return every element until the iterable is exhausted.\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "dropwhile?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It has the input arguments ```predicate``` and ```iterable```. These are followed by a ```/``` and therefore must be provided positionally."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example the following tuple of ```letters``` can be the ```iterable``` and the ```predicate``` can be a ```lambda``` expression that is ```False``` unless the letter is ```'d'```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 204,
   "metadata": {},
   "outputs": [],
   "source": [
    "letters = ('a', 'b', 'c', 'd', 'e', 'f', 'g', 'h')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 205,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = dropwhile(lambda x: x != 'd', letters)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 206,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<itertools.dropwhile at 0x2b4ca8db840>"
      ]
     },
     "execution_count": 206,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When ```next``` is called, the value at the first occurance of a ```False``` condition is returned: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 207,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'d'"
      ]
     },
     "execution_count": 207,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then iterator with ```next``` proceeds as normal:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 208,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'e'"
      ]
     },
     "execution_count": 208,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 209,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'f'"
      ]
     },
     "execution_count": 209,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Take While"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```itertools.takewhile``` class is the inverse of the ```itertools.dropwhile``` class. It will take each item in an iterable until a ```predicate``` is taken to be ```False```. i.e. the first ```False``` acts as a trigger point and all values dropping this value and all subsequent items. Its initialisation signature can be viewed by inputting:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 210,
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import takewhile"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 211,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mtakewhile\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mpredicate\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0miterable\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m      Return successive entries from an iterable as long as the predicate evaluates to true for each entry.\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "takewhile?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It has the input arguments ```predicate``` and ```iterable```. These are followed by a ```/``` and therefore must be provided positionally."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The same example can be viewed as before:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 212,
   "metadata": {},
   "outputs": [],
   "source": [
    "letters = ('a', 'b', 'c', 'd', 'e', 'f', 'g', 'h')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 213,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = itertools.takewhile(lambda x: x != 'd', letters)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 214,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<itertools.takewhile at 0x2b4ca8f0e80>"
      ]
     },
     "execution_count": 214,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When ```next``` is called, the ```next``` value in the sequence is returned unless the condition is ```False```, at this point the iterator is exhausted: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 215,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'a'"
      ]
     },
     "execution_count": 215,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 216,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'b'"
      ]
     },
     "execution_count": 216,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 217,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'c'"
      ]
     },
     "execution_count": 217,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The two classes are complementary to each other and this can be seen when casting to a ```tuple```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 218,
   "metadata": {},
   "outputs": [],
   "source": [
    "letters = ('a', 'b', 'c', 'd', 'e', 'f', 'g', 'h')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 219,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('a', 'b', 'c')"
      ]
     },
     "execution_count": 219,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(takewhile(lambda x: x != 'd', letters))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 220,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('d', 'e', 'f', 'g', 'h')"
      ]
     },
     "execution_count": 220,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(dropwhile(lambda x: x != 'd', letters))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Compress"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```itertools.compress``` class can be used to compress data using a selector. Its initialisation signature can be viewed by"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 221,
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import compress"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 222,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mcompress\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mdata\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mselectors\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m     \n",
       "Return data elements corresponding to true selector elements.\n",
       "\n",
       "Forms a shorter iterator from selected data elements using the selectors to\n",
       "choose the data elements.\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "compress?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example, the ```data``` can be the ```tuple``` instance ```letters``` and the ```selector``` can be the ```tuple``` instance conditions. Note that both of these have the same length:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 223,
   "metadata": {},
   "outputs": [],
   "source": [
    "letters = ('a', 'b', 'c', 'd', 'e', 'f')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 224,
   "metadata": {},
   "outputs": [],
   "source": [
    "conditions = (True, True, False, False, True, True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The compressed iterator is therefore:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 225,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = compress(letters, conditions)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 226,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<itertools.compress at 0x2b4ca831f00>"
      ]
     },
     "execution_count": 226,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Only the values in ```letters``` where the condition in ```condiiton``` is ```true``` are seen in the ```tuple``` instance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 227,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('a', 'b', 'e', 'f')"
      ]
     },
     "execution_count": 227,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(compress(letters, conditions))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Combinations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```itertools.combinations``` class can be used to display the unique combinations available from items in an iterable using a ```r-length```. This is best visualised pictorially. For example if the iterable has ```3``` colour circles and a ```r-length``` of ```2```. The combinations look like:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![img_002](./images/img_002.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Its initialisation signature can be viewed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 228,
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import combinations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 229,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mcombinations\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0miterable\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mr\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m     \n",
       "Return successive r-length combinations of elements in the iterable.\n",
       "\n",
       "combinations(range(4), 3) --> (0,1,2), (0,1,3), (0,2,3), (1,2,3)\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "combinations?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The example above can be created using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 230,
   "metadata": {},
   "outputs": [],
   "source": [
    "colors = ('c', 'y', 'm')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 231,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = itertools.combinations(colors, 2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 232,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<itertools.combinations at 0x2b4ca892750>"
      ]
     },
     "execution_count": 232,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 233,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('c', 'y'), ('c', 'm'), ('y', 'm')]"
      ]
     },
     "execution_count": 233,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Combinations With Replacement"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```itertools.combinations_with_replacement``` class can be used to display the unique combinations available from items in an iterable using a ```r-length``` when the items in the iterable can be duplicated. This is best visualised pictorially."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example if the iterable has ```3``` colour circles and a ```r-length``` of ```2```. The combinations with replacement would look like:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![img_003](./images/img_003.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Its initialisation signature can be viewed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 234,
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import combinations_with_replacement"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 235,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mcombinations_with_replacement\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0miterable\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mr\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m     \n",
       "Return successive r-length combinations of elements in the iterable allowing individual elements to have successive repeats.\n",
       "\n",
       "combinations_with_replacement('ABC', 2) --> ('A','A'), ('A','B'), ('A','C'), ('B','B'), ('B','C'), ('C','C')\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "combinations_with_replacement?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The example above can be created using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 236,
   "metadata": {},
   "outputs": [],
   "source": [
    "colors = ('c', 'y', 'm')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 237,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = combinations_with_replacement(colors, 2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 238,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<itertools.combinations_with_replacement at 0x2b4ca8a0e00>"
      ]
     },
     "execution_count": 238,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 239,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('c', 'c'), ('c', 'y'), ('c', 'm'), ('y', 'y'), ('y', 'm'), ('m', 'm')]"
      ]
     },
     "execution_count": 239,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Permutations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```itertools.permutations``` class can be used to display the unique permutations available from items in an iterable using a ```r-length```. In a combination, the order of the values in the tuple representing the combination doesn't matter. In a permutation this order matters. This is best visualised pictorially. For example if the iterable has ```3``` colour circles and a ```r-length``` of ```2```. The combinations would look like:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![img_004](./images/img_004.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Its initialisation signature can be viewed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 240,
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import permutations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 241,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mpermutations\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0miterable\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mr\u001b[0m\u001b[1;33m=\u001b[0m\u001b[1;32mNone\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m     \n",
       "Return successive r-length permutations of elements in the iterable.\n",
       "\n",
       "permutations(range(3), 2) --> (0,1), (0,2), (1,0), (1,2), (2,0), (2,1)\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "permutations?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The example above can be created using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 242,
   "metadata": {},
   "outputs": [],
   "source": [
    "colors = ('c', 'y', 'm')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 243,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = permutations(colors, 2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 244,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<itertools.permutations at 0x2b4ca78de40>"
      ]
     },
     "execution_count": 244,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 245,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('c', 'y'), ('c', 'm'), ('y', 'c'), ('y', 'm'), ('m', 'c'), ('m', 'y')]"
      ]
     },
     "execution_count": 245,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Product"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```itertools.product``` class can be used to display the unique permutations with replacement available from items in an iterable using a ```r-length```. This is best visualised pictorially. For example if the iterable has ```3``` colour circles and a ```r-length``` of ```2```. The product would look like:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![img_005](./images/img_005.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Its initialisation signature can be viewed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 246,
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import product"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 247,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mproduct\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mself\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m*\u001b[0m\u001b[0margs\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m     \n",
       "product(*iterables, repeat=1) --> product object\n",
       "\n",
       "Cartesian product of input iterables.  Equivalent to nested for-loops.\n",
       "\n",
       "For example, product(A, B) returns the same as:  ((x,y) for x in A for y in B).\n",
       "The leftmost iterators are in the outermost for-loop, so the output tuples\n",
       "cycle in a manner similar to an odometer (with the rightmost element changing\n",
       "on every iteration).\n",
       "\n",
       "To compute the product of an iterable with itself, specify the number\n",
       "of repetitions with the optional repeat keyword argument. For example,\n",
       "product(A, repeat=4) means the same as product(A, A, A, A).\n",
       "\n",
       "product('ab', range(3)) --> ('a',0) ('a',1) ('a',2) ('b',0) ('b',1) ('b',2)\n",
       "product((0,1), (0,1), (0,1)) --> (0,0,0) (0,0,1) (0,1,0) (0,1,1) (1,0,0) ...\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "product?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When a single iterable is supplied and repeat is assigned to the previously used ```r-length```, this calculates the permutations with replacement:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 248,
   "metadata": {},
   "outputs": [],
   "source": [
    "colors = ('c', 'y', 'm')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 249,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = product(colors, repeat=2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 250,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<itertools.product at 0x2b4ca914540>"
      ]
     },
     "execution_count": 250,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 251,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('c', 'c'),\n",
       " ('c', 'y'),\n",
       " ('c', 'm'),\n",
       " ('y', 'c'),\n",
       " ('y', 'y'),\n",
       " ('y', 'm'),\n",
       " ('m', 'c'),\n",
       " ('m', 'y'),\n",
       " ('m', 'm')]"
      ]
     },
     "execution_count": 251,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If multiple iterables of equal length are supplied, the product creates an iterator. When ```next``` is called a ```tuple``` is returned which takes a value from each of the sequences:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 252,
   "metadata": {},
   "outputs": [],
   "source": [
    "letters = ('a', 'b', 'c')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 253,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = (1, 2, 3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 254,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = product(letters, nums)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 255,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<itertools.product at 0x2b4ca719c40>"
      ]
     },
     "execution_count": 255,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 256,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('a', 1),\n",
       " ('a', 2),\n",
       " ('a', 3),\n",
       " ('b', 1),\n",
       " ('b', 2),\n",
       " ('b', 3),\n",
       " ('c', 1),\n",
       " ('c', 2),\n",
       " ('c', 3)]"
      ]
     },
     "execution_count": 256,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If multiple iterables of equal length are supplied, and ```repeat``` is assigned to ```2```, the ```tuple``` returned has two values from each sequence. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 257,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = product(letters, nums, repeat=2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 258,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<itertools.product at 0x2b4ca7b1580>"
      ]
     },
     "execution_count": 258,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 259,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('a', 1, 'a', 1),\n",
       " ('a', 1, 'a', 2),\n",
       " ('a', 1, 'a', 3),\n",
       " ('a', 1, 'b', 1),\n",
       " ('a', 1, 'b', 2),\n",
       " ('a', 1, 'b', 3),\n",
       " ('a', 1, 'c', 1),\n",
       " ('a', 1, 'c', 2),\n",
       " ('a', 1, 'c', 3),\n",
       " ('a', 2, 'a', 1),\n",
       " ('a', 2, 'a', 2),\n",
       " ('a', 2, 'a', 3),\n",
       " ('a', 2, 'b', 1),\n",
       " ('a', 2, 'b', 2),\n",
       " ('a', 2, 'b', 3),\n",
       " ('a', 2, 'c', 1),\n",
       " ('a', 2, 'c', 2),\n",
       " ('a', 2, 'c', 3),\n",
       " ('a', 3, 'a', 1),\n",
       " ('a', 3, 'a', 2),\n",
       " ('a', 3, 'a', 3),\n",
       " ('a', 3, 'b', 1),\n",
       " ('a', 3, 'b', 2),\n",
       " ('a', 3, 'b', 3),\n",
       " ('a', 3, 'c', 1),\n",
       " ('a', 3, 'c', 2),\n",
       " ('a', 3, 'c', 3),\n",
       " ('b', 1, 'a', 1),\n",
       " ('b', 1, 'a', 2),\n",
       " ('b', 1, 'a', 3),\n",
       " ('b', 1, 'b', 1),\n",
       " ('b', 1, 'b', 2),\n",
       " ('b', 1, 'b', 3),\n",
       " ('b', 1, 'c', 1),\n",
       " ('b', 1, 'c', 2),\n",
       " ('b', 1, 'c', 3),\n",
       " ('b', 2, 'a', 1),\n",
       " ('b', 2, 'a', 2),\n",
       " ('b', 2, 'a', 3),\n",
       " ('b', 2, 'b', 1),\n",
       " ('b', 2, 'b', 2),\n",
       " ('b', 2, 'b', 3),\n",
       " ('b', 2, 'c', 1),\n",
       " ('b', 2, 'c', 2),\n",
       " ('b', 2, 'c', 3),\n",
       " ('b', 3, 'a', 1),\n",
       " ('b', 3, 'a', 2),\n",
       " ('b', 3, 'a', 3),\n",
       " ('b', 3, 'b', 1),\n",
       " ('b', 3, 'b', 2),\n",
       " ('b', 3, 'b', 3),\n",
       " ('b', 3, 'c', 1),\n",
       " ('b', 3, 'c', 2),\n",
       " ('b', 3, 'c', 3),\n",
       " ('c', 1, 'a', 1),\n",
       " ('c', 1, 'a', 2),\n",
       " ('c', 1, 'a', 3),\n",
       " ('c', 1, 'b', 1),\n",
       " ('c', 1, 'b', 2),\n",
       " ('c', 1, 'b', 3),\n",
       " ('c', 1, 'c', 1),\n",
       " ('c', 1, 'c', 2),\n",
       " ('c', 1, 'c', 3),\n",
       " ('c', 2, 'a', 1),\n",
       " ('c', 2, 'a', 2),\n",
       " ('c', 2, 'a', 3),\n",
       " ('c', 2, 'b', 1),\n",
       " ('c', 2, 'b', 2),\n",
       " ('c', 2, 'b', 3),\n",
       " ('c', 2, 'c', 1),\n",
       " ('c', 2, 'c', 2),\n",
       " ('c', 2, 'c', 3),\n",
       " ('c', 3, 'a', 1),\n",
       " ('c', 3, 'a', 2),\n",
       " ('c', 3, 'a', 3),\n",
       " ('c', 3, 'b', 1),\n",
       " ('c', 3, 'b', 2),\n",
       " ('c', 3, 'b', 3),\n",
       " ('c', 3, 'c', 1),\n",
       " ('c', 3, 'c', 2),\n",
       " ('c', 3, 'c', 3)]"
      ]
     },
     "execution_count": 259,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Groupby"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```itertools.groupby``` class can be used to group repeating elements in an iterable together using an optional ```key```. Its initialisation signature can be viewed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 260,
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import groupby"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 261,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mInit signature:\u001b[0m \u001b[0mgroupby\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0miterable\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mkey\u001b[0m\u001b[1;33m=\u001b[0m\u001b[1;32mNone\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m     \n",
       "make an iterator that returns consecutive keys and groups from the iterable\n",
       "\n",
       "iterable\n",
       "  Elements to divide into groups according to the key function.\n",
       "key\n",
       "  A function for computing the group category for each element.\n",
       "  If the key function is not specified or is None, the element itself\n",
       "  is used for grouping.\n",
       "\u001b[1;31mType:\u001b[0m           type\n",
       "\u001b[1;31mSubclasses:\u001b[0m     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "groupby?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the simplest case, there is no ```key``` and therefore each unique value in the ```iterable``` is automatically taken to be a key. Each group is a collection of identical values that correspond to this key. The following ```tuple``` can be examined:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 262,
   "metadata": {},
   "outputs": [],
   "source": [
    "values = ('a', 'b', 'c', 'a', 'a', 'a', 'b', 'b', 'c', 'a')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In order to be grouped, the iterable must be sorted:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 263,
   "metadata": {},
   "outputs": [],
   "source": [
    "values = tuple(sorted(values))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 264,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['a', 'a', 'a', 'a', 'a', 'b', 'b', 'b', 'c', 'c']"
      ]
     },
     "execution_count": 264,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sorted(values)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An iterator of three groups can be created using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 265,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = groupby(values)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 266,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<itertools.groupby at 0x2b4c8175900>"
      ]
     },
     "execution_count": 266,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When ```next``` is used on the iterator, a ```tuple``` is displayed containing the ```key``` in the first position and an ```iterator``` of these grouped values in the second position:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 267,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('a', <itertools._grouper at 0x2b4c82242b0>)"
      ]
     },
     "execution_count": 267,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 268,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('b', <itertools._grouper at 0x2b4ca88f550>)"
      ]
     },
     "execution_count": 268,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 269,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('c', <itertools._grouper at 0x2b4c8225b40>)"
      ]
     },
     "execution_count": 269,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Recreating the iterator, each ```tuple``` can be unpacked and the ```key``` and ```group``` can be examined. To view all the elements in the group iterator, it can be cast into a ```tuple```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 270,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = groupby(values)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 271,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<itertools.groupby at 0x2b4ca771de0>"
      ]
     },
     "execution_count": 271,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 272,
   "metadata": {},
   "outputs": [],
   "source": [
    "key, group = next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 273,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'a'"
      ]
     },
     "execution_count": 273,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "key"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 274,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('a', 'a', 'a', 'a', 'a')"
      ]
     },
     "execution_count": 274,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(group)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 275,
   "metadata": {},
   "outputs": [],
   "source": [
    "key, group = next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 276,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'b'"
      ]
     },
     "execution_count": 276,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "key"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 277,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('b', 'b', 'b')"
      ]
     },
     "execution_count": 277,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(group)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 278,
   "metadata": {},
   "outputs": [],
   "source": [
    "key, group = next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 279,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'c'"
      ]
     },
     "execution_count": 279,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "key"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 280,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('c', 'c')"
      ]
     },
     "execution_count": 280,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(group)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The return value of the ```groupby``` class is an iterator of nested ```2``` element ```tuple``` instances which can be conceptualised as an item containing a ```key``` and ```iterator```. A ```dict``` instance ```mapping``` can be populated using a ```for``` loop:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 281,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = groupby(values)\n",
    "mapping = {}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 282,
   "metadata": {},
   "outputs": [],
   "source": [
    "for item in forward:\n",
    "    key = item[0]\n",
    "    group = item[1]\n",
    "    mapping[key] = tuple(group)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 283,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'a': ('a', 'a', 'a', 'a', 'a'), 'b': ('b', 'b', 'b'), 'c': ('c', 'c')}"
      ]
     },
     "execution_count": 283,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mapping"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now supposing the following tuple of ```values``` is created:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 284,
   "metadata": {},
   "outputs": [],
   "source": [
    "values = ('a', 'b', 'c', 'A', 'A', 'a', 'B', 'b', 'C', 'a')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Sorting it gives all the lower case letters first followed by all the upper case letters as the ordinal values of the lower case letters is smaller than that of the upper case letters:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 285,
   "metadata": {},
   "outputs": [],
   "source": [
    "values = sorted(values)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 286,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['A', 'A', 'B', 'C', 'a', 'a', 'a', 'b', 'b', 'c']"
      ]
     },
     "execution_count": 286,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "values"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now ```itertools.groupby``` can be used with a ```key```. This ```key``` can be assigned to a ```lamba``` expression which uses the ```str``` method ```islower``` to check to see if a ```value``` is a upper or lower case ```str``` instance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 287,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = itertools.groupby(values, \n",
    "                            key=lambda x: x.islower())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 288,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<itertools.groupby at 0x2b4ca770d60>"
      ]
     },
     "execution_count": 288,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "forward"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can be seen by calling ```next``` on the ```itertools.groupby``` iterator:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 289,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(False, <itertools._grouper at 0x2b4ca70d360>)"
      ]
     },
     "execution_count": 289,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 290,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(True, <itertools._grouper at 0x2b4ca90bb50>)"
      ]
     },
     "execution_count": 290,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(forward)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Recreating the iterator, a similar ```dict``` instance can be configured to before:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 291,
   "metadata": {},
   "outputs": [],
   "source": [
    "forward = itertools.groupby(values, \n",
    "                            key=lambda x: x.islower())\n",
    "mapping = {}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 292,
   "metadata": {},
   "outputs": [],
   "source": [
    "for item in forward:\n",
    "    if item[0] == False:\n",
    "        key = 'upper'\n",
    "    else:\n",
    "        key = 'lower'\n",
    "    group = item[1]\n",
    "    mapping[key] = tuple(group)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 293,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'upper': ('A', 'A', 'B', 'C'), 'lower': ('a', 'a', 'a', 'b', 'b', 'c')}"
      ]
     },
     "execution_count": 293,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mapping"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[Return to Anaconda Tutorial](../readme.md)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.12.1"
  },
  "vscode": {
   "interpreter": {
    "hash": "61808a9acc4b8515b668b4e06161b951f49c2459739faa6f724b9f3f5cc42d03"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}