~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 Clients</title><link href="stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">Writing Clients</h1><div class="toc"><ol><li><a href="#auto0">Overview</a></li><li><a href="#auto1">Protocol</a></li><li><a href="#auto2">Simple, single-use clients</a></li><li><a href="#auto3">ClientFactory</a></li><ul><li><a href="#auto4">Reconnection</a></li></ul><li><a href="#auto5">A Higher-Level Example: ircLogBot</a></li><ul><li><a href="#auto6">Overview of ircLogBot</a></li><li><a href="#auto7">Persistent Data in the Factory</a></li></ul><li><a href="#auto8">Further Reading</a></li></ol></div><div class="content"><h2>Overview<a name="auto0"></a></h2>Twisted is a framework designed to be very flexible, and let you write

<?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 Clients</title>

</head>

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

<div class="toc"><ol><li><a href="#auto0">Overview</a></li><li><a href="#auto1">Protocol</a></li><li><a href="#auto2">Simple, single-use clients</a></li><li><a href="#auto3">ClientFactory</a></li><ul><li><a href="#auto4">Reconnection</a></li></ul><li><a href="#auto5">A Higher-Level Example: ircLogBot</a></li><ul><li><a href="#auto6">Overview of ircLogBot</a></li><li><a href="#auto7">Persistent Data in the Factory</a></li></ul><li><a href="#auto8">Further Reading</a></li></ol></div>

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

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 <a href="udp.html">in

a different document</a>.At the base, the place where you actually implement the protocol parsing

used for TCP, SSL and Unix sockets, UDP is covered <a href="udp.html" shape="rect">in

a different document</a>.

At the base, the place where you actually implement the protocol parsing

and handling, is the Protocol class. This class will usually be decended

from <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

from <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 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 <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.protocol.ClientFactory.html" title="twisted.internet.protocol.ClientFactory">twisted.internet.protocol.ClientFactory</a></code>. The default

saved in the Protocol.

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.ClientFactory.html" title="twisted.internet.protocol.ClientFactory">twisted.internet.protocol.ClientFactory</a></code>. The default

factory class just instantiate the Protocol, and then sets on it an

attribute called <code>factory</code> which points to itself. This let

the Protocol access, and possibly modify, the persistent

configuration.<h2>Protocol<a name="auto1"></a></h2>As mentioned above, this, and auxiliary classes and functions, is where

configuration.

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

As mentioned above, this, and 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

rather responds to events as they arrive from the network.

Here is a simple example:

<pre class="python">1

from twisted.internet.protocol import Protocol

from sys import stdout

class Echo(Protocol):

def dataReceived(self, data):

stdout.write(data)

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

</pre>

This is one of the simplest protocols. It simply writes to standard

output whatever it reads from the connection. There are many events it

does not respond to. Here is an example of a Protocol responding to

another event.<pre class="python">

another event.

<pre class="python">1

class WelcomeMessage(Protocol):

def connectionMade(self):

self.transport.write("Hello server, I am the client!\r\n")

self.transport.loseConnection()

</pre>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

</pre>

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.<h2>Simple, single-use clients<a name="auto2"></a></h2>In many cases, the protocol only needs to connect to the server once,

objects is done in connectionLost.

<h2>Simple, single-use clients<a name="auto2"/></h2>

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 <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.protocol.ClientCreator.html" title="twisted.internet.protocol.ClientCreator">twisted.internet.protocol.ClientCreator</a></code> provides the

appropriate API.<pre class="python">

from twisted.internet import reactor

those cases <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.protocol.ClientCreator.html" title="twisted.internet.protocol.ClientCreator">twisted.internet.protocol.ClientCreator</a></code> provides the

appropriate API.

<pre class="python"> 1

100

101

102

103

104

105

106

107

108

109

110

111

112

from twisted.internet import reactor

113

114

115

class Greeter(Protocol):

123

124

c = ClientCreator(reactor, Greeter)

125

