diff --git a/doc/mail/tutorial/smtpclient/smtpclient.xhtml b/doc/mail/tutorial/smtpclient/smtpclient.xhtml index aea44ba..9e89a84 100644 --- a/doc/mail/tutorial/smtpclient/smtpclient.xhtml +++ b/doc/mail/tutorial/smtpclient/smtpclient.xhtml @@ -29,18 +29,17 @@ files.

SMTP Client 1

The first step is to create the most -minimal .tac file possible for use by -twistd.

+minimal .tac file possible for use by twistd .

 from twisted.application import service
-

The first line of the .tac file imports -twisted.application.service, a module which contains many -of the basic service classes and helper functions available -in Twisted. In particular, we will be using the -Application function to create a new application +

The first line of the .tac file +imports twisted.application.service, a module which +contains many of the basic service classes and helper +functions available in Twisted. In particular, we will be using +the Application function to create a new application service. An application service simply acts as a central object on which to store certain kinds of deployment configuration.

@@ -49,19 +48,19 @@ configuration.

application = service.Application("SMTP Client Tutorial") -

The second line of the .tac file creates a new -application service and binds it to the local name -application. twistd requires this local -name in each .tac file it runs. It uses various pieces -of configuration on the object to determine its behavior. For +

The second line of the .tac file creates a +new application service and binds it to the local +name application. twistd requires this +local name in each .tac file it runs. It uses various +pieces of configuration on the object to determine its behavior. For example, "SMTP Client Tutorial" will be used as the name of the .tap file into which to serialize application state, should it be necessary to do so.

-

That does it for the first example. We now have enough of a -.tac file to pass to twistd. If we run smtpclient-1.tac using the -twistd command line:

+

That does it for the first example. We now have enough of +a .tac file to pass to twistd. If we +run smtpclient-1.tac using +the twistd command line:

 twistd -ny smtpclient-1.tac
@@ -101,13 +100,13 @@ from twisted.application import internet
 from twisted.internet import protocol
-

twisted.application.internet is another -application service module. It provides services for +

twisted.application.internet is +another application service 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). -twisted.internet.protocol provides base implementations -of many of the core Twisted concepts, such as factories and -protocols.

+servers, though we are not interested in those parts for the +moment). twisted.internet.protocol provides base +implementations of many of the core Twisted concepts, such +as factories and protocols.

The next line of smtpclient-2.tac instantiates a new client factory.

@@ -116,12 +115,12 @@ instantiates a new client factory.

smtpClientFactory = protocol.ClientFactory() -

Client factories are responsible for constructing -protocol instances 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.

+

Client factories are responsible for +constructing protocol instances 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.

Now that we have a client factory, we'll need to hook it up to the network somehow. The next line of smtpclient-2.tac does @@ -131,16 +130,16 @@ just that:

smtpClientService = internet.TCPClient(None, None, smtpClientFactory) -

We'll ignore the first two arguments to -internet.TCPClient for the moment and instead focus on +

We'll ignore the first two arguments +to internet.TCPClient for the moment and instead focus on the third. TCPClient is one of those application service classes. It creates TCP connections to a specified address and then uses its third argument, a client factory, to get a protocol instance. It then associates the TCP connection with the protocol instance and gets out of the way.

-

We can try to run smtpclient-2.tac the same way we ran -smtpclient-1.tac, but the results might be a little +

We can try to run smtpclient-2.tac the same way we +ran smtpclient-1.tac, but the results might be a little disappointing:

@@ -198,11 +197,11 @@ something with a bit more meaning:

 smtpClientService = internet.TCPClient('localhost', 25, smtpClientFactory)
-

This directs the client to connect to localhost on port -25. This isn't the address we want ultimately, but it's a -good place-holder for the time being. We can run smtpclient-3.tac and see what this change -gets us:

+

This directs the client to connect to localhost on +port 25. This isn't the address we want ultimately, but it's +a good place-holder for the time being. We can +run smtpclient-3.tac and see what this +change gets us:

 exarkun@boson:~/mail/tutorial/smtpclient$ twistd -ny smtpclient-3.tac
@@ -246,9 +245,9 @@ exarkun@boson:~/mail/tutorial/smtpclient$

A meagre amount of progress, but the service still raises an -exception. This time, it's because we haven't specified a -protocol class for the factory to use. We'll do that in the -next example.

+exception. This time, it's because we haven't specified +a protocol class for the factory to use. We'll do that in +the next example.

SMTP Client 4

@@ -288,25 +287,26 @@ exarkun@boson:~/doc/mail/tutorial/smtpclient$ twistd -ny smtpclient-4.tac exarkun@boson:~/doc/mail/tutorial/smtpclient$ -

But what does this mean? -twisted.internet.protocol.Protocol is the base -protocol implementation. For those familiar with the classic -UNIX network services, it is equivalent to the discard -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.

+

But what does this +mean? twisted.internet.protocol.Protocol is the +base protocol implementation. For those familiar with the +classic UNIX network services, it is equivalent to +the discard 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.

SMTP Client 5

In smtpclient-5.tac, we will begin to use Twisted's SMTP protocol implementation for the first time. -We'll make the obvious change, simply swapping out -twisted.internet.protocol.Protocol in favor of -twisted.mail.smtp.ESMTPClient. Don't worry about the -E in ESMTP. It indicates we're actually using a -newer version of the SMTP protocol. There is an -SMTPClient in Twisted, but there's essentially no reason -to ever use it.

