Ticket #4568: core-lowlevel.xhtml.patch

doc/core/howto/defer.xhtml

@@ -38 +38 @@
 <h2>Deferreds</h2>
 
 <p>Twisted uses the <code class="API"
-base="twisted.internet.defer">Deferred</code> object to manage the callback
-sequence. The client application attaches a series of functions to the
-deferred to be called in order when the results of the asychronous request are
-available (this series of functions is known as a series of
-<strong>callbacks</strong>, or a <strong>callback chain</strong>), together
-with a series of functions to be called if there is an error in the
-asychronous request (known as a series of <strong>errbacks</strong> or an
-<strong>errback chain</strong>). The asychronous library code calls the first
-callback when the result is available, or the first errback when an error
-occurs, and the <code>Deferred</code> object then hands the results of each
-callback or errback function to the next function in the chain.</p> 
+base="twisted.internet.defer">Deferred</code> object to manage the
+callback sequence. The client application attaches a series of
+functions to the deferred to be called in order when the results of
+the asychronous request are available (this series of functions is
+known as a series of <strong>callbacks</strong>, or a <strong>callback
+chain</strong>), together with a series of functions to be called if
+there is an error in the asychronous request (known as a series
+of <strong>errbacks</strong> or an <strong>errback
+chain</strong>). The asychronous library code calls the first callback
+when the result is available, or the first errback when an error
+occurs, and the <code>Deferred</code> object then hands the results of
+each callback or errback function to the next function in the
+chain.</p>
 
 <h2>Callbacks</h2>
 
@@ -296 +298 @@
 d.addCallbacks(callback2, errback2)  
 </pre>
 
-<p>If an error occurs in <code class="python">callback1</code>, then for Case 1
-<code class="python">errback1</code> will be called with the failure. For Case
-2, <code class="python">errback2</code> will be called. Be careful with your
-callbacks and errbacks.</p>
+<p>If an error occurs in <code class="python">callback1</code>, then
+for Case 1 <code class="python">errback1</code> will be called with
+the failure. For Case 2, <code class="python">errback2</code> will be
+called. Be careful with your callbacks and errbacks.</p>
 
-<p>What this means in a practical sense is in Case 1, &quot;A&quot; will
-handle a success condition from <code>getDeferredFromSomewhere</code>, and
-&quot;B&quot; will handle any errors that occur <em>from either the upstream
-source, or that occur in 'A'</em>.  In Case 2, &quot;C&quot;'s errback1
-<em>will only handle an error condition raised by
-<code>getDeferredFromSomewhere</code></em>, it will not do any handling of
-errors raised in callback1.</p>
+<p>What this means in a practical sense is in Case 1, &quot;A&quot;
+will handle a success condition
+from <code>getDeferredFromSomewhere</code>, and &quot;B&quot; will
+handle any errors that occur <em>from either the upstream source, or
+that occur in 'A'</em>.  In Case 2, &quot;C&quot;'s errback1 <em>will
+only handle an error condition raised
+by </em> <code>getDeferredFromSomewhere</code>, it will not do any
+handling of errors raised in callback1.</p>
 
 
 <h3>Unhandled Errors</h3>
@@ -390 +393 @@
     return d
 </pre>
 
-<p> Our original implementation of <code>authenticateUser</code> expected
-<code>isValidUser</code> to be synchronous, but now we need to change it to handle both
-synchronous and asynchronous implementations of <code>isValidUser</code>. For this, we
-use <code class="API" base="twisted.internet.defer">maybeDeferred</code> to
-call <code>isValidUser</code>, ensuring that the result of <code>isValidUser</code> is a Deferred,
-even if <code>isValidUser</code> is a synchronous function:
+<p> Our original implementation of <code>authenticateUser</code>
+expected <code>isValidUser</code> to be synchronous, but now we need
+to change it to handle both synchronous and asynchronous
+implementations of <code>isValidUser</code>. For this, we
+use <code class="API"
+base="twisted.internet.defer">maybeDeferred</code> to
+call <code>isValidUser</code>, ensuring that the result
+of <code>isValidUser</code> is a Deferred, even
+if <code>isValidUser</code> is a synchronous function:
 </p>
 
 <pre class="python">
