~certify-web-dev/twisted/certify-staging

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><title>Twisted Documentation: Writing Servers</title><link href="stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">Writing Servers</h1><div class="toc"><ol><li><a href="#auto0">Overview</a></li><li><a href="#auto1">Protocols</a></li><ul><li><a href="#auto2">Using the Protocol</a></li><li><a href="#auto3">Helper Protocols</a></li><li><a href="#auto4">State Machines</a></li></ul><li><a href="#auto5">Factories</a></li><ul><li><a href="#auto6">Putting it All Together</a></li></ul></ol></div><div class="content"><h2>Overview<a name="auto0"></a></h2>Twisted is a framework designed to be very flexible and let

<?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'>

<head>

<title>Twisted Documentation: Writing Servers</title>

</head>

<h1 class="title">Writing Servers</h1>

<div class="toc"><ol><li><a href="#auto0">Overview</a></li><li><a href="#auto1">Protocols</a></li><ul><li><a href="#auto2">Using the Protocol</a></li><li><a href="#auto3">Helper Protocols</a></li><li><a href="#auto4">State Machines</a></li></ul><li><a href="#auto5">Factories</a></li><ul><li><a href="#auto6">Putting it All Together</a></li></ul></ol></div>

<h2>Overview<a name="auto0"/></h2>

Twisted is a framework designed to be very flexible and let

you write powerful servers. The cost of this flexibility is a

few layers in the way to writing your server.This document describes the

<code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.protocol.Protocol.html" title="twisted.internet.protocol.Protocol">Protocol</a></code>

few layers in the way to writing your server.

This document describes the

<code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.protocol.Protocol.html" title="twisted.internet.protocol.Protocol">Protocol</a></code>

layer, where you

implement protocol parsing and handling. If you are implementing

an application then you should read this document second, after

first reading the top level overview of how to begin writing your

Twisted application, in <a href="plugin.html">Writing Plug-Ins

Twisted application, in <a href="plugin.html" shape="rect">Writing Plug-Ins

for Twisted</a>. This document is only relevant to TCP, SSL and

Unix socket servers, there is a <a href="udp.html">separate document</a>

for UDP.Your protocol handling class will usually subclass <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.protocol.Protocol.html" title="twisted.internet.protocol.Protocol">twisted.internet.protocol.Protocol</a></code>. Most

Unix socket servers, there is a <a href="udp.html" shape="rect">separate document</a>

for UDP.

Your protocol handling class will usually subclass <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.protocol.Protocol.html" title="twisted.internet.protocol.Protocol">twisted.internet.protocol.Protocol</a></code>. Most

protocol handlers inherit either from this class or from one of

its convenience children. An instance of the protocol class

might be instantiated per-connection, on demand, and might go

away when the connection is finished. This means that

persistent configuration is not saved in the

<code>Protocol</code>.The persistent configuration is kept in a Factory class,

which usually inherits from <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.protocol.Factory.html" title="twisted.internet.protocol.Factory">twisted.internet.protocol.Factory</a></code>. The

<code>Protocol</code>.

The persistent configuration is kept in a Factory class,

which usually inherits from <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.protocol.Factory.html" title="twisted.internet.protocol.Factory">twisted.internet.protocol.Factory</a></code>. The

default factory class just instantiates each <code>Protocol</code>, and then

sets on it an attribute called <code>factory</code> which

points to itself. This lets every <code>Protocol</code> access,

and possibly modify, the persistent configuration.It is usually useful to be able to offer the same service on

and possibly modify, the persistent configuration.

It is usually useful to be able to offer the same service on

multiple ports or network addresses. This is why the <code>Factory</code>

does not listen to connections, and in fact does not

know anything about the network. See <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.interfaces.IReactorTCP.listenTCP.html" title="twisted.internet.interfaces.IReactorTCP.listenTCP">twisted.internet.interfaces.IReactorTCP.listenTCP</a></code>,

know anything about the network. See <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.interfaces.IReactorTCP.listenTCP.html" title="twisted.internet.interfaces.IReactorTCP.listenTCP">twisted.internet.interfaces.IReactorTCP.listenTCP</a></code>,

and the other <code>IReactor*.listen*</code> APIs for more

information.This document will explain each step of the way.<h2>Protocols<a name="auto1"></a></h2>As mentioned above, this, along with auxiliary classes and

information.

This document will explain each step of the way.

<h2>Protocols<a name="auto1"/></h2>

As mentioned above, this, along with auxiliary classes and

functions, is where most of the code is. A Twisted protocol

handles data in an asynchronous manner. What this means is that

the protocol never waits for an event, but rather responds to

events as they arrive from the network.Here is a simple example:<pre class="python">

from twisted.internet.protocol import Protocol

events as they arrive from the network.

Here is a simple example:

<pre class="python">1

from twisted.internet.protocol import Protocol

class Echo(Protocol):

def dataReceived(self, data):

self.transport.write(data)

</pre>This is one of the simplest protocols. It simply writes back

</pre>

