Ticket #4572: smtpclient.xhtml.patch

doc/mail/tutorial/smtpclient/smtpclient.xhtml

@@ -29 +29 @@
 <h3>SMTP Client 1</h3>
 
 <p>The first step is to create <a href="smtpclient-1.tac">the most
-minimal <code>.tac</code> file</a> possible for use by
-<code>twistd</code>.</p>
+minimal <code>.tac</code> file</a> possible for use by <code>twistd</code> .</p>
 
 <pre class="python">
 from twisted.application import service
 </pre>
 
-<p>The first line of the <code>.tac</code> file imports
-<code>twisted.application.service</code>, a module which contains many
-of the basic <em>service</em> classes and helper functions available
-in Twisted.  In particular, we will be using the
-<code>Application</code> function to create a new <em>application
+<p>The first line of the <code>.tac</code> file
+imports <code>twisted.application.service</code>, a module which
+contains many of the basic <em>service</em> classes and helper
+functions available in Twisted.  In particular, we will be using
+the <code>Application</code> function to create a new <em>application
 service</em>.  An <em>application service</em> simply acts as a
 central object on which to store certain kinds of deployment
 configuration.</p>
@@ -49 +48 @@
 application = service.Application("SMTP Client Tutorial")
 </pre>
 
-<p>The second line of the <code>.tac</code> file creates a new
-<em>application service</em> and binds it to the local name
-<code>application</code>.  <code>twistd</code> requires this local
-name in each <code>.tac</code> file it runs.  It uses various pieces
-of configuration on the object to determine its behavior.  For
+<p>The second line of the <code>.tac</code> file creates a
+new <em>application service</em> and binds it to the local
+name <code>application</code>.  <code>twistd</code> requires this
+local name in each <code>.tac</code> file it runs.  It uses various
+pieces of configuration on the object to determine its behavior.  For
 example, <code>"SMTP Client Tutorial"</code> will be used as the name
 of the <code>.tap</code> file into which to serialize application
 state, should it be necessary to do so.</p>
 
-<p>That does it for the first example.  We now have enough of a
-<code>.tac</code> file to pass to <code>twistd</code>.  If we run <a
-href="smtpclient-1.tac">smtpclient-1.tac</a> using the
-<code>twistd</code> command line:</p>
+<p>That does it for the first example.  We now have enough of
+a <code>.tac</code> file to pass to <code>twistd</code>.  If we
+run <a href="smtpclient-1.tac">smtpclient-1.tac</a> using
+the <code>twistd</code> command line:</p>
 
 <pre class="python">
 twistd -ny smtpclient-1.tac
@@ -101 +100 @@
 from twisted.internet import protocol
 </pre>
 
-<p><code>twisted.application.internet</code> is another
-<em>application service</em> module.  It provides services for
+<p><code>twisted.application.internet</code> is
+another <em>application service</em> module.  It provides services for
 establishing outgoing connections (as well as creating network
-servers, though we are not interested in those parts for the moment).
-<code>twisted.internet.protocol</code> provides base implementations
-of many of the core Twisted concepts, such as <em>factories</em> and
-<em>protocols</em>.</p>
+servers, though we are not interested in those parts for the
+moment). <code>twisted.internet.protocol</code> provides base
+implementations of many of the core Twisted concepts, such
+as <em>factories</em> and <em>protocols</em>.</p>
 
 <p>The next line of <a href="smtpclient-2.tac">smtpclient-2.tac</a>
 instantiates a new <em>client factory</em>.</p>
@@ -116 +115 @@
 smtpClientFactory = protocol.ClientFactory()
 </pre>
 
-<p><em>Client factories</em> are responsible for constructing
-<em>protocol instances</em> whenever connections are established.
-They may be required to create just one instance, or many instances if
-many different connections are established, or they may never be
-required to create one at all, if no connection ever manages to be
-established.</p>
+<p><em>Client factories</em> are responsible for
+constructing <em>protocol instances</em> whenever connections are
+established.  They may be required to create just one instance, or
+many instances if many different connections are established, or they
+may never be required to create one at all, if no connection ever
+manages to be established.</p>
 
 <p>Now that we have a client factory, we'll need to hook it up to the
 network somehow.  The next line of <code>smtpclient-2.tac</code> does