@@ -413 +419 @@
 </pre>
 
 <p>
-Now <code>isValidUser</code> could be either <code>synchronousIsValidUser</code> or
-<code>asynchronousIsValidUser</code>.
+Now <code>isValidUser</code> could be
+either <code>synchronousIsValidUser</code>
+or <code>asynchronousIsValidUser</code>.
 </p>
 
 <p>It is also possible to modify <code>synchronousIsValidUser</code> to return
@@ -436 +443 @@
 dl = defer.DeferredList([deferred1, deferred2, deferred3])
 </pre>
 
-<p>You can now treat the DeferredList like an ordinary Deferred; you can call
-<code>addCallbacks</code> and so on.  The DeferredList will call its callback
-when all the deferreds have completed.  The callback will be called with a list
-of the results of the Deferreds it contains, like so:</p>
+<p>You can now treat the DeferredList like an ordinary Deferred; you
+can call <code>addCallbacks</code> and so on.  The DeferredList will
+call its callback when all the deferreds have completed.  The callback
+will be called with a list of the results of the Deferreds it
+contains, like so:</p>
 
 <pre class="python">
 def printResult(result):
@@ -518 +526 @@
 
 <h3>Other behaviours</h3>
 
-<p>DeferredList accepts three keyword arguments that modify its behaviour:
-<code>fireOnOneCallback</code>, <code>fireOnOneErrback</code> and
-<code>consumeErrors</code>.  If <code>fireOnOneCallback</code> is set, the
-DeferredList will immediately call its callback as soon as any of its Deferreds
-call their callback.  Similarly, <code>fireOnOneErrback</code> will call errback
-as soon as any of the Deferreds call their errback.  Note that DeferredList is
-still one-shot, like ordinary Deferreds, so after a callback or errback has been
-called the DeferredList will do nothing further (it will just silently ignore
-any other results from its Deferreds).</p>
+<p>DeferredList accepts three keyword arguments that modify its
+behaviour: <code>fireOnOneCallback</code>, <code>fireOnOneErrback</code>
+and <code>consumeErrors</code>.  If <code>fireOnOneCallback</code> is
+set, the DeferredList will immediately call its callback as soon as
+any of its Deferreds call their callback.
+Similarly, <code>fireOnOneErrback</code> will call errback as soon as
+any of the Deferreds call their errback.  Note that DeferredList is
+still one-shot, like ordinary Deferreds, so after a callback or
+errback has been called the DeferredList will do nothing further (it
+will just silently ignore any other results from its Deferreds).</p>
 
 <p>The <code>fireOnOneErrback</code> option is particularly useful when you
 want to wait for all the results if everything succeeds, but also want to know
 immediately if something fails.</p>
 
-<p>The <code>consumeErrors</code> argument will stop the DeferredList from
-propagating any errors along the callback chains of any Deferreds it contains
-(usually creating a DeferredList has no effect on the results passed along the
-callbacks and errbacks of their Deferreds).  Stopping errors at the DeferredList
-with this option will prevent <q>Unhandled error in Deferred</q> warnings from
-the Deferreds it contains without needing to add extra errbacks<span
-class="footnote">Unless of course a later callback starts a fresh error &mdash;
-but as we've already noted, adding callbacks to a Deferred after its used in a
-DeferredList is confusing and usually avoided.</span>.  Passing a true value
-for the <code>consumeErrors</code> parameter will not change the behavior of
-<code>fireOnOneCallback</code> or <code>fireOnOneErrback</code>.</p>
+<p>The <code>consumeErrors</code> argument will stop the DeferredList
+from propagating any errors along the callback chains of any Deferreds
+it contains (usually creating a DeferredList has no effect on the
+results passed along the callbacks and errbacks of their Deferreds).
+Stopping errors at the DeferredList with this option will
+prevent <q>Unhandled error in Deferred</q> warnings from the Deferreds
+it contains without needing to add extra
+errbacks<span class="footnote">Unless of course a later callback
+starts a fresh error &mdash; but as we've already noted, adding
+callbacks to a Deferred after its used in a DeferredList is confusing
+and usually avoided.</span>.  Passing a true value for
+the <code>consumeErrors</code> parameter will not change the behavior
+of <code>fireOnOneCallback</code>
+or <code>fireOnOneErrback</code>.</p>
 
 <a name="class"></a>
 
