~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: Deferred Reference</title><link href="stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">Deferred Reference</h1><div class="toc"><ol><li><a href="#auto0">Callbacks</a></li><ul><li><a href="#auto1">Multiple callbacks</a></li><li><a href="#auto2">Visual Explanation</a></li></ul><li><a href="#auto3">Errbacks</a></li><ul><li><a href="#auto4">Unhandled Errors</a></li></ul><li><a href="#auto5">Handling either synchronous or asynchronous results</a></li><ul><li><a href="#auto6">Handling possible Deferreds in the library code</a></li></ul><li><a href="#auto7">DeferredList</a></li><ul><li><a href="#auto8">Other behaviours</a></li></ul><li><a href="#auto9">Class Overview</a></li><ul><li><a href="#auto10">Basic Callback Functions</a></li><li><a href="#auto11">Chaining Deferreds</a></li></ul><li><a href="#auto12">See also</a></li></ol></div><div class="content">This document is a guide to the behaviour of the <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">twisted.internet.defer.Deferred</a></code> object, and to various

ways you can use them when they are returned by functions.This document assumes that you are familiar with the basic principle that

<?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: Deferred Reference</title>

</head>

<h1 class="title">Deferred Reference</h1>

<div class="toc"><ol><li><a href="#auto0">Deferreds</a></li><li><a href="#auto1">Callbacks</a></li><ul><li><a href="#auto2">Multiple callbacks</a></li><li><a href="#auto3">Visual Explanation</a></li></ul><li><a href="#auto4">Errbacks</a></li><ul><li><a href="#auto5">Unhandled Errors</a></li></ul><li><a href="#auto6">Handling either synchronous or asynchronous results</a></li><ul><li><a href="#auto7">Handling possible Deferreds in the library code</a></li></ul><li><a href="#auto8">DeferredList</a></li><ul><li><a href="#auto9">Other behaviours</a></li></ul><li><a href="#auto10">Class Overview</a></li><ul><li><a href="#auto11">Basic Callback Functions</a></li><li><a href="#auto12">Chaining Deferreds</a></li></ul><li><a href="#auto13">See also</a></li></ol></div>

This document is a guide to the behaviour of the <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">twisted.internet.defer.Deferred</a></code> object, and to various

ways you can use them when they are returned by functions.

This document assumes that you are familiar with the basic principle that

the Twisted framework is structured around: asynchronous, callback-based

programming, where instead of having blocking code in your program or using

threads to run blocking code, you have functions that return immediately and

then begin a callback chain when data is available.See these documents for more information:<ul><li><a href="async.html">Asynchronous Programming with Twisted</a></li></ul>

then begin a callback chain when data is available.

After reading this document, the reader should expect to be able to

deal with most simple APIs in Twisted and Twisted-using code that

return Deferreds.

<ul><li>what sorts of things you can do when you get a Deferred from a

function call; and</li><li>how you can write your code to robustly handle errors in Deferred

code.</li></ul>Unless you're already very familiar with asynchronous programming,

it's strongly recommended you read

the <a href="async.html#deferreds">Deferreds section</a> of the

Asynchronous programming document to get an idea of why Deferreds

exist.

<h2>Callbacks<a name="auto0"></a></h2>A <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">twisted.internet.defer.Deferred</a></code> is a promise that

<ul>

<li>what sorts of things you can do when you get a Deferred from a

function call; and</li>

<li>how you can write your code to robustly handle errors in Deferred

code.</li>

</ul>

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

Twisted uses the <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">Deferred</a></code> object to manage the callback

sequence. The client application attaches a series of functions to the

deferred to be called in order when the results of the asychronous request are

available (this series of functions is known as a series of

callbacks, or a callback chain), together

with a series of functions to be called if there is an error in the

asychronous request (known as a series of errbacks or an

errback chain). The asychronous library code calls the first

callback when the result is available, or the first errback when an error

occurs, and the <code>Deferred</code> object then hands the results of each

callback or errback function to the next function in the chain.

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

A <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">twisted.internet.defer.Deferred</a></code> is a promise that

a function will at some point have a result. We can attach callback functions

to a Deferred, and once it gets a result these callbacks will be called. In

addition Deferreds allow the developer to register a callback for an error,

with the default behavior of logging the error. The deferred mechanism

standardizes the application programmer's interface with all sorts of

blocking or delayed operations.<pre class="python">

from twisted.internet import reactor, defer

blocking or delayed operations.

<pre class="python"> 1

from twisted.internet import reactor, defer

def getDummyData(x):

"""

100

hard to understand this.

101

"""