This is one of the simplest protocols. It simply writes back

whatever is written to it, and does not respond to all events. Here is an

example of a Protocol responding to another event:<pre class="python">

example of a Protocol responding to another event:

<pre class="python">1

class QOTD(Protocol):

def connectionMade(self):

self.transport.write("An apple a day keeps the doctor away\r\n")

self.transport.loseConnection()

</pre>This protocol responds to the initial connection with a well

known quote, and then terminates the connection.The connectionMade event is usually where set up of the

</pre>

100

This protocol responds to the initial connection with a well

101

known quote, and then terminates the connection.

102

103

The connectionMade event is usually where set up of the

104

connection object happens, as well as any initial greetings (as

105

in the QOTD protocol above, which is actually based on RFC

106

865). The <code>connectionLost</code> event is where tearing down of any

connection-specific objects is done. Here is an example:<pre class="python">

107

connection-specific objects is done. Here is an example:

108

<pre class="python"> 1

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

class Echo(Protocol):

126

135

136

def dataReceived(self, data):

137

self.transport.write(data)

</pre>Here <code>connectionMade</code> and

138

</pre>

139

140

Here <code>connectionMade</code> and

141

<code>connectionLost</code> cooperate to keep a count of the

142

active protocols in the factory. <code>connectionMade</code>

143

immediately closes the connection if there are too many active

protocols.<h3>Using the Protocol<a name="auto2"></a></h3>In this section, I will explain how to test your protocol

144

protocols.

145

146

<h3>Using the Protocol<a name="auto2"/></h3>

147

148

In this section, I will explain how to test your protocol

149

easily. (In order to see how you should write a production-grade Twisted

server, though, you should read the <a href="plugin.html">Writing Plug-Ins

for Twisted</a> HOWTO as well).Here is code that will run the QOTD server discussed

earlier<pre class="python">

150

server, though, you should read the <a href="plugin.html" shape="rect">Writing Plug-Ins

151

for Twisted</a> HOWTO as well).

152

153

Here is code that will run the QOTD server discussed

154

earlier

155

<pre class="python"> 1

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

from twisted.internet import reactor

173

174

class QOTD(Protocol):

177

178

self.transport.loseConnection()

179

# Next lines are magic:

factory = Factory()

180

# Next lines are magic:

181

factory = Factory()

182

factory.protocol = QOTD

183

# 8007 is the port you want to run under. Choose something >1024

reactor.listenTCP(8007, factory)

184

# 8007 is the port you want to run under. Choose something >1024

185

reactor.listenTCP(8007, factory)

186

reactor.run()

</pre>Don't worry about the last 6 magic lines -- you will

understand what they do later in the document.<h3>Helper Protocols<a name="auto3"></a></h3>Many protocols build upon similar lower-level abstraction.

187

</pre>

188

189

Don't worry about the last 6 magic lines -- you will

190

understand what they do later in the document.

191

192

<h3>Helper Protocols<a name="auto3"/></h3>

193

194

Many protocols build upon similar lower-level abstraction.

195

The most popular in internet protocols is being line-based.

Lines are usually terminated with a CR-LF combinations.However, quite a few protocols are mixed - they have

196

Lines are usually terminated with a CR-LF combinations.

197

198

However, quite a few protocols are mixed - they have

100

199

line-based sections and then raw data sections. Examples

101

include HTTP/1.1 and the Freenet protocol.For those cases, there is the <code>LineReceiver</code>

200

include HTTP/1.1 and the Freenet protocol.

201

202

For those cases, there is the <code>LineReceiver</code>

102

203

protocol. This protocol dispatches to two different event

103

204

handlers - <code>lineReceived</code> and

104

205

<code>rawDataReceived</code>. By default, only

106

207

However, if <code>setRawMode</code> is called, the protocol

107

208

will call <code>rawDataReceived</code> until

108

209

<code>setLineMode</code> is called, which returns it to using

109

<code>lineReceived</code>.Here is an example for a simple use of the line

110

receiver:<pre class="python">

111

from twisted.protocols.basic import LineReceiver

210

<code>lineReceived</code>.

211

212

Here is an example for a simple use of the line

213

receiver:

214

<pre class="python"> 1

215

216

217

218

219

220

221

222

223

224

225

from twisted.protocols.basic import LineReceiver

112

226

113

227

class Answer(LineReceiver):

114

228

119

233

self.sendLine(self.answers[line])

120

234

else:

121

235

122

</pre>Note that the delimiter is not part of the line.Several other, less popular, helpers exist, such as a

236

</pre>

237

238

Note that the delimiter is not part of the line.

239

240

Several other, less popular, helpers exist, such as a

123

241

netstring based protocol and a prefixed-message-length

124

protocol.<h3>State Machines<a name="auto4"></a></h3>Many Twisted protocol handlers need to write a state machine

242

protocol.

243

244

<h3>State Machines<a name="auto4"/></h3>

245

246

Many Twisted protocol handlers need to write a state machine

125

247

