1
<?xml version="1.0" encoding="utf-8"?><!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">
3
<title>Twisted Documentation: Designing Twisted Applications</title>
4
<link href="stylesheet.css" rel="stylesheet" type="text/css"/>
8
<h1 class="title">Designing Twisted Applications</h1>
9
<div class="toc"><ol><li><a href="#auto0">Goals</a></li><li><a href="#auto1">Example of a modular design: TwistedQuotes</a></li><ul><li><a href="#auto2">Set up the project directory</a></li><li><a href="#auto3">A Look at the Heart of the Application</a></li></ul></ol></div>
14
<h2>Goals<a name="auto0"/></h2>
16
<p>This document describes how a good Twisted application is structured. It
17
should be useful for beginning Twisted developers who want to structure their
18
code in a clean, maintainable way that reflects current best practices.</p>
20
<p>Readers will want to be familiar with writing <a href="servers.html" shape="rect">servers</a> and <a href="clients.html" shape="rect">clients</a> using Twisted.</p>
22
<h2>Example of a modular design: TwistedQuotes<a name="auto1"/></h2>
24
<p><code>TwistedQuotes</code> is a very simple plugin which is a great
26
Twisted's power. It will export a small kernel of functionality -- Quote of
27
the Day -- which can be accessed through every interface that Twisted supports:
28
web pages, e-mail, instant messaging, a specific Quote of the Day protocol, and
31
<h3>Set up the project directory<a name="auto2"/></h3>
33
<p>See the description of <a href="quotes.html" shape="rect">setting up the TwistedQuotes
36
<h3>A Look at the Heart of the Application<a name="auto3"/></h3>
38
<div class="py-listing"><pre><p class="py-linenumber"> 1
77
</p><span class="py-src-keyword">from</span> <span class="py-src-variable">random</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">choice</span>
79
<span class="py-src-keyword">from</span> <span class="py-src-variable">zope</span>.<span class="py-src-variable">interface</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">implements</span>
81
<span class="py-src-keyword">from</span> <span class="py-src-variable">TwistedQuotes</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">quoteproto</span>
85
<span class="py-src-keyword">class</span> <span class="py-src-identifier">StaticQuoter</span>:
86
<span class="py-src-string">"""
87
Return a static quote.
88
"""</span>
90
<span class="py-src-variable">implements</span>(<span class="py-src-variable">quoteproto</span>.<span class="py-src-variable">IQuoter</span>)
92
<span class="py-src-keyword">def</span> <span class="py-src-identifier">__init__</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">quote</span>):
93
<span class="py-src-variable">self</span>.<span class="py-src-variable">quote</span> = <span class="py-src-variable">quote</span>
96
<span class="py-src-keyword">def</span> <span class="py-src-identifier">getQuote</span>(<span class="py-src-parameter">self</span>):
97
<span class="py-src-keyword">return</span> <span class="py-src-variable">self</span>.<span class="py-src-variable">quote</span>
101
<span class="py-src-keyword">class</span> <span class="py-src-identifier">FortuneQuoter</span>:
102
<span class="py-src-string">"""
103
Load quotes from a fortune-format file.
104
"""</span>
105
<span class="py-src-variable">implements</span>(<span class="py-src-variable">quoteproto</span>.<span class="py-src-variable">IQuoter</span>)
107
<span class="py-src-keyword">def</span> <span class="py-src-identifier">__init__</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">filenames</span>):
108
<span class="py-src-variable">self</span>.<span class="py-src-variable">filenames</span> = <span class="py-src-variable">filenames</span>
111
<span class="py-src-keyword">def</span> <span class="py-src-identifier">getQuote</span>(<span class="py-src-parameter">self</span>):
112
<span class="py-src-variable">quoteFile</span> = <span class="py-src-variable">file</span>(<span class="py-src-variable">choice</span>(<span class="py-src-variable">self</span>.<span class="py-src-variable">filenames</span>))
113
<span class="py-src-variable">quotes</span> = <span class="py-src-variable">quoteFile</span>.<span class="py-src-variable">read</span>().<span class="py-src-variable">split</span>(<span class="py-src-string">'\n%\n'</span>)
114
<span class="py-src-variable">quoteFile</span>.<span class="py-src-variable">close</span>()
115
<span class="py-src-keyword">return</span> <span class="py-src-variable">choice</span>(<span class="py-src-variable">quotes</span>)
116
</pre><div class="caption">Twisted Quotes
117
Central Abstraction - <a href="listings/TwistedQuotes/quoters.py"><span class="filename">listings/TwistedQuotes/quoters.py</span></a></div></div>
119
<p>This code listing shows us what the Twisted Quotes system is all about. The
120
code doesn't have any way of talking to the outside world, but it provides a
121
library which is a clear and uncluttered abstraction: <q>give me the quote of
124
<p>Note that this module does not import any Twisted functionality at all! The
125
reason for doing things this way is integration. If your <q>business
126
objects</q> are not stuck to your user interface, you can make a module that
127
can integrate those objects with different protocols, GUIs, and file formats.
128
Having such classes provides a way to decouple your components from each other,
129
by allowing each to be used independently.</p>
131
<p>In this manner, Twisted itself has minimal impact on the logic of your
132
program. Although the Twisted <q>dot products</q> are highly interoperable,
134
also follow this approach. You can use them independently because they are not
135
stuck to each other. They communicate in well-defined ways, and only when that
136
communication provides some additional feature. Thus, you can use <code class="API"><a href="http://twistedmatrix.com/documents/13.2.0/api/twisted.web.html" title="twisted.web">twisted.web</a></code> with <code class="API"><a href="http://twistedmatrix.com/documents/13.2.0/api/twisted.enterprise.html" title="twisted.enterprise">twisted.enterprise</a></code>, but neither requires the other, because
137
they are integrated around the concept of <a href="defer.html" shape="rect">Deferreds</a>.</p>
139
<p>Your Twisted applications should follow this style as much as possible.
140
Have (at least) one module which implements your specific functionality,
141
independent of any user-interface code. </p>
143
<p>Next, we're going to need to associate this abstract logic with some way of
144
displaying it to the user. We'll do this by writing a Twisted server protocol,
145
which will respond to the clients that connect to it by sending a quote to the
146
client and then closing the connection. Note: don't get too focused on the
147
details of this -- different ways to interface with the user are 90% of what
148
Twisted does, and there are lots of documents describing the different ways to
151
<div class="py-listing"><pre><p class="py-linenumber"> 1
187
</p><span class="py-src-keyword">from</span> <span class="py-src-variable">zope</span>.<span class="py-src-variable">interface</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">Interface</span>
189
<span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">internet</span>.<span class="py-src-variable">protocol</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">Factory</span>, <span class="py-src-variable">Protocol</span>
193
<span class="py-src-keyword">class</span> <span class="py-src-identifier">IQuoter</span>(<span class="py-src-parameter">Interface</span>):
194
<span class="py-src-string">"""
195
An object that returns quotes.
196
"""</span>
197
<span class="py-src-keyword">def</span> <span class="py-src-identifier">getQuote</span>():
198
<span class="py-src-string">"""
200
"""</span>
204
<span class="py-src-keyword">class</span> <span class="py-src-identifier">QOTD</span>(<span class="py-src-parameter">Protocol</span>):
205
<span class="py-src-keyword">def</span> <span class="py-src-identifier">connectionMade</span>(<span class="py-src-parameter">self</span>):
206
<span class="py-src-variable">self</span>.<span class="py-src-variable">transport</span>.<span class="py-src-variable">write</span>(<span class="py-src-variable">self</span>.<span class="py-src-variable">factory</span>.<span class="py-src-variable">quoter</span>.<span class="py-src-variable">getQuote</span>()+<span class="py-src-string">'\r\n'</span>)
207
<span class="py-src-variable">self</span>.<span class="py-src-variable">transport</span>.<span class="py-src-variable">loseConnection</span>()
211
<span class="py-src-keyword">class</span> <span class="py-src-identifier">QOTDFactory</span>(<span class="py-src-parameter">Factory</span>):
212
<span class="py-src-string">"""
213
A factory for the Quote of the Day protocol.
215
@type quoter: L{IQuoter} provider
216
@ivar quoter: An object which provides L{IQuoter} which will be used by
217
the L{QOTD} protocol to get quotes to emit.
218
"""</span>
219
<span class="py-src-variable">protocol</span> = <span class="py-src-variable">QOTD</span>
221
<span class="py-src-keyword">def</span> <span class="py-src-identifier">__init__</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">quoter</span>):
222
<span class="py-src-variable">self</span>.<span class="py-src-variable">quoter</span> = <span class="py-src-variable">quoter</span>
223
</pre><div class="caption">Twisted
224
Quotes Protocol Implementation - <a href="listings/TwistedQuotes/quoteproto.py"><span class="filename">listings/TwistedQuotes/quoteproto.py</span></a></div></div>
226
<p>This is a very straightforward <code>Protocol</code> implementation, and the
227
pattern described above is repeated here. The Protocol contains essentially no
228
logic of its own, just enough to tie together an object which can generate
229
quotes (a <code class="python">Quoter</code>) and an object which can relay
230
bytes to a TCP connection (a <code class="python">Transport</code>). When a
231
client connects to this server, a <code class="python">QOTD</code> instance is
232
created, and its <code class="python">connectionMade</code> method is called.
235
<p> The <code class="python">QOTDFactory</code>'s role is to specify to the
236
Twisted framework how to create a <code class="python">Protocol</code> instance
237
that will handle the connection. Twisted will not instantiate a <code class="python">QOTDFactory</code>; you will do that yourself later, in a <code class="shell">twistd</code> plug-in.
240
<p>Note: you can read more specifics of <code class="python">Protocol</code> and <code class="python">Factory</code> in the <a href="servers.html" shape="rect">Writing
241
Servers</a> HOWTO.</p>
243
<p>Once we have an abstraction -- a <code>Quoter</code> -- and we have a
244
mechanism to connect it to the network -- the <code>QOTD</code> protocol -- the
245
next thing to do is to put the last link in the chain of functionality between
246
abstraction and user. This last link will allow a user to choose a <code>Quoter</code> and configure the protocol. Writing this configuration is
247
covered in the <a href="application.html" shape="rect">Application HOWTO</a>.</p>
251
<p><a href="index.html">Index</a></p>
252
<span class="version">Version: 13.2.0</span>
b'\\ No newline at end of file'
added
removed
doc/core/howto/design.html