@@ -553 +565 @@
 substitute for the docstrings in the Deferred class, but can provide guidelines
 for its use.</p>
 
-<p>There is a parallel overview of functions used by the Deferred's
-<em>creator</em> in <a href="gendefer.xhtml#class">Generating Deferreds</a>.</p>
+<p>There is a parallel overview of functions used by the
+Deferred's <em>creator</em>
+in <a href="gendefer.xhtml#class">Generating Deferreds</a>.</p>
 
 <h3>Basic Callback Functions</h3>
 

doc/core/howto/deferredindepth.xhtml

@@ -10 +10 @@
 <h2>Introduction</h2>
 
 <p>Deferreds are quite possibly the single most confusing topic that a
-newcomer to Twisted has to deal with. I am going to forgo the normal talk
-about what deferreds are, what they aren't, and why they're used in Twisted.
-Instead, I'm going show you the logic behind what they
-<strong>do</strong>.</p>
+newcomer to Twisted has to deal with. I am going to forgo the normal
+talk about what deferreds are, what they aren't, and why they're used
+in Twisted.  Instead, I'm going show you the logic behind what
+they <strong>do</strong>.</p>
 
 
 <p>A deferred allows you to encapsulate the logic that you'd normally use to
@@ -254 +254 @@
         got result: damage control successful!
 </pre>
 
-<p>Two things to note here. First, &quot;- A -&quot; was skipped, like we wanted it to,
-and the second thing is that after &quot;- A -&quot;, noDecision is called, because
-<strong>it is the next errback that exists in the chain</strong>. It returns a
-non-failure, so processing continues with the next callback at &quot;- B -&quot;, and
-the errback at the end of the chain is never called </p>
+<p>Two things to note here. First, &quot;- A -&quot; was skipped, like
+we wanted it to, and the second thing is that after &quot;- A -&quot;,
+noDecision is called, because <strong>it is the next errback that
+exists in the chain</strong>. It returns a non-failure, so processing
+continues with the next callback at &quot;- B -&quot;, and the errback
+at the end of the chain is never called </p>
 
 <h2>Hints, tips, common mistakes, and miscellaney</h2>
 

doc/core/howto/gendefer.xhtml

@@ -120 +120 @@
 d.addCallback(printNumber)
 </pre>
 
-<p>You will notice that despite creating a Deferred in the
-<code>largeFibonnaciNumber</code> function, these things happened:</p>
+<p>You will notice that despite creating a Deferred in
+the <code>largeFibonnaciNumber</code> function, these things
+happened:</p>
 <ul>
 <li>the &quot;Total time taken for largeFibonnaciNumber call&quot; output
 shows that the function did not return immediately as asynchronous functions
@@ -286 +287 @@
 
 <h3>Firing Deferreds more than once is impossible</h3>
 
-<p>Deferreds are one-shot. You can only call <code>Deferred.callback</code> or
-<code>Deferred.errback</code> once. The processing chain continues each time
-you add new callbacks to an already-called-back-to Deferred.</p>
+<p>Deferreds are one-shot. You can only
+call <code>Deferred.callback</code> or <code>Deferred.errback</code>
+once. The processing chain continues each time you add new callbacks
+to an already-called-back-to Deferred.</p>
 
 <h3>Synchronous callback execution</h3>
 
