This file is indexed.

/usr/share/doc/python-toolz-doc/html/control.html is in python-toolz-doc 0.8.2-3.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Control Flow &#8212; Toolz 0.8.2 documentation</title>
    
    <link rel="stylesheet" href="_static/classic.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '0.8.2',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true,
        SOURCELINK_SUFFIX: '.txt'
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Curry" href="curry.html" />
    <link rel="prev" title="Laziness" href="laziness.html" /> 
  </head>
  <body role="document">
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="curry.html" title="Curry"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="laziness.html" title="Laziness"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">Toolz 0.8.2 documentation</a> &#187;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="control-flow">
<h1>Control Flow<a class="headerlink" href="#control-flow" title="Permalink to this headline"></a></h1>
<p>Programming is hard when we think simultaneously about several concepts.  Good
programming breaks down big problems into small problems and
builds up small solutions into big solutions.  By this practice the
need for simultaneous thought is restricted to only a few elements at a time.</p>
<p>All modern languages provide mechanisms to build data into data structures and
to build functions out of other functions.  The third element of programming,
besides data and functions, is control flow.  Building complex control flow
out of simple control flow presents deeper challenges.</p>
<div class="section" id="what">
<h2>What?<a class="headerlink" href="#what" title="Permalink to this headline"></a></h2>
<p>Each element in a computer program is either</p>
<ul class="simple">
<li>A variable or value literal like <code class="docutils literal"><span class="pre">x</span></code>, <code class="docutils literal"><span class="pre">total</span></code>, or <code class="docutils literal"><span class="pre">5</span></code></li>
<li>A function or computation like the <code class="docutils literal"><span class="pre">+</span></code> in <code class="docutils literal"><span class="pre">x</span> <span class="pre">+</span> <span class="pre">1</span></code>, the function <code class="docutils literal"><span class="pre">fib</span></code>
in <code class="docutils literal"><span class="pre">fib(3)</span></code>, the method <code class="docutils literal"><span class="pre">split</span></code> in <code class="docutils literal"><span class="pre">line.split(',')</span></code>, or the <code class="docutils literal"><span class="pre">=</span></code> in
<code class="docutils literal"><span class="pre">x</span> <span class="pre">=</span> <span class="pre">0</span></code></li>
<li>Control flow like <code class="docutils literal"><span class="pre">if</span></code>, <code class="docutils literal"><span class="pre">for</span></code>, or <code class="docutils literal"><span class="pre">return</span></code></li>
</ul>
<p>Here is a piece of code; see if you can label each term as either
variable/value, function/computation, or control flow</p>
<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">fib</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>
    <span class="n">a</span><span class="p">,</span> <span class="n">b</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</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>
        <span class="n">a</span><span class="p">,</span> <span class="n">b</span> <span class="o">=</span> <span class="n">b</span><span class="p">,</span> <span class="n">a</span> <span class="o">+</span> <span class="n">b</span>
    <span class="k">return</span> <span class="n">b</span>
</pre></div>
</div>
<p>Programming is hard when we have to juggle many code elements of each type at
the same time.  Good programming is about managing these three elements so that
the developer is only required to think about a handful of them at a time.  For
example we might collect many integer variables into a list of integers or
build a big function out of smaller ones.  While we have natural ways to manage
data and functions, control flow presents more of a challenge.</p>
<p>We organize our data into <strong>data structures</strong> like lists, dictionaries, or objects
in order to group related data together &#8211; this allows us to manipulate large
collections of related data as if we were only manipulating a single entity.</p>
<p>We <strong>build large functions out of smaller ones</strong>; enabling us to break up a
complex task like doing laundry into a sequence of simpler tasks.</p>
<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">do_laundry</span><span class="p">(</span><span class="n">clothes</span><span class="p">):</span>
    <span class="n">wet_clothes</span> <span class="o">=</span> <span class="n">wash</span><span class="p">(</span><span class="n">clothes</span><span class="p">,</span> <span class="n">coins</span><span class="p">)</span>
    <span class="n">dry_clothes</span> <span class="o">=</span> <span class="n">dry</span><span class="p">(</span><span class="n">wet_clothes</span><span class="p">,</span> <span class="n">coins</span><span class="p">)</span>
    <span class="k">return</span> <span class="n">fold</span><span class="p">(</span><span class="n">dry_clothes</span><span class="p">)</span>
</pre></div>
</div>
<p><strong>Control flow is more challenging</strong>; how do we break down complex control flow
into simpler pieces that fit in our brain?  How do we encapsulate commonly
recurring patterns?</p>
<p>Lets motivate this with an example of a common control structure, applying a
function to each element in a list.  Imagine we want to download the HTML
source for a number of webpages.</p>
<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">urllib</span> <span class="k">import</span> <span class="n">urlopen</span>