c.connectTCP("localhost", 1234).addCallback(gotProtocol)

</pre><h2>ClientFactory<a name="auto3"></a></h2>We use reactor.connect* and a ClientFactory. The ClientFactory is in

126

</pre>

127

128

<h2>ClientFactory<a name="auto3"/></h2>

129

130

We use reactor.connect* and a ClientFactory. The ClientFactory is in

131

charge of creating the Protocol, and also receives events relating to the

132

connection state. This allows it to do things like reconnect on the event

133

of a connection error. Here is an example of a simple ClientFactory that

134

uses the Echo protocol (above) and also prints what state the connection

is in.<pre class="python">

135

is in.

136

137

<pre class="python"> 1

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

from sys import stdout

159

160

class Echo(Protocol):

174

175

def clientConnectionFailed(self, connector, reason):

176

print 'Connection failed. Reason:', reason

</pre>To connect this EchoClientFactory to a server, you could use this

code:<pre class="python">

177

</pre>

178

179

To connect this EchoClientFactory to a server, you could use this

180

code:

181

182

<pre class="python">1

183

184

185

186

reactor.connectTCP(host, port, EchoClientFactory())

187

reactor.run()

</pre>Note that <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.protocol.ClientFactory.clientConnectionFailed.html" title="twisted.internet.protocol.ClientFactory.clientConnectionFailed">clientConnectionFailed</a></code>

is called when a connection could not be established, and that <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.protocol.ClientFactory.clientConnectionLost.html" title="twisted.internet.protocol.ClientFactory.clientConnectionLost">clientConnectionLost</a></code>

is called when a connection was made and then disconnected.<h3>Reconnection<a name="auto4"></a></h3>Many times, the connection of a client will be lost unintentionally due

188

</pre>

189

190

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

191

is called when a connection could not be established, and that <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.protocol.ClientFactory.clientConnectionLost.html" title="twisted.internet.protocol.ClientFactory.clientConnectionLost">clientConnectionLost</a></code>

192

is called when a connection was made and then disconnected.

193

194

<h3>Reconnection<a name="auto4"/></h3>

195

196

Many times, the connection of a client will be lost unintentionally due

197

to network errors. One way to reconnect after a disconnection would be to

198

call <code class="python">connector.connect()</code> when the

199

connection is lost:

200

201

202

<pre class="python">1

203

204

205

206

207

208

100

209

class EchoClientFactory(ClientFactory):

101

210

def clientConnectionLost(self, connector, reason):

102

211

connector.connect()

103

</pre>The connector passed as the first argument is the interface between a

212

</pre>

213

214

The connector passed as the first argument is the interface between a

104

215

connection and a protocol. When the connection fails and the factory

105

216

receives the clientConnectionLost event, the factory can call <code class="python">connector.connect()</code> to start the connection over

106

again from scratch.

107

However, most programs that want this functionality should implement <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.protocol.ReconnectingClientFactory.html" title="twisted.internet.protocol.ReconnectingClientFactory">ReconnectingClientFactory</a></code> instead,

217

again from scratch.

218

219

220

However, most programs that want this functionality should implement <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.protocol.ReconnectingClientFactory.html" title="twisted.internet.protocol.ReconnectingClientFactory">ReconnectingClientFactory</a></code> instead,

108

221

which tries to reconnect if a connection is lost or fails, and which

109

222

exponentially delays repeated reconnect attempts.

110

223

224

225

111

226

Here is the Echo protocol implemented with a ReconnectingClientFactory:

112

113

227

228

229

<pre class="python"> 1

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

114

255

from sys import stdout

115

256

116

257

class Echo(Protocol):

135

276

print 'Connection failed. Reason:', reason

136

277

ReconnectingClientFactory.clientConnectionFailed(self, connector,

137

278

reason)

138

</pre><h2>A Higher-Level Example: ircLogBot<a name="auto5"></a></h2><h3>Overview of ircLogBot<a name="auto6"></a></h3>The clients so far have been fairly simple. A more complicated