-<p>If a Deferred already has a result available, addCallback
-<strong>may</strong> call the callback synchronously: that is, immediately
-after it's been added.  In situations where callbacks modify state, it is
-might be desirable for the chain of processing to halt until all callbacks are
-added. For this, it is possible to <code>pause</code> and <code>unpause</code>
-a Deferred's processing chain while you are adding lots of callbacks.</p>
+<p>If a Deferred already has a result available,
+addCallback <strong>may</strong> call the callback synchronously: that
+is, immediately after it's been added.  In situations where callbacks
+modify state, it is might be desirable for the chain of processing to
+halt until all callbacks are added. For this, it is possible
+to <code>pause</code> and <code>unpause</code> a Deferred's processing
+chain while you are adding lots of callbacks.</p>
 
 <p>Be careful when you use these methods! If you <code>pause</code> a
-Deferred, it is <em>your</em> responsibility to make sure that you unpause it.
-The function adding the callbacks must unpause a paused Deferred, it should
-<em>never</em> be the responsibility of the code that actually fires the
-callback chain by calling <code>callback</code> or <code>errback</code> as
-this would negate its usefulness!</p>
+Deferred, it is <em>your</em> responsibility to make sure that you
+unpause it.  The function adding the callbacks must unpause a paused
+Deferred, it should <em>never</em> be the responsibility of the code
+that actually fires the callback chain by
+calling <code>callback</code> or <code>errback</code> as this would
+negate its usefulness!</p>
 
 </body>
 </html>

doc/core/howto/process.xhtml

@@ -85 +85 @@
 
 </ul>
 
-<p><code>args</code> and <code>env</code> have empty default values, but
-many programs depend upon them to be set correctly. At the very least,
-<code>args[0]</code> should probably be the same as <code>executable</code>.
-If you just provide <code>os.environ</code> for <code>env</code>, the child
-program will inherit the environment from the current process, which is
-usually the civilized thing to do (unless you want to explicitly clean the
-environment as a security precaution). The default is to give an empty
-<code>env</code> to the child.</p>
+<p><code>args</code> and <code>env</code> have empty default values,
+but many programs depend upon them to be set correctly. At the very
+least, <code>args[0]</code> should probably be the same
+as <code>executable</code>.  If you just
+provide <code>os.environ</code> for <code>env</code>, the child
+program will inherit the environment from the current process, which
+is usually the civilized thing to do (unless you want to explicitly
+clean the environment as a security precaution). The default is to
+give an empty <code>env</code> to the child.</p>
 
 <p><code>reactor.spawnProcess</code> returns an instance that
 implements <code base="twisted.internet.interfaces" class="API">
@@ -167 +168 @@
 
 <h2>Things that can happen to your ProcessProtocol</h2>
 
-<p>These are the methods that you can usefully override in your subclass of
-<code>ProcessProtocol</code>:</p>
+<p>These are the methods that you can usefully override in your
+subclass of <code>ProcessProtocol</code>:</p>
 
 <ul>
 
@@ -380 +381 @@
 
 <h3>ProcessProtocols with extra file descriptors</h3>
 
-<p>When you provide a <q>childFDs</q> dictionary with more than the normal
-three fds, you need addtional methods to access those pipes. These methods
-are more generalized than the <code>.outReceived</code> ones described above.
-In fact, those methods (<code>outReceived</code> and
-<code>errReceived</code>) are actually just wrappers left in for
-compatibility with older code, written before this generalized fd mapping was
-implemented. The new list of things that can happen to your ProcessProtocol
-is as follows:</p>
+<p>When you provide a <q>childFDs</q> dictionary with more than the
+normal three fds, you need addtional methods to access those
+pipes. These methods are more generalized than
+the <code>.outReceived</code> ones described above.  In fact, those
+methods (<code>outReceived</code> and <code>errReceived</code>) are
+actually just wrappers left in for compatibility with older code,
+written before this generalized fd mapping was implemented. The new
+list of things that can happen to your ProcessProtocol is as
+follows:</p>
 
 <ul>