Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
Следить 1
В избранное 0
Вики 捐赠
gooderp18绿色标准版
Вы не можете выбрать более 25 тем Темы должны начинаться с буквы или цифры, могут содержать дефисы(-) и должны содержать не более 35 символов.
Дерево: 0f75e31513
Ветки Теги
${ item.name }
Создать ветку ${ searchTerm }
из '0f75e31513'
${ noResults }
Green_GoodERP18_FSJ_Standard/python/Doc/html/library/itertools.html

1506 lines
162KB
Исходник Blame История 

  1. <!DOCTYPE html>

  2. 

  3. <html lang="en" data-content_root="../">

  4.   <head>

  5.     <meta charset="utf-8" />

  6.     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  7. <meta property="og:title" content="itertools — Functions creating iterators for efficient looping" />

  8. <meta property="og:type" content="website" />

  9. <meta property="og:url" content="https://docs.python.org/3/library/itertools.html" />

  10. <meta property="og:site_name" content="Python documentation" />

  11. <meta property="og:description" content="This module implements a number of iterator building blocks inspired by constructs from APL, Haskell, and SML. Each has been recast in a form suitable for Python. The module standardizes a core set..." />

  12. <meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />

  13. <meta property="og:image:alt" content="Python documentation" />

  14. <meta name="description" content="This module implements a number of iterator building blocks inspired by constructs from APL, Haskell, and SML. Each has been recast in a form suitable for Python. The module standardizes a core set..." />

  15. <meta property="og:image:width" content="200" />

  16. <meta property="og:image:height" content="200" />

  17. <meta name="theme-color" content="#3776ab" />

  18. 

  19.     <title>itertools — Functions creating iterators for efficient looping &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">

  20.     

  21.     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />

  22.     <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />

  23.     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />

  24.     

  25.     <script src="../_static/documentation_options.js?v=2c828074"></script>

  26.     <script src="../_static/doctools.js?v=888ff710"></script>

  27.     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>

  28.     

  29.     <script src="../_static/sidebar.js"></script>

  30.     

  31.     <link rel="search" type="application/opensearchdescription+xml"

  32.           title="Search within Python 3.12.3 documentation"

  33.           href="../_static/opensearch.xml"/>

  34.     <link rel="author" title="About these documents" href="../about.html" />

  35.     <link rel="index" title="Index" href="../genindex.html" />

  36.     <link rel="search" title="Search" href="../search.html" />

  37.     <link rel="copyright" title="Copyright" href="../copyright.html" />

  38.     <link rel="next" title="functools — Higher-order functions and operations on callable objects" href="functools.html" />

  39.     <link rel="prev" title="Functional Programming Modules" href="functional.html" />

  40.     <link rel="canonical" href="https://docs.python.org/3/library/itertools.html" />

  41.     

  42.       

  43.     

  44. 

  45.     

  46.     <style>

  47.       @media only screen {

  48.         table.full-width-table {

  49.             width: 100%;

  50.         }

  51.       }

  52.     </style>

  53. <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">

  54.     <link rel="shortcut icon" type="image/png" href="../_static/py.svg" />

  55.             <script type="text/javascript" src="../_static/copybutton.js"></script>

  56.             <script type="text/javascript" src="../_static/menu.js"></script>

  57.             <script type="text/javascript" src="../_static/search-focus.js"></script>

  58.             <script type="text/javascript" src="../_static/themetoggle.js"></script> 

  59. 

  60.   </head>

  61. <body>

  62. <div class="mobile-nav">

  63.     <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"

  64.            aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />

  65.     <nav class="nav-content" role="navigation">

  66.         <label for="menuToggler" class="toggler__label">

  67.             <span></span>

  68.         </label>

  69.         <span class="nav-items-wrapper">

  70.             <a href="https://www.python.org/" class="nav-logo">

  71.                 <img src="../_static/py.svg" alt="Python logo"/>

  72.             </a>

  73.             <span class="version_switcher_placeholder"></span>

  74.             <form role="search" class="search" action="../search.html" method="get">

  75.                 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">

  76.                     <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>

  77.                 </svg>

  78.                 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />

  79.                 <input type="submit" value="Go"/>

  80.             </form>

  81.         </span>

  82.     </nav>

  83.     <div class="menu-wrapper">

  84.         <nav class="menu" role="navigation" aria-label="main navigation">

  85.             <div class="language_switcher_placeholder"></div>

  86.             

  87. <label class="theme-selector-label">

  88.     Theme

  89.     <select class="theme-selector" oninput="activateTheme(this.value)">

  90.         <option value="auto" selected>Auto</option>

  91.         <option value="light">Light</option>

  92.         <option value="dark">Dark</option>

  93.     </select>

  94. </label>

  95.   <div>

  96.     <h3><a href="../contents.html">Table of Contents</a></h3>

  97.     <ul>

  98. <li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">itertools</span></code> — Functions creating iterators for efficient looping</a><ul>

  99. <li><a class="reference internal" href="#itertool-functions">Itertool Functions</a></li>

  100. <li><a class="reference internal" href="#itertools-recipes">Itertools Recipes</a></li>

  101. </ul>

  102. </li>

  103. </ul>

  104. 

  105.   </div>

  106.   <div>

  107.     <h4>Previous topic</h4>

  108.     <p class="topless"><a href="functional.html"

  109.                           title="previous chapter">Functional Programming Modules</a></p>

  110.   </div>

  111.   <div>

  112.     <h4>Next topic</h4>

  113.     <p class="topless"><a href="functools.html"

  114.                           title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">functools</span></code> — Higher-order functions and operations on callable objects</a></p>

  115.   </div>

  116.   <div role="note" aria-label="source link">

  117.     <h3>This Page</h3>

  118.     <ul class="this-page-menu">

  119.       <li><a href="../bugs.html">Report a Bug</a></li>

  120.       <li>

  121.         <a href="https://github.com/python/cpython/blob/main/Doc/library/itertools.rst"

  122.             rel="nofollow">Show Source

  123.         </a>

  124.       </li>

  125.     </ul>

  126.   </div>

  127.         </nav>

  128.     </div>

  129. </div>

  130. 

  131.   

  132.     <div class="related" role="navigation" aria-label="related navigation">

  133.       <h3>Navigation</h3>

  134.       <ul>

  135.         <li class="right" style="margin-right: 10px">

  136.           <a href="../genindex.html" title="General Index"

  137.              accesskey="I">index</a></li>

  138.         <li class="right" >

  139.           <a href="../py-modindex.html" title="Python Module Index"

  140.              >modules</a> |</li>

  141.         <li class="right" >

  142.           <a href="functools.html" title="functools — Higher-order functions and operations on callable objects"

  143.              accesskey="N">next</a> |</li>

  144.         <li class="right" >

  145.           <a href="functional.html" title="Functional Programming Modules"

  146.              accesskey="P">previous</a> |</li>

  147. 

  148.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  149.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  150.           <li class="switchers">

  151.             <div class="language_switcher_placeholder"></div>

  152.             <div class="version_switcher_placeholder"></div>

  153.           </li>

  154.           <li>

  155.               

  156.           </li>

  157.     <li id="cpython-language-and-version">

  158.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  159.     </li>

  160. 

  161.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  162.           <li class="nav-item nav-item-2"><a href="functional.html" accesskey="U">Functional Programming Modules</a> &#187;</li>

  163.         <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">itertools</span></code> — Functions creating iterators for efficient looping</a></li>

  164.                 <li class="right">

  165.                     

  166. 

  167.     <div class="inline-search" role="search">

  168.         <form class="inline-search" action="../search.html" method="get">

  169.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  170.           <input type="submit" value="Go" />

  171.         </form>

  172.     </div>

  173.                      |

  174.                 </li>

  175.             <li class="right">

  176. <label class="theme-selector-label">

  177.     Theme

  178.     <select class="theme-selector" oninput="activateTheme(this.value)">

  179.         <option value="auto" selected>Auto</option>

  180.         <option value="light">Light</option>

  181.         <option value="dark">Dark</option>

  182.     </select>

  183. </label> |</li>

  184.             

  185.       </ul>

  186.     </div>    

  187. 

  188.     <div class="document">

  189.       <div class="documentwrapper">

  190.         <div class="bodywrapper">

  191.           <div class="body" role="main">

  192.             

  193.   <section id="module-itertools">

  194. <span id="itertools-functions-creating-iterators-for-efficient-looping"></span><h1><a class="reference internal" href="#module-itertools" title="itertools: Functions creating iterators for efficient looping."><code class="xref py py-mod docutils literal notranslate"><span class="pre">itertools</span></code></a> — Functions creating iterators for efficient looping<a class="headerlink" href="#module-itertools" title="Link to this heading">¶</a></h1>

  195. <hr class="docutils" />

  196. <p>This module implements a number of <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a> building blocks inspired

  197. by constructs from APL, Haskell, and SML.  Each has been recast in a form

  198. suitable for Python.</p>

  199. <p>The module standardizes a core set of fast, memory efficient tools that are

  200. useful by themselves or in combination.  Together, they form an “iterator

  201. algebra” making it possible to construct specialized tools succinctly and

  202. efficiently in pure Python.</p>

  203. <p>For instance, SML provides a tabulation tool: <code class="docutils literal notranslate"><span class="pre">tabulate(f)</span></code> which produces a

  204. sequence <code class="docutils literal notranslate"><span class="pre">f(0),</span> <span class="pre">f(1),</span> <span class="pre">...</span></code>.  The same effect can be achieved in Python

  205. by combining <a class="reference internal" href="functions.html#map" title="map"><code class="xref py py-func docutils literal notranslate"><span class="pre">map()</span></code></a> and <a class="reference internal" href="#itertools.count" title="itertools.count"><code class="xref py py-func docutils literal notranslate"><span class="pre">count()</span></code></a> to form <code class="docutils literal notranslate"><span class="pre">map(f,</span> <span class="pre">count())</span></code>.</p>

  206. <p>These tools and their built-in counterparts also work well with the high-speed

  207. functions in the <a class="reference internal" href="operator.html#module-operator" title="operator: Functions corresponding to the standard operators."><code class="xref py py-mod docutils literal notranslate"><span class="pre">operator</span></code></a> module.  For example, the multiplication

  208. operator can be mapped across two vectors to form an efficient dot-product:

  209. <code class="docutils literal notranslate"><span class="pre">sum(starmap(operator.mul,</span> <span class="pre">zip(vec1,</span> <span class="pre">vec2,</span> <span class="pre">strict=True)))</span></code>.</p>

  210. <p><strong>Infinite iterators:</strong></p>

  211. <table class="docutils align-default">

  212. <thead>

  213. <tr class="row-odd"><th class="head"><p>Iterator</p></th>

  214. <th class="head"><p>Arguments</p></th>

  215. <th class="head"><p>Results</p></th>

  216. <th class="head"><p>Example</p></th>

  217. </tr>

  218. </thead>

  219. <tbody>

  220. <tr class="row-even"><td><p><a class="reference internal" href="#itertools.count" title="itertools.count"><code class="xref py py-func docutils literal notranslate"><span class="pre">count()</span></code></a></p></td>

  221. <td><p>[start[, step]]</p></td>

  222. <td><p>start, start+step, start+2*step, …</p></td>

  223. <td><p><code class="docutils literal notranslate"><span class="pre">count(10)</span> <span class="pre">→</span> <span class="pre">10</span> <span class="pre">11</span> <span class="pre">12</span> <span class="pre">13</span> <span class="pre">14</span> <span class="pre">...</span></code></p></td>

  224. </tr>

  225. <tr class="row-odd"><td><p><a class="reference internal" href="#itertools.cycle" title="itertools.cycle"><code class="xref py py-func docutils literal notranslate"><span class="pre">cycle()</span></code></a></p></td>

  226. <td><p>p</p></td>

  227. <td><p>p0, p1, … plast, p0, p1, …</p></td>

  228. <td><p><code class="docutils literal notranslate"><span class="pre">cycle('ABCD')</span> <span class="pre">→</span> <span class="pre">A</span> <span class="pre">B</span> <span class="pre">C</span> <span class="pre">D</span> <span class="pre">A</span> <span class="pre">B</span> <span class="pre">C</span> <span class="pre">D</span> <span class="pre">...</span></code></p></td>

  229. </tr>

  230. <tr class="row-even"><td><p><a class="reference internal" href="#itertools.repeat" title="itertools.repeat"><code class="xref py py-func docutils literal notranslate"><span class="pre">repeat()</span></code></a></p></td>

  231. <td><p>elem [,n]</p></td>

  232. <td><p>elem, elem, elem, … endlessly or up to n times</p></td>

  233. <td><p><code class="docutils literal notranslate"><span class="pre">repeat(10,</span> <span class="pre">3)</span> <span class="pre">→</span> <span class="pre">10</span> <span class="pre">10</span> <span class="pre">10</span></code></p></td>

  234. </tr>

  235. </tbody>

  236. </table>

  237. <p><strong>Iterators terminating on the shortest input sequence:</strong></p>

  238. <table class="docutils align-default">

  239. <thead>

  240. <tr class="row-odd"><th class="head"><p>Iterator</p></th>

  241. <th class="head"><p>Arguments</p></th>

  242. <th class="head"><p>Results</p></th>

  243. <th class="head"><p>Example</p></th>

  244. </tr>

  245. </thead>

  246. <tbody>

  247. <tr class="row-even"><td><p><a class="reference internal" href="#itertools.accumulate" title="itertools.accumulate"><code class="xref py py-func docutils literal notranslate"><span class="pre">accumulate()</span></code></a></p></td>

  248. <td><p>p [,func]</p></td>

  249. <td><p>p0, p0+p1, p0+p1+p2, …</p></td>

  250. <td><p><code class="docutils literal notranslate"><span class="pre">accumulate([1,2,3,4,5])</span> <span class="pre">→</span> <span class="pre">1</span> <span class="pre">3</span> <span class="pre">6</span> <span class="pre">10</span> <span class="pre">15</span></code></p></td>

  251. </tr>

  252. <tr class="row-odd"><td><p><a class="reference internal" href="#itertools.batched" title="itertools.batched"><code class="xref py py-func docutils literal notranslate"><span class="pre">batched()</span></code></a></p></td>

  253. <td><p>p, n</p></td>

  254. <td><p>(p0, p1, …, p_n-1), …</p></td>

  255. <td><p><code class="docutils literal notranslate"><span class="pre">batched('ABCDEFG',</span> <span class="pre">n=3)</span> <span class="pre">→</span> <span class="pre">ABC</span> <span class="pre">DEF</span> <span class="pre">G</span></code></p></td>

  256. </tr>

  257. <tr class="row-even"><td><p><a class="reference internal" href="#itertools.chain" title="itertools.chain"><code class="xref py py-func docutils literal notranslate"><span class="pre">chain()</span></code></a></p></td>

  258. <td><p>p, q, …</p></td>

  259. <td><p>p0, p1, … plast, q0, q1, …</p></td>

  260. <td><p><code class="docutils literal notranslate"><span class="pre">chain('ABC',</span> <span class="pre">'DEF')</span> <span class="pre">→</span> <span class="pre">A</span> <span class="pre">B</span> <span class="pre">C</span> <span class="pre">D</span> <span class="pre">E</span> <span class="pre">F</span></code></p></td>

  261. </tr>

  262. <tr class="row-odd"><td><p><a class="reference internal" href="#itertools.chain.from_iterable" title="itertools.chain.from_iterable"><code class="xref py py-func docutils literal notranslate"><span class="pre">chain.from_iterable()</span></code></a></p></td>

  263. <td><p>iterable</p></td>

  264. <td><p>p0, p1, … plast, q0, q1, …</p></td>

  265. <td><p><code class="docutils literal notranslate"><span class="pre">chain.from_iterable(['ABC',</span> <span class="pre">'DEF'])</span> <span class="pre">→</span> <span class="pre">A</span> <span class="pre">B</span> <span class="pre">C</span> <span class="pre">D</span> <span class="pre">E</span> <span class="pre">F</span></code></p></td>

  266. </tr>

  267. <tr class="row-even"><td><p><a class="reference internal" href="#itertools.compress" title="itertools.compress"><code class="xref py py-func docutils literal notranslate"><span class="pre">compress()</span></code></a></p></td>

  268. <td><p>data, selectors</p></td>

  269. <td><p>(d[0] if s[0]), (d[1] if s[1]), …</p></td>

  270. <td><p><code class="docutils literal notranslate"><span class="pre">compress('ABCDEF',</span> <span class="pre">[1,0,1,0,1,1])</span> <span class="pre">→</span> <span class="pre">A</span> <span class="pre">C</span> <span class="pre">E</span> <span class="pre">F</span></code></p></td>

  271. </tr>

  272. <tr class="row-odd"><td><p><a class="reference internal" href="#itertools.dropwhile" title="itertools.dropwhile"><code class="xref py py-func docutils literal notranslate"><span class="pre">dropwhile()</span></code></a></p></td>

  273. <td><p>predicate, seq</p></td>

  274. <td><p>seq[n], seq[n+1], starting when predicate fails</p></td>

  275. <td><p><code class="docutils literal notranslate"><span class="pre">dropwhile(lambda</span> <span class="pre">x:</span> <span class="pre">x&lt;5,</span> <span class="pre">[1,4,6,4,1])</span> <span class="pre">→</span> <span class="pre">6</span> <span class="pre">4</span> <span class="pre">1</span></code></p></td>

  276. </tr>

  277. <tr class="row-even"><td><p><a class="reference internal" href="#itertools.filterfalse" title="itertools.filterfalse"><code class="xref py py-func docutils literal notranslate"><span class="pre">filterfalse()</span></code></a></p></td>

  278. <td><p>predicate, seq</p></td>

  279. <td><p>elements of seq where predicate(elem) fails</p></td>

  280. <td><p><code class="docutils literal notranslate"><span class="pre">filterfalse(lambda</span> <span class="pre">x:</span> <span class="pre">x%2,</span> <span class="pre">range(10))</span> <span class="pre">→</span> <span class="pre">0</span> <span class="pre">2</span> <span class="pre">4</span> <span class="pre">6</span> <span class="pre">8</span></code></p></td>

  281. </tr>

  282. <tr class="row-odd"><td><p><a class="reference internal" href="#itertools.groupby" title="itertools.groupby"><code class="xref py py-func docutils literal notranslate"><span class="pre">groupby()</span></code></a></p></td>

  283. <td><p>iterable[, key]</p></td>

  284. <td><p>sub-iterators grouped by value of key(v)</p></td>

  285. <td></td>

  286. </tr>

  287. <tr class="row-even"><td><p><a class="reference internal" href="#itertools.islice" title="itertools.islice"><code class="xref py py-func docutils literal notranslate"><span class="pre">islice()</span></code></a></p></td>

  288. <td><p>seq, [start,] stop [, step]</p></td>

  289. <td><p>elements from seq[start:stop:step]</p></td>

  290. <td><p><code class="docutils literal notranslate"><span class="pre">islice('ABCDEFG',</span> <span class="pre">2,</span> <span class="pre">None)</span> <span class="pre">→</span> <span class="pre">C</span> <span class="pre">D</span> <span class="pre">E</span> <span class="pre">F</span> <span class="pre">G</span></code></p></td>

  291. </tr>

  292. <tr class="row-odd"><td><p><a class="reference internal" href="#itertools.pairwise" title="itertools.pairwise"><code class="xref py py-func docutils literal notranslate"><span class="pre">pairwise()</span></code></a></p></td>

  293. <td><p>iterable</p></td>

  294. <td><p>(p[0], p[1]), (p[1], p[2])</p></td>

  295. <td><p><code class="docutils literal notranslate"><span class="pre">pairwise('ABCDEFG')</span> <span class="pre">→</span> <span class="pre">AB</span> <span class="pre">BC</span> <span class="pre">CD</span> <span class="pre">DE</span> <span class="pre">EF</span> <span class="pre">FG</span></code></p></td>

  296. </tr>

  297. <tr class="row-even"><td><p><a class="reference internal" href="#itertools.starmap" title="itertools.starmap"><code class="xref py py-func docutils literal notranslate"><span class="pre">starmap()</span></code></a></p></td>

  298. <td><p>func, seq</p></td>

  299. <td><p>func(*seq[0]), func(*seq[1]), …</p></td>

  300. <td><p><code class="docutils literal notranslate"><span class="pre">starmap(pow,</span> <span class="pre">[(2,5),</span> <span class="pre">(3,2),</span> <span class="pre">(10,3)])</span> <span class="pre">→</span> <span class="pre">32</span> <span class="pre">9</span> <span class="pre">1000</span></code></p></td>

  301. </tr>

  302. <tr class="row-odd"><td><p><a class="reference internal" href="#itertools.takewhile" title="itertools.takewhile"><code class="xref py py-func docutils literal notranslate"><span class="pre">takewhile()</span></code></a></p></td>

  303. <td><p>predicate, seq</p></td>

  304. <td><p>seq[0], seq[1], until predicate fails</p></td>

  305. <td><p><code class="docutils literal notranslate"><span class="pre">takewhile(lambda</span> <span class="pre">x:</span> <span class="pre">x&lt;5,</span> <span class="pre">[1,4,6,4,1])</span> <span class="pre">→</span> <span class="pre">1</span> <span class="pre">4</span></code></p></td>

  306. </tr>

  307. <tr class="row-even"><td><p><a class="reference internal" href="#itertools.tee" title="itertools.tee"><code class="xref py py-func docutils literal notranslate"><span class="pre">tee()</span></code></a></p></td>

  308. <td><p>it, n</p></td>

  309. <td><p>it1, it2, … itn  splits one iterator into n</p></td>

  310. <td></td>

  311. </tr>

  312. <tr class="row-odd"><td><p><a class="reference internal" href="#itertools.zip_longest" title="itertools.zip_longest"><code class="xref py py-func docutils literal notranslate"><span class="pre">zip_longest()</span></code></a></p></td>

  313. <td><p>p, q, …</p></td>

  314. <td><p>(p[0], q[0]), (p[1], q[1]), …</p></td>

  315. <td><p><code class="docutils literal notranslate"><span class="pre">zip_longest('ABCD',</span> <span class="pre">'xy',</span> <span class="pre">fillvalue='-')</span> <span class="pre">→</span> <span class="pre">Ax</span> <span class="pre">By</span> <span class="pre">C-</span> <span class="pre">D-</span></code></p></td>

  316. </tr>

  317. </tbody>

  318. </table>

  319. <p><strong>Combinatoric iterators:</strong></p>

  320. <table class="docutils align-default">

  321. <thead>

  322. <tr class="row-odd"><th class="head"><p>Iterator</p></th>

  323. <th class="head"><p>Arguments</p></th>

  324. <th class="head"><p>Results</p></th>

  325. </tr>

  326. </thead>

  327. <tbody>

  328. <tr class="row-even"><td><p><a class="reference internal" href="#itertools.product" title="itertools.product"><code class="xref py py-func docutils literal notranslate"><span class="pre">product()</span></code></a></p></td>

  329. <td><p>p, q, … [repeat=1]</p></td>

  330. <td><p>cartesian product, equivalent to a nested for-loop</p></td>

  331. </tr>

  332. <tr class="row-odd"><td><p><a class="reference internal" href="#itertools.permutations" title="itertools.permutations"><code class="xref py py-func docutils literal notranslate"><span class="pre">permutations()</span></code></a></p></td>

  333. <td><p>p[, r]</p></td>

  334. <td><p>r-length tuples, all possible orderings, no repeated elements</p></td>

  335. </tr>

  336. <tr class="row-even"><td><p><a class="reference internal" href="#itertools.combinations" title="itertools.combinations"><code class="xref py py-func docutils literal notranslate"><span class="pre">combinations()</span></code></a></p></td>

  337. <td><p>p, r</p></td>

  338. <td><p>r-length tuples, in sorted order, no repeated elements</p></td>

  339. </tr>

  340. <tr class="row-odd"><td><p><a class="reference internal" href="#itertools.combinations_with_replacement" title="itertools.combinations_with_replacement"><code class="xref py py-func docutils literal notranslate"><span class="pre">combinations_with_replacement()</span></code></a></p></td>

  341. <td><p>p, r</p></td>

  342. <td><p>r-length tuples, in sorted order, with repeated elements</p></td>

  343. </tr>

  344. </tbody>

  345. </table>

  346. <table class="docutils align-default">

  347. <thead>

  348. <tr class="row-odd"><th class="head"><p>Examples</p></th>

  349. <th class="head"><p>Results</p></th>

  350. </tr>

  351. </thead>

  352. <tbody>

  353. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">product('ABCD',</span> <span class="pre">repeat=2)</span></code></p></td>

  354. <td><p><code class="docutils literal notranslate"><span class="pre">AA</span> <span class="pre">AB</span> <span class="pre">AC</span> <span class="pre">AD</span> <span class="pre">BA</span> <span class="pre">BB</span> <span class="pre">BC</span> <span class="pre">BD</span> <span class="pre">CA</span> <span class="pre">CB</span> <span class="pre">CC</span> <span class="pre">CD</span> <span class="pre">DA</span> <span class="pre">DB</span> <span class="pre">DC</span> <span class="pre">DD</span></code></p></td>

  355. </tr>

  356. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">permutations('ABCD',</span> <span class="pre">2)</span></code></p></td>

  357. <td><p><code class="docutils literal notranslate"><span class="pre">AB</span> <span class="pre">AC</span> <span class="pre">AD</span> <span class="pre">BA</span> <span class="pre">BC</span> <span class="pre">BD</span> <span class="pre">CA</span> <span class="pre">CB</span> <span class="pre">CD</span> <span class="pre">DA</span> <span class="pre">DB</span> <span class="pre">DC</span></code></p></td>

  358. </tr>

  359. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">combinations('ABCD',</span> <span class="pre">2)</span></code></p></td>

  360. <td><p><code class="docutils literal notranslate"><span class="pre">AB</span> <span class="pre">AC</span> <span class="pre">AD</span> <span class="pre">BC</span> <span class="pre">BD</span> <span class="pre">CD</span></code></p></td>

  361. </tr>

  362. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">combinations_with_replacement('ABCD', 2)</span></code></p></td>

  363. <td><p><code class="docutils literal notranslate"><span class="pre">AA</span> <span class="pre">AB</span> <span class="pre">AC</span> <span class="pre">AD</span> <span class="pre">BB</span> <span class="pre">BC</span> <span class="pre">BD</span> <span class="pre">CC</span> <span class="pre">CD</span> <span class="pre">DD</span></code></p></td>

  364. </tr>

  365. </tbody>

  366. </table>

  367. <section id="itertool-functions">

  368. <span id="itertools-functions"></span><h2>Itertool Functions<a class="headerlink" href="#itertool-functions" title="Link to this heading">¶</a></h2>

  369. <p>The following module functions all construct and return iterators. Some provide

  370. streams of infinite length, so they should only be accessed by functions or

  371. loops that truncate the stream.</p>

  372. <dl class="py function">

  373. <dt class="sig sig-object py" id="itertools.accumulate">

  374. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">accumulate</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">iterable</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">func</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">initial=None</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#itertools.accumulate" title="Link to this definition">¶</a></dt>

  375. <dd><p>Make an iterator that returns accumulated sums, or accumulated

  376. results of other binary functions (specified via the optional

  377. <em>func</em> argument).</p>

  378. <p>If <em>func</em> is supplied, it should be a function

  379. of two arguments. Elements of the input <em>iterable</em> may be any type

  380. that can be accepted as arguments to <em>func</em>. (For example, with

  381. the default operation of addition, elements may be any addable

  382. type including <a class="reference internal" href="decimal.html#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> or

  383. <a class="reference internal" href="fractions.html#fractions.Fraction" title="fractions.Fraction"><code class="xref py py-class docutils literal notranslate"><span class="pre">Fraction</span></code></a>.)</p>

  384. <p>Usually, the number of elements output matches the input iterable.

  385. However, if the keyword argument <em>initial</em> is provided, the

  386. accumulation leads off with the <em>initial</em> value so that the output

  387. has one more element than the input iterable.</p>

  388. <p>Roughly equivalent to:</p>

  389. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">accumulate</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">func</span><span class="o">=</span><span class="n">operator</span><span class="o">.</span><span class="n">add</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">initial</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  390.     <span class="s1">&#39;Return running totals&#39;</span>

  391.     <span class="c1"># accumulate([1,2,3,4,5]) → 1 3 6 10 15</span>

  392.     <span class="c1"># accumulate([1,2,3,4,5], initial=100) → 100 101 103 106 110 115</span>

  393.     <span class="c1"># accumulate([1,2,3,4,5], operator.mul) → 1 2 6 24 120</span>

  394.     <span class="n">it</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>

  395.     <span class="n">total</span> <span class="o">=</span> <span class="n">initial</span>

  396.     <span class="k">if</span> <span class="n">initial</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  397.         <span class="k">try</span><span class="p">:</span>

  398.             <span class="n">total</span> <span class="o">=</span> <span class="nb">next</span><span class="p">(</span><span class="n">it</span><span class="p">)</span>

  399.         <span class="k">except</span> <span class="ne">StopIteration</span><span class="p">:</span>

  400.             <span class="k">return</span>

  401.     <span class="k">yield</span> <span class="n">total</span>

  402.     <span class="k">for</span> <span class="n">element</span> <span class="ow">in</span> <span class="n">it</span><span class="p">:</span>

  403.         <span class="n">total</span> <span class="o">=</span> <span class="n">func</span><span class="p">(</span><span class="n">total</span><span class="p">,</span> <span class="n">element</span><span class="p">)</span>

  404.         <span class="k">yield</span> <span class="n">total</span>

  405. </pre></div>

  406. </div>

  407. <p>There are a number of uses for the <em>func</em> argument.  It can be set to

  408. <a class="reference internal" href="functions.html#min" title="min"><code class="xref py py-func docutils literal notranslate"><span class="pre">min()</span></code></a> for a running minimum, <a class="reference internal" href="functions.html#max" title="max"><code class="xref py py-func docutils literal notranslate"><span class="pre">max()</span></code></a> for a running maximum, or

  409. <a class="reference internal" href="operator.html#operator.mul" title="operator.mul"><code class="xref py py-func docutils literal notranslate"><span class="pre">operator.mul()</span></code></a> for a running product.  Amortization tables can be

  410. built by accumulating interest and applying payments:</p>

  411. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">data</span> <span class="o">=</span> <span class="p">[</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">9</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">8</span><span class="p">]</span>

  412. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">accumulate</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">operator</span><span class="o">.</span><span class="n">mul</span><span class="p">))</span>     <span class="c1"># running product</span>

  413. <span class="go">[3, 12, 72, 144, 144, 1296, 0, 0, 0, 0]</span>

  414. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">accumulate</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="nb">max</span><span class="p">))</span>              <span class="c1"># running maximum</span>

  415. <span class="go">[3, 4, 6, 6, 6, 9, 9, 9, 9, 9]</span>

  416. 

  417. <span class="go"># Amortize a 5% loan of 1000 with 10 annual payments of 90</span>

  418. <span class="gp">&gt;&gt;&gt; </span><span class="n">account_update</span> <span class="o">=</span> <span class="k">lambda</span> <span class="n">bal</span><span class="p">,</span> <span class="n">pmt</span><span class="p">:</span> <span class="nb">round</span><span class="p">(</span><span class="n">bal</span> <span class="o">*</span> <span class="mf">1.05</span><span class="p">)</span> <span class="o">+</span> <span class="n">pmt</span>

  419. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">accumulate</span><span class="p">(</span><span class="n">repeat</span><span class="p">(</span><span class="o">-</span><span class="mi">90</span><span class="p">,</span> <span class="mi">10</span><span class="p">),</span> <span class="n">account_update</span><span class="p">,</span> <span class="n">initial</span><span class="o">=</span><span class="mi">1_000</span><span class="p">))</span>

  420. <span class="go">[1000, 960, 918, 874, 828, 779, 728, 674, 618, 559, 497]</span>

  421. </pre></div>

  422. </div>

  423. <p>See <a class="reference internal" href="functools.html#functools.reduce" title="functools.reduce"><code class="xref py py-func docutils literal notranslate"><span class="pre">functools.reduce()</span></code></a> for a similar function that returns only the

  424. final accumulated value.</p>

  425. <div class="versionadded">

  426. <p><span class="versionmodified added">New in version 3.2.</span></p>

  427. </div>

  428. <div class="versionchanged">

  429. <p><span class="versionmodified changed">Changed in version 3.3: </span>Added the optional <em>func</em> parameter.</p>

  430. </div>

  431. <div class="versionchanged">

  432. <p><span class="versionmodified changed">Changed in version 3.8: </span>Added the optional <em>initial</em> parameter.</p>

  433. </div>

  434. </dd></dl>

  435. 

  436. <dl class="py function">

  437. <dt class="sig sig-object py" id="itertools.batched">

  438. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">batched</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">iterable</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">n</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#itertools.batched" title="Link to this definition">¶</a></dt>

  439. <dd><p>Batch data from the <em>iterable</em> into tuples of length <em>n</em>. The last

  440. batch may be shorter than <em>n</em>.</p>

  441. <p>Loops over the input iterable and accumulates data into tuples up to

  442. size <em>n</em>.  The input is consumed lazily, just enough to fill a batch.

  443. The result is yielded as soon as the batch is full or when the input

  444. iterable is exhausted:</p>

  445. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">flattened_data</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;roses&#39;</span><span class="p">,</span> <span class="s1">&#39;red&#39;</span><span class="p">,</span> <span class="s1">&#39;violets&#39;</span><span class="p">,</span> <span class="s1">&#39;blue&#39;</span><span class="p">,</span> <span class="s1">&#39;sugar&#39;</span><span class="p">,</span> <span class="s1">&#39;sweet&#39;</span><span class="p">]</span>

  446. <span class="gp">&gt;&gt;&gt; </span><span class="n">unflattened</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">batched</span><span class="p">(</span><span class="n">flattened_data</span><span class="p">,</span> <span class="mi">2</span><span class="p">))</span>

  447. <span class="gp">&gt;&gt;&gt; </span><span class="n">unflattened</span>

  448. <span class="go">[(&#39;roses&#39;, &#39;red&#39;), (&#39;violets&#39;, &#39;blue&#39;), (&#39;sugar&#39;, &#39;sweet&#39;)]</span>

  449. 

  450. <span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">batch</span> <span class="ow">in</span> <span class="n">batched</span><span class="p">(</span><span class="s1">&#39;ABCDEFG&#39;</span><span class="p">,</span> <span class="mi">3</span><span class="p">):</span>

  451. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">batch</span><span class="p">)</span>

  452. <span class="gp">...</span>

  453. <span class="go">(&#39;A&#39;, &#39;B&#39;, &#39;C&#39;)</span>

  454. <span class="go">(&#39;D&#39;, &#39;E&#39;, &#39;F&#39;)</span>

  455. <span class="go">(&#39;G&#39;,)</span>

  456. </pre></div>

  457. </div>

  458. <p>Roughly equivalent to:</p>

  459. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">batched</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">n</span><span class="p">):</span>

  460.     <span class="c1"># batched(&#39;ABCDEFG&#39;, 3) → ABC DEF G</span>

  461.     <span class="k">if</span> <span class="n">n</span> <span class="o">&lt;</span> <span class="mi">1</span><span class="p">:</span>

  462.         <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s1">&#39;n must be at least one&#39;</span><span class="p">)</span>

  463.     <span class="n">it</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>

  464.     <span class="k">while</span> <span class="n">batch</span> <span class="o">:=</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">islice</span><span class="p">(</span><span class="n">it</span><span class="p">,</span> <span class="n">n</span><span class="p">)):</span>

  465.         <span class="k">yield</span> <span class="n">batch</span>

  466. </pre></div>

  467. </div>

  468. <div class="versionadded">

  469. <p><span class="versionmodified added">New in version 3.12.</span></p>

  470. </div>

  471. </dd></dl>

  472. 

  473. <dl class="py function">

  474. <dt class="sig sig-object py" id="itertools.chain">

  475. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">chain</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">iterables</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#itertools.chain" title="Link to this definition">¶</a></dt>

  476. <dd><p>Make an iterator that returns elements from the first iterable until it is

  477. exhausted, then proceeds to the next iterable, until all of the iterables are

  478. exhausted.  Used for treating consecutive sequences as a single sequence.

  479. Roughly equivalent to:</p>

  480. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">chain</span><span class="p">(</span><span class="o">*</span><span class="n">iterables</span><span class="p">):</span>

  481.     <span class="c1"># chain(&#39;ABC&#39;, &#39;DEF&#39;) → A B C D E F</span>

  482.     <span class="k">for</span> <span class="n">it</span> <span class="ow">in</span> <span class="n">iterables</span><span class="p">:</span>

  483.         <span class="k">for</span> <span class="n">element</span> <span class="ow">in</span> <span class="n">it</span><span class="p">:</span>

  484.             <span class="k">yield</span> <span class="n">element</span>

  485. </pre></div>

  486. </div>

  487. </dd></dl>

  488. 

  489. <dl class="py method">

  490. <dt class="sig sig-object py" id="itertools.chain.from_iterable">

  491. <em class="property"><span class="pre">classmethod</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chain.</span></span><span class="sig-name descname"><span class="pre">from_iterable</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">iterable</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#itertools.chain.from_iterable" title="Link to this definition">¶</a></dt>

  492. <dd><p>Alternate constructor for <a class="reference internal" href="#itertools.chain" title="itertools.chain"><code class="xref py py-func docutils literal notranslate"><span class="pre">chain()</span></code></a>.  Gets chained inputs from a

  493. single iterable argument that is evaluated lazily.  Roughly equivalent to:</p>

  494. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">from_iterable</span><span class="p">(</span><span class="n">iterables</span><span class="p">):</span>

  495.     <span class="c1"># chain.from_iterable([&#39;ABC&#39;, &#39;DEF&#39;]) → A B C D E F</span>

  496.     <span class="k">for</span> <span class="n">it</span> <span class="ow">in</span> <span class="n">iterables</span><span class="p">:</span>

  497.         <span class="k">for</span> <span class="n">element</span> <span class="ow">in</span> <span class="n">it</span><span class="p">:</span>

  498.             <span class="k">yield</span> <span class="n">element</span>

  499. </pre></div>

  500. </div>

  501. </dd></dl>

  502. 

  503. <dl class="py function">

  504. <dt class="sig sig-object py" id="itertools.combinations">

  505. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">combinations</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">iterable</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">r</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#itertools.combinations" title="Link to this definition">¶</a></dt>

  506. <dd><p>Return <em>r</em> length subsequences of elements from the input <em>iterable</em>.</p>

  507. <p>The combination tuples are emitted in lexicographic ordering according to

  508. the order of the input <em>iterable</em>. So, if the input <em>iterable</em> is sorted,

  509. the output tuples will be produced in sorted order.</p>

  510. <p>Elements are treated as unique based on their position, not on their

  511. value.  So if the input elements are unique, there will be no repeated

  512. values in each combination.</p>

  513. <p>Roughly equivalent to:</p>

  514. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">combinations</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">r</span><span class="p">):</span>

  515.     <span class="c1"># combinations(&#39;ABCD&#39;, 2) → AB AC AD BC BD CD</span>

  516.     <span class="c1"># combinations(range(4), 3) → 012 013 023 123</span>

  517.     <span class="n">pool</span> <span class="o">=</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>

  518.     <span class="n">n</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">pool</span><span class="p">)</span>

  519.     <span class="k">if</span> <span class="n">r</span> <span class="o">&gt;</span> <span class="n">n</span><span class="p">:</span>

  520.         <span class="k">return</span>

  521.     <span class="n">indices</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">r</span><span class="p">))</span>

  522.     <span class="k">yield</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">pool</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">)</span>

  523.     <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>

  524.         <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">reversed</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">r</span><span class="p">)):</span>

  525.             <span class="k">if</span> <span class="n">indices</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">!=</span> <span class="n">i</span> <span class="o">+</span> <span class="n">n</span> <span class="o">-</span> <span class="n">r</span><span class="p">:</span>

  526.                 <span class="k">break</span>

  527.         <span class="k">else</span><span class="p">:</span>

  528.             <span class="k">return</span>

  529.         <span class="n">indices</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+=</span> <span class="mi">1</span>

  530.         <span class="k">for</span> <span class="n">j</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">i</span><span class="o">+</span><span class="mi">1</span><span class="p">,</span> <span class="n">r</span><span class="p">):</span>

  531.             <span class="n">indices</span><span class="p">[</span><span class="n">j</span><span class="p">]</span> <span class="o">=</span> <span class="n">indices</span><span class="p">[</span><span class="n">j</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> <span class="o">+</span> <span class="mi">1</span>

  532.         <span class="k">yield</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">pool</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">)</span>

  533. </pre></div>

  534. </div>

  535. <p>The code for <a class="reference internal" href="#itertools.combinations" title="itertools.combinations"><code class="xref py py-func docutils literal notranslate"><span class="pre">combinations()</span></code></a> can be also expressed as a subsequence

  536. of <a class="reference internal" href="#itertools.permutations" title="itertools.permutations"><code class="xref py py-func docutils literal notranslate"><span class="pre">permutations()</span></code></a> after filtering entries where the elements are not

  537. in sorted order (according to their position in the input pool):</p>

  538. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">combinations</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">r</span><span class="p">):</span>

  539.     <span class="n">pool</span> <span class="o">=</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>

  540.     <span class="n">n</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">pool</span><span class="p">)</span>

  541.     <span class="k">for</span> <span class="n">indices</span> <span class="ow">in</span> <span class="n">permutations</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">n</span><span class="p">),</span> <span class="n">r</span><span class="p">):</span>

  542.         <span class="k">if</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">indices</span><span class="p">)</span> <span class="o">==</span> <span class="nb">list</span><span class="p">(</span><span class="n">indices</span><span class="p">):</span>

  543.             <span class="k">yield</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">pool</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">)</span>

  544. </pre></div>

  545. </div>

  546. <p>The number of items returned is <code class="docutils literal notranslate"><span class="pre">n!</span> <span class="pre">/</span> <span class="pre">r!</span> <span class="pre">/</span> <span class="pre">(n-r)!</span></code> when <code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre">&lt;=</span> <span class="pre">r</span> <span class="pre">&lt;=</span> <span class="pre">n</span></code>

  547. or zero when <code class="docutils literal notranslate"><span class="pre">r</span> <span class="pre">&gt;</span> <span class="pre">n</span></code>.</p>

  548. </dd></dl>

  549. 

  550. <dl class="py function">

  551. <dt class="sig sig-object py" id="itertools.combinations_with_replacement">

  552. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">combinations_with_replacement</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">iterable</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">r</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#itertools.combinations_with_replacement" title="Link to this definition">¶</a></dt>

  553. <dd><p>Return <em>r</em> length subsequences of elements from the input <em>iterable</em>

  554. allowing individual elements to be repeated more than once.</p>

  555. <p>The combination tuples are emitted in lexicographic ordering according to

  556. the order of the input <em>iterable</em>. So, if the input <em>iterable</em> is sorted,

  557. the output tuples will be produced in sorted order.</p>

  558. <p>Elements are treated as unique based on their position, not on their

  559. value.  So if the input elements are unique, the generated combinations

  560. will also be unique.</p>

  561. <p>Roughly equivalent to:</p>

  562. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">combinations_with_replacement</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">r</span><span class="p">):</span>

  563.     <span class="c1"># combinations_with_replacement(&#39;ABC&#39;, 2) → AA AB AC BB BC CC</span>

  564.     <span class="n">pool</span> <span class="o">=</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>

  565.     <span class="n">n</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">pool</span><span class="p">)</span>

  566.     <span class="k">if</span> <span class="ow">not</span> <span class="n">n</span> <span class="ow">and</span> <span class="n">r</span><span class="p">:</span>

  567.         <span class="k">return</span>

  568.     <span class="n">indices</span> <span class="o">=</span> <span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">*</span> <span class="n">r</span>

  569.     <span class="k">yield</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">pool</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">)</span>

  570.     <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>

  571.         <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">reversed</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">r</span><span class="p">)):</span>

  572.             <span class="k">if</span> <span class="n">indices</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">!=</span> <span class="n">n</span> <span class="o">-</span> <span class="mi">1</span><span class="p">:</span>

  573.                 <span class="k">break</span>

  574.         <span class="k">else</span><span class="p">:</span>

  575.             <span class="k">return</span>

  576.         <span class="n">indices</span><span class="p">[</span><span class="n">i</span><span class="p">:]</span> <span class="o">=</span> <span class="p">[</span><span class="n">indices</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="mi">1</span><span class="p">]</span> <span class="o">*</span> <span class="p">(</span><span class="n">r</span> <span class="o">-</span> <span class="n">i</span><span class="p">)</span>

  577.         <span class="k">yield</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">pool</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">)</span>

  578. </pre></div>

  579. </div>

  580. <p>The code for <a class="reference internal" href="#itertools.combinations_with_replacement" title="itertools.combinations_with_replacement"><code class="xref py py-func docutils literal notranslate"><span class="pre">combinations_with_replacement()</span></code></a> can be also expressed as

  581. a subsequence of <a class="reference internal" href="#itertools.product" title="itertools.product"><code class="xref py py-func docutils literal notranslate"><span class="pre">product()</span></code></a> after filtering entries where the elements

  582. are not in sorted order (according to their position in the input pool):</p>

  583. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">combinations_with_replacement</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">r</span><span class="p">):</span>

  584.     <span class="n">pool</span> <span class="o">=</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>

  585.     <span class="n">n</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">pool</span><span class="p">)</span>

  586.     <span class="k">for</span> <span class="n">indices</span> <span class="ow">in</span> <span class="n">product</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">n</span><span class="p">),</span> <span class="n">repeat</span><span class="o">=</span><span class="n">r</span><span class="p">):</span>

  587.         <span class="k">if</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">indices</span><span class="p">)</span> <span class="o">==</span> <span class="nb">list</span><span class="p">(</span><span class="n">indices</span><span class="p">):</span>

  588.             <span class="k">yield</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">pool</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">)</span>

  589. </pre></div>

  590. </div>

  591. <p>The number of items returned is <code class="docutils literal notranslate"><span class="pre">(n+r-1)!</span> <span class="pre">/</span> <span class="pre">r!</span> <span class="pre">/</span> <span class="pre">(n-1)!</span></code> when <code class="docutils literal notranslate"><span class="pre">n</span> <span class="pre">&gt;</span> <span class="pre">0</span></code>.</p>

  592. <div class="versionadded">

  593. <p><span class="versionmodified added">New in version 3.1.</span></p>

  594. </div>

  595. </dd></dl>

  596. 

  597. <dl class="py function">

  598. <dt class="sig sig-object py" id="itertools.compress">

  599. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">compress</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">selectors</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#itertools.compress" title="Link to this definition">¶</a></dt>

  600. <dd><p>Make an iterator that filters elements from <em>data</em> returning only those that

  601. have a corresponding element in <em>selectors</em> that evaluates to <code class="docutils literal notranslate"><span class="pre">True</span></code>.

  602. Stops when either the <em>data</em> or <em>selectors</em> iterables has been exhausted.

  603. Roughly equivalent to:</p>

  604. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">compress</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">selectors</span><span class="p">):</span>

  605.     <span class="c1"># compress(&#39;ABCDEF&#39;, [1,0,1,0,1,1]) → A C E F</span>

  606.     <span class="k">return</span> <span class="p">(</span><span class="n">d</span> <span class="k">for</span> <span class="n">d</span><span class="p">,</span> <span class="n">s</span> <span class="ow">in</span> <span class="nb">zip</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">selectors</span><span class="p">)</span> <span class="k">if</span> <span class="n">s</span><span class="p">)</span>

  607. </pre></div>

  608. </div>

  609. <div class="versionadded">

  610. <p><span class="versionmodified added">New in version 3.1.</span></p>

  611. </div>

  612. </dd></dl>

  613. 

  614. <dl class="py function">

  615. <dt class="sig sig-object py" id="itertools.count">

  616. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">count</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">start</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">step</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#itertools.count" title="Link to this definition">¶</a></dt>

  617. <dd><p>Make an iterator that returns evenly spaced values starting with number <em>start</em>. Often

  618. used as an argument to <a class="reference internal" href="functions.html#map" title="map"><code class="xref py py-func docutils literal notranslate"><span class="pre">map()</span></code></a> to generate consecutive data points.

  619. Also, used with <a class="reference internal" href="functions.html#zip" title="zip"><code class="xref py py-func docutils literal notranslate"><span class="pre">zip()</span></code></a> to add sequence numbers.  Roughly equivalent to:</p>

  620. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">count</span><span class="p">(</span><span class="n">start</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">step</span><span class="o">=</span><span class="mi">1</span><span class="p">):</span>

  621.     <span class="c1"># count(10) → 10 11 12 13 14 ...</span>

  622.     <span class="c1"># count(2.5, 0.5) → 2.5 3.0 3.5 ...</span>

  623.     <span class="n">n</span> <span class="o">=</span> <span class="n">start</span>

  624.     <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>

  625.         <span class="k">yield</span> <span class="n">n</span>

  626.         <span class="n">n</span> <span class="o">+=</span> <span class="n">step</span>

  627. </pre></div>

  628. </div>

  629. <p>When counting with floating point numbers, better accuracy can sometimes be

  630. achieved by substituting multiplicative code such as: <code class="docutils literal notranslate"><span class="pre">(start</span> <span class="pre">+</span> <span class="pre">step</span> <span class="pre">*</span> <span class="pre">i</span>

  631. <span class="pre">for</span> <span class="pre">i</span> <span class="pre">in</span> <span class="pre">count())</span></code>.</p>

  632. <div class="versionchanged">

  633. <p><span class="versionmodified changed">Changed in version 3.1: </span>Added <em>step</em> argument and allowed non-integer arguments.</p>

  634. </div>

  635. </dd></dl>

  636. 

  637. <dl class="py function">

  638. <dt class="sig sig-object py" id="itertools.cycle">

  639. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">cycle</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">iterable</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#itertools.cycle" title="Link to this definition">¶</a></dt>

  640. <dd><p>Make an iterator returning elements from the iterable and saving a copy of each.

  641. When the iterable is exhausted, return elements from the saved copy.  Repeats

  642. indefinitely.  Roughly equivalent to:</p>

  643. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">cycle</span><span class="p">(</span><span class="n">iterable</span><span class="p">):</span>

  644.     <span class="c1"># cycle(&#39;ABCD&#39;) → A B C D A B C D A B C D ...</span>

  645.     <span class="n">saved</span> <span class="o">=</span> <span class="p">[]</span>

  646.     <span class="k">for</span> <span class="n">element</span> <span class="ow">in</span> <span class="n">iterable</span><span class="p">:</span>

  647.         <span class="k">yield</span> <span class="n">element</span>

  648.         <span class="n">saved</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">element</span><span class="p">)</span>

  649.     <span class="k">while</span> <span class="n">saved</span><span class="p">:</span>

  650.         <span class="k">for</span> <span class="n">element</span> <span class="ow">in</span> <span class="n">saved</span><span class="p">:</span>

  651.               <span class="k">yield</span> <span class="n">element</span>

  652. </pre></div>

  653. </div>

  654. <p>Note, this member of the toolkit may require significant auxiliary storage

  655. (depending on the length of the iterable).</p>

  656. </dd></dl>

  657. 

  658. <dl class="py function">

  659. <dt class="sig sig-object py" id="itertools.dropwhile">

  660. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">dropwhile</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">predicate</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">iterable</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#itertools.dropwhile" title="Link to this definition">¶</a></dt>

  661. <dd><p>Make an iterator that drops elements from the iterable as long as the predicate

  662. is true; afterwards, returns every element.  Note, the iterator does not produce

  663. <em>any</em> output until the predicate first becomes false, so it may have a lengthy

  664. start-up time.  Roughly equivalent to:</p>

  665. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">dropwhile</span><span class="p">(</span><span class="n">predicate</span><span class="p">,</span> <span class="n">iterable</span><span class="p">):</span>

  666.     <span class="c1"># dropwhile(lambda x: x&lt;5, [1,4,6,4,1]) → 6 4 1</span>

  667.     <span class="n">iterable</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>

  668.     <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">iterable</span><span class="p">:</span>

  669.         <span class="k">if</span> <span class="ow">not</span> <span class="n">predicate</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>

  670.             <span class="k">yield</span> <span class="n">x</span>

  671.             <span class="k">break</span>

  672.     <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">iterable</span><span class="p">:</span>

  673.         <span class="k">yield</span> <span class="n">x</span>

  674. </pre></div>

  675. </div>

  676. </dd></dl>

  677. 

  678. <dl class="py function">

  679. <dt class="sig sig-object py" id="itertools.filterfalse">

  680. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">filterfalse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">predicate</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">iterable</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#itertools.filterfalse" title="Link to this definition">¶</a></dt>

  681. <dd><p>Make an iterator that filters elements from iterable returning only those for

  682. which the predicate is false. If <em>predicate</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, return the items

  683. that are false. Roughly equivalent to:</p>

  684. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">filterfalse</span><span class="p">(</span><span class="n">predicate</span><span class="p">,</span> <span class="n">iterable</span><span class="p">):</span>

  685.     <span class="c1"># filterfalse(lambda x: x%2, range(10)) → 0 2 4 6 8</span>

  686.     <span class="k">if</span> <span class="n">predicate</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  687.         <span class="n">predicate</span> <span class="o">=</span> <span class="nb">bool</span>

  688.     <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">iterable</span><span class="p">:</span>

  689.         <span class="k">if</span> <span class="ow">not</span> <span class="n">predicate</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>

  690.             <span class="k">yield</span> <span class="n">x</span>

  691. </pre></div>

  692. </div>

  693. </dd></dl>

  694. 

  695. <dl class="py function">

  696. <dt class="sig sig-object py" id="itertools.groupby">

  697. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">groupby</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">iterable</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">key</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#itertools.groupby" title="Link to this definition">¶</a></dt>

  698. <dd><p>Make an iterator that returns consecutive keys and groups from the <em>iterable</em>.

  699. The <em>key</em> is a function computing a key value for each element.  If not

  700. specified or is <code class="docutils literal notranslate"><span class="pre">None</span></code>, <em>key</em> defaults to an identity function and returns

  701. the element unchanged.  Generally, the iterable needs to already be sorted on

  702. the same key function.</p>

  703. <p>The operation of <a class="reference internal" href="#itertools.groupby" title="itertools.groupby"><code class="xref py py-func docutils literal notranslate"><span class="pre">groupby()</span></code></a> is similar to the <code class="docutils literal notranslate"><span class="pre">uniq</span></code> filter in Unix.  It

  704. generates a break or new group every time the value of the key function changes

  705. (which is why it is usually necessary to have sorted the data using the same key

  706. function).  That behavior differs from SQL’s GROUP BY which aggregates common

  707. elements regardless of their input order.</p>

  708. <p>The returned group is itself an iterator that shares the underlying iterable

  709. with <a class="reference internal" href="#itertools.groupby" title="itertools.groupby"><code class="xref py py-func docutils literal notranslate"><span class="pre">groupby()</span></code></a>.  Because the source is shared, when the <a class="reference internal" href="#itertools.groupby" title="itertools.groupby"><code class="xref py py-func docutils literal notranslate"><span class="pre">groupby()</span></code></a>

  710. object is advanced, the previous group is no longer visible.  So, if that data

  711. is needed later, it should be stored as a list:</p>

  712. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">groups</span> <span class="o">=</span> <span class="p">[]</span>

  713. <span class="n">uniquekeys</span> <span class="o">=</span> <span class="p">[]</span>

  714. <span class="n">data</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="n">keyfunc</span><span class="p">)</span>

  715. <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">g</span> <span class="ow">in</span> <span class="n">groupby</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">keyfunc</span><span class="p">):</span>

  716.     <span class="n">groups</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="n">g</span><span class="p">))</span>      <span class="c1"># Store group iterator as a list</span>

  717.     <span class="n">uniquekeys</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">k</span><span class="p">)</span>

  718. </pre></div>

  719. </div>

  720. <p><a class="reference internal" href="#itertools.groupby" title="itertools.groupby"><code class="xref py py-func docutils literal notranslate"><span class="pre">groupby()</span></code></a> is roughly equivalent to:</p>

  721. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">groupby</span><span class="p">:</span>

  722.     <span class="c1"># [k for k, g in groupby(&#39;AAAABBBCCDAABBB&#39;)] → A B C D A B</span>

  723.     <span class="c1"># [list(g) for k, g in groupby(&#39;AAAABBBCCD&#39;)] → AAAA BBB CC D</span>

  724. 

  725.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">iterable</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  726.         <span class="k">if</span> <span class="n">key</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  727.             <span class="n">key</span> <span class="o">=</span> <span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="n">x</span>

  728.         <span class="bp">self</span><span class="o">.</span><span class="n">keyfunc</span> <span class="o">=</span> <span class="n">key</span>

  729.         <span class="bp">self</span><span class="o">.</span><span class="n">it</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>

  730.         <span class="bp">self</span><span class="o">.</span><span class="n">tgtkey</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">currkey</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">currvalue</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>

  731. 

  732.     <span class="k">def</span> <span class="fm">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  733.         <span class="k">return</span> <span class="bp">self</span>

  734. 

  735.     <span class="k">def</span> <span class="fm">__next__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  736.         <span class="bp">self</span><span class="o">.</span><span class="n">id</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>

  737.         <span class="k">while</span> <span class="bp">self</span><span class="o">.</span><span class="n">currkey</span> <span class="o">==</span> <span class="bp">self</span><span class="o">.</span><span class="n">tgtkey</span><span class="p">:</span>

  738.             <span class="bp">self</span><span class="o">.</span><span class="n">currvalue</span> <span class="o">=</span> <span class="nb">next</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">it</span><span class="p">)</span>    <span class="c1"># Exit on StopIteration</span>

  739.             <span class="bp">self</span><span class="o">.</span><span class="n">currkey</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">keyfunc</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">currvalue</span><span class="p">)</span>

  740.         <span class="bp">self</span><span class="o">.</span><span class="n">tgtkey</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">currkey</span>

  741.         <span class="k">return</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">currkey</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">_grouper</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">tgtkey</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">id</span><span class="p">))</span>

  742. 

  743.     <span class="k">def</span> <span class="nf">_grouper</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">tgtkey</span><span class="p">,</span> <span class="nb">id</span><span class="p">):</span>

  744.         <span class="k">while</span> <span class="bp">self</span><span class="o">.</span><span class="n">id</span> <span class="ow">is</span> <span class="nb">id</span> <span class="ow">and</span> <span class="bp">self</span><span class="o">.</span><span class="n">currkey</span> <span class="o">==</span> <span class="n">tgtkey</span><span class="p">:</span>

  745.             <span class="k">yield</span> <span class="bp">self</span><span class="o">.</span><span class="n">currvalue</span>

  746.             <span class="k">try</span><span class="p">:</span>

  747.                 <span class="bp">self</span><span class="o">.</span><span class="n">currvalue</span> <span class="o">=</span> <span class="nb">next</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">it</span><span class="p">)</span>

  748.             <span class="k">except</span> <span class="ne">StopIteration</span><span class="p">:</span>

  749.                 <span class="k">return</span>

  750.             <span class="bp">self</span><span class="o">.</span><span class="n">currkey</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">keyfunc</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">currvalue</span><span class="p">)</span>

  751. </pre></div>

  752. </div>

  753. </dd></dl>

  754. 

  755. <dl class="py function">

  756. <dt class="sig sig-object py" id="itertools.islice">

  757. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">islice</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">iterable</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">stop</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#itertools.islice" title="Link to this definition">¶</a></dt>

  758. <dt class="sig sig-object py">

  759. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">islice</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">iterable</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">start</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">stop</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">step</span></span></em><span class="optional">]</span><span class="sig-paren">)</span></dt>

  760. <dd><p>Make an iterator that returns selected elements from the iterable. If <em>start</em> is

  761. non-zero, then elements from the iterable are skipped until start is reached.

  762. Afterward, elements are returned consecutively unless <em>step</em> is set higher than

  763. one which results in items being skipped.  If <em>stop</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, then iteration

  764. continues until the iterator is exhausted, if at all; otherwise, it stops at the

  765. specified position.</p>

  766. <p>If <em>start</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, then iteration starts at zero. If <em>step</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>,

  767. then the step defaults to one.</p>

  768. <p>Unlike regular slicing, <a class="reference internal" href="#itertools.islice" title="itertools.islice"><code class="xref py py-func docutils literal notranslate"><span class="pre">islice()</span></code></a> does not support negative values for

  769. <em>start</em>, <em>stop</em>, or <em>step</em>.  Can be used to extract related fields from

  770. data where the internal structure has been flattened (for example, a

  771. multi-line report may list a name field on every third line).</p>

  772. <p>Roughly equivalent to:</p>

  773. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">islice</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">):</span>

  774.     <span class="c1"># islice(&#39;ABCDEFG&#39;, 2) → A B</span>

  775.     <span class="c1"># islice(&#39;ABCDEFG&#39;, 2, 4) → C D</span>

  776.     <span class="c1"># islice(&#39;ABCDEFG&#39;, 2, None) → C D E F G</span>

  777.     <span class="c1"># islice(&#39;ABCDEFG&#39;, 0, None, 2) → A C E G</span>

  778.     <span class="n">s</span> <span class="o">=</span> <span class="nb">slice</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">)</span>

  779.     <span class="n">start</span><span class="p">,</span> <span class="n">stop</span><span class="p">,</span> <span class="n">step</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">start</span> <span class="ow">or</span> <span class="mi">0</span><span class="p">,</span> <span class="n">s</span><span class="o">.</span><span class="n">stop</span> <span class="ow">or</span> <span class="n">sys</span><span class="o">.</span><span class="n">maxsize</span><span class="p">,</span> <span class="n">s</span><span class="o">.</span><span class="n">step</span> <span class="ow">or</span> <span class="mi">1</span>

  780.     <span class="n">it</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">start</span><span class="p">,</span> <span class="n">stop</span><span class="p">,</span> <span class="n">step</span><span class="p">))</span>

  781.     <span class="k">try</span><span class="p">:</span>

  782.         <span class="n">nexti</span> <span class="o">=</span> <span class="nb">next</span><span class="p">(</span><span class="n">it</span><span class="p">)</span>

  783.     <span class="k">except</span> <span class="ne">StopIteration</span><span class="p">:</span>

  784.         <span class="c1"># Consume *iterable* up to the *start* position.</span>

  785.         <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">element</span> <span class="ow">in</span> <span class="nb">zip</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">start</span><span class="p">),</span> <span class="n">iterable</span><span class="p">):</span>

  786.             <span class="k">pass</span>

  787.         <span class="k">return</span>

  788.     <span class="k">try</span><span class="p">:</span>

  789.         <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">element</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">iterable</span><span class="p">):</span>

  790.             <span class="k">if</span> <span class="n">i</span> <span class="o">==</span> <span class="n">nexti</span><span class="p">:</span>

  791.                 <span class="k">yield</span> <span class="n">element</span>

  792.                 <span class="n">nexti</span> <span class="o">=</span> <span class="nb">next</span><span class="p">(</span><span class="n">it</span><span class="p">)</span>

  793.     <span class="k">except</span> <span class="ne">StopIteration</span><span class="p">:</span>

  794.         <span class="c1"># Consume to *stop*.</span>

  795.         <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">element</span> <span class="ow">in</span> <span class="nb">zip</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">i</span> <span class="o">+</span> <span class="mi">1</span><span class="p">,</span> <span class="n">stop</span><span class="p">),</span> <span class="n">iterable</span><span class="p">):</span>

  796.             <span class="k">pass</span>

  797. </pre></div>

  798. </div>

  799. </dd></dl>

  800. 

  801. <dl class="py function">

  802. <dt class="sig sig-object py" id="itertools.pairwise">

  803. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">pairwise</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">iterable</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#itertools.pairwise" title="Link to this definition">¶</a></dt>

  804. <dd><p>Return successive overlapping pairs taken from the input <em>iterable</em>.</p>

  805. <p>The number of 2-tuples in the output iterator will be one fewer than the

  806. number of inputs.  It will be empty if the input iterable has fewer than

  807. two values.</p>

  808. <p>Roughly equivalent to:</p>

  809. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">pairwise</span><span class="p">(</span><span class="n">iterable</span><span class="p">):</span>

  810.     <span class="c1"># pairwise(&#39;ABCDEFG&#39;) → AB BC CD DE EF FG</span>

  811.     <span class="n">iterator</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>

  812.     <span class="n">a</span> <span class="o">=</span> <span class="nb">next</span><span class="p">(</span><span class="n">iterator</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>

  813.     <span class="k">for</span> <span class="n">b</span> <span class="ow">in</span> <span class="n">iterator</span><span class="p">:</span>

  814.         <span class="k">yield</span> <span class="n">a</span><span class="p">,</span> <span class="n">b</span>

  815.         <span class="n">a</span> <span class="o">=</span> <span class="n">b</span>

  816. </pre></div>

  817. </div>

  818. <div class="versionadded">

  819. <p><span class="versionmodified added">New in version 3.10.</span></p>

  820. </div>

  821. </dd></dl>

  822. 

  823. <dl class="py function">

  824. <dt class="sig sig-object py" id="itertools.permutations">

  825. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">permutations</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">iterable</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">r</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#itertools.permutations" title="Link to this definition">¶</a></dt>

  826. <dd><p>Return successive <em>r</em> length permutations of elements in the <em>iterable</em>.</p>

  827. <p>If <em>r</em> is not specified or is <code class="docutils literal notranslate"><span class="pre">None</span></code>, then <em>r</em> defaults to the length

  828. of the <em>iterable</em> and all possible full-length permutations

  829. are generated.</p>

  830. <p>The permutation tuples are emitted in lexicographic order according to

  831. the order of the input <em>iterable</em>. So, if the input <em>iterable</em> is sorted,

  832. the output tuples will be produced in sorted order.</p>

  833. <p>Elements are treated as unique based on their position, not on their

  834. value.  So if the input elements are unique, there will be no repeated

  835. values within a permutation.</p>

  836. <p>Roughly equivalent to:</p>

  837. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">permutations</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">r</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  838.     <span class="c1"># permutations(&#39;ABCD&#39;, 2) → AB AC AD BA BC BD CA CB CD DA DB DC</span>

  839.     <span class="c1"># permutations(range(3)) → 012 021 102 120 201 210</span>

  840.     <span class="n">pool</span> <span class="o">=</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>

  841.     <span class="n">n</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">pool</span><span class="p">)</span>

  842.     <span class="n">r</span> <span class="o">=</span> <span class="n">n</span> <span class="k">if</span> <span class="n">r</span> <span class="ow">is</span> <span class="kc">None</span> <span class="k">else</span> <span class="n">r</span>

  843.     <span class="k">if</span> <span class="n">r</span> <span class="o">&gt;</span> <span class="n">n</span><span class="p">:</span>

  844.         <span class="k">return</span>

  845.     <span class="n">indices</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">n</span><span class="p">))</span>

  846.     <span class="n">cycles</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">n</span><span class="p">,</span> <span class="n">n</span><span class="o">-</span><span class="n">r</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">))</span>

  847.     <span class="k">yield</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">pool</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">[:</span><span class="n">r</span><span class="p">])</span>

  848.     <span class="k">while</span> <span class="n">n</span><span class="p">:</span>

  849.         <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">reversed</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">r</span><span class="p">)):</span>

  850.             <span class="n">cycles</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">-=</span> <span class="mi">1</span>

  851.             <span class="k">if</span> <span class="n">cycles</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>

  852.                 <span class="n">indices</span><span class="p">[</span><span class="n">i</span><span class="p">:]</span> <span class="o">=</span> <span class="n">indices</span><span class="p">[</span><span class="n">i</span><span class="o">+</span><span class="mi">1</span><span class="p">:]</span> <span class="o">+</span> <span class="n">indices</span><span class="p">[</span><span class="n">i</span><span class="p">:</span><span class="n">i</span><span class="o">+</span><span class="mi">1</span><span class="p">]</span>

  853.                 <span class="n">cycles</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">n</span> <span class="o">-</span> <span class="n">i</span>

  854.             <span class="k">else</span><span class="p">:</span>

  855.                 <span class="n">j</span> <span class="o">=</span> <span class="n">cycles</span><span class="p">[</span><span class="n">i</span><span class="p">]</span>

  856.                 <span class="n">indices</span><span class="p">[</span><span class="n">i</span><span class="p">],</span> <span class="n">indices</span><span class="p">[</span><span class="o">-</span><span class="n">j</span><span class="p">]</span> <span class="o">=</span> <span class="n">indices</span><span class="p">[</span><span class="o">-</span><span class="n">j</span><span class="p">],</span> <span class="n">indices</span><span class="p">[</span><span class="n">i</span><span class="p">]</span>

  857.                 <span class="k">yield</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">pool</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">[:</span><span class="n">r</span><span class="p">])</span>

  858.                 <span class="k">break</span>

  859.         <span class="k">else</span><span class="p">:</span>

  860.             <span class="k">return</span>

  861. </pre></div>

  862. </div>

  863. <p>The code for <a class="reference internal" href="#itertools.permutations" title="itertools.permutations"><code class="xref py py-func docutils literal notranslate"><span class="pre">permutations()</span></code></a> can be also expressed as a subsequence of

  864. <a class="reference internal" href="#itertools.product" title="itertools.product"><code class="xref py py-func docutils literal notranslate"><span class="pre">product()</span></code></a>, filtered to exclude entries with repeated elements (those

  865. from the same position in the input pool):</p>

  866. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">permutations</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">r</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  867.     <span class="n">pool</span> <span class="o">=</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>

  868.     <span class="n">n</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">pool</span><span class="p">)</span>

  869.     <span class="n">r</span> <span class="o">=</span> <span class="n">n</span> <span class="k">if</span> <span class="n">r</span> <span class="ow">is</span> <span class="kc">None</span> <span class="k">else</span> <span class="n">r</span>

  870.     <span class="k">for</span> <span class="n">indices</span> <span class="ow">in</span> <span class="n">product</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">n</span><span class="p">),</span> <span class="n">repeat</span><span class="o">=</span><span class="n">r</span><span class="p">):</span>

  871.         <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="nb">set</span><span class="p">(</span><span class="n">indices</span><span class="p">))</span> <span class="o">==</span> <span class="n">r</span><span class="p">:</span>

  872.             <span class="k">yield</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">pool</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">)</span>

  873. </pre></div>

  874. </div>

  875. <p>The number of items returned is <code class="docutils literal notranslate"><span class="pre">n!</span> <span class="pre">/</span> <span class="pre">(n-r)!</span></code> when <code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre">&lt;=</span> <span class="pre">r</span> <span class="pre">&lt;=</span> <span class="pre">n</span></code>

  876. or zero when <code class="docutils literal notranslate"><span class="pre">r</span> <span class="pre">&gt;</span> <span class="pre">n</span></code>.</p>

  877. </dd></dl>

  878. 

  879. <dl class="py function">

  880. <dt class="sig sig-object py" id="itertools.product">

  881. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">product</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">iterables</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">repeat</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#itertools.product" title="Link to this definition">¶</a></dt>

  882. <dd><p>Cartesian product of input iterables.</p>

  883. <p>Roughly equivalent to nested for-loops in a generator expression. For example,

  884. <code class="docutils literal notranslate"><span class="pre">product(A,</span> <span class="pre">B)</span></code> returns the same as <code class="docutils literal notranslate"><span class="pre">((x,y)</span> <span class="pre">for</span> <span class="pre">x</span> <span class="pre">in</span> <span class="pre">A</span> <span class="pre">for</span> <span class="pre">y</span> <span class="pre">in</span> <span class="pre">B)</span></code>.</p>

  885. <p>The nested loops cycle like an odometer with the rightmost element advancing

  886. on every iteration.  This pattern creates a lexicographic ordering so that if

  887. the input’s iterables are sorted, the product tuples are emitted in sorted

  888. order.</p>

  889. <p>To compute the product of an iterable with itself, specify the number of

  890. repetitions with the optional <em>repeat</em> keyword argument.  For example,

  891. <code class="docutils literal notranslate"><span class="pre">product(A,</span> <span class="pre">repeat=4)</span></code> means the same as <code class="docutils literal notranslate"><span class="pre">product(A,</span> <span class="pre">A,</span> <span class="pre">A,</span> <span class="pre">A)</span></code>.</p>

  892. <p>This function is roughly equivalent to the following code, except that the

  893. actual implementation does not build up intermediate results in memory:</p>

  894. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">product</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="n">repeat</span><span class="o">=</span><span class="mi">1</span><span class="p">):</span>

  895.     <span class="c1"># product(&#39;ABCD&#39;, &#39;xy&#39;) → Ax Ay Bx By Cx Cy Dx Dy</span>

  896.     <span class="c1"># product(range(2), repeat=3) → 000 001 010 011 100 101 110 111</span>

  897.     <span class="n">pools</span> <span class="o">=</span> <span class="p">[</span><span class="nb">tuple</span><span class="p">(</span><span class="n">pool</span><span class="p">)</span> <span class="k">for</span> <span class="n">pool</span> <span class="ow">in</span> <span class="n">args</span><span class="p">]</span> <span class="o">*</span> <span class="n">repeat</span>

  898.     <span class="n">result</span> <span class="o">=</span> <span class="p">[[]]</span>

  899.     <span class="k">for</span> <span class="n">pool</span> <span class="ow">in</span> <span class="n">pools</span><span class="p">:</span>

  900.         <span class="n">result</span> <span class="o">=</span> <span class="p">[</span><span class="n">x</span><span class="o">+</span><span class="p">[</span><span class="n">y</span><span class="p">]</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">result</span> <span class="k">for</span> <span class="n">y</span> <span class="ow">in</span> <span class="n">pool</span><span class="p">]</span>

  901.     <span class="k">for</span> <span class="n">prod</span> <span class="ow">in</span> <span class="n">result</span><span class="p">:</span>

  902.         <span class="k">yield</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">prod</span><span class="p">)</span>

  903. </pre></div>

  904. </div>

  905. <p>Before <a class="reference internal" href="#itertools.product" title="itertools.product"><code class="xref py py-func docutils literal notranslate"><span class="pre">product()</span></code></a> runs, it completely consumes the input iterables,

  906. keeping pools of values in memory to generate the products.  Accordingly,

  907. it is only useful with finite inputs.</p>

  908. </dd></dl>

  909. 

  910. <dl class="py function">

  911. <dt class="sig sig-object py" id="itertools.repeat">

  912. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">repeat</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">object</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">times</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#itertools.repeat" title="Link to this definition">¶</a></dt>

  913. <dd><p>Make an iterator that returns <em>object</em> over and over again. Runs indefinitely

  914. unless the <em>times</em> argument is specified.</p>

  915. <p>Roughly equivalent to:</p>

  916. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">repeat</span><span class="p">(</span><span class="nb">object</span><span class="p">,</span> <span class="n">times</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  917.     <span class="c1"># repeat(10, 3) → 10 10 10</span>

  918.     <span class="k">if</span> <span class="n">times</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  919.         <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>

  920.             <span class="k">yield</span> <span class="nb">object</span>

  921.     <span class="k">else</span><span class="p">:</span>

  922.         <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">times</span><span class="p">):</span>

  923.             <span class="k">yield</span> <span class="nb">object</span>

  924. </pre></div>

  925. </div>

  926. <p>A common use for <em>repeat</em> is to supply a stream of constant values to <em>map</em>

  927. or <em>zip</em>:</p>

  928. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="nb">map</span><span class="p">(</span><span class="nb">pow</span><span class="p">,</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">),</span> <span class="n">repeat</span><span class="p">(</span><span class="mi">2</span><span class="p">)))</span>

  929. <span class="go">[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]</span>

  930. </pre></div>

  931. </div>

  932. </dd></dl>

  933. 

  934. <dl class="py function">

  935. <dt class="sig sig-object py" id="itertools.starmap">

  936. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">starmap</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">function</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">iterable</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#itertools.starmap" title="Link to this definition">¶</a></dt>

  937. <dd><p>Make an iterator that computes the function using arguments obtained from

  938. the iterable.  Used instead of <a class="reference internal" href="functions.html#map" title="map"><code class="xref py py-func docutils literal notranslate"><span class="pre">map()</span></code></a> when argument parameters are already

  939. grouped in tuples from a single iterable (when the data has been

  940. “pre-zipped”).</p>

  941. <p>The difference between <a class="reference internal" href="functions.html#map" title="map"><code class="xref py py-func docutils literal notranslate"><span class="pre">map()</span></code></a> and <a class="reference internal" href="#itertools.starmap" title="itertools.starmap"><code class="xref py py-func docutils literal notranslate"><span class="pre">starmap()</span></code></a> parallels the

  942. distinction between <code class="docutils literal notranslate"><span class="pre">function(a,b)</span></code> and <code class="docutils literal notranslate"><span class="pre">function(*c)</span></code>. Roughly

  943. equivalent to:</p>

  944. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">starmap</span><span class="p">(</span><span class="n">function</span><span class="p">,</span> <span class="n">iterable</span><span class="p">):</span>

  945.     <span class="c1"># starmap(pow, [(2,5), (3,2), (10,3)]) → 32 9 1000</span>

  946.     <span class="k">for</span> <span class="n">args</span> <span class="ow">in</span> <span class="n">iterable</span><span class="p">:</span>

  947.         <span class="k">yield</span> <span class="n">function</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">)</span>

  948. </pre></div>

  949. </div>

  950. </dd></dl>

  951. 

  952. <dl class="py function">

  953. <dt class="sig sig-object py" id="itertools.takewhile">

  954. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">takewhile</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">predicate</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">iterable</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#itertools.takewhile" title="Link to this definition">¶</a></dt>

  955. <dd><p>Make an iterator that returns elements from the iterable as long as the

  956. predicate is true.  Roughly equivalent to:</p>

  957. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">takewhile</span><span class="p">(</span><span class="n">predicate</span><span class="p">,</span> <span class="n">iterable</span><span class="p">):</span>

  958.     <span class="c1"># takewhile(lambda x: x&lt;5, [1,4,6,4,1]) → 1 4</span>

  959.     <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">iterable</span><span class="p">:</span>

  960.         <span class="k">if</span> <span class="n">predicate</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>

  961.             <span class="k">yield</span> <span class="n">x</span>

  962.         <span class="k">else</span><span class="p">:</span>

  963.             <span class="k">break</span>

  964. </pre></div>

  965. </div>

  966. <p>Note, the element that first fails the predicate condition is

  967. consumed from the input iterator and there is no way to access it.

  968. This could be an issue if an application wants to further consume the

  969. input iterator after takewhile has been run to exhaustion.  To work

  970. around this problem, consider using <a class="reference external" href="https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.before_and_after">more-iterools before_and_after()</a>

  971. instead.</p>

  972. </dd></dl>

  973. 

  974. <dl class="py function">

  975. <dt class="sig sig-object py" id="itertools.tee">

  976. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">tee</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">iterable</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">n</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">2</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#itertools.tee" title="Link to this definition">¶</a></dt>

  977. <dd><p>Return <em>n</em> independent iterators from a single iterable.</p>

  978. <p>The following Python code helps explain what <em>tee</em> does (although the actual

  979. implementation is more complex and uses only a single underlying

  980. <abbr title="first-in, first-out">FIFO</abbr> queue):</p>

  981. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">tee</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">n</span><span class="o">=</span><span class="mi">2</span><span class="p">):</span>

  982.     <span class="n">it</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>

  983.     <span class="n">deques</span> <span class="o">=</span> <span class="p">[</span><span class="n">collections</span><span class="o">.</span><span class="n">deque</span><span class="p">()</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">n</span><span class="p">)]</span>

  984.     <span class="k">def</span> <span class="nf">gen</span><span class="p">(</span><span class="n">mydeque</span><span class="p">):</span>

  985.         <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>

  986.             <span class="k">if</span> <span class="ow">not</span> <span class="n">mydeque</span><span class="p">:</span>             <span class="c1"># when the local deque is empty</span>

  987.                 <span class="k">try</span><span class="p">:</span>

  988.                     <span class="n">newval</span> <span class="o">=</span> <span class="nb">next</span><span class="p">(</span><span class="n">it</span><span class="p">)</span>   <span class="c1"># fetch a new value and</span>

  989.                 <span class="k">except</span> <span class="ne">StopIteration</span><span class="p">:</span>

  990.                     <span class="k">return</span>

  991.                 <span class="k">for</span> <span class="n">d</span> <span class="ow">in</span> <span class="n">deques</span><span class="p">:</span>        <span class="c1"># load it to all the deques</span>

  992.                     <span class="n">d</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">newval</span><span class="p">)</span>

  993.             <span class="k">yield</span> <span class="n">mydeque</span><span class="o">.</span><span class="n">popleft</span><span class="p">()</span>

  994.     <span class="k">return</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">gen</span><span class="p">(</span><span class="n">d</span><span class="p">)</span> <span class="k">for</span> <span class="n">d</span> <span class="ow">in</span> <span class="n">deques</span><span class="p">)</span>

  995. </pre></div>

  996. </div>

  997. <p>Once a <a class="reference internal" href="#itertools.tee" title="itertools.tee"><code class="xref py py-func docutils literal notranslate"><span class="pre">tee()</span></code></a> has been created, the original <em>iterable</em> should not be

  998. used anywhere else; otherwise, the <em>iterable</em> could get advanced without

  999. the tee objects being informed.</p>

  1000. <p><code class="docutils literal notranslate"><span class="pre">tee</span></code> iterators are not threadsafe. A <a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a> may be

  1001. raised when simultaneously using iterators returned by the same <a class="reference internal" href="#itertools.tee" title="itertools.tee"><code class="xref py py-func docutils literal notranslate"><span class="pre">tee()</span></code></a>

  1002. call, even if the original <em>iterable</em> is threadsafe.</p>

  1003. <p>This itertool may require significant auxiliary storage (depending on how

  1004. much temporary data needs to be stored). In general, if one iterator uses

  1005. most or all of the data before another iterator starts, it is faster to use

  1006. <a class="reference internal" href="stdtypes.html#list" title="list"><code class="xref py py-func docutils literal notranslate"><span class="pre">list()</span></code></a> instead of <a class="reference internal" href="#itertools.tee" title="itertools.tee"><code class="xref py py-func docutils literal notranslate"><span class="pre">tee()</span></code></a>.</p>

  1007. </dd></dl>

  1008. 

  1009. <dl class="py function">

  1010. <dt class="sig sig-object py" id="itertools.zip_longest">

  1011. <span class="sig-prename descclassname"><span class="pre">itertools.</span></span><span class="sig-name descname"><span class="pre">zip_longest</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">iterables</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fillvalue</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#itertools.zip_longest" title="Link to this definition">¶</a></dt>

  1012. <dd><p>Make an iterator that aggregates elements from each of the iterables. If the

  1013. iterables are of uneven length, missing values are filled-in with <em>fillvalue</em>.

  1014. Iteration continues until the longest iterable is exhausted.  Roughly equivalent to:</p>

  1015. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">zip_longest</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="n">fillvalue</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  1016.     <span class="c1"># zip_longest(&#39;ABCD&#39;, &#39;xy&#39;, fillvalue=&#39;-&#39;) → Ax By C- D-</span>

  1017.     <span class="n">iterators</span> <span class="o">=</span> <span class="p">[</span><span class="nb">iter</span><span class="p">(</span><span class="n">it</span><span class="p">)</span> <span class="k">for</span> <span class="n">it</span> <span class="ow">in</span> <span class="n">args</span><span class="p">]</span>

  1018.     <span class="n">num_active</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">iterators</span><span class="p">)</span>

  1019.     <span class="k">if</span> <span class="ow">not</span> <span class="n">num_active</span><span class="p">:</span>

  1020.         <span class="k">return</span>

  1021.     <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>

  1022.         <span class="n">values</span> <span class="o">=</span> <span class="p">[]</span>

  1023.         <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">it</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">iterators</span><span class="p">):</span>

  1024.             <span class="k">try</span><span class="p">:</span>

  1025.                 <span class="n">value</span> <span class="o">=</span> <span class="nb">next</span><span class="p">(</span><span class="n">it</span><span class="p">)</span>

  1026.             <span class="k">except</span> <span class="ne">StopIteration</span><span class="p">:</span>

  1027.                 <span class="n">num_active</span> <span class="o">-=</span> <span class="mi">1</span>

  1028.                 <span class="k">if</span> <span class="ow">not</span> <span class="n">num_active</span><span class="p">:</span>

  1029.                     <span class="k">return</span>

  1030.                 <span class="n">iterators</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">repeat</span><span class="p">(</span><span class="n">fillvalue</span><span class="p">)</span>

  1031.                 <span class="n">value</span> <span class="o">=</span> <span class="n">fillvalue</span>

  1032.             <span class="n">values</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>

  1033.         <span class="k">yield</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">values</span><span class="p">)</span>

  1034. </pre></div>

  1035. </div>

  1036. <p>If one of the iterables is potentially infinite, then the <a class="reference internal" href="#itertools.zip_longest" title="itertools.zip_longest"><code class="xref py py-func docutils literal notranslate"><span class="pre">zip_longest()</span></code></a>

  1037. function should be wrapped with something that limits the number of calls

  1038. (for example <a class="reference internal" href="#itertools.islice" title="itertools.islice"><code class="xref py py-func docutils literal notranslate"><span class="pre">islice()</span></code></a> or <a class="reference internal" href="#itertools.takewhile" title="itertools.takewhile"><code class="xref py py-func docutils literal notranslate"><span class="pre">takewhile()</span></code></a>).  If not specified,

  1039. <em>fillvalue</em> defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>

  1040. </dd></dl>

  1041. 

  1042. </section>

  1043. <section id="itertools-recipes">

  1044. <span id="id1"></span><h2>Itertools Recipes<a class="headerlink" href="#itertools-recipes" title="Link to this heading">¶</a></h2>

  1045. <p>This section shows recipes for creating an extended toolset using the existing

  1046. itertools as building blocks.</p>

  1047. <p>The primary purpose of the itertools recipes is educational.  The recipes show

  1048. various ways of thinking about individual tools — for example, that

  1049. <code class="docutils literal notranslate"><span class="pre">chain.from_iterable</span></code> is related to the concept of flattening.  The recipes

  1050. also give ideas about ways that the tools can be combined — for example, how

  1051. <code class="docutils literal notranslate"><span class="pre">starmap()</span></code> and <code class="docutils literal notranslate"><span class="pre">repeat()</span></code> can work together.  The recipes also show patterns

  1052. for using itertools with the <a class="reference internal" href="operator.html#module-operator" title="operator: Functions corresponding to the standard operators."><code class="xref py py-mod docutils literal notranslate"><span class="pre">operator</span></code></a> and <a class="reference internal" href="collections.html#module-collections" title="collections: Container datatypes"><code class="xref py py-mod docutils literal notranslate"><span class="pre">collections</span></code></a> modules as

  1053. well as with the built-in itertools such as <code class="docutils literal notranslate"><span class="pre">map()</span></code>, <code class="docutils literal notranslate"><span class="pre">filter()</span></code>,

  1054. <code class="docutils literal notranslate"><span class="pre">reversed()</span></code>, and <code class="docutils literal notranslate"><span class="pre">enumerate()</span></code>.</p>

  1055. <p>A secondary purpose of the recipes is to serve as an incubator.  The

  1056. <code class="docutils literal notranslate"><span class="pre">accumulate()</span></code>, <code class="docutils literal notranslate"><span class="pre">compress()</span></code>, and <code class="docutils literal notranslate"><span class="pre">pairwise()</span></code> itertools started out as

  1057. recipes.  Currently, the <code class="docutils literal notranslate"><span class="pre">sliding_window()</span></code>, <code class="docutils literal notranslate"><span class="pre">iter_index()</span></code>, and <code class="docutils literal notranslate"><span class="pre">sieve()</span></code>

  1058. recipes are being tested to see whether they prove their worth.</p>

  1059. <p>Substantially all of these recipes and many, many others can be installed from

  1060. the <a class="reference external" href="https://pypi.org/project/more-itertools/">more-itertools project</a> found

  1061. on the Python Package Index:</p>

  1062. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">more</span><span class="o">-</span><span class="n">itertools</span>

  1063. </pre></div>

  1064. </div>

  1065. <p>Many of the recipes offer the same high performance as the underlying toolset.

  1066. Superior memory performance is kept by processing elements one at a time rather

  1067. than bringing the whole iterable into memory all at once. Code volume is kept

  1068. small by linking the tools together in a <a class="reference external" href="https://www.cs.kent.ac.uk/people/staff/dat/miranda/whyfp90.pdf">functional style</a>.  High speed

  1069. is retained by preferring “vectorized” building blocks over the use of for-loops

  1070. and <a class="reference internal" href="../glossary.html#term-generator"><span class="xref std std-term">generators</span></a> which incur interpreter overhead.</p>

  1071. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">collections</span>

  1072. <span class="kn">import</span> <span class="nn">functools</span>

  1073. <span class="kn">import</span> <span class="nn">math</span>

  1074. <span class="kn">import</span> <span class="nn">operator</span>

  1075. <span class="kn">import</span> <span class="nn">random</span>

  1076. 

  1077. <span class="k">def</span> <span class="nf">take</span><span class="p">(</span><span class="n">n</span><span class="p">,</span> <span class="n">iterable</span><span class="p">):</span>

  1078.     <span class="s2">&quot;Return first n items of the iterable as a list.&quot;</span>

  1079.     <span class="k">return</span> <span class="nb">list</span><span class="p">(</span><span class="n">islice</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">n</span><span class="p">))</span>

  1080. 

  1081. <span class="k">def</span> <span class="nf">prepend</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">iterable</span><span class="p">):</span>

  1082.     <span class="s2">&quot;Prepend a single value in front of an iterable.&quot;</span>

  1083.     <span class="c1"># prepend(1, [2, 3, 4]) → 1 2 3 4</span>

  1084.     <span class="k">return</span> <span class="n">chain</span><span class="p">([</span><span class="n">value</span><span class="p">],</span> <span class="n">iterable</span><span class="p">)</span>

  1085. 

  1086. <span class="k">def</span> <span class="nf">tabulate</span><span class="p">(</span><span class="n">function</span><span class="p">,</span> <span class="n">start</span><span class="o">=</span><span class="mi">0</span><span class="p">):</span>

  1087.     <span class="s2">&quot;Return function(0), function(1), ...&quot;</span>

  1088.     <span class="k">return</span> <span class="nb">map</span><span class="p">(</span><span class="n">function</span><span class="p">,</span> <span class="n">count</span><span class="p">(</span><span class="n">start</span><span class="p">))</span>

  1089. 

  1090. <span class="k">def</span> <span class="nf">repeatfunc</span><span class="p">(</span><span class="n">func</span><span class="p">,</span> <span class="n">times</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">):</span>

  1091. <span class="w">    </span><span class="sd">&quot;&quot;&quot;Repeat calls to func with specified arguments.</span>

  1092. 

  1093. <span class="sd">    Example:  repeatfunc(random.random)</span>

  1094. <span class="sd">    &quot;&quot;&quot;</span>

  1095.     <span class="k">if</span> <span class="n">times</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  1096.         <span class="k">return</span> <span class="n">starmap</span><span class="p">(</span><span class="n">func</span><span class="p">,</span> <span class="n">repeat</span><span class="p">(</span><span class="n">args</span><span class="p">))</span>

  1097.     <span class="k">return</span> <span class="n">starmap</span><span class="p">(</span><span class="n">func</span><span class="p">,</span> <span class="n">repeat</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">times</span><span class="p">))</span>

  1098. 

  1099. <span class="k">def</span> <span class="nf">flatten</span><span class="p">(</span><span class="n">list_of_lists</span><span class="p">):</span>

  1100.     <span class="s2">&quot;Flatten one level of nesting.&quot;</span>

  1101.     <span class="k">return</span> <span class="n">chain</span><span class="o">.</span><span class="n">from_iterable</span><span class="p">(</span><span class="n">list_of_lists</span><span class="p">)</span>

  1102. 

  1103. <span class="k">def</span> <span class="nf">ncycles</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">n</span><span class="p">):</span>

  1104.     <span class="s2">&quot;Returns the sequence elements n times.&quot;</span>

  1105.     <span class="k">return</span> <span class="n">chain</span><span class="o">.</span><span class="n">from_iterable</span><span class="p">(</span><span class="n">repeat</span><span class="p">(</span><span class="nb">tuple</span><span class="p">(</span><span class="n">iterable</span><span class="p">),</span> <span class="n">n</span><span class="p">))</span>

  1106. 

  1107. <span class="k">def</span> <span class="nf">tail</span><span class="p">(</span><span class="n">n</span><span class="p">,</span> <span class="n">iterable</span><span class="p">):</span>

  1108.     <span class="s2">&quot;Return an iterator over the last n items.&quot;</span>

  1109.     <span class="c1"># tail(3, &#39;ABCDEFG&#39;) → E F G</span>

  1110.     <span class="k">return</span> <span class="nb">iter</span><span class="p">(</span><span class="n">collections</span><span class="o">.</span><span class="n">deque</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">maxlen</span><span class="o">=</span><span class="n">n</span><span class="p">))</span>

  1111. 

  1112. <span class="k">def</span> <span class="nf">consume</span><span class="p">(</span><span class="n">iterator</span><span class="p">,</span> <span class="n">n</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  1113.     <span class="s2">&quot;Advance the iterator n-steps ahead. If n is None, consume entirely.&quot;</span>

  1114.     <span class="c1"># Use functions that consume iterators at C speed.</span>

  1115.     <span class="k">if</span> <span class="n">n</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  1116.         <span class="c1"># feed the entire iterator into a zero-length deque</span>

  1117.         <span class="n">collections</span><span class="o">.</span><span class="n">deque</span><span class="p">(</span><span class="n">iterator</span><span class="p">,</span> <span class="n">maxlen</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>

  1118.     <span class="k">else</span><span class="p">:</span>

  1119.         <span class="c1"># advance to the empty slice starting at position n</span>

  1120.         <span class="nb">next</span><span class="p">(</span><span class="n">islice</span><span class="p">(</span><span class="n">iterator</span><span class="p">,</span> <span class="n">n</span><span class="p">,</span> <span class="n">n</span><span class="p">),</span> <span class="kc">None</span><span class="p">)</span>

  1121. 

  1122. <span class="k">def</span> <span class="nf">nth</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">n</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  1123.     <span class="s2">&quot;Returns the nth item or a default value.&quot;</span>

  1124.     <span class="k">return</span> <span class="nb">next</span><span class="p">(</span><span class="n">islice</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">n</span><span class="p">,</span> <span class="kc">None</span><span class="p">),</span> <span class="n">default</span><span class="p">)</span>

  1125. 

  1126. <span class="k">def</span> <span class="nf">quantify</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">predicate</span><span class="o">=</span><span class="nb">bool</span><span class="p">):</span>

  1127.     <span class="s2">&quot;Given a predicate that returns True or False, count the True results.&quot;</span>

  1128.     <span class="k">return</span> <span class="nb">sum</span><span class="p">(</span><span class="nb">map</span><span class="p">(</span><span class="n">predicate</span><span class="p">,</span> <span class="n">iterable</span><span class="p">))</span>

  1129. 

  1130. <span class="k">def</span> <span class="nf">first_true</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">predicate</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  1131.     <span class="s2">&quot;Returns the first true value or the *default* if there is no true value.&quot;</span>

  1132.     <span class="c1"># first_true([a,b,c], x) → a or b or c or x</span>

  1133.     <span class="c1"># first_true([a,b], x, f) → a if f(a) else b if f(b) else x</span>

  1134.     <span class="k">return</span> <span class="nb">next</span><span class="p">(</span><span class="nb">filter</span><span class="p">(</span><span class="n">predicate</span><span class="p">,</span> <span class="n">iterable</span><span class="p">),</span> <span class="n">default</span><span class="p">)</span>

  1135. 

  1136. <span class="k">def</span> <span class="nf">all_equal</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  1137.     <span class="s2">&quot;Returns True if all the elements are equal to each other.&quot;</span>

  1138.     <span class="c1"># all_equal(&#39;4٤໔４৪&#39;, key=int) → True</span>

  1139.     <span class="k">return</span> <span class="nb">len</span><span class="p">(</span><span class="n">take</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="n">groupby</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">key</span><span class="p">)))</span> <span class="o">&lt;=</span> <span class="mi">1</span>

  1140. 

  1141. <span class="k">def</span> <span class="nf">unique_justseen</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  1142.     <span class="s2">&quot;List unique elements, preserving order. Remember only the element just seen.&quot;</span>

  1143.     <span class="c1"># unique_justseen(&#39;AAAABBBCCDAABBB&#39;) → A B C D A B</span>

  1144.     <span class="c1"># unique_justseen(&#39;ABBcCAD&#39;, str.casefold) → A B c A D</span>

  1145.     <span class="k">if</span> <span class="n">key</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  1146.         <span class="k">return</span> <span class="nb">map</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">itemgetter</span><span class="p">(</span><span class="mi">0</span><span class="p">),</span> <span class="n">groupby</span><span class="p">(</span><span class="n">iterable</span><span class="p">))</span>

  1147.     <span class="k">return</span> <span class="nb">map</span><span class="p">(</span><span class="nb">next</span><span class="p">,</span> <span class="nb">map</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">itemgetter</span><span class="p">(</span><span class="mi">1</span><span class="p">),</span> <span class="n">groupby</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">key</span><span class="p">)))</span>

  1148. 

  1149. <span class="k">def</span> <span class="nf">unique_everseen</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  1150.     <span class="s2">&quot;List unique elements, preserving order. Remember all elements ever seen.&quot;</span>

  1151.     <span class="c1"># unique_everseen(&#39;AAAABBBCCDAABBB&#39;) → A B C D</span>

  1152.     <span class="c1"># unique_everseen(&#39;ABBcCAD&#39;, str.casefold) → A B c D</span>

  1153.     <span class="n">seen</span> <span class="o">=</span> <span class="nb">set</span><span class="p">()</span>

  1154.     <span class="k">if</span> <span class="n">key</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  1155.         <span class="k">for</span> <span class="n">element</span> <span class="ow">in</span> <span class="n">filterfalse</span><span class="p">(</span><span class="n">seen</span><span class="o">.</span><span class="fm">__contains__</span><span class="p">,</span> <span class="n">iterable</span><span class="p">):</span>

  1156.             <span class="n">seen</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">element</span><span class="p">)</span>

  1157.             <span class="k">yield</span> <span class="n">element</span>

  1158.     <span class="k">else</span><span class="p">:</span>

  1159.         <span class="k">for</span> <span class="n">element</span> <span class="ow">in</span> <span class="n">iterable</span><span class="p">:</span>

  1160.             <span class="n">k</span> <span class="o">=</span> <span class="n">key</span><span class="p">(</span><span class="n">element</span><span class="p">)</span>

  1161.             <span class="k">if</span> <span class="n">k</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">seen</span><span class="p">:</span>

  1162.                 <span class="n">seen</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">k</span><span class="p">)</span>

  1163.                 <span class="k">yield</span> <span class="n">element</span>

  1164. 

  1165. <span class="k">def</span> <span class="nf">sliding_window</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">n</span><span class="p">):</span>

  1166.     <span class="s2">&quot;Collect data into overlapping fixed-length chunks or blocks.&quot;</span>

  1167.     <span class="c1"># sliding_window(&#39;ABCDEFG&#39;, 4) → ABCD BCDE CDEF DEFG</span>

  1168.     <span class="n">it</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>

  1169.     <span class="n">window</span> <span class="o">=</span> <span class="n">collections</span><span class="o">.</span><span class="n">deque</span><span class="p">(</span><span class="n">islice</span><span class="p">(</span><span class="n">it</span><span class="p">,</span> <span class="n">n</span><span class="o">-</span><span class="mi">1</span><span class="p">),</span> <span class="n">maxlen</span><span class="o">=</span><span class="n">n</span><span class="p">)</span>

  1170.     <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">it</span><span class="p">:</span>

  1171.         <span class="n">window</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>

  1172.         <span class="k">yield</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">window</span><span class="p">)</span>

  1173. 

  1174. <span class="k">def</span> <span class="nf">grouper</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">n</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">incomplete</span><span class="o">=</span><span class="s1">&#39;fill&#39;</span><span class="p">,</span> <span class="n">fillvalue</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  1175.     <span class="s2">&quot;Collect data into non-overlapping fixed-length chunks or blocks.&quot;</span>

  1176.     <span class="c1"># grouper(&#39;ABCDEFG&#39;, 3, fillvalue=&#39;x&#39;) → ABC DEF Gxx</span>

  1177.     <span class="c1"># grouper(&#39;ABCDEFG&#39;, 3, incomplete=&#39;strict&#39;) → ABC DEF ValueError</span>

  1178.     <span class="c1"># grouper(&#39;ABCDEFG&#39;, 3, incomplete=&#39;ignore&#39;) → ABC DEF</span>

  1179.     <span class="n">iterators</span> <span class="o">=</span> <span class="p">[</span><span class="nb">iter</span><span class="p">(</span><span class="n">iterable</span><span class="p">)]</span> <span class="o">*</span> <span class="n">n</span>

  1180.     <span class="k">match</span> <span class="n">incomplete</span><span class="p">:</span>

  1181.         <span class="k">case</span> <span class="s1">&#39;fill&#39;</span><span class="p">:</span>

  1182.             <span class="k">return</span> <span class="n">zip_longest</span><span class="p">(</span><span class="o">*</span><span class="n">iterators</span><span class="p">,</span> <span class="n">fillvalue</span><span class="o">=</span><span class="n">fillvalue</span><span class="p">)</span>

  1183.         <span class="k">case</span> <span class="s1">&#39;strict&#39;</span><span class="p">:</span>

  1184.             <span class="k">return</span> <span class="nb">zip</span><span class="p">(</span><span class="o">*</span><span class="n">iterators</span><span class="p">,</span> <span class="n">strict</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>

  1185.         <span class="k">case</span> <span class="s1">&#39;ignore&#39;</span><span class="p">:</span>

  1186.             <span class="k">return</span> <span class="nb">zip</span><span class="p">(</span><span class="o">*</span><span class="n">iterators</span><span class="p">)</span>

  1187.         <span class="k">case</span><span class="w"> </span><span class="k">_</span><span class="p">:</span>

  1188.             <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s1">&#39;Expected fill, strict, or ignore&#39;</span><span class="p">)</span>

  1189. 

  1190. <span class="k">def</span> <span class="nf">roundrobin</span><span class="p">(</span><span class="o">*</span><span class="n">iterables</span><span class="p">):</span>

  1191.     <span class="s2">&quot;Visit input iterables in a cycle until each is exhausted.&quot;</span>

  1192.     <span class="c1"># roundrobin(&#39;ABC&#39;, &#39;D&#39;, &#39;EF&#39;) → A D E B F C</span>

  1193.     <span class="c1"># Algorithm credited to George Sakkis</span>

  1194.     <span class="n">iterators</span> <span class="o">=</span> <span class="nb">map</span><span class="p">(</span><span class="nb">iter</span><span class="p">,</span> <span class="n">iterables</span><span class="p">)</span>

  1195.     <span class="k">for</span> <span class="n">num_active</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">iterables</span><span class="p">),</span> <span class="mi">0</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">):</span>

  1196.         <span class="n">iterators</span> <span class="o">=</span> <span class="n">cycle</span><span class="p">(</span><span class="n">islice</span><span class="p">(</span><span class="n">iterators</span><span class="p">,</span> <span class="n">num_active</span><span class="p">))</span>

  1197.         <span class="k">yield from</span> <span class="nb">map</span><span class="p">(</span><span class="nb">next</span><span class="p">,</span> <span class="n">iterators</span><span class="p">)</span>

  1198. 

  1199. <span class="k">def</span> <span class="nf">partition</span><span class="p">(</span><span class="n">predicate</span><span class="p">,</span> <span class="n">iterable</span><span class="p">):</span>

  1200. <span class="w">    </span><span class="sd">&quot;&quot;&quot;Partition entries into false entries and true entries.</span>

  1201. 

  1202. <span class="sd">    If *predicate* is slow, consider wrapping it with functools.lru_cache().</span>

  1203. <span class="sd">    &quot;&quot;&quot;</span>

  1204.     <span class="c1"># partition(is_odd, range(10)) → 0 2 4 6 8   and  1 3 5 7 9</span>

  1205.     <span class="n">t1</span><span class="p">,</span> <span class="n">t2</span> <span class="o">=</span> <span class="n">tee</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>

  1206.     <span class="k">return</span> <span class="n">filterfalse</span><span class="p">(</span><span class="n">predicate</span><span class="p">,</span> <span class="n">t1</span><span class="p">),</span> <span class="nb">filter</span><span class="p">(</span><span class="n">predicate</span><span class="p">,</span> <span class="n">t2</span><span class="p">)</span>

  1207. 

  1208. <span class="k">def</span> <span class="nf">subslices</span><span class="p">(</span><span class="n">seq</span><span class="p">):</span>

  1209.     <span class="s2">&quot;Return all contiguous non-empty subslices of a sequence.&quot;</span>

  1210.     <span class="c1"># subslices(&#39;ABCD&#39;) → A AB ABC ABCD B BC BCD C CD D</span>

  1211.     <span class="n">slices</span> <span class="o">=</span> <span class="n">starmap</span><span class="p">(</span><span class="nb">slice</span><span class="p">,</span> <span class="n">combinations</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">seq</span><span class="p">)</span> <span class="o">+</span> <span class="mi">1</span><span class="p">),</span> <span class="mi">2</span><span class="p">))</span>

  1212.     <span class="k">return</span> <span class="nb">map</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">getitem</span><span class="p">,</span> <span class="n">repeat</span><span class="p">(</span><span class="n">seq</span><span class="p">),</span> <span class="n">slices</span><span class="p">)</span>

  1213. 

  1214. <span class="k">def</span> <span class="nf">iter_index</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">start</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">stop</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  1215.     <span class="s2">&quot;Return indices where a value occurs in a sequence or iterable.&quot;</span>

  1216.     <span class="c1"># iter_index(&#39;AABCADEAF&#39;, &#39;A&#39;) → 0 1 4 7</span>

  1217.     <span class="n">seq_index</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="s1">&#39;index&#39;</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>

  1218.     <span class="k">if</span> <span class="n">seq_index</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  1219.         <span class="c1"># Path for general iterables</span>

  1220.         <span class="n">it</span> <span class="o">=</span> <span class="n">islice</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">start</span><span class="p">,</span> <span class="n">stop</span><span class="p">)</span>

  1221.         <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">element</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">it</span><span class="p">,</span> <span class="n">start</span><span class="p">):</span>

  1222.             <span class="k">if</span> <span class="n">element</span> <span class="ow">is</span> <span class="n">value</span> <span class="ow">or</span> <span class="n">element</span> <span class="o">==</span> <span class="n">value</span><span class="p">:</span>

  1223.                 <span class="k">yield</span> <span class="n">i</span>

  1224.     <span class="k">else</span><span class="p">:</span>

  1225.         <span class="c1"># Path for sequences with an index() method</span>

  1226.         <span class="n">stop</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span> <span class="k">if</span> <span class="n">stop</span> <span class="ow">is</span> <span class="kc">None</span> <span class="k">else</span> <span class="n">stop</span>

  1227.         <span class="n">i</span> <span class="o">=</span> <span class="n">start</span>

  1228.         <span class="k">try</span><span class="p">:</span>

  1229.             <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>

  1230.                 <span class="k">yield</span> <span class="p">(</span><span class="n">i</span> <span class="o">:=</span> <span class="n">seq_index</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">i</span><span class="p">,</span> <span class="n">stop</span><span class="p">))</span>

  1231.                 <span class="n">i</span> <span class="o">+=</span> <span class="mi">1</span>

  1232.         <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>

  1233.             <span class="k">pass</span>

  1234. 

  1235. <span class="k">def</span> <span class="nf">iter_except</span><span class="p">(</span><span class="n">func</span><span class="p">,</span> <span class="n">exception</span><span class="p">,</span> <span class="n">first</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  1236. <span class="w">    </span><span class="sd">&quot;&quot;&quot; Call a function repeatedly until an exception is raised.</span>

  1237. 

  1238. <span class="sd">    Converts a call-until-exception interface to an iterator interface.</span>

  1239. <span class="sd">    &quot;&quot;&quot;</span>

  1240.     <span class="c1"># iter_except(d.popitem, KeyError) → non-blocking dictionary iterator</span>

  1241.     <span class="k">try</span><span class="p">:</span>

  1242.         <span class="k">if</span> <span class="n">first</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>

  1243.             <span class="k">yield</span> <span class="n">first</span><span class="p">()</span>

  1244.         <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>

  1245.             <span class="k">yield</span> <span class="n">func</span><span class="p">()</span>

  1246.     <span class="k">except</span> <span class="n">exception</span><span class="p">:</span>

  1247.         <span class="k">pass</span>

  1248. </pre></div>

  1249. </div>

  1250. <p>The following recipes have a more mathematical flavor:</p>

  1251. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">powerset</span><span class="p">(</span><span class="n">iterable</span><span class="p">):</span>

  1252.     <span class="s2">&quot;powerset([1,2,3]) → () (1,) (2,) (3,) (1,2) (1,3) (2,3) (1,2,3)&quot;</span>

  1253.     <span class="n">s</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>

  1254.     <span class="k">return</span> <span class="n">chain</span><span class="o">.</span><span class="n">from_iterable</span><span class="p">(</span><span class="n">combinations</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">r</span><span class="p">)</span> <span class="k">for</span> <span class="n">r</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">s</span><span class="p">)</span><span class="o">+</span><span class="mi">1</span><span class="p">))</span>

  1255. 

  1256. <span class="k">def</span> <span class="nf">sum_of_squares</span><span class="p">(</span><span class="n">iterable</span><span class="p">):</span>

  1257.     <span class="s2">&quot;Add up the squares of the input values.&quot;</span>

  1258.     <span class="c1"># sum_of_squares([10, 20, 30]) → 1400</span>

  1259.     <span class="k">return</span> <span class="n">math</span><span class="o">.</span><span class="n">sumprod</span><span class="p">(</span><span class="o">*</span><span class="n">tee</span><span class="p">(</span><span class="n">iterable</span><span class="p">))</span>

  1260. 

  1261. <span class="k">def</span> <span class="nf">reshape</span><span class="p">(</span><span class="n">matrix</span><span class="p">,</span> <span class="n">cols</span><span class="p">):</span>

  1262.     <span class="s2">&quot;Reshape a 2-D matrix to have a given number of columns.&quot;</span>

  1263.     <span class="c1"># reshape([(0, 1), (2, 3), (4, 5)], 3) →  (0, 1, 2), (3, 4, 5)</span>

  1264.     <span class="k">return</span> <span class="n">batched</span><span class="p">(</span><span class="n">chain</span><span class="o">.</span><span class="n">from_iterable</span><span class="p">(</span><span class="n">matrix</span><span class="p">),</span> <span class="n">cols</span><span class="p">)</span>

  1265. 

  1266. <span class="k">def</span> <span class="nf">transpose</span><span class="p">(</span><span class="n">matrix</span><span class="p">):</span>

  1267.     <span class="s2">&quot;Swap the rows and columns of a 2-D matrix.&quot;</span>

  1268.     <span class="c1"># transpose([(1, 2, 3), (11, 22, 33)]) → (1, 11) (2, 22) (3, 33)</span>

  1269.     <span class="k">return</span> <span class="nb">zip</span><span class="p">(</span><span class="o">*</span><span class="n">matrix</span><span class="p">,</span> <span class="n">strict</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>

  1270. 

  1271. <span class="k">def</span> <span class="nf">matmul</span><span class="p">(</span><span class="n">m1</span><span class="p">,</span> <span class="n">m2</span><span class="p">):</span>

  1272.     <span class="s2">&quot;Multiply two matrices.&quot;</span>

  1273.     <span class="c1"># matmul([(7, 5), (3, 5)], [(2, 5), (7, 9)]) → (49, 80), (41, 60)</span>

  1274.     <span class="n">n</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">m2</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span>

  1275.     <span class="k">return</span> <span class="n">batched</span><span class="p">(</span><span class="n">starmap</span><span class="p">(</span><span class="n">math</span><span class="o">.</span><span class="n">sumprod</span><span class="p">,</span> <span class="n">product</span><span class="p">(</span><span class="n">m1</span><span class="p">,</span> <span class="n">transpose</span><span class="p">(</span><span class="n">m2</span><span class="p">))),</span> <span class="n">n</span><span class="p">)</span>

  1276. 

  1277. <span class="k">def</span> <span class="nf">convolve</span><span class="p">(</span><span class="n">signal</span><span class="p">,</span> <span class="n">kernel</span><span class="p">):</span>

  1278. <span class="w">    </span><span class="sd">&quot;&quot;&quot;Discrete linear convolution of two iterables.</span>

  1279. <span class="sd">    Equivalent to polynomial multiplication.</span>

  1280. 

  1281. <span class="sd">    Convolutions are mathematically commutative; however, the inputs are</span>

  1282. <span class="sd">    evaluated differently.  The signal is consumed lazily and can be</span>

  1283. <span class="sd">    infinite. The kernel is fully consumed before the calculations begin.</span>

  1284. 

  1285. <span class="sd">    Article:  https://betterexplained.com/articles/intuitive-convolution/</span>

  1286. <span class="sd">    Video:    https://www.youtube.com/watch?v=KuXjwB4LzSA</span>

  1287. <span class="sd">    &quot;&quot;&quot;</span>

  1288.     <span class="c1"># convolve([1, -1, -20], [1, -3]) → 1 -4 -17 60</span>

  1289.     <span class="c1"># convolve(data, [0.25, 0.25, 0.25, 0.25]) → Moving average (blur)</span>

  1290.     <span class="c1"># convolve(data, [1/2, 0, -1/2]) → 1st derivative estimate</span>

  1291.     <span class="c1"># convolve(data, [1, -2, 1]) → 2nd derivative estimate</span>

  1292.     <span class="n">kernel</span> <span class="o">=</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">kernel</span><span class="p">)[::</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>

  1293.     <span class="n">n</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">kernel</span><span class="p">)</span>

  1294.     <span class="n">padded_signal</span> <span class="o">=</span> <span class="n">chain</span><span class="p">(</span><span class="n">repeat</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="n">n</span><span class="o">-</span><span class="mi">1</span><span class="p">),</span> <span class="n">signal</span><span class="p">,</span> <span class="n">repeat</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="n">n</span><span class="o">-</span><span class="mi">1</span><span class="p">))</span>

  1295.     <span class="n">windowed_signal</span> <span class="o">=</span> <span class="n">sliding_window</span><span class="p">(</span><span class="n">padded_signal</span><span class="p">,</span> <span class="n">n</span><span class="p">)</span>

  1296.     <span class="k">return</span> <span class="nb">map</span><span class="p">(</span><span class="n">math</span><span class="o">.</span><span class="n">sumprod</span><span class="p">,</span> <span class="n">repeat</span><span class="p">(</span><span class="n">kernel</span><span class="p">),</span> <span class="n">windowed_signal</span><span class="p">)</span>

  1297. 

  1298. <span class="k">def</span> <span class="nf">polynomial_from_roots</span><span class="p">(</span><span class="n">roots</span><span class="p">):</span>

  1299. <span class="w">    </span><span class="sd">&quot;&quot;&quot;Compute a polynomial&#39;s coefficients from its roots.</span>

  1300. 

  1301. <span class="sd">       (x - 5) (x + 4) (x - 3)  expands to:   x³ -4x² -17x + 60</span>

  1302. <span class="sd">    &quot;&quot;&quot;</span>

  1303.     <span class="c1"># polynomial_from_roots([5, -4, 3]) → [1, -4, -17, 60]</span>

  1304.     <span class="n">factors</span> <span class="o">=</span> <span class="nb">zip</span><span class="p">(</span><span class="n">repeat</span><span class="p">(</span><span class="mi">1</span><span class="p">),</span> <span class="nb">map</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">neg</span><span class="p">,</span> <span class="n">roots</span><span class="p">))</span>

  1305.     <span class="k">return</span> <span class="nb">list</span><span class="p">(</span><span class="n">functools</span><span class="o">.</span><span class="n">reduce</span><span class="p">(</span><span class="n">convolve</span><span class="p">,</span> <span class="n">factors</span><span class="p">,</span> <span class="p">[</span><span class="mi">1</span><span class="p">]))</span>

  1306. 

  1307. <span class="k">def</span> <span class="nf">polynomial_eval</span><span class="p">(</span><span class="n">coefficients</span><span class="p">,</span> <span class="n">x</span><span class="p">):</span>

  1308. <span class="w">    </span><span class="sd">&quot;&quot;&quot;Evaluate a polynomial at a specific value.</span>

  1309. 

  1310. <span class="sd">    Computes with better numeric stability than Horner&#39;s method.</span>

  1311. <span class="sd">    &quot;&quot;&quot;</span>

  1312.     <span class="c1"># Evaluate x³ -4x² -17x + 60 at x = 5</span>

  1313.     <span class="c1"># polynomial_eval([1, -4, -17, 60], x=5) → 0</span>

  1314.     <span class="n">n</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">coefficients</span><span class="p">)</span>

  1315.     <span class="k">if</span> <span class="ow">not</span> <span class="n">n</span><span class="p">:</span>

  1316.         <span class="k">return</span> <span class="nb">type</span><span class="p">(</span><span class="n">x</span><span class="p">)(</span><span class="mi">0</span><span class="p">)</span>

  1317.     <span class="n">powers</span> <span class="o">=</span> <span class="nb">map</span><span class="p">(</span><span class="nb">pow</span><span class="p">,</span> <span class="n">repeat</span><span class="p">(</span><span class="n">x</span><span class="p">),</span> <span class="nb">reversed</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">n</span><span class="p">)))</span>

  1318.     <span class="k">return</span> <span class="n">math</span><span class="o">.</span><span class="n">sumprod</span><span class="p">(</span><span class="n">coefficients</span><span class="p">,</span> <span class="n">powers</span><span class="p">)</span>

  1319. 

  1320. <span class="k">def</span> <span class="nf">polynomial_derivative</span><span class="p">(</span><span class="n">coefficients</span><span class="p">):</span>

  1321. <span class="w">    </span><span class="sd">&quot;&quot;&quot;Compute the first derivative of a polynomial.</span>

  1322. 

  1323. <span class="sd">       f(x)  =  x³ -4x² -17x + 60</span>

  1324. <span class="sd">       f&#39;(x) = 3x² -8x  -17</span>

  1325. <span class="sd">    &quot;&quot;&quot;</span>

  1326.     <span class="c1"># polynomial_derivative([1, -4, -17, 60]) → [3, -8, -17]</span>

  1327.     <span class="n">n</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">coefficients</span><span class="p">)</span>

  1328.     <span class="n">powers</span> <span class="o">=</span> <span class="nb">reversed</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="n">n</span><span class="p">))</span>

  1329.     <span class="k">return</span> <span class="nb">list</span><span class="p">(</span><span class="nb">map</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">mul</span><span class="p">,</span> <span class="n">coefficients</span><span class="p">,</span> <span class="n">powers</span><span class="p">))</span>

  1330. 

  1331. <span class="k">def</span> <span class="nf">sieve</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>

  1332.     <span class="s2">&quot;Primes less than n.&quot;</span>

  1333.     <span class="c1"># sieve(30) → 2 3 5 7 11 13 17 19 23 29</span>

  1334.     <span class="k">if</span> <span class="n">n</span> <span class="o">&gt;</span> <span class="mi">2</span><span class="p">:</span>

  1335.         <span class="k">yield</span> <span class="mi">2</span>

  1336.     <span class="n">start</span> <span class="o">=</span> <span class="mi">3</span>

  1337.     <span class="n">data</span> <span class="o">=</span> <span class="nb">bytearray</span><span class="p">((</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">))</span> <span class="o">*</span> <span class="p">(</span><span class="n">n</span> <span class="o">//</span> <span class="mi">2</span><span class="p">)</span>

  1338.     <span class="n">limit</span> <span class="o">=</span> <span class="n">math</span><span class="o">.</span><span class="n">isqrt</span><span class="p">(</span><span class="n">n</span><span class="p">)</span> <span class="o">+</span> <span class="mi">1</span>

  1339.     <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">iter_index</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">start</span><span class="p">,</span> <span class="n">limit</span><span class="p">):</span>

  1340.         <span class="k">yield from</span> <span class="n">iter_index</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">start</span><span class="p">,</span> <span class="n">p</span><span class="o">*</span><span class="n">p</span><span class="p">)</span>

  1341.         <span class="n">data</span><span class="p">[</span><span class="n">p</span><span class="o">*</span><span class="n">p</span> <span class="p">:</span> <span class="n">n</span> <span class="p">:</span> <span class="n">p</span><span class="o">+</span><span class="n">p</span><span class="p">]</span> <span class="o">=</span> <span class="nb">bytes</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">p</span><span class="o">*</span><span class="n">p</span><span class="p">,</span> <span class="n">n</span><span class="p">,</span> <span class="n">p</span><span class="o">+</span><span class="n">p</span><span class="p">)))</span>

  1342.         <span class="n">start</span> <span class="o">=</span> <span class="n">p</span><span class="o">*</span><span class="n">p</span>

  1343.     <span class="k">yield from</span> <span class="n">iter_index</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">start</span><span class="p">)</span>

  1344. 

  1345. <span class="k">def</span> <span class="nf">factor</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>

  1346.     <span class="s2">&quot;Prime factors of n.&quot;</span>

  1347.     <span class="c1"># factor(99) → 3 3 11</span>

  1348.     <span class="c1"># factor(1_000_000_000_000_007) → 47 59 360620266859</span>

  1349.     <span class="c1"># factor(1_000_000_000_000_403) → 1000000000000403</span>

  1350.     <span class="k">for</span> <span class="n">prime</span> <span class="ow">in</span> <span class="n">sieve</span><span class="p">(</span><span class="n">math</span><span class="o">.</span><span class="n">isqrt</span><span class="p">(</span><span class="n">n</span><span class="p">)</span> <span class="o">+</span> <span class="mi">1</span><span class="p">):</span>

  1351.         <span class="k">while</span> <span class="ow">not</span> <span class="n">n</span> <span class="o">%</span> <span class="n">prime</span><span class="p">:</span>

  1352.             <span class="k">yield</span> <span class="n">prime</span>

  1353.             <span class="n">n</span> <span class="o">//=</span> <span class="n">prime</span>

  1354.             <span class="k">if</span> <span class="n">n</span> <span class="o">==</span> <span class="mi">1</span><span class="p">:</span>

  1355.                 <span class="k">return</span>

  1356.     <span class="k">if</span> <span class="n">n</span> <span class="o">&gt;</span> <span class="mi">1</span><span class="p">:</span>

  1357.         <span class="k">yield</span> <span class="n">n</span>

  1358. 

  1359. <span class="k">def</span> <span class="nf">totient</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>

  1360.     <span class="s2">&quot;Count of natural numbers up to n that are coprime to n.&quot;</span>

  1361.     <span class="c1"># https://mathworld.wolfram.com/TotientFunction.html</span>

  1362.     <span class="c1"># totient(12) → 4 because len([1, 5, 7, 11]) == 4</span>

  1363.     <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">unique_justseen</span><span class="p">(</span><span class="n">factor</span><span class="p">(</span><span class="n">n</span><span class="p">)):</span>

  1364.         <span class="n">n</span> <span class="o">-=</span> <span class="n">n</span> <span class="o">//</span> <span class="n">p</span>

  1365.     <span class="k">return</span> <span class="n">n</span>

  1366. </pre></div>

  1367. </div>

  1368. </section>

  1369. </section>

  1370. 

  1371. 

  1372.             <div class="clearer"></div>

  1373.           </div>

  1374.         </div>

  1375.       </div>

  1376.       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">

  1377.         <div class="sphinxsidebarwrapper">

  1378.   <div>

  1379.     <h3><a href="../contents.html">Table of Contents</a></h3>

  1380.     <ul>

  1381. <li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">itertools</span></code> — Functions creating iterators for efficient looping</a><ul>

  1382. <li><a class="reference internal" href="#itertool-functions">Itertool Functions</a></li>

  1383. <li><a class="reference internal" href="#itertools-recipes">Itertools Recipes</a></li>

  1384. </ul>

  1385. </li>

  1386. </ul>

  1387. 

  1388.   </div>

  1389.   <div>

  1390.     <h4>Previous topic</h4>

  1391.     <p class="topless"><a href="functional.html"

  1392.                           title="previous chapter">Functional Programming Modules</a></p>

  1393.   </div>

  1394.   <div>

  1395.     <h4>Next topic</h4>

  1396.     <p class="topless"><a href="functools.html"

  1397.                           title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">functools</span></code> — Higher-order functions and operations on callable objects</a></p>

  1398.   </div>

  1399.   <div role="note" aria-label="source link">

  1400.     <h3>This Page</h3>

  1401.     <ul class="this-page-menu">

  1402.       <li><a href="../bugs.html">Report a Bug</a></li>

  1403.       <li>

  1404.         <a href="https://github.com/python/cpython/blob/main/Doc/library/itertools.rst"

  1405.             rel="nofollow">Show Source

  1406.         </a>

  1407.       </li>

  1408.     </ul>

  1409.   </div>

  1410.         </div>

  1411. <div id="sidebarbutton" title="Collapse sidebar">

  1412. <span>«</span>

  1413. </div>

  1414. 

  1415.       </div>

  1416.       <div class="clearer"></div>

  1417.     </div>  

  1418.     <div class="related" role="navigation" aria-label="related navigation">

  1419.       <h3>Navigation</h3>

  1420.       <ul>

  1421.         <li class="right" style="margin-right: 10px">

  1422.           <a href="../genindex.html" title="General Index"

  1423.              >index</a></li>

  1424.         <li class="right" >

  1425.           <a href="../py-modindex.html" title="Python Module Index"

  1426.              >modules</a> |</li>

  1427.         <li class="right" >

  1428.           <a href="functools.html" title="functools — Higher-order functions and operations on callable objects"

  1429.              >next</a> |</li>

  1430.         <li class="right" >

  1431.           <a href="functional.html" title="Functional Programming Modules"

  1432.              >previous</a> |</li>

  1433. 

  1434.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  1435.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  1436.           <li class="switchers">

  1437.             <div class="language_switcher_placeholder"></div>

  1438.             <div class="version_switcher_placeholder"></div>

  1439.           </li>

  1440.           <li>

  1441.               

  1442.           </li>

  1443.     <li id="cpython-language-and-version">

  1444.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  1445.     </li>

  1446. 

  1447.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  1448.           <li class="nav-item nav-item-2"><a href="functional.html" >Functional Programming Modules</a> &#187;</li>

  1449.         <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">itertools</span></code> — Functions creating iterators for efficient looping</a></li>

  1450.                 <li class="right">

  1451.                     

  1452. 

  1453.     <div class="inline-search" role="search">

  1454.         <form class="inline-search" action="../search.html" method="get">

  1455.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  1456.           <input type="submit" value="Go" />

  1457.         </form>

  1458.     </div>

  1459.                      |

  1460.                 </li>

  1461.             <li class="right">

  1462. <label class="theme-selector-label">

  1463.     Theme

  1464.     <select class="theme-selector" oninput="activateTheme(this.value)">

  1465.         <option value="auto" selected>Auto</option>

  1466.         <option value="light">Light</option>

  1467.         <option value="dark">Dark</option>

  1468.     </select>

  1469. </label> |</li>

  1470.             

  1471.       </ul>

  1472.     </div>  

  1473.     <div class="footer">

  1474.     &copy; 

  1475.       <a href="../copyright.html">

  1476.     

  1477.     Copyright

  1478.     

  1479.       </a>

  1480.      2001-2024, Python Software Foundation.

  1481.     <br />

  1482.     This page is licensed under the Python Software Foundation License Version 2.

  1483.     <br />

  1484.     Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.

  1485.     <br />

  1486.     

  1487.       See <a href="/license.html">History and License</a> for more information.<br />

  1488.     

  1489.     

  1490.     <br />

  1491. 

  1492.     The Python Software Foundation is a non-profit corporation.

  1493. <a href="https://www.python.org/psf/donations/">Please donate.</a>

  1494. <br />

  1495.     <br />

  1496.       Last updated on Apr 09, 2024 (13:47 UTC).

  1497.     

  1498.       <a href="/bugs.html">Found a bug</a>?

  1499.     

  1500.     <br />

  1501. 

  1502.     Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.

  1503.     </div>

  1504. 

  1505.   </body>

  1506. </html>
上海开阖软件有限公司 沪ICP备12045867号-1