<span class="n">urls</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;http://www.google.com&#39;</span><span class="p">,</span> <span class="s1">&#39;http://www.wikipedia.com&#39;</span><span class="p">,</span> <span class="s1">&#39;http://www.apple.com&#39;</span><span class="p">]</span>
<span class="n">html_texts</span> <span class="o">=</span> <span class="p">[]</span>
<span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">urls</span><span class="p">:</span>
    <span class="n">html_texts</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">urlopen</span><span class="p">(</span><span class="n">item</span><span class="p">))</span>
<span class="k">return</span> <span class="n">html_texts</span>
</pre></div>
</div>
<p>Or maybe we want to compute the Fibonacci numbers on a particular set of
integers</p>
<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="n">integers</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</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">5</span><span class="p">]</span>
<span class="n">fib_integers</span> <span class="o">=</span> <span class="p">[]</span>
<span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">integers</span><span class="p">:</span>
    <span class="n">fib_integers</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">fib</span><span class="p">(</span><span class="n">item</span><span class="p">))</span>
<span class="k">return</span> <span class="n">fib_integers</span>
</pre></div>
</div>
<p>These two unrelated applications share an identical control flow pattern.  They
apply a function (<code class="docutils literal"><span class="pre">urlopen</span></code> or <code class="docutils literal"><span class="pre">fib</span></code>) onto each element of an input list
(<code class="docutils literal"><span class="pre">urls</span></code>, or <code class="docutils literal"><span class="pre">integers</span></code>), appending the result onto an output list.  Because
this control flow pattern is so common we give it a name, <code class="docutils literal"><span class="pre">map</span></code>, and say that
we map a function (like <code class="docutils literal"><span class="pre">urlopen</span></code>) onto a list (like <code class="docutils literal"><span class="pre">urls</span></code>).</p>
<p>Because Python can treat functions like variables we can encode this control
pattern into a higher-order-function as follows:</p>
<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">map</span><span class="p">(</span><span class="n">function</span><span class="p">,</span> <span class="n">sequence</span><span class="p">):</span>
    <span class="n">output</span> <span class="o">=</span> <span class="p">[]</span>
    <span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">sequence</span><span class="p">:</span>
        <span class="n">output</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">item</span><span class="p">))</span>
    <span class="k">return</span> <span class="n">output</span>