139

example comes with Twisted Words in the doc/examples directory.<div class="py-listing"><pre>

140

# twisted imports

141

from twisted.words.protocols import irc

279

</pre>

280

281

<h2>A Higher-Level Example: ircLogBot<a name="auto5"/></h2>

282

283

<h3>Overview of ircLogBot<a name="auto6"/></h3>

284

285

The clients so far have been fairly simple. A more complicated

286

example comes with Twisted Words in the doc/examples directory.

287

288

<div class="py-listing"><pre> 1

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

100

388

101

389

102

390

103

391

104

392

105

393

106

394

107

395

108

396

109

397

110

398

111

399

112

400

113

401

114

402

115

403

116

404

117

405

118

406

119

407

120

408

121

409

122

410

123

411

124

412

125

413

126

414

127

415

128

416

129

417

130

418

131

419

132

420

# twisted imports

421

from twisted.words.protocols import irc

142

422

143

423

from twisted.python import log

144

424

145

# system imports

146

import time, sys

425

# system imports

426

import time, sys

147

427

148

428

149

429

class MessageLogger:

182

462

self.logger.close()

183

463

184

464

185

# callbacks for events

186

465

# callbacks for events

466

187

467

def signedOn(self):

188

468

"""Called when bot has succesfully signed on to server."""

189

469

self.join(self.factory.channel)

197

477

user = user.split('!', 1)[0]

198

478

self.logger.log("<%s> %s" % (user, msg))

199

479

200

# Check to see if they're sending me a private message

201

if channel == self.nickname:

480

# Check to see if they're sending me a private message

481

if channel == self.nickname:

202

482

msg = "It isn't nice to whisper! Play nice with the group."

203

483

self.msg(user, msg)

204

484

return

205

485

206

# Otherwise check to see if it is a message directed at me

207

if msg.startswith(self.nickname + ":"):

486

# Otherwise check to see if it is a message directed at me

487

if msg.startswith(self.nickname + ":"):

208

488

msg = "%s: I am a log bot" % user

209

489

self.msg(channel, msg)

210

490

self.logger.log("<%s> %s" % (self.nickname, msg))

214

494

215

495

self.logger.log("* %s %s" % (user, msg))

216

496

217

# irc callbacks

218

497

# irc callbacks

498

219

499

def irc_NICK(self, prefix, params):

220

500

"""Called when an IRC user changes their nickname."""

221

501

old_nick = prefix.split('!')[0]

223

503

self.logger.log("%s is now known as %s" % (old_nick, new_nick))

224

504

225

505

506

# For fun, override the method that determines how a nickname is changed on

507

# collisions. The default method appends an underscore.

508

def alterCollidedNick(self, nickname):

509

"""

510

Generate an altered version of a nickname that caused a collision in an

511

effort to create an unused related name for subsequent registration.

512

"""

513

return nickname + '^'

514

515

516

226

517

class LogBotFactory(protocol.ClientFactory):

227

518

"""A factory for LogBots.

228

519

229

520

A new protocol instance will be created each time we connect to the server.

230

521

"""

231

522

232

# the class of the protocol to build when new connection is made

233

protocol = LogBot

523

# the class of the protocol to build when new connection is made

524

protocol = LogBot

234

525

235

526

def __init__(self, channel, filename):

236

527

self.channel = channel

246

537

247

538

248

539

if __name__ == '__main__':

249

# initialize logging

250

log.startLogging(sys.stdout)

251

252

# create factory protocol and application

253

f = LogBotFactory(sys.argv[1], sys.argv[2])

254

255

# connect factory to this host and port

256

reactor.connectTCP("irc.freenode.net", 6667, f)

257

258

# run bot

259

reactor.run()

260

</pre><div class="caption">Source listing - <a href="../../words/examples/ircLogBot.py">../../words/examples/ircLogBot.py</a></div></div>ircLogBot.py connects to an IRC server, joins a channel, and logs all

540

# initialize logging

541

log.startLogging(sys.stdout)

542

543

# create factory protocol and application

544

f = LogBotFactory(sys.argv[1], sys.argv[2])

545

546

# connect factory to this host and port

547

reactor.connectTCP("irc.freenode.net", 6667, f)

548

549

# run bot

550

reactor.run()

551

</pre><div class="caption">Source listing - <a href="../../words/examples/ircLogBot.py">../../words/examples/ircLogBot.py</a></div></div>

552

553

ircLogBot.py connects to an IRC server, joins a channel, and logs all

261

554

traffic on it to a file. It demonstrates some of the connection-level

262

555

logic of reconnecting on a lost connection, as well as storing persistent

263

data in the Factory.<h3>Persistent Data in the Factory<a name="auto7"></a></h3>Since the Protocol instance is recreated each time the connection is

556

data in the Factory.

557

558

<h3>Persistent Data in the Factory<a name="auto7"/></h3>

559

560

Since the Protocol instance is recreated each time the connection is

264

561

made, the client needs some way to keep track of data that should be

265

562

persisted. In the case of the logging bot, it needs to know which channel

266

it is logging, and where to log it to.<pre class="python">

267

563

it is logging, and where to log it to.

564

565

<pre class="python"> 1

566

567

568

569

570

571

572

573

574

575

576

577

578

579

580

581

582

583

584

585

586

587

268

588

from twisted.protocols import irc

269

589

270

590

class LogBot(irc.IRCClient):

286

606

287

607

self.channel = channel

288

608

self.filename = filename

289

</pre>When the protocol is created, it gets a reference to the factory as

609

</pre>

610

611

When the protocol is created, it gets a reference to the factory as

290

612

self.factory. It can then access attributes of the factory in its logic.

291

613

In the case of LogBot, it opens the file and connects to the channel

292

stored in the factory.<h2>Further Reading<a name="auto8"></a></h2>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>

293

class used throughout this document is a base implementation of <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.interfaces.IProtocol.html" title="twisted.internet.interfaces.IProtocol">IProtocol</a></code> used in

614

stored in the factory.

615

616

<h2>Further Reading<a name="auto8"/></h2>

617

618

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>

619

class used throughout this document is a base implementation of <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.interfaces.IProtocol.html" title="twisted.internet.interfaces.IProtocol">IProtocol</a></code> used in

294

620

most Twisted applications for convenience. To learn about the

295

621

complete<code>IProtocol</code> interface, see the API documentation for

296

<code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.interfaces.IProtocol.html" title="twisted.internet.interfaces.IProtocol">IProtocol</a></code>.The <code>transport</code> attribute used in some examples in this

297

document provides the <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.interfaces.

298

ITCPTransport.html" title="twisted.internet.interfaces.

299

ITCPTransport">

622

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

623

624

The <code>transport</code> attribute used in some examples in this

625

document provides the <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.interfaces.

626

.html" title="twisted.internet.interfaces.

627

300

628

ITCPTransport</a></code> interface. To learn about the complete interface, see

301

the API documentation for <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.interfaces.ITCPTransport.html" title="twisted.internet.interfaces.ITCPTransport">ITCPTransport</a></code>.Interface classes are a way of specifying what methods and attributes an

302

object has and how they behave. See the <a href="components.html">

303

Components: Interfaces and Adapters</a> document.</div><a href="index.html">Index</a>Version: 8.2.0</body></html>

b'\\ No newline at end of file'

629

the API documentation for <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.interfaces.ITCPTransport.html" title="twisted.internet.interfaces.ITCPTransport">ITCPTransport</a></code>.

630

631

Interface classes are a way of specifying what methods and attributes an

632

object has and how they behave. See the <a href="components.html" shape="rect">

633

Components: Interfaces and Adapters</a> document.

634

</div>

635

636

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

637

Version: 9.0.0

638

</body>

639

</html>

b'\\ No newline at end of file'

Older »