@@ -131 +130 @@
 smtpClientService = internet.TCPClient(None, None, smtpClientFactory)
 </pre>
 
-<p>We'll ignore the first two arguments to
-<code>internet.TCPClient</code> for the moment and instead focus on
+<p>We'll ignore the first two arguments
+to <code>internet.TCPClient</code> for the moment and instead focus on
 the third.  <code>TCPClient</code> is one of those <em>application
 service</em> classes.  It creates TCP connections to a specified
 address and then uses its third argument, a <em>client factory</em>,
 to get a <em>protocol instance</em>.  It then associates the TCP
 connection with the protocol instance and gets out of the way.</p>
 
-<p>We can try to run <code>smtpclient-2.tac</code> the same way we ran
-<code>smtpclient-1.tac</code>, but the results might be a little
+<p>We can try to run <code>smtpclient-2.tac</code> the same way we
+ran <code>smtpclient-1.tac</code>, but the results might be a little
 disappointing:</p>
 
 <pre class="shell">
@@ -198 +197 @@
 smtpClientService = internet.TCPClient('localhost', 25, smtpClientFactory)
 </pre>
 
-<p>This directs the client to connect to <em>localhost</em> on port
-<em>25</em>.  This isn't the address we want ultimately, but it's a
-good place-holder for the time being.  We can run <a
-href="smtpclient-3.tac">smtpclient-3.tac</a> and see what this change
-gets us:</p>
+<p>This directs the client to connect to <em>localhost</em> on
+port <em>25</em>.  This isn't the address we want ultimately, but it's
+a good place-holder for the time being.  We can
+run <a href="smtpclient-3.tac">smtpclient-3.tac</a> and see what this
+change gets us:</p>
 
 <pre class="shell">
 exarkun@boson:~/mail/tutorial/smtpclient$ twistd -ny smtpclient-3.tac
@@ -246 +245 @@
 </pre>
 
 <p>A meagre amount of progress, but the service still raises an
-exception.  This time, it's because we haven't specified a
-<em>protocol class</em> for the factory to use.  We'll do that in the
-next example.</p>
+exception.  This time, it's because we haven't specified
+a <em>protocol class</em> for the factory to use.  We'll do that in
+the next example.</p>
 
 <h3>SMTP Client 4</h3>
 
@@ -288 +287 @@
 exarkun@boson:~/doc/mail/tutorial/smtpclient$
 </pre>
 
-<p>But what does this mean?
-<code>twisted.internet.protocol.Protocol</code> is the base
-<em>protocol</em> implementation.  For those familiar with the classic
-UNIX network services, it is equivalent to the <em>discard</em>
-service.  It never produces any output and it discards all its input.
-Not terribly useful, and certainly nothing like an SMTP client.  Let's
-see how we can improve this in the next example.</p>
+<p>But what does this
+mean? <code>twisted.internet.protocol.Protocol</code> is the
+base <em>protocol</em> implementation.  For those familiar with the
+classic UNIX network services, it is equivalent to
+the <em>discard</em> service.  It never produces any output and it
+discards all its input.  Not terribly useful, and certainly nothing
+like an SMTP client.  Let's see how we can improve this in the next
+example.</p>
 
 <h3>SMTP Client 5</h3>
 
 <p>In <a href="smtpclient-5.tac">smtpclient-5.tac</a>, we will begin
 to use Twisted's SMTP protocol implementation for the first time.
-We'll make the obvious change, simply swapping out
-<code>twisted.internet.protocol.Protocol</code> in favor of
-<code>twisted.mail.smtp.ESMTPClient</code>.  Don't worry about the
-<em>E</em> in <em>ESMTP</em>.  It indicates we're actually using a
-newer version of the SMTP protocol.  There is an
-<code>SMTPClient</code> in Twisted, but there's essentially no reason
-to ever use it.</p>
+We'll make the obvious change, simply swapping
+out <code>twisted.internet.protocol.Protocol</code> in favor
+of <code>twisted.mail.smtp.ESMTPClient</code>.  Don't worry about
+the <em>E</em> in <em>ESMTP</em>.  It indicates we're actually using a
+newer version of the SMTP protocol.  There is
+an <code>SMTPClient</code> in Twisted, but there's essentially no
+reason to ever use it.</p>
 
 <p>smtpclient-5.tac adds a new import:</p>
 