</pre></div>
</div>
<p>This allows us to simplify our code above to the following, pithy solutions</p>
<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="n">html_texts</span> <span class="o">=</span> <span class="nb">map</span><span class="p">(</span><span class="n">urlopen</span><span class="p">,</span> <span class="n">urls</span><span class="p">)</span>
<span class="n">fib_integers</span> <span class="o">=</span> <span class="nb">map</span><span class="p">(</span><span class="n">fib</span><span class="p">,</span> <span class="n">integers</span><span class="p">)</span>
</pre></div>
</div>
<p>Experienced Python programmers know that this control pattern is so popular
that it has been elevated to the status of <strong>syntax</strong> with the popular list
comprehension</p>
<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="n">html_texts</span> <span class="o">=</span> <span class="p">[</span><span class="n">urlopen</span><span class="p">(</span><span class="n">url</span><span class="p">)</span> <span class="k">for</span> <span class="n">url</span> <span class="ow">in</span> <span class="n">urls</span><span class="p">]</span>
</pre></div>
</div>
</div>
<div class="section" id="why">
<h2>Why?<a class="headerlink" href="#why" title="Permalink to this headline"></a></h2>
<p>So maybe you already knew about <code class="docutils literal"><span class="pre">map</span></code> and don&#8217;t use it or maybe you just
prefer list comprehensions.  Why should you keep reading?</p>
<div class="section" id="managing-complexity">
<h3>Managing Complexity<a class="headerlink" href="#managing-complexity" title="Permalink to this headline"></a></h3>
<p>The higher order function <code class="docutils literal"><span class="pre">map</span></code> gives us a name to call a particular control
pattern.  Regardless of whether or not you use a for loop, a list
comprehension, or <code class="docutils literal"><span class="pre">map</span></code> itself, it is useful to recognize the operation
and to give it a name.  Naming control patterns lets us tackle
complex problems a larger scale without burdening our mind with rote details.
It is just as important as bundling data into data structures or building
complex functions out of simple ones.</p>
<p><em>Naming control flow patterns enables programmers to manipulate increasingly
complex operations.</em></p>
</div>
<div class="section" id="other-patterns">
<h3>Other Patterns<a class="headerlink" href="#other-patterns" title="Permalink to this headline"></a></h3>
<p>The function <code class="docutils literal"><span class="pre">map</span></code> has friends.  Advanced programmers may know about
<code class="docutils literal"><span class="pre">map</span></code>&#8216;s siblings, <code class="docutils literal"><span class="pre">filter</span></code> and <code class="docutils literal"><span class="pre">reduce</span></code>.  The <code class="docutils literal"><span class="pre">filter</span></code> control pattern
is also handled by list comprehension syntax and <code class="docutils literal"><span class="pre">reduce</span></code> is often replaced
by straight for loops, so if you don&#8217;t want to use them there is no immediately
practical reason why you would care.</p>
<p>Most programmers however don&#8217;t know about the many cousins of
<code class="docutils literal"><span class="pre">map</span></code>/<code class="docutils literal"><span class="pre">filter</span></code>/<code class="docutils literal"><span class="pre">reduce</span></code>.  Consider for example the unsung heroine,
<code class="docutils literal"><span class="pre">groupby</span></code>.  A brief example grouping names by their length follows:</p>
<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">names</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;Alice&#39;</span><span class="p">,</span> <span class="s1">&#39;Bob&#39;</span><span class="p">,</span> <span class="s1">&#39;Charlie&#39;</span><span class="p">,</span> <span class="s1">&#39;Dan&#39;</span><span class="p">,</span> <span class="s1">&#39;Edith&#39;</span><span class="p">,</span> <span class="s1">&#39;Frank&#39;</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">groupby</span><span class="p">(</span><span class="nb">len</span><span class="p">,</span> <span class="n">names</span><span class="p">)</span>
<span class="go">{3: [&#39;Bob&#39;, &#39;Dan&#39;], 5: [&#39;Alice&#39;, &#39;Edith&#39;, &#39;Frank&#39;], 7: [&#39;Charlie&#39;]}</span>
</pre></div>
</div>
<p>Groupby collects each element of a list into sublists determined by the value
of a function.  Lets see <code class="docutils literal"><span class="pre">groupby</span></code> in action again, grouping numbers by
evenness.</p>
<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">iseven</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>
<span class="gp">... </span>    <span class="k">return</span> <span class="n">n</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">groupby</span><span class="p">(</span><span class="n">iseven</span><span class="p">,</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</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">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">7</span><span class="p">])</span>
<span class="go">{True: [2, 4, 6], False: [1, 3, 5, 7]}</span>
</pre></div>
</div>
<p>If we were to write this second operation out by hand it might look something
like the following:</p>
<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="n">evens</span> <span class="o">=</span> <span class="p">[]</span>
<span class="n">odds</span> <span class="o">=</span> <span class="p">[]</span>
<span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">numbers</span><span class="p">:</span>
    <span class="k">if</span> <span class="n">iseven</span><span class="p">(</span><span class="n">item</span><span class="p">):</span>
        <span class="n">evens</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">item</span><span class="p">)</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="n">odds</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">item</span><span class="p">)</span>
</pre></div>
</div>
<p>Most programmers have written code exactly like this over and over again, just
like they may have repeated the <code class="docutils literal"><span class="pre">map</span></code> control pattern.  When we identify code
as a <code class="docutils literal"><span class="pre">groupby</span></code> operation we mentally collapse the detailed manipulation into
a single concept.</p>
<p>The Toolz library contains dozens of patterns like <code class="docutils literal"><span class="pre">map</span></code> and <code class="docutils literal"><span class="pre">groupby</span></code>.
Learning a core set (maybe a dozen) covers the vast majority of common
programming tasks often done by hand.</p>
<p><em>A rich vocabulary of core control functions conveys the following benefits:</em></p>
<ul class="simple">
<li>You identify new patterns</li>
<li>You make fewer errors in rote coding</li>
<li>You can depend on well tested and benchmarked implementations</li>
</ul>
<p>But this does not come for free.  As in spoken language the use of a rich
vocabulary can alienate new practitioners.  Most functional languages have
fallen into this trap and are seen as unapproachable and smug.  Python
maintains a low-brow reputation and benefits from it.  Just as with spoken
language the value of using just-the-right-word must be moderated with the
comprehension of the intended audience.</p>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Control Flow</a><ul>
<li><a class="reference internal" href="#what">What?</a></li>
<li><a class="reference internal" href="#why">Why?</a><ul>
<li><a class="reference internal" href="#managing-complexity">Managing Complexity</a></li>
<li><a class="reference internal" href="#other-patterns">Other Patterns</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="laziness.html"
                        title="previous chapter">Laziness</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="curry.html"
                        title="next chapter">Curry</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="_sources/control.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <div><input type="text" name="q" /></div>
      <div><input type="submit" value="Go" /></div>
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="curry.html" title="Curry"
             >next</a> |</li>
        <li class="right" >
          <a href="laziness.html" title="Laziness"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">Toolz 0.8.2 documentation</a> &#187;</li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright 2017, Matthew Rocklin, John Jacobsen.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
    </div>
  </body>
</html>