to record the state they are at. Here are some pieces of advice

126

which help to write state machines:<ul><li>Don't write big state machines. Prefer to write a state

248

which help to write state machines:

249

250

<ul>

251

<li>Don't write big state machines. Prefer to write a state

127

252

machine which deals with one level of abstraction at a

128

time.</li><li>Use Python's dynamicity to create open ended state

253

time.</li>

254

255

<li>Use Python's dynamicity to create open ended state

129

256

machines. See, for example, the code for the SMTP

130

client.</li><li>Don't mix application-specific code with Protocol

257

client.</li>

258

259

<li>Don't mix application-specific code with Protocol

131

260

handling code. When the protocol handler has to make an

132

application-specific call, keep it as a method call.</li></ul><h2>Factories<a name="auto5"></a></h2>As mentioned before, usually the class <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.protocol.Factory.html" title="twisted.internet.protocol.Factory">twisted.internet.protocol.Factory</a></code> works,

261

application-specific call, keep it as a method call.</li>

262

</ul>

263

264

<h2>Factories<a name="auto5"/></h2>

265

266

As mentioned before, usually the class <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.protocol.Factory.html" title="twisted.internet.protocol.Factory">twisted.internet.protocol.Factory</a></code> works,

133

267

and there is no need to subclass it. However, sometimes there

134

268

can be factory-specific configuration of the protocols, or

135

269

other considerations. In those cases, there is a need to

136

subclass <code>Factory</code>.For a factory which simply instantiates instances of a

270

subclass <code>Factory</code>.

271

272

For a factory which simply instantiates instances of a

137

273

specific protocol class, simply instantiate

138

<code>Factory</code>, and sets its <code>protocol</code> attribute:<pre class="python">

139

274

<code>Factory</code>, and sets its <code>protocol</code> attribute:

275

<pre class="python">1

276

277

278

279

280

140

281

from twisted.protocols.wire import Echo

141

282

142

283

myFactory = Factory()

143

284

myFactory.protocol = Echo

144

</pre>If there is a need to easily construct factories for a

145

specific configuration, a factory function is often useful:<pre class="python">

146

285

</pre>

286

287

If there is a need to easily construct factories for a

288

specific configuration, a factory function is often useful:

289

<pre class="python"> 1

290

291

292

293

294

295

296

297

298

299

300

301

302

303

147

304

148

305

class QOTD(Protocol):

149

306

157

314

factory.protocol = QOTD

158

315

factory.quote = quote or 'An apple a day keeps the doctor away'

159

316

return factory

160

</pre>A Factory has two methods to perform application-specific

317

</pre>

318

319

A Factory has two methods to perform application-specific

161

320

building up and tearing down (since a Factory is frequently

162

321

persisted, it is often not appropriate to do them in <code>__init__</code>

163

or <code>__del__</code>, and would frequently be too early or too late).Here is an example of a factory which allows its Protocols

164

to write to a special log-file:<pre class="python">

165

322

or <code>__del__</code>, and would frequently be too early or too late).

323

324

Here is an example of a factory which allows its Protocols

325

to write to a special log-file:

326

<pre class="python"> 1

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

166

349

167

350

168

351

184

367

185

368

def stopFactory(self):

186

369

self.fp.close()

187

</pre><h3>Putting it All Together<a name="auto6"></a></h3>So, you know what factories are, and want to run the QOTD

370

</pre>

371

372

<h3>Putting it All Together<a name="auto6"/></h3>

373

374

So, you know what factories are, and want to run the QOTD

188

375

with configurable quote server, do you? No problems, here is an

189

example.<pre class="python">

190

376

example.

377

378

<pre class="python"> 1

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

191

398

192

399

193

400

class QOTD(Protocol):

206

413

207

414

reactor.listenTCP(8007, QOTDFactory("configurable quote"))

208

415

reactor.run()

209

</pre>The only lines you might not understand are the last two.<code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.interfaces.IReactorTCP.listenTCP.html" title="twisted.internet.interfaces.IReactorTCP.listenTCP">listenTCP</a></code> is

416

</pre>

417

418

The only lines you might not understand are the last two.

419

420

<code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.interfaces.IReactorTCP.listenTCP.html" title="twisted.internet.interfaces.IReactorTCP.listenTCP">listenTCP</a></code> is

210

421

the method which connects a <code>Factory</code> to the network.

211

422

It uses the reactor interface, which lets many different loops handle

212

423

the networking code, without modifying end-user code, like this.

213

424

As mentioned above, if you want to write your code to be a production-grade

214

425

Twisted server, and not a mere 20-line hack, you will want to

215

use <a href="application.html">the Application object</a>.</div><a href="index.html">Index</a>Version: 8.2.0</body></html>

b'\\ No newline at end of file'

426

use <a href="application.html" shape="rect">the Application object</a>.

427

428

</div>

429

430

<a href="index.html">Index</a>

431

Version: 9.0.0

432

</body>

433

</html>

b'\\ No newline at end of file'

Older »