102

d = defer.Deferred()

# simulate a delayed result by asking the reactor to fire the

# Deferred in 2 seconds time with the result x * 3

reactor.callLater(2, d.callback, x * 3)

103

# simulate a delayed result by asking the reactor to fire the

104

# Deferred in 2 seconds time with the result x * 3

105

106

return d

107

108

def printData(d):

115

d = getDummyData(3)

116

d.addCallback(printData)

117

# manually set up the end of the process by asking the reactor to

# stop itself in 4 seconds time

reactor.callLater(4, reactor.stop)

# start up the Twisted reactor (event loop handler) manually

reactor.run()

</pre><h3>Multiple callbacks<a name="auto1"></a></h3>Multiple callbacks can be added to a Deferred. The first callback in the

118

# manually set up the end of the process by asking the reactor to

119

# stop itself in 4 seconds time

120

reactor.callLater(4, reactor.stop)

121

# start up the Twisted reactor (event loop handler) manually

122

reactor.run()

123

</pre>

124

125

<h3>Multiple callbacks<a name="auto2"/></h3>

126

127

Multiple callbacks can be added to a Deferred. The first callback in the

128

Deferred's callback chain will be called with the result, the second with the

129

result of the first callback, and so on. Why do we need this? Well, consider

130

a Deferred returned by twisted.enterprise.adbapi - the result of a SQL query.

131

A web widget might add a callback that converts this result into HTML, and

132

pass the Deferred onwards, where the callback will be used by twisted to

133

return the result to the HTTP client. The callback chain will be bypassed in

case of errors or exceptions.<pre class="python">

134

case of errors or exceptions.

135

136

<pre class="python"> 1

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

class Getter:

203

def gotResults(self, x):

235

setup.

236

