Ticket #1956: tubes-1956-3-howto-corrections.patch

File tubes-1956-3-howto-corrections.patch, 6.8 KB (added by rwall, 14 months ago)

One or two corrections and suggestions for the tubes tutorial.

  • doc/core/howto/listings/tubes/intparse.py

     
    1515        else: 
    1616            result = int(item) 
    1717        self.tube.deliver(result) 
    18  
    19 def product(numbers): 
    20     return reduce(operator.mul, numbers, 1) 
  • doc/core/howto/tube.xhtml

     
    3333 
    3434<p> 
    3535Also, when dealing with streams of data from networks, it's common to want to send data somewhere as well as receiving it from somewhere. 
    36 Even if your program is concerned with converting a sequence bytes into a sequence of lines, it needs to be aware of the fact that its output may be full, and unprepared receive any more lines. 
     36Even if your program is concerned with converting a sequence bytes 
     37into a sequence of lines, it needs to be aware of the fact that its 
     38output buffer may be full, and unprepared to receive any more lines. 
    3739For example, the line-splitting code above might be used in a proxy that relays output from a cloud server with a very fast datacenter uplink, to computers on very slow consumer networks. 
    3840The cloud server's output will easily outpace a home network's input, which means that if the line parser is going as fast as it can, lines will pile up in outgoing buffers while waiting to be sent out, and consume all of the proxy's memory. 
    3941When this happens, the line parsing program needs to tell <em>its</em> input to slow down, by indicating that it should no longer produce bytes, until the program consuming the line parser's output is ready again. 
    4042</p> 
    4143 
    4244<p> 
    43 The <code>twisted.tubes</code> package contains several interfaces and utilities for dealing with passing inputs to outputs, buffering intermediary data, and dealing with flow-control. 
     45The <code>twisted.tubes</code> package contains several interfaces and utilities for passing inputs to outputs, buffering intermediary data, and dealing with flow-control. 
    4446<code>tubes</code> will solve some of the problems above for you automatically, and for those problems you need to solve yourself, it will provide common abstractions that make solving them easier. 
    4547This document will teach you how to use the <code>twisted.tubes</code> package. 
    4648</p> 
     
    6365    </li> 
    6466    <li> 
    6567    <code>twisted.tubes</code> <em>handles flow control automatically</em>. 
    66     The manual flow-control notifications provided by <code>IProducer</code> and <code>IConsumer</code> are still used internnally in <code>tubes</code> to hook up to <code>twisted.internet</code>, but the interfaces defined in <code>tubes</code> itself are considerably more flexible, as they allow you to hook together chains of arbitrary length, as opposed to just get buffer notifications for a single connection. 
     68    The manual flow-control notifications provided by <code>IProducer</code> and <code>IConsumer</code> are still used internally in <code>tubes</code> to hook up to <code>twisted.internet</code>, but the interfaces defined in <code>tubes</code> itself are considerably more flexible, as they allow you to hook together chains of arbitrary length, as opposed to just getting buffer notifications for a single connection. 
    6769    </li> 
    6870</ol> 
    6971</div> 
     
    8688</p> 
    8789 
    8890<p> 
    89 Let's do exactly that, and get <code>echoFlow</code> called with a real, network-facing <code>fount</code> and <code>drain</code>. 
     91Let's do exactly that, and call <code>echoFlow</code> with a real, network-facing <code>fount</code> and <code>drain</code>. 
    9092</p> 
    9193 
    9294<a href="listings/tubes/echotube.py" class="py-listing">echotube.py</a> 
     
    125127<p> 
    126128To demonstrate this, we'll build a little network-based calculator. 
    127129This program will take input, provided as a series of lines. 
    128 These lines will contain data (numbers) and instructions (arithmetic operations, in this case "SUM" and "PRODUCT" for addition and multipliciation respectively) and produce output data (lines containing an equal sign and then results). 
     130These lines will contain data (numbers) and instructions (arithmetic operations, in this case "SUM" and "PRODUCT" for addition and multiplication respectively) and produce output data (lines containing an equal sign and then results). 
    129131</p> 
    130132 
    131133<p> 
     
    191193<a href="listings/tubes/portforward.py" class="py-listing">portforward.py</a> 
    192194 
    193195<p> 
    194 For each incoming connection on port <code>6543</code>, we creating an outgoing connection to the echo server in our previous example. 
     196For each incoming connection on port <code>6543</code>, we create an outgoing connection to the echo server in our previous example. 
    195197When we have successfully connected to the echo server we connect our incoming <code>listeningFount</code> to our outgoing <code>connectingDrain</code> and our <code>connectingFount</code> to our <code>listeningDrain</code>. 
    196198This forwards all bytes from your <code>telnet</code> client to our echo server, and all bytes from our echo server to your client. 
    197199</p> 
    198200 
     201<h2>XXX: Add a subheading here to give some context</h2> 
     202<p>XXX: ...and isn't this the same as using series?</p> 
    199203<pre class="python"> 
    200204def echoFlow(fount, drain): 
    201205    return (fount.flowTo(Tube(stringToNetstring())) 
     
    205209<p> 
    206210<code class="API" base="twisted.tubes.itube.IFount">flowTo</code> can return a <code class="API" base="twisted.tube.itube">IFount</code> so we can chain <code class="API" base="twisted.tubes.itube.IFount">flowTo</code> calls (in other words, call <code>flowTo</code> on the result of <code>flowTo</code>) to construct a "flow". 
    207211In this case, <code>.flowTo(Tube(stringToNetstring()))</code> returns a new <code class="API" base="twisted.tubes.itube">IFount</code> whose output will be <a href="http://cr.yp.to/proto/netstrings.txt">netstring</a>s. 
     212 
     213<p>XXX: The following note is very difficult to read. I didn't find it helpful.</p> 
    208214<div class="note"> 
    209215    If you're curious: specifically, <code class="API" base="twisted.tubes.itube.IFount">flowTo</code> takes an <code class="API" base="twisted.tube.itube">IDrain</code>, and returns the result of that <code class="API" base="twisted.tube.itube">IDrain</code>'s <code class="API" base="twisted.tubes.itube.IDrain">flowingFrom</code> method. 
    210216    This allows the <code>Tube</code> - which is the <code>IDrain</code> in this scenario, and therefore what knows what the output will be after it's processed it, to affect the return value of the previous <code>IFount</code>'s <code>flowTo</code> method. 
     
    213219This demonstrates how you can manipulate data as it passes through a flow. 
    214220</p> 
    215221 
     222<h2>Conclusion</h2> 
     223<p>XXX: Add a conclusion section - what has been learned, where to go next.</p> 
     224 
    216225</body> 
    217226</html>