@@ -314 +314 @@
 from twisted.mail import smtp
 </pre>
 
-<p>All of the mail related code in Twisted exists beneath the
-<code>twisted.mail</code> package.  More specifically, everything
-having to do with the SMTP protocol implementation is defined in the
-<code>twisted.mail.smtp</code> module.</p>
+<p>All of the mail related code in Twisted exists beneath
+the <code>twisted.mail</code> package.  More specifically, everything
+having to do with the SMTP protocol implementation is defined in
+the <code>twisted.mail.smtp</code> module.</p>
 
 <p>Next we remove a line we added in smtpclient-4.tac:</p>
 
@@ -379 +379 @@
 
 <p>Oops, back to getting a traceback.  This time, the default
 implementation of <code>buildProtocol</code> seems no longer to be
-sufficient.  It instantiates the protocol with no arguments, but
-<code>ESMTPClient</code> wants at least one argument.  In the next
+sufficient.  It instantiates the protocol with no arguments,
+but <code>ESMTPClient</code> wants at least one argument.  In the next
 version of the client, we'll override <code>buildProtocol</code> to
 fix this problem.</p>
 
 <h3>SMTP Client 6</h3>
 
-<p><a href="smtpclient-6.tac">smtpclient-6.tac</a> introduces a
-<code>twisted.internet.protocol.ClientFactory</code> subclass with an
-overridden <code>buildProtocol</code> method to overcome the problem
-encountered in the previous example.</p>
+<p><a href="smtpclient-6.tac">smtpclient-6.tac</a> introduces
+a <code>twisted.internet.protocol.ClientFactory</code> subclass with
+an overridden <code>buildProtocol</code> method to overcome the
+problem encountered in the previous example.</p>
 
 <pre class="python">
 class SMTPClientFactory(protocol.ClientFactory):
@@ -421 +421 @@
 smtpClientFactory = SMTPClientFactory()
 </pre>
 
-<p>Running this version of the code, we observe that the code
-<strong>still</strong> isn't quite traceback-free.</p>
+<p>Running this version of the code, we observe that the
+code <strong>still</strong> isn't quite traceback-free.</p>
 
 <pre class="shell">
 exarkun@boson:~/doc/mail/tutorial/smtpclient$ twistd -ny smtpclient-6.tac
@@ -484 +484 @@
 actually includes message data to transmit.  For simplicity's sake,
 the message is defined as part of a new class.  In a useful program
 which sent email, message data might be pulled in from the filesystem,
-a database, or be generated based on user-input.  <a
-href="smtpclient-7.tac">smtpclient-7.tac</a>, however, defines a new
-class, <code>SMTPTutorialClient</code>, with three class attributes
-(<code>mailFrom</code>, <code>mailTo</code>, and
-<code>mailData</code>):</p>
+a database, or be generated based on
+user-input.  <a href="smtpclient-7.tac">smtpclient-7.tac</a>, however,
+defines a new class, <code>SMTPTutorialClient</code>, with three class
+attributes (<code>mailFrom</code>, <code>mailTo</code>,
+and <code>mailData</code>):</p>
 
 <pre class="python">
 class SMTPTutorialClient(smtp.ESMTPClient):
@@ -552 +552 @@
 </pre>
 
 <p>This one is quite simple as well: it returns a file or a file-like
-object which contains the message contents.  In our case, we return a
-<code>StringIO</code> since we already have a string containing our
-message.  If the contents of the file returned by
-<code>getMailData</code> span multiple lines (as email messages often
-do), the lines should be <code>\n</code> delimited (as they would be
-when opening a text file in the <code>"rt"</code> mode): necessary
-newline translation will be performed by <code>SMTPClient</code>
-automatically.</p>
+object which contains the message contents.  In our case, we return
+a <code>StringIO</code> since we already have a string containing our
+message.  If the contents of the file returned
+by <code>getMailData</code> span multiple lines (as email messages
+often do), the lines should be <code>\n</code> delimited (as they
+would be when opening a text file in the <code>"rt"</code> mode):
+necessary newline translation will be performed
+by <code>SMTPClient</code> automatically.</p>
 
 <p>There is one more new callback method defined in smtpclient-7.tac.
 This one isn't for providing information about the messages to
@@ -587 +587 @@
 data, and disconnects.  Notably missing, however, is application
 shutdown.  Hitting ^C is fine during development, but it's not exactly
 a long-term solution.  Fortunately, programmatic shutdown is extremely
-simple.  <a href="smtpclient-8.tac">smtpclient-8.tac</a> extends
-<code>sentMail</code> with these two lines:</p>
+simple.  <a href="smtpclient-8.tac">smtpclient-8.tac</a>
+extends <code>sentMail</code> with these two lines:</p>
 
 <pre class="python">
         from twisted.internet import reactor
@@ -667 +667 @@
     return defer.succeed('localhost')
 </pre>
 
-<p><code>defer.succeed</code> is a function which creates a new
-<code>Deferred</code> which already has a result, in this case
-<code>'localhost'</code>.  Now we need to adjust our
-<code>TCPClient</code>-constructing code to expect and properly handle
-this <code>Deferred</code>:</p>
+<p><code>defer.succeed</code> is a function which creates a
+new <code>Deferred</code> which already has a result, in this
+case <code>'localhost'</code>.  Now we need to adjust
+our <code>TCPClient</code>-constructing code to expect and properly
+handle this <code>Deferred</code>:</p>
 
 <pre class="python">
 def cbMailExchange(exchange):
@@ -687 +687 @@
 scope of this document.  For such a look, see
 the <a href="../../../core/howto/defer.html">Deferred Reference</a>.
 However, in brief, what this version of the code does is to delay the
-creation of the <code>TCPClient</code> until the
-<code>Deferred</code> returned by <code>getMailExchange</code> fires.
-Once it does, we proceed normally through the creation of our
-<code>SMTPClientFactory</code> and <code>TCPClient</code>, as well as
-set the <code>TCPClient</code>'s service parent, just as we did in the
-previous examples.</p>
+creation of the <code>TCPClient</code> until the <code>Deferred</code>
+returned by <code>getMailExchange</code> fires.  Once it does, we
+proceed normally through the creation of
+our <code>SMTPClientFactory</code> and <code>TCPClient</code>, as well
+as set the <code>TCPClient</code>'s service parent, just as we did in
+the previous examples.</p>
 
 <h3>SMTP Client 11</h3>
 
 <p>At last we're ready to perform the mail exchange lookup.  We do
-this by calling on an object provided specifically for this task,
-<code>twisted.mail.relaymanager.MXCalculator</code>:</p>
+this by calling on an object provided specifically for this
+task, <code>twisted.mail.relaymanager.MXCalculator</code>:</p>
 
 <pre class="python">
 def getMailExchange(host):
@@ -710 +710 @@
 <p>Because <code>getMX</code> returns a <code>Record_MX</code> object
 rather than a string, we do a little bit of post-processing to get the
 results we want.  We have already converted the rest of the tutorial
-application to expect a <code>Deferred</code> from
-<code>getMailExchange</code>, so no further changes are required.  <a
-href="smtpclient-11.tac">smtpclient-11.tac</a> completes this tutorial
-by being able to both look up the mail exchange host for the recipient
-domain, connect to it, complete an SMTP transaction, report its
-results, and finally shut down the reactor.</p>
-
-<!-- TODO: write a conclusion
-
-<h3>Conclusion</h3>
+application to expect a <code>Deferred</code>
+from <code>getMailExchange</code>, so no further changes are
+required.  <a href="smtpclient-11.tac">smtpclient-11.tac</a> completes
+this tutorial by being able to both look up the mail exchange host for
+the recipient domain, connect to it, complete an SMTP transaction,
+report its results, and finally shut down the reactor.</p>
 
-<p>XXX wrap it up</p>
+<!-- TODO: write a conclusion to wrap it up -->
 
--->
 </body>
 </html>