"""

237

self.d = defer.Deferred()

100

# simulate a delayed result by asking the reactor to schedule

101

# gotResults in 2 seconds time

102

reactor.callLater(2, self.gotResults, x)

238

# simulate a delayed result by asking the reactor to schedule

239

# gotResults in 2 seconds time

240

103

241

self.d.addCallback(self._toHTML)

104

242

return self.d

105

243

110

248

import sys

111

249

sys.stderr.write(str(failure))

112

250

113

# this series of callbacks and errbacks will print an error message

114

g = Getter()

251

# this series of callbacks and errbacks will print an error message

252

g = Getter()

115

253

d = g.getDummyData(3)

116

254

d.addCallback(printData)

117

255

d.addErrback(printError)

118

256

119

# this series of callbacks and errbacks will print "Result: 12"

120

g = Getter()

257

# this series of callbacks and errbacks will print "Result: 12"

258

g = Getter()

121

259

d = g.getDummyData(4)

122

260

d.addCallback(printData)

123

261

d.addErrback(printError)

124

262

125

263

126

</pre><h3>Visual Explanation<a name="auto2"></a></h3><div hlint="off" align="center"><img src="../img/deferred-attach.png" /></div><ol><li>Requesting method (data sink) requests data, gets

127

Deferred object.</li><li>Requesting method attaches callbacks to Deferred

128

object.</li></ol><img src="../img/deferred-process.png" hlint="off" align="left" /><ol><li>When the result is ready, give it to the Deferred

264

</pre>

265

266

<h3>Visual Explanation<a name="auto3"/></h3>

267

268

269

270

</div>

271

272

<ol>

273

<li>Requesting method (data sink) requests data, gets

274

Deferred object.</li>

275

276

<li>Requesting method attaches callbacks to Deferred

277

object.</li>

278

</ol>

279

280

281

<ol>

282

283

<li>When the result is ready, give it to the Deferred

129

284

object. <code>.callback(result)</code> if the operation succeeded,

130

285

<code>.errback(failure)</code> if it failed. Note that

131

<code>failure</code> is typically an instance of a <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.python.failure.Failure.html" title="twisted.python.failure.Failure">twisted.python.failure.Failure</a></code>

132

instance.</li><li>Deferred object triggers previously-added (call/err)back

286

<code>failure</code> is typically an instance of a <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.python.failure.Failure.html" title="twisted.python.failure.Failure">twisted.python.failure.Failure</a></code>

287

instance.</li>

288

289

<li>Deferred object triggers previously-added (call/err)back

133

290

with the <code>result</code> or <code>failure</code>.

134

291

Execution then follows the following rules, going down the

135

292

chain of callbacks to be processed.

136

293

137

<ul><li>Result of the callback is always passed as the first

294

<ul>

295

<li>Result of the callback is always passed as the first

138

296

argument to the next callback, creating a chain of

139

processors.</li><li>If a callback raises an exception, switch to

140

errback.</li><li>An unhandled failure gets passed down the line of

297

processors.</li>

298

299

<li>If a callback raises an exception, switch to

300

errback.</li>

301

302

<li>An unhandled failure gets passed down the line of

141

303

errbacks, this creating an asynchronous analog to a

142

304

series to a series of <code>except:</code>

143

statements.</li><li>If an errback doesn't raise an exception or return a

144

<code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.python.failure.Failure.html" title="twisted.python.failure.Failure">twisted.python.failure.Failure</a></code>

145

instance, switch to callback.</li></ul></li></ol> <h2>Errbacks<a name="auto3"></a></h2>Deferred's error handling is modeled after Python's

305

statements.</li>

306

307

<li>If an errback doesn't raise an exception or return a

308

<code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.python.failure.Failure.html" title="twisted.python.failure.Failure">twisted.python.failure.Failure</a></code>

309

instance, switch to callback.</li>

310

</ul> </li>

311

</ol>

312

313

314

<h2>Errbacks<a name="auto4"/></h2>

315

316

Deferred's error handling is modeled after Python's

146

317

exception handling. In the case that no errors occur, all the

147

callbacks run, one after the other, as described above.If the errback is called instead of the callback (e.g. because a DB query

148

raised an error), then a <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.python.failure.Failure.html" title="twisted.python.failure.Failure">twisted.python.failure.Failure</a></code> is passed into the first

318

callbacks run, one after the other, as described above.

319

320

If the errback is called instead of the callback (e.g. because a DB query

321

raised an error), then a <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.python.failure.Failure.html" title="twisted.python.failure.Failure">twisted.python.failure.Failure</a></code> is passed into the first

149

322

errback (you can add multiple errbacks, just like with callbacks). You can

150

323

think of your errbacks as being like <code class="python">except</code> blocks

151

of ordinary Python code.Unless you explicitly <code class="python">raise</code> an error in except

324

of ordinary Python code.

325

326

Unless you explicitly <code class="python">raise</code> an error in except

152

327

block, the <code class="python">Exception</code> is caught and stops

153

328

propagating, and normal execution continues. The same thing happens with

154

329

errbacks: unless you explicitly <code class="python">return</code> a <code class="python">Failure</code> or (re-)raise an exception, the error stops

155

330

propagating, and normal callbacks continue executing from that point (using the

156

331

value returned from the errback). If the errback does returns a <code class="python">Failure</code> or raise an exception, then that is passed to the

157

next errback, and so on.Note: If an errback doesn't return anything, then it effectively

332

next errback, and so on.

333

334

Note: If an errback doesn't return anything, then it effectively

158

335

returns <code class="python">None</code>, meaning that callbacks will continue

159

336

to be executed after this errback. This may not be what you expect to happen,

160

337

so be careful. Make sure your errbacks return a <code class="python">Failure</code> (probably the one that was passed to it), or a

161

meaningful return value for the next callback.Also, <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.python.failure.Failure.html" title="twisted.python.failure.Failure">twisted.python.failure.Failure</a></code> instances have

338

meaningful return value for the next callback.

339

340

Also, <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.python.failure.Failure.html" title="twisted.python.failure.Failure">twisted.python.failure.Failure</a></code> instances have

162

341

a useful method called trap, allowing you to effectively do the equivalent

163

of:<pre class="python">

164

try:

165

# code that may throw an exception

166

cookSpamAndEggs()

342

of:

343

344

<pre class="python">1

345

346

347

348

349

350

try:

351

# code that may throw an exception

352

cookSpamAndEggs()

167

353

except (SpamException, EggException):

168

# Handle SpamExceptions and EggExceptions

169

...

170

</pre>You do this by:<pre class="python">

171

def errorHandler(failure):

354

# Handle SpamExceptions and EggExceptions

355

...

356

</pre>

357

358

You do this by:

359

<pre class="python">1

360

361

362

363

364

365

def errorHandler(failure):

172

366

failure.trap(SpamException, EggException)

173

# Handle SpamExceptions and EggExceptions

174

367

# Handle SpamExceptions and EggExceptions

368

175

369

d.addCallback(cookSpamAndEggs)

176

370

d.addErrback(errorHandler)

177

</pre>If none of arguments passed to <code class="python">failure.trap</code>

371

</pre>

372

373

If none of arguments passed to <code class="python">failure.trap</code>

178

374

match the error encapsulated in that <code class="python">Failure</code>, then

179

it re-raises the error.There's another potential <q>gotcha</q> here. There's a

180

method <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.defer.Deferred.addCallbacks.html" title="twisted.internet.defer.Deferred.addCallbacks">twisted.internet.defer.Deferred.addCallbacks</a></code>

181

which is similar to, but not exactly the same as, <code class="python">addCallback</code> followed by <code class="python">addErrback</code>. In particular, consider these two cases:<pre class="python">

182

# Case 1

183

d = getDeferredFromSomewhere()

375

it re-raises the error.

376

377

There's another potential <q>gotcha</q> here. There's a

378

method <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.defer.Deferred.addCallbacks.html" title="twisted.internet.defer.Deferred.addCallbacks">twisted.internet.defer.Deferred.addCallbacks</a></code>

379

which is similar to, but not exactly the same as, <code class="python">addCallback</code> followed by <code class="python">addErrback</code>. In particular, consider these two cases:

380

381

<pre class="python"> 1

382

383

384

385

386

387

388

389

390

391

392

# Case 1

393

d = getDeferredFromSomewhere()

184

394

d.addCallback(callback1) # A

185

395

d.addErrback(errback1) # B

186

396

d.addCallback(callback2)

187

397

d.addErrback(errback2)

188

398

189

# Case 2

190

d = getDeferredFromSomewhere()

399

# Case 2

400

d = getDeferredFromSomewhere()

191

401

d.addCallbacks(callback1, errback1) # C

192

402

d.addCallbacks(callback2, errback2)

193

</pre>If an error occurs in <code class="python">callback1</code>, then for Case 1

403

</pre>

404

405

If an error occurs in <code class="python">callback1</code>, then for Case 1

194

406

<code class="python">errback1</code> will be called with the failure. For Case

195

407

2, <code class="python">errback2</code> will be called. Be careful with your

196

callbacks and errbacks.What this means in a practical sense is in Case 1, "A" will

408

callbacks and errbacks.

409

410

What this means in a practical sense is in Case 1, "A" will

197

411

handle a success condition from <code>getDeferredFromSomewhere</code>, and

198

412

"B" will handle any errors that occur from either the upstream

199

413

source, or that occur in 'A'. In Case 2, "C"'s errback1

200

414

will only handle an error condition raised by

201

415

<code>getDeferredFromSomewhere</code>, it will not do any handling of

202

errors raised in callback1.<h3>Unhandled Errors<a name="auto4"></a></h3>If a Deferred is garbage-collected with an unhandled error (i.e. it would

416

errors raised in callback1.

417

418

419

<h3>Unhandled Errors<a name="auto5"/></h3>

420

421

If a Deferred is garbage-collected with an unhandled error (i.e. it would

203

422

call the next errback if there was one), then Twisted will write the error's

204

423

traceback to the log file. This means that you can typically get away with not

205

424

adding errbacks and still get errors logged. Be careful though; if you keep a

206

425

reference to the Deferred around, preventing it from being garbage-collected,

207

426

then you may never see the error (and your callbacks will mysteriously seem to

208

427

have never been called). If unsure, you should explicitly add an errback after

209

your callbacks, even if all you do is:<pre class="python">

210

# Make sure errors get logged

211

from twisted.python import log

428

your callbacks, even if all you do is:

429

430

<pre class="python">1

431

432

433

# Make sure errors get logged

434

from twisted.python import log

212

435

d.addErrback(log.err)

213

</pre><h2>Handling either synchronous or asynchronous results<a name="auto5"></a></h2>

436

</pre>

437

438

<h2>Handling either synchronous or asynchronous results<a name="auto6"/></h2>

439

214

440

In some applications, there are functions that might be either asynchronous or

215

441

synchronous. For example, a user authentication function might be able to

216

442

check in memory whether a user is authenticated, allowing the authentication

219

445

when that data arrives. However, a function that wants to check if a user is

220

446

authenticated will then need to accept both immediate results and

221

447

Deferreds.

222

448

449

450

223

451

In this example, the library function <code>authenticateUser</code> uses the

224

452

application function <code>isValidUser</code> to authenticate a user:

225

226

def authenticateUser(isValidUser, user):

453

454

455

<pre class="python">1

456

457

458

459

460

def authenticateUser(isValidUser, user):

227

461

if isValidUser(user):

228

462

print "User is authenticated"

229

463

else:

230

464

print "User is not authenticated"

231

</pre>

465

</pre>

466

467

232

468

However, it assumes that <code>isValidUser</code> returns immediately,

233

469

whereas <code>isValidUser</code> may actually authenticate the user

234

470

asynchronously and return a Deferred. It is possible to adapt this

240

476

alternatives: handling functions that might be synchronous or

241

477

asynchronous in the library function (<code>authenticateUser</code>)

242

478

or in the application code.

243

<h3>Handling possible Deferreds in the library code<a name="auto6"></a></h3>

479

480

481

<h3>Handling possible Deferreds in the library code<a name="auto7"/></h3>

482

483

244

484

Here is an example of a synchronous user authentication function that might be

245

485

passed to <code>authenticateUser</code>:

246

247

def synchronousIsValidUser(user):

486

487

488

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

489

490

491

492

493

def synchronousIsValidUser(user):

248

494

'''

249

495

Return true if user is a valid user, false otherwise

250

496

'''

251

497

return user in ["Alice", "Angus", "Agnes"]

252

</pre><div class="caption">Source listing - <a href="listings/deferred/synch-validation.py">listings/deferred/synch-validation.py</a></div></div>

498

</pre><div class="caption">Source listing - <a href="listings/deferred/synch-validation.py">listings/deferred/synch-validation.py</a></div></div>

499

500

253

501

However, here's an <code>asynchronousIsValidUser</code> function that returns

254

502

a Deferred:

255

256

503

504

505

<pre class="python">1

506

507

508

509

510

511

257

512

258

513

def asynchronousIsValidUser(d, user):

259

514

d = Deferred()

260

515

reactor.callLater(2, d.callback, user in ["Alice", "Angus", "Agnes"])

261

516

return d

262

</pre> Our original implementation of <code>authenticateUser</code> expected

517

</pre>

518

519

Our original implementation of <code>authenticateUser</code> expected

263

520

<code>isValidUser</code> to be synchronous, but now we need to change it to handle both

264

521

synchronous and asynchronous implementations of <code>isValidUser</code>. For this, we

265

use <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.defer.maybeDeferred.html" title="twisted.internet.defer.maybeDeferred">maybeDeferred</a></code> to

522

use <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.defer.maybeDeferred.html" title="twisted.internet.defer.maybeDeferred">maybeDeferred</a></code> to

266

523

call <code>isValidUser</code>, ensuring that the result of <code>isValidUser</code> is a Deferred,

267

524

even if <code>isValidUser</code> is a synchronous function:

268

269

525

526

527

<pre class="python"> 1

528

529

530

531

532

533

534

535

536

537

538

270

539

271

540

def printResult(result):

272

541

if result:

277

546

def authenticateUser(isValidUser, user):

278

547

d = defer.maybeDeferred(isValidUser, user)

279

548

d.addCallback(printResult)

280

</pre>

549

</pre>

550

551

281

552

Now <code>isValidUser</code> could be either <code>synchronousIsValidUser</code> or

282

553

<code>asynchronousIsValidUser</code>.

283

It is also possible to modify <code>synchronousIsValidUser</code> to return

284

a Deferred, see <a href="gendefer.html">Generating Deferreds</a> for more

285

information.<h2>DeferredList<a name="auto7"></a></h2>Sometimes you want to be notified after several different events have all

554

555

556

It is also possible to modify <code>synchronousIsValidUser</code> to return

557

a Deferred, see <a href="gendefer.html" shape="rect">Generating Deferreds</a> for more

558

information.

559

560

<h2>DeferredList<a name="auto8"/></h2>

561

562

Sometimes you want to be notified after several different events have all

286

563

happened, rather than waiting for each one individually. For example, you may

287

want to wait for all the connections in a list to close. <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.internet.defer.DeferredList.html" title="twisted.internet.defer.DeferredList">twisted.internet.defer.DeferredList</a></code> is the way to do

288

this.To create a DeferredList from multiple Deferreds, you simply pass a list of

289

the Deferreds you want it to wait for:<pre class="python">

290

# Creates a DeferredList

291

dl = defer.DeferredList([deferred1, deferred2, deferred3])

292

</pre>You can now treat the DeferredList like an ordinary Deferred; you can call

564

want to wait for all the connections in a list to close. <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.defer.DeferredList.html" title="twisted.internet.defer.DeferredList">twisted.internet.defer.DeferredList</a></code> is the way to do

565

this.

566

567

To create a DeferredList from multiple Deferreds, you simply pass a list of

568

the Deferreds you want it to wait for:

569

<pre class="python">1

570

571

# Creates a DeferredList

572

dl = defer.DeferredList([deferred1, deferred2, deferred3])

573

</pre>

574

575

You can now treat the DeferredList like an ordinary Deferred; you can call

293

576

<code>addCallbacks</code> and so on. The DeferredList will call its callback

294

577

when all the deferreds have completed. The callback will be called with a list

295

of the results of the Deferreds it contains, like so:<pre class="python">

296

def printResult(result):

578

of the results of the Deferreds it contains, like so:

579

580

<pre class="python"> 1

581

582

583

584

585

586

587

588

589

590

591

592

593

594

595

596

597

598

599

def printResult(result):

297

600

for (success, value) in result:

298

601

if success:

299

602

print 'Success:', value

307

610

deferred1.callback('one')

308

611

deferred2.errback(Exception('bang!'))

309

612

deferred3.callback('three')

310

# At this point, dl will fire its callback, printing:

311

# Success: one

312

# Failure: bang!

313

# Success: three

314

# (note that defer.SUCCESS == True, and defer.FAILURE == False)

315

</pre>A standard DeferredList will never call errback, but failures in Deferreds

613

# At this point, dl will fire its callback, printing:

614

# Success: one

615

# Failure: bang!

616

# Success: three

617

# (note that defer.SUCCESS == True, and defer.FAILURE == False)

618

</pre>

619

620

A standard DeferredList will never call errback, but failures in Deferreds

316

621

passed to a DeferredList will still errback unless <code>consumeErrors</code>

317

622

is passed <code>True</code>. See below for more details about this and other

318

flags which modify the behavior of DeferredList.<div class="note">Note: If you want to apply callbacks to the individual Deferreds that

623

flags which modify the behavior of DeferredList.

624

625

<div class="note">Note:

626

If you want to apply callbacks to the individual Deferreds that

319

627

go into the DeferredList, you should be careful about when those callbacks

320

628

are added. The act of adding a Deferred to a DeferredList inserts a callback

321

629

into that Deferred (when that callback is run, it checks to see if the

322

630

DeferredList has been completed yet). The important thing to remember is

323

631

that it is this callback which records the value that goes into the

324

result list handed to the DeferredList's callback.<!-- TODO: add picture here: three columns of callback chains, with a value

325

being snarfed out of the middle of each and handed off to the DeferredList

326

-->Therefore, if you add a callback to the Deferred after adding the

632

result list handed to the DeferredList's callback.

633

634

635

636

Therefore, if you add a callback to the Deferred after adding the

327

637

Deferred to the DeferredList, the value returned by that callback will not

328

638

be given to the DeferredList's callback. To avoid confusion, we recommend not

329

adding callbacks to a Deferred once it has been used in a DeferredList.</div><pre class="python">

330

def printResult(result):

639

adding callbacks to a Deferred once it has been used in a DeferredList.

640

</div>

641

642

<pre class="python"> 1

643

644

645

646

647

648

649

650

651

652

653

654

655

656

657

658

659

660

661

662

663

664

665

666

667

668

def printResult(result):

331

669

print result

332

670

def addTen(result):

333

671

return result + " ten"

334

672

335

# Deferred gets callback before DeferredList is created

336

deferred1 = defer.Deferred()

673

# Deferred gets callback before DeferredList is created

674

deferred1 = defer.Deferred()

337

675

deferred2 = defer.Deferred()

338

676

deferred1.addCallback(addTen)

339

677

340

678

dl.addCallback(printResult)

341

679

deferred1.callback("one") # fires addTen, checks DeferredList, stores "one ten"

342

680

deferred2.callback("two")

343

# At this point, dl will fire its callback, printing:

344

# [(1, 'one ten'), (1, 'two')]

345

346

# Deferred gets callback after DeferredList is created

347

deferred1 = defer.Deferred()

681

# At this point, dl will fire its callback, printing:

682

# [(1, 'one ten'), (1, 'two')]

683

684

# Deferred gets callback after DeferredList is created

685

deferred1 = defer.Deferred()

348

686

deferred2 = defer.Deferred()

349

687

350

688

deferred1.addCallback(addTen) # will run *after* DeferredList gets its value

351

689

dl.addCallback(printResult)

352

690

deferred1.callback("one") # checks DeferredList, stores "one", fires addTen

353

691

deferred2.callback("two")

354

# At this point, dl will fire its callback, printing:

355

# [(1, 'one), (1, 'two')]

356

</pre><h3>Other behaviours<a name="auto8"></a></h3>DeferredList accepts three keyword arguments that modify its behaviour:

692

# At this point, dl will fire its callback, printing:

693

# [(1, 'one), (1, 'two')]

694

</pre>

695

696

<h3>Other behaviours<a name="auto9"/></h3>

697

698

DeferredList accepts three keyword arguments that modify its behaviour:

357

699

<code>fireOnOneCallback</code>, <code>fireOnOneErrback</code> and

358

700

<code>consumeErrors</code>. If <code>fireOnOneCallback</code> is set, the

359

701

DeferredList will immediately call its callback as soon as any of its Deferreds

361

703

as soon as any of the Deferreds call their errback. Note that DeferredList is

362

704

still one-shot, like ordinary Deferreds, so after a callback or errback has been

363

705

called the DeferredList will do nothing further (it will just silently ignore

364

any other results from its Deferreds).The <code>fireOnOneErrback</code> option is particularly useful when you

706

any other results from its Deferreds).

707

708

The <code>fireOnOneErrback</code> option is particularly useful when you

365

709

want to wait for all the results if everything succeeds, but also want to know

366

immediately if something fails.The <code>consumeErrors</code> argument will stop the DeferredList from

710

immediately if something fails.

711

712

The <code>consumeErrors</code> argument will stop the DeferredList from

367

713

propagating any errors along the callback chains of any Deferreds it contains

368

714

(usually creating a DeferredList has no effect on the results passed along the

369

715

callbacks and errbacks of their Deferreds). Stopping errors at the DeferredList

370

716

with this option will prevent <q>Unhandled error in Deferred</q> warnings from

371

the Deferreds it contains without needing to add extra errbacks<a href="#footnote-1" title="Unless of course a later callback starts a fresh error &mdash; but as we've already noted, adding callbacks to a Deferred after its used in a DeferredList is confusing and usually avoided."><super>1</super></a>.<a name="class"></a><h2>Class Overview<a name="auto9"></a></h2>This is an overview API reference for Deferred from the point of using a

717

the Deferreds it contains without needing to add extra errbacks<a href="#footnote-1" title="Unless of course a later callback starts a fresh error — but as we've already noted, adding callbacks to a Deferred after its used in a DeferredList is confusing and usually avoided."><super>1</super></a>.

718

719

720

721

<h2>Class Overview<a name="auto10"/></h2>

722

723

This is an overview API reference for Deferred from the point of using a

372

724

Deferred returned by a function. It is not meant to be a

373

725

substitute for the docstrings in the Deferred class, but can provide guidelines

374

for its use.There is a parallel overview of functions used by the Deferred's

375

creator in <a href="gendefer.html#class">Generating Deferreds</a>.<h3>Basic Callback Functions<a name="auto10"></a></h3><ul><li><code class="py-prototype">addCallbacks(self, callback[, errback, callbackArgs,

376

callbackKeywords, errbackArgs, errbackKeywords])</code>This is the method you will use to interact

726

for its use.

727

728

There is a parallel overview of functions used by the Deferred's

729

creator in <a href="gendefer.html#class" shape="rect">Generating Deferreds</a>.

730

731

<h3>Basic Callback Functions<a name="auto11"/></h3>

732

733

<ul>

734

<li>

735

<code class="py-prototype">addCallbacks(self, callback[, errback, callbackArgs,

736

callbackKeywords, errbackArgs, errbackKeywords])</code>

737

738

This is the method you will use to interact

377

739

with Deferred. It adds a pair of callbacks <q>parallel</q> to

378

740

each other (see diagram above) in the list of callbacks

379

741

made when the Deferred is called back to. The signature of

382

744

**methodKeywords)</code>. If your method is passed in the

383

745

callback slot, for example, all arguments in the tuple

384

746

<code>callbackArgs</code> will be passed as

385

<code>*methodArgs</code> to your method.There are various convenience methods that are

747

<code>*methodArgs</code> to your method.

748

749

There are various convenience methods that are

386

750

derivative of addCallbacks. I will not cover them in detail

387

751

here, but it is important to know about them in order to

388

create concise code.<ul><li><code class="py-prototype">addCallback(callback, *callbackArgs,

389

**callbackKeywords)</code>Adds your callback at the next point in the

752

create concise code.

753

754

<ul>

755

<li>

756

<code class="py-prototype">addCallback(callback, *callbackArgs,

757

**callbackKeywords)</code>

758

759

Adds your callback at the next point in the

390

760

processing chain, while adding an errback that will

391

761

re-raise its first argument, not affecting further

392

processing in the error case.Note that, while addCallbacks (plural) requires the arguments to be

762

processing in the error case.

763

764

Note that, while addCallbacks (plural) requires the arguments to be

393

765

passed in a tuple, addCallback (singular) takes all its remaining

394

766

arguments as things to be passed to the callback function. The reason is

395

767

obvious: addCallbacks (plural) cannot tell whether the arguments are

396

768

meant for the callback or the errback, so they must be specifically

397

769

marked by putting them into a tuple. addCallback (singular) knows that

398

770

everything is destined to go to the callback, so it can use Python's

399

<q>*</q> and <q>**</q> syntax to collect the remaining arguments.</li><li><code class="py-prototype">addErrback(errback, *errbackArgs,

400

**errbackKeywords)</code>Adds your errback at the next point in the

771

<q>*</q> and <q>**</q> syntax to collect the remaining arguments.

772

773

</li>

774

775

<li>

776

<code class="py-prototype">addErrback(errback, *errbackArgs,

777

**errbackKeywords)</code>

778

779

Adds your errback at the next point in the

401

780

processing chain, while adding a callback that will

402

781

return its first argument, not affecting further

403

processing in the success case.</li><li><code class="py-prototype">addBoth(callbackOrErrback,

782

processing in the success case.

783

</li>

784

785

<li>

786

<code class="py-prototype">addBoth(callbackOrErrback,

404

787

*callbackOrErrbackArgs,

405

**callbackOrErrbackKeywords)</code>This method adds the same callback into both sides

788

**callbackOrErrbackKeywords)</code>

789

790

This method adds the same callback into both sides

406

791

of the processing chain at both points. Keep in mind

407

792

that the type of the first argument is indeterminate if

408

793

you use this method! Use it for <code>finally:</code>

409

style blocks.</li></ul></li></ul><h3>Chaining Deferreds<a name="auto11"></a></h3>If you need one Deferred to wait on another, all you need to do is return a

794

style blocks.

795

</li>

796

</ul> </li>

797

798

</ul>

799

800

801

<h3>Chaining Deferreds<a name="auto12"/></h3>

802

803

If you need one Deferred to wait on another, all you need to do is return a

410

804

Deferred from a method added to addCallbacks. Specifically, if you return

411

805

Deferred B from a method added to Deferred A using A.addCallbacks, Deferred A's

412

806

processing chain will stop until Deferred B's .callback() method is called; at

413

807

that point, the next callback in A will be passed the result of the last

414

callback in Deferred B's processing chain at the time.If this seems confusing, don't worry about it right now -- when you run into

808

callback in Deferred B's processing chain at the time.

809

810

If this seems confusing, don't worry about it right now -- when you run into

415

811

a situation where you need this behavior, you will probably recognize it

416

812

immediately and realize why this happens. If you want to chain deferreds

417

manually, there is also a convenience method to help you.<ul><li><code class="py-prototype">chainDeferred(otherDeferred)</code>Add <code>otherDeferred</code> to the end of this

813

manually, there is also a convenience method to help you.

814

815

<ul>

816

<li>

817

<code class="py-prototype">chainDeferred(otherDeferred)</code>

818

819

Add <code>otherDeferred</code> to the end of this

418

820

Deferred's processing chain. When self.callback is called,

419

821

the result of my processing chain up to this point will be

420

822

passed to <code>otherDeferred.callback</code>. Further

421

823

additions to my callback chain do not affect

422

<code>otherDeferred</code>This is the same as <code class="python">self.addCallbacks(otherDeferred.callback,

423

otherDeferred.errback)</code></li></ul><h2>See also<a name="auto12"></a></h2><ol><li><a href="gendefer.html">Generating Deferreds</a>, an introduction to

424

writing asynchronous functions that return Deferreds.</li></ol><h2>Footnotes</h2><ol><li><a name="footnote-1">Unless of course a later callback starts a fresh error —

824

<code>otherDeferred</code>

825

This is the same as <code class="python">self.addCallbacks(otherDeferred.callback,

826

otherDeferred.errback)</code>

827

</li>

828

</ul>

829

830

831

832

<ol>

833

<li><a href="gendefer.html" shape="rect">Generating Deferreds</a>, an introduction to

834

writing asynchronous functions that return Deferreds.</li>

835

</ol>

836

837

<h2>Footnotes</h2><ol><li><a name="footnote-1">Unless of course a later callback starts a fresh error —

425

838

but as we've already noted, adding callbacks to a Deferred after its used in a

426

DeferredList is confusing and usually avoided.</a></li></ol></div><a href="index.html">Index</a>Version: 8.2.0</body></html>

b'\\ No newline at end of file'

839

DeferredList is confusing and usually avoided.</a></li></ol></div>

840

841

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

842

Version: 9.0.0

843

</body>

844

</html>

b'\\ No newline at end of file'

Older »