Overview
Twisted is a framework designed to be very flexible, and let you write powerful clients. The cost of this flexibility is a few layers in the way to writing your client. This document covers creating clients that can be used for TCP, SSL and Unix sockets. UDP is covered in a different document.
At the base, the place where you actually implement the protocol parsing
and handling, is the Protocol
class. This class will usually be
descended
from twisted.internet.protocol.Protocol
. Most
protocol handlers inherit either from this class or from one of its
convenience children. An instance of the protocol class will be instantiated
when you connect to the server and will go away when the connection is
finished. This means that persistent configuration is not saved in the
Protocol
.
The persistent configuration is kept in a Factory
class, which usually inherits from twisted.internet.protocol.Factory
(or twisted.internet.protocol.ClientFactory
: see
below). The default factory class just instantiates the Protocol
and then sets the protocol's factory
attribute to point to
itself (the factory). This lets the Protocol
access, and
possibly modify, the persistent configuration.
Protocol
As mentioned above, this and auxiliary classes and functions are where most of the code is. A Twisted protocol handles data in an asynchronous manner. This means that the protocol never waits for an event, but rather responds to events as they arrive from the network.
Here is a simple example:
1 2 3 4 5 6
from twisted.internet.protocol import Protocol from sys import stdout class Echo(Protocol): def dataReceived(self, data): stdout.write(data)
This is one of the simplest protocols. It just writes whatever it reads
from the connection to standard output. There are many events it does not
respond to. Here is an example of a Protocol
responding to
another event:
1 2 3 4 5 6
from twisted.internet.protocol import Protocol class WelcomeMessage(Protocol): def connectionMade(self): self.transport.write("Hello server, I am the client!\r\n") self.transport.loseConnection()
This protocol connects to the server, sends it a welcome message, and then terminates the connection.
The connectionMade
event is
usually where set up of the Protocol
object happens, as well as
any initial greetings (as in the
WelcomeMessage
protocol above). Any tearing down of
Protocol
-specific objects is done in connectionLost
.
Simple, single-use clients
In many cases, the protocol only needs to connect to the server once, and
the code just wants to get a connected instance of the protocol. In those
cases twisted.internet.endpoints
provides the
appropriate API.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
from twisted.internet import reactor from twisted.internet.protocol import Factory, Protocol from twisted.internet.endpoints import TCP4ClientEndpoint class Greeter(Protocol): def sendMessage(self, msg): self.transport.write("MESSAGE %s\n" % msg) class GreeterFactory(Factory): def buildProtocol(self, addr): return Greeter() def gotProtocol(p): p.sendMessage("Hello") reactor.callLater(1, p.sendMessage, "This is sent in a second") reactor.callLater(2, p.transport.loseConnection) point = TCP4ClientEndpoint(reactor, "localhost", 1234) d = point.connect(GreeterFactory()) d.addCallback(gotProtocol) reactor.run()
Regardless of the type of client endpoint, the way to set up a new
connection is simply to call the connect
method on it and pass
in a factory. This means it's easy to change the mechanism you're using to
connect, without changing the rest of your program. For example, to run
the greeter example over SSL, the only change required is to instantiate an
SSL4ClientEndpoint
instead of a
TCP4ClientEndpoint
. To take advantage of this, functions and
methods which initiates a new connection should generally accept an
endpoint as an argument and let the caller construct it, rather than taking
arguments like 'host' and 'port' and constructing its own before calling
connect
.
For more information on different ways you can make outgoing connections to different types of endpoints, as well as parsing strings into endpoints, see the documentation for the endpoints API.
ClientFactory
before,
make sure you remember that the connect
method takes a
Factory
, not a ClientFactory
. Even if you pass a
ClientFactory
to endpoint.connect
, its
clientConnectionFailed
and clientConnectionLost
methods will not be called.You may come across code using ClientCreator
, an older API which is not as flexible as
the endpoint API. Rather than calling connect
on an endpoint,
such code will look like this:
1 2 3 4 5 6 7 8
from twisted.internet.protocol import ClientCreator ... creator = ClientCreator(reactor, Greeter) d = creator.connectTCP("localhost", 1234) d.addCallback(gotProtocol) reactor.run()
In general, the endpoint API should be preferred in new code, as it lets the caller select the method of connecting.
ClientFactory
Still, there's plenty of code out there that uses lower-level APIs, and a few features (such as automatic reconnection) have not been re-implemented with endpoints yet, so in some cases they may be more convenient to use.
To use the lower-level connection APIs, you will need to call one of the
reactor.connect* methods directly. For these cases, you need a
ClientFactory
.
The ClientFactory
is in charge of creating the
Protocol
and also receives events relating to the connection
state. This allows it to do things like reconnect in the event of a
connection error. Here is an example of a simple ClientFactory
that uses the Echo
protocol (above) and also prints what state
the connection is in.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
from twisted.internet.protocol import Protocol, ClientFactory from sys import stdout class Echo(Protocol): def dataReceived(self, data): stdout.write(data) class EchoClientFactory(ClientFactory): def startedConnecting(self, connector): print 'Started to connect.' def buildProtocol(self, addr): print 'Connected.' return Echo() def clientConnectionLost(self, connector, reason): print 'Lost connection. Reason:', reason def clientConnectionFailed(self, connector, reason): print 'Connection failed. Reason:', reason
To connect this EchoClientFactory
to a server, you could use
this code:
1 2 3
from twisted.internet import reactor reactor.connectTCP(host, port, EchoClientFactory()) reactor.run()
Note that clientConnectionFailed
is called when a connection could not be established, and that clientConnectionLost
is called when a connection was made and then disconnected.
Reconnection
Often, the connection of a client will be lost unintentionally due to
network problems. One way to reconnect after a disconnection would be to
call connector.connect()
when the connection is lost:
1 2 3 4 5
from twisted.internet.protocol import ClientFactory class EchoClientFactory(ClientFactory): def clientConnectionLost(self, connector, reason): connector.connect()
The connector passed as the first argument is the interface between a
connection and a protocol. When the connection fails and the factory
receives the clientConnectionLost
event, the factory can
call connector.connect()
to start the connection over again
from scratch.
However, most programs that want this functionality should
implement ReconnectingClientFactory
instead,
which tries to reconnect if a connection is lost or fails and which
exponentially delays repeated reconnect attempts.
Here is the Echo
protocol implemented with
a ReconnectingClientFactory
:
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
from twisted.internet.protocol import Protocol, ReconnectingClientFactory from sys import stdout class Echo(Protocol): def dataReceived(self, data): stdout.write(data) class EchoClientFactory(ReconnectingClientFactory): def startedConnecting(self, connector): print 'Started to connect.' def buildProtocol(self, addr): print 'Connected.' print 'Resetting reconnection delay' self.resetDelay() return Echo() def clientConnectionLost(self, connector, reason): print 'Lost connection. Reason:', reason ReconnectingClientFactory.clientConnectionLost(self, connector, reason) def clientConnectionFailed(self, connector, reason): print 'Connection failed. Reason:', reason ReconnectingClientFactory.clientConnectionFailed(self, connector, reason)
A Higher-Level Example: ircLogBot
Overview of ircLogBot
The clients so far have been fairly simple. A more complicated example
comes with Twisted Words in the doc/words/examples
directory.
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
# twisted imports from twisted.words.protocols import irc from twisted.internet import reactor, protocol from twisted.python import log # system imports import time, sys class MessageLogger: """ An independent logger class (because separation of application and protocol logic is a good thing). """ def __init__(self, file): self.file = file def log(self, message): """Write a message to the file.""" timestamp = time.strftime("[%H:%M:%S]", time.localtime(time.time())) self.file.write('%s %s\n' % (timestamp, message)) self.file.flush() def close(self): self.file.close() class LogBot(irc.IRCClient): """A logging IRC bot.""" nickname = "twistedbot" def connectionMade(self): irc.IRCClient.connectionMade(self) self.logger = MessageLogger(open(self.factory.filename, "a")) self.logger.log("[connected at %s]" % time.asctime(time.localtime(time.time()))) def connectionLost(self, reason): irc.IRCClient.connectionLost(self, reason) self.logger.log("[disconnected at %s]" % time.asctime(time.localtime(time.time()))) self.logger.close() # callbacks for events def signedOn(self): """Called when bot has succesfully signed on to server.""" self.join(self.factory.channel) def joined(self, channel): """This will get called when the bot joins the channel.""" self.logger.log("[I have joined %s]" % channel) def privmsg(self, user, channel, msg): """This will get called when the bot receives a message.""" user = user.split('!', 1)[0] self.logger.log("<%s> %s" % (user, msg)) # Check to see if they're sending me a private message if channel == self.nickname: msg = "It isn't nice to whisper! Play nice with the group." self.msg(user, msg) return # Otherwise check to see if it is a message directed at me if msg.startswith(self.nickname + ":"): msg = "%s: I am a log bot" % user self.msg(channel, msg) self.logger.log("<%s> %s" % (self.nickname, msg)) def action(self, user, channel, msg): """This will get called when the bot sees someone do an action.""" user = user.split('!', 1)[0] self.logger.log("* %s %s" % (user, msg)) # irc callbacks def irc_NICK(self, prefix, params): """Called when an IRC user changes their nickname.""" old_nick = prefix.split('!')[0] new_nick = params[0] self.logger.log("%s is now known as %s" % (old_nick, new_nick)) # For fun, override the method that determines how a nickname is changed on # collisions. The default method appends an underscore. def alterCollidedNick(self, nickname): """ Generate an altered version of a nickname that caused a collision in an effort to create an unused related name for subsequent registration. """ return nickname + '^' class LogBotFactory(protocol.ClientFactory): """A factory for LogBots. A new protocol instance will be created each time we connect to the server. """ def __init__(self, channel, filename): self.channel = channel self.filename = filename def buildProtocol(self, addr): p = LogBot() p.factory = self return p def clientConnectionLost(self, connector, reason): """If we get disconnected, reconnect to server.""" connector.connect() def clientConnectionFailed(self, connector, reason): print "connection failed:", reason reactor.stop() if __name__ == '__main__': # initialize logging log.startLogging(sys.stdout) # create factory protocol and application f = LogBotFactory(sys.argv[1], sys.argv[2]) # connect factory to this host and port reactor.connectTCP("irc.freenode.net", 6667, f) # run bot reactor.run()
ircLogBot.py
connects to an IRC server, joins a channel, and
logs all traffic on it to a file. It demonstrates some of the
connection-level logic of reconnecting on a lost connection, as well as
storing persistent data in the Factory
.
Persistent Data in the Factory
Since the Protocol
instance is recreated each time the
connection is made, the client needs some way to keep track of data that
should be persisted. In the case of the logging bot, it needs to know which
channel it is logging, and where to log it.
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
from twisted.words.protocols import irc from twisted.internet import protocol class LogBot(irc.IRCClient): def connectionMade(self): irc.IRCClient.connectionMade(self) self.logger = MessageLogger(open(self.factory.filename, "a")) self.logger.log("[connected at %s]" % time.asctime(time.localtime(time.time()))) def signedOn(self): self.join(self.factory.channel) class LogBotFactory(protocol.ClientFactory): def __init__(self, channel, filename): self.channel = channel self.filename = filename def buildProtocol(self, addr): p = LogBot() p.factory = self return p
When the protocol is created, it gets a reference to the factory as
self.factory
. It can then access attributes of the factory in
its logic. In the case of LogBot
, it opens the file and
connects to the channel stored in the factory.
Factories have a default implementation of buildProtocol
that does the same thing the example above does, using
the protocol
attribute of the factory to create the protocol
instance. In the example above, the factory could be rewritten to look
like this:
1 2 3 4 5 6
class LogBotFactory(protocol.ClientFactory): protocol = LogBot def __init__(self, channel, filename): self.channel = channel self.filename = filename
Further Reading
The Protocol
class used throughout this document is a base implementation
of IProtocol
used in most Twisted applications for convenience. To learn about the
complete IProtocol
interface, see the API documentation for
IProtocol
.
The transport
attribute used in some examples in this
document provides the ITCPTransport
interface. To learn
about the complete interface, see the API documentation
for ITCPTransport
.
Interface classes are a way of specifying what methods and attributes an object has and how they behave. See the Components: Interfaces and Adapters document for more information on using interfaces in Twisted.