+We'll make the obvious change, simply swapping +out twisted.internet.protocol.Protocol in favor +of twisted.mail.smtp.ESMTPClient. Don't worry about +the E in ESMTP. It indicates we're actually using a +newer version of the SMTP protocol. There is +an SMTPClient in Twisted, but there's essentially no +reason to ever use it.

smtpclient-5.tac adds a new import:

@@ -314,10 +314,10 @@ to ever use it.

from twisted.mail import smtp -

All of the mail related code in Twisted exists beneath the -twisted.mail package. More specifically, everything -having to do with the SMTP protocol implementation is defined in the -twisted.mail.smtp module.

+

All of the mail related code in Twisted exists beneath +the twisted.mail package. More specifically, everything +having to do with the SMTP protocol implementation is defined in +the twisted.mail.smtp module.

Next we remove a line we added in smtpclient-4.tac:

@@ -379,17 +379,17 @@ exarkun@boson:~/doc/mail/tutorial/smtpclient$

Oops, back to getting a traceback. This time, the default implementation of buildProtocol seems no longer to be -sufficient. It instantiates the protocol with no arguments, but -ESMTPClient wants at least one argument. In the next +sufficient. It instantiates the protocol with no arguments, +but ESMTPClient wants at least one argument. In the next version of the client, we'll override buildProtocol to fix this problem.

SMTP Client 6

-

smtpclient-6.tac introduces a -twisted.internet.protocol.ClientFactory subclass with an -overridden buildProtocol method to overcome the problem -encountered in the previous example.

+

smtpclient-6.tac introduces +a twisted.internet.protocol.ClientFactory subclass with +an overridden buildProtocol method to overcome the +problem encountered in the previous example.

 class SMTPClientFactory(protocol.ClientFactory):
@@ -421,8 +421,8 @@ will now instantiate SMTPClientFactory:

 smtpClientFactory = SMTPClientFactory()
-

Running this version of the code, we observe that the code -still isn't quite traceback-free.

+

Running this version of the code, we observe that the +code still isn't quite traceback-free.

 exarkun@boson:~/doc/mail/tutorial/smtpclient$ twistd -ny smtpclient-6.tac
@@ -484,11 +484,11 @@ provide that information to it.

 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.  smtpclient-7.tac, however, defines a new
-class, SMTPTutorialClient, with three class attributes
-(mailFrom, mailTo, and
-mailData):

+a database, or be generated based on
+user-input.  smtpclient-7.tac, however,
+defines a new class, SMTPTutorialClient, with three class
+attributes (mailFrom, mailTo,
+and mailData):

 
 
 class SMTPTutorialClient(smtp.ESMTPClient):
@@ -552,14 +552,14 @@ Twisted is getMailData:

 

 
 
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
-StringIO since we already have a string containing our
-message.  If the contents of the file returned by
-getMailData span multiple lines (as email messages often
-do), the lines should be \n delimited (as they would be
-when opening a text file in the "rt" mode): necessary
-newline translation will be performed by SMTPClient
-automatically.

+object which contains the message contents.  In our case, we return
+a StringIO since we already have a string containing our
+message.  If the contents of the file returned
+by getMailData span multiple lines (as email messages
+often do), the lines should be \n delimited (as they
+would be when opening a text file in the "rt" mode):
+necessary newline translation will be performed
+by SMTPClient automatically.

 
 
There is one more new callback method defined in smtpclient-7.tac.
 This one isn't for providing information about the messages to
@@ -587,8 +587,8 @@ which starts up, connects to a (possibly) remote host, transmits some
 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.  smtpclient-8.tac extends
-sentMail with these two lines:

+simple.  smtpclient-8.tac
+extends sentMail with these two lines:

 
 
         from twisted.internet import reactor
@@ -667,11 +667,11 @@ def getMailExchange(host):
     return defer.succeed('localhost')
 

 
-
defer.succeed is a function which creates a new
-Deferred which already has a result, in this case
-'localhost'.  Now we need to adjust our
-TCPClient-constructing code to expect and properly handle
-this Deferred:

+
defer.succeed is a function which creates a
+new Deferred which already has a result, in this
+case 'localhost'.  Now we need to adjust
+our TCPClient-constructing code to expect and properly
+handle this Deferred:

 
 
 def cbMailExchange(exchange):
@@ -687,18 +687,18 @@ getMailExchange('example.net').addCallback(cbMailExchange)
 scope of this document.  For such a look, see
 the Deferred Reference.
 However, in brief, what this version of the code does is to delay the
-creation of the TCPClient until the
-Deferred returned by getMailExchange fires.
-Once it does, we proceed normally through the creation of our
-SMTPClientFactory and TCPClient, as well as
-set the TCPClient's service parent, just as we did in the
-previous examples.

+creation of the TCPClient until the Deferred
+returned by getMailExchange fires.  Once it does, we
+proceed normally through the creation of
+our SMTPClientFactory and TCPClient, as well
+as set the TCPClient's service parent, just as we did in
+the previous examples.

 
 
SMTP Client 11

 
 
At last we're ready to perform the mail exchange lookup.  We do
-this by calling on an object provided specifically for this task,
-twisted.mail.relaymanager.MXCalculator:

+this by calling on an object provided specifically for this
+task, twisted.mail.relaymanager.MXCalculator:

 
 
 def getMailExchange(host):
@@ -710,19 +710,14 @@ def getMailExchange(host):
 
Because getMX returns a Record_MX 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 Deferred from
-getMailExchange, so no further changes are required.  smtpclient-11.tac 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.

-
-
 
--->