twisted/test/test_defer.py

   1 # Copyright (c) Twisted Matrix Laboratories.
   2 # See LICENSE for details.
   3
   4 """
   5 Test cases for defer module.
   6 """
   7
   8 import gc, traceback
   9
  10 from twisted.trial import unittest
  11 from twisted.internet import reactor, defer
  12 from twisted.internet.task import Clock
  13 from twisted.python import failure, log
  14 from twisted.python.util import unsignedID
  15
  16 class GenericError(Exception):
  17     pass
  18
  19
  20
  21 class DeferredTestCase(unittest.TestCase):
  22
  23     def setUp(self):
  24         self.callbackResults = None
  25         self.errbackResults = None
  26         self.callback2Results = None
  27         # Restore the debug flag to its original state when done.
  28         self.addCleanup(defer.setDebugging, defer.getDebugging())
  29
  30     def _callback(self, *args, **kw):
  31         self.callbackResults = args, kw
  32         return args[0]
  33
  34     def _callback2(self, *args, **kw):
  35         self.callback2Results = args, kw
  36
  37     def _errback(self, *args, **kw):
  38         self.errbackResults = args, kw
  39
  40     def testCallbackWithoutArgs(self):
  41         deferred = defer.Deferred()
  42         deferred.addCallback(self._callback)
  43         deferred.callback("hello")
  44         self.assertEqual(self.errbackResults, None)
  45         self.assertEqual(self.callbackResults, (('hello',), {}))
  46
  47     def testCallbackWithArgs(self):
  48         deferred = defer.Deferred()
  49         deferred.addCallback(self._callback, "world")
  50         deferred.callback("hello")
  51         self.assertEqual(self.errbackResults, None)
  52         self.assertEqual(self.callbackResults, (('hello', 'world'), {}))
  53
  54     def testCallbackWithKwArgs(self):
  55         deferred = defer.Deferred()
  56         deferred.addCallback(self._callback, world="world")
  57         deferred.callback("hello")
  58         self.assertEqual(self.errbackResults, None)
  59         self.assertEqual(self.callbackResults,
  60                              (('hello',), {'world': 'world'}))
  61
  62     def testTwoCallbacks(self):
  63         deferred = defer.Deferred()
  64         deferred.addCallback(self._callback)
  65         deferred.addCallback(self._callback2)
  66         deferred.callback("hello")
  67         self.assertEqual(self.errbackResults, None)
  68         self.assertEqual(self.callbackResults,
  69                              (('hello',), {}))
  70         self.assertEqual(self.callback2Results,
  71                              (('hello',), {}))
  72
  73     def testDeferredList(self):
  74         defr1 = defer.Deferred()
  75         defr2 = defer.Deferred()
  76         defr3 = defer.Deferred()
  77         dl = defer.DeferredList([defr1, defr2, defr3])
  78         result = []
  79         def cb(resultList, result=result):
  80             result.extend(resultList)
  81         def catch(err):
  82             return None
  83         dl.addCallbacks(cb, cb)
  84         defr1.callback("1")
  85         defr2.addErrback(catch)
  86         # "catch" is added to eat the GenericError that will be passed on by
  87         # the DeferredList's callback on defr2. If left unhandled, the
  88         # Failure object would cause a log.err() warning about "Unhandled
  89         # error in Deferred". Twisted's pyunit watches for log.err calls and
  90         # treats them as failures. So "catch" must eat the error to prevent
  91         # it from flunking the test.
  92         defr2.errback(GenericError("2"))
  93         defr3.callback("3")
  94         self.assertEqual([result[0],
  95                     #result[1][1] is now a Failure instead of an Exception
  96                               (result[1][0], str(result[1][1].value)),
  97                               result[2]],
  98
  99                              [(defer.SUCCESS, "1"),
 100                               (defer.FAILURE, "2"),
 101                               (defer.SUCCESS, "3")])
 102
 103     def testEmptyDeferredList(self):
 104         result = []
 105         def cb(resultList, result=result):
 106             result.append(resultList)
 107
 108         dl = defer.DeferredList([])
 109         dl.addCallbacks(cb)
 110         self.assertEqual(result, [[]])
 111
 112         result[:] = []
 113         dl = defer.DeferredList([], fireOnOneCallback=1)
 114         dl.addCallbacks(cb)
 115         self.assertEqual(result, [])
 116
 117     def testDeferredListFireOnOneError(self):
 118         defr1 = defer.Deferred()
 119         defr2 = defer.Deferred()
 120         defr3 = defer.Deferred()
 121         dl = defer.DeferredList([defr1, defr2, defr3], fireOnOneErrback=1)
 122         result = []
 123         dl.addErrback(result.append)
 124
 125         # consume errors after they pass through the DeferredList (to avoid
 126         # 'Unhandled error in Deferred'.
 127         def catch(err):
 128             return None
 129         defr2.addErrback(catch)
 130
 131         # fire one Deferred's callback, no result yet
 132         defr1.callback("1")
 133         self.assertEqual(result, [])
 134
 135         # fire one Deferred's errback -- now we have a result
 136         defr2.errback(GenericError("from def2"))
 137         self.assertEqual(len(result), 1)
 138
 139         # extract the result from the list
 140         aFailure = result[0]
 141
 142         # the type of the failure is a FirstError
 143         self.failUnless(issubclass(aFailure.type, defer.FirstError),
 144             'issubclass(aFailure.type, defer.FirstError) failed: '
 145             "failure's type is %r" % (aFailure.type,)
 146         )
 147
 148         firstError = aFailure.value
 149
 150         # check that the GenericError("2") from the deferred at index 1
 151         # (defr2) is intact inside failure.value
 152         self.assertEqual(firstError.subFailure.type, GenericError)
 153         self.assertEqual(firstError.subFailure.value.args, ("from def2",))
 154         self.assertEqual(firstError.index, 1)
 155
 156
 157     def testDeferredListDontConsumeErrors(self):
 158         d1 = defer.Deferred()
 159         dl = defer.DeferredList([d1])
 160
 161         errorTrap = []
 162         d1.addErrback(errorTrap.append)
 163
 164         result = []
 165         dl.addCallback(result.append)
 166
 167         d1.errback(GenericError('Bang'))
 168         self.assertEqual('Bang', errorTrap[0].value.args[0])
 169         self.assertEqual(1, len(result))
 170         self.assertEqual('Bang', result[0][0][1].value.args[0])
 171
 172     def testDeferredListConsumeErrors(self):
 173         d1 = defer.Deferred()
 174         dl = defer.DeferredList([d1], consumeErrors=True)
 175
 176         errorTrap = []
 177         d1.addErrback(errorTrap.append)
 178
 179         result = []
 180         dl.addCallback(result.append)
 181
 182         d1.errback(GenericError('Bang'))
 183         self.assertEqual([], errorTrap)
 184         self.assertEqual(1, len(result))
 185         self.assertEqual('Bang', result[0][0][1].value.args[0])
 186
 187     def testDeferredListFireOnOneErrorWithAlreadyFiredDeferreds(self):
 188         # Create some deferreds, and errback one
 189         d1 = defer.Deferred()
 190         d2 = defer.Deferred()
 191         d1.errback(GenericError('Bang'))
 192
 193         # *Then* build the DeferredList, with fireOnOneErrback=True
 194         dl = defer.DeferredList([d1, d2], fireOnOneErrback=True)
 195         result = []
 196         dl.addErrback(result.append)
 197         self.assertEqual(1, len(result))
 198
 199         d1.addErrback(lambda e: None)  # Swallow error
 200
 201     def testDeferredListWithAlreadyFiredDeferreds(self):
 202         # Create some deferreds, and err one, call the other
 203         d1 = defer.Deferred()
 204         d2 = defer.Deferred()
 205         d1.errback(GenericError('Bang'))
 206         d2.callback(2)
 207
 208         # *Then* build the DeferredList
 209         dl = defer.DeferredList([d1, d2])
 210
 211         result = []
 212         dl.addCallback(result.append)
 213
 214         self.assertEqual(1, len(result))
 215
 216         d1.addErrback(lambda e: None)  # Swallow error
 217
 218
 219     def testImmediateSuccess(self):
 220         l = []
 221         d = defer.succeed("success")
 222         d.addCallback(l.append)
 223         self.assertEqual(l, ["success"])
 224
 225
 226     def testImmediateFailure(self):
 227         l = []
 228         d = defer.fail(GenericError("fail"))
 229         d.addErrback(l.append)
 230         self.assertEqual(str(l[0].value), "fail")
 231
 232     def testPausedFailure(self):
 233         l = []
 234         d = defer.fail(GenericError("fail"))
 235         d.pause()
 236         d.addErrback(l.append)
 237         self.assertEqual(l, [])
 238         d.unpause()
 239         self.assertEqual(str(l[0].value), "fail")
 240
 241     def testCallbackErrors(self):
 242         l = []
 243         d = defer.Deferred().addCallback(lambda _: 1 / 0).addErrback(l.append)
 244         d.callback(1)
 245         self.assert_(isinstance(l[0].value, ZeroDivisionError))
 246         l = []
 247         d = defer.Deferred().addCallback(
 248             lambda _: failure.Failure(ZeroDivisionError())).addErrback(l.append)
 249         d.callback(1)
 250         self.assert_(isinstance(l[0].value, ZeroDivisionError))
 251
 252     def testUnpauseBeforeCallback(self):
 253         d = defer.Deferred()
 254         d.pause()
 255         d.addCallback(self._callback)
 256         d.unpause()
 257
 258     def testReturnDeferred(self):
 259         d = defer.Deferred()
 260         d2 = defer.Deferred()
 261         d2.pause()
 262         d.addCallback(lambda r, d2=d2: d2)
 263         d.addCallback(self._callback)
 264         d.callback(1)
 265         assert self.callbackResults is None, "Should not have been called yet."
 266         d2.callback(2)
 267         assert self.callbackResults is None, "Still should not have been called yet."
 268         d2.unpause()
 269         assert self.callbackResults[0][0] == 2, "Result should have been from second deferred:%s" % (self.callbackResults,)
 270
 271
 272     def test_chainedPausedDeferredWithResult(self):
 273         """
 274         When a paused Deferred with a result is returned from a callback on
 275         another Deferred, the other Deferred is chained to the first and waits
 276         for it to be unpaused.
 277         """
 278         expected = object()
 279         paused = defer.Deferred()
 280         paused.callback(expected)
 281         paused.pause()
 282         chained = defer.Deferred()
 283         chained.addCallback(lambda ignored: paused)
 284         chained.callback(None)
 285
 286         result = []
 287         chained.addCallback(result.append)
 288         self.assertEqual(result, [])
 289         paused.unpause()
 290         self.assertEqual(result, [expected])
 291
 292
 293     def test_pausedDeferredChained(self):
 294         """
 295         A paused Deferred encountered while pushing a result forward through a
 296         chain does not prevent earlier Deferreds from continuing to execute
 297         their callbacks.
 298         """
 299         first = defer.Deferred()
 300         second = defer.Deferred()
 301         first.addCallback(lambda ignored: second)
 302         first.callback(None)
 303         first.pause()
 304         second.callback(None)
 305         result = []
 306         second.addCallback(result.append)
 307         self.assertEqual(result, [None])
 308
 309
 310     def test_gatherResults(self):
 311         # test successful list of deferreds
 312         l = []
 313         defer.gatherResults([defer.succeed(1), defer.succeed(2)]).addCallback(l.append)
 314         self.assertEqual(l, [[1, 2]])
 315         # test failing list of deferreds
 316         l = []
 317         dl = [defer.succeed(1), defer.fail(ValueError)]
 318         defer.gatherResults(dl).addErrback(l.append)
 319         self.assertEqual(len(l), 1)
 320         self.assert_(isinstance(l[0], failure.Failure))
 321         # get rid of error
 322         dl[1].addErrback(lambda e: 1)
 323
 324
 325     def test_gatherResultsWithConsumeErrors(self):
 326         """
 327         If a L{Deferred} in the list passed to L{gatherResults} fires with a
 328         failure and C{consumerErrors} is C{True}, the failure is converted to a
 329         C{None} result on that L{Deferred}.
 330         """
 331         # test successful list of deferreds
 332         dgood = defer.succeed(1)
 333         dbad = defer.fail(RuntimeError("oh noes"))
 334         d = defer.gatherResults([dgood, dbad], consumeErrors=True)
 335         unconsumedErrors = []
 336         dbad.addErrback(unconsumedErrors.append)
 337         gatheredErrors = []
 338         d.addErrback(gatheredErrors.append)
 339
 340         self.assertEqual((len(unconsumedErrors), len(gatheredErrors)),
 341                          (0, 1))
 342         self.assertIsInstance(gatheredErrors[0].value, defer.FirstError)
 343         firstError = gatheredErrors[0].value.subFailure
 344         self.assertIsInstance(firstError.value, RuntimeError)
 345
 346
 347     def test_maybeDeferredSync(self):
 348         """
 349         L{defer.maybeDeferred} should retrieve the result of a synchronous
 350         function and pass it to its resulting L{defer.Deferred}.
 351         """
 352         S, E = [], []
 353         d = defer.maybeDeferred((lambda x: x + 5), 10)
 354         d.addCallbacks(S.append, E.append)
 355         self.assertEqual(E, [])
 356         self.assertEqual(S, [15])
 357         return d
 358
 359
 360     def test_maybeDeferredSyncError(self):
 361         """
 362         L{defer.maybeDeferred} should catch exception raised by a synchronous
 363         function and errback its resulting L{defer.Deferred} with it.
 364         """
 365         S, E = [], []
 366         try:
 367             '10' + 5
 368         except TypeError, e:
 369             expected = str(e)
 370         d = defer.maybeDeferred((lambda x: x + 5), '10')
 371         d.addCallbacks(S.append, E.append)
 372         self.assertEqual(S, [])
 373         self.assertEqual(len(E), 1)
 374         self.assertEqual(str(E[0].value), expected)
 375         return d
 376
 377
 378     def test_maybeDeferredAsync(self):
 379         """
 380         L{defer.maybeDeferred} should let L{defer.Deferred} instance pass by
 381         so that original result is the same.
 382         """
 383         d = defer.Deferred()
 384         d2 = defer.maybeDeferred(lambda: d)
 385         d.callback('Success')
 386         return d2.addCallback(self.assertEqual, 'Success')
 387
 388
 389     def test_maybeDeferredAsyncError(self):
 390         """
 391         L{defer.maybeDeferred} should let L{defer.Deferred} instance pass by
 392         so that L{failure.Failure} returned by the original instance is the
 393         same.
 394         """
 395         d = defer.Deferred()
 396         d2 = defer.maybeDeferred(lambda: d)
 397         d.errback(failure.Failure(RuntimeError()))
 398         return self.assertFailure(d2, RuntimeError)
 399
 400
 401     def test_innerCallbacksPreserved(self):
 402         """
 403         When a L{Deferred} encounters a result which is another L{Deferred}
 404         which is waiting on a third L{Deferred}, the middle L{Deferred}'s
 405         callbacks are executed after the third L{Deferred} fires and before the
 406         first receives a result.
 407         """
 408         results = []
 409         failures = []
 410         inner = defer.Deferred()
 411         def cb(result):
 412             results.append(('start-of-cb', result))
 413             d = defer.succeed('inner')
 414             def firstCallback(result):
 415                 results.append(('firstCallback', 'inner'))
 416                 return inner
 417             def secondCallback(result):
 418                 results.append(('secondCallback', result))
 419                 return result * 2
 420             d.addCallback(firstCallback).addCallback(secondCallback)
 421             d.addErrback(failures.append)
 422             return d
 423         outer = defer.succeed('outer')
 424         outer.addCallback(cb)
 425         inner.callback('orange')
 426         outer.addCallback(results.append)
 427         inner.addErrback(failures.append)
 428         outer.addErrback(failures.append)
 429         self.assertEqual([], failures)
 430         self.assertEqual(
 431             results,
 432             [('start-of-cb', 'outer'),
 433              ('firstCallback', 'inner'),
 434              ('secondCallback', 'orange'),
 435              'orangeorange'])
 436
 437
 438     def test_continueCallbackNotFirst(self):
 439         """
 440         The continue callback of a L{Deferred} waiting for another L{Deferred}
 441         is not necessarily the first one. This is somewhat a whitebox test
 442         checking that we search for that callback among the whole list of
 443         callbacks.
 444         """
 445         results = []
 446         failures = []
 447         a = defer.Deferred()
 448
 449         def cb(result):
 450             results.append(('cb', result))
 451             d = defer.Deferred()
 452
 453             def firstCallback(ignored):
 454                 results.append(('firstCallback', ignored))
 455                 return defer.gatherResults([a])
 456
 457             def secondCallback(result):
 458                 results.append(('secondCallback', result))
 459
 460             d.addCallback(firstCallback)
 461             d.addCallback(secondCallback)
 462             d.addErrback(failures.append)
 463             d.callback(None)
 464             return d
 465
 466         outer = defer.succeed('outer')
 467         outer.addCallback(cb)
 468         outer.addErrback(failures.append)
 469         self.assertEqual([('cb', 'outer'), ('firstCallback', None)], results)
 470         a.callback('withers')
 471         self.assertEqual([], failures)
 472         self.assertEqual(
 473             results,
 474             [('cb', 'outer'),
 475              ('firstCallback', None),
 476              ('secondCallback', ['withers'])])
 477
 478
 479     def test_callbackOrderPreserved(self):
 480         """
 481         A callback added to a L{Deferred} after a previous callback attached
 482         another L{Deferred} as a result is run after the callbacks of the other
 483         L{Deferred} are run.
 484         """
 485         results = []
 486         failures = []
 487         a = defer.Deferred()
 488
 489         def cb(result):
 490             results.append(('cb', result))
 491             d = defer.Deferred()
 492
 493             def firstCallback(ignored):
 494                 results.append(('firstCallback', ignored))
 495                 return defer.gatherResults([a])
 496
 497             def secondCallback(result):
 498                 results.append(('secondCallback', result))
 499
 500             d.addCallback(firstCallback)
 501             d.addCallback(secondCallback)
 502             d.addErrback(failures.append)
 503             d.callback(None)
 504             return d
 505
 506         outer = defer.Deferred()
 507         outer.addCallback(cb)
 508         outer.addCallback(lambda x: results.append('final'))
 509         outer.addErrback(failures.append)
 510         outer.callback('outer')
 511         self.assertEqual([('cb', 'outer'), ('firstCallback', None)], results)
 512         a.callback('withers')
 513         self.assertEqual([], failures)
 514         self.assertEqual(
 515             results,
 516             [('cb', 'outer'),
 517              ('firstCallback', None),
 518              ('secondCallback', ['withers']), 'final'])
 519
 520
 521     def test_reentrantRunCallbacks(self):
 522         """
 523         A callback added to a L{Deferred} by a callback on that L{Deferred}
 524         should be added to the end of the callback chain.
 525         """
 526         deferred = defer.Deferred()
 527         called = []
 528         def callback3(result):
 529             called.append(3)
 530         def callback2(result):
 531             called.append(2)
 532         def callback1(result):
 533             called.append(1)
 534             deferred.addCallback(callback3)
 535         deferred.addCallback(callback1)
 536         deferred.addCallback(callback2)
 537         deferred.callback(None)
 538         self.assertEqual(called, [1, 2, 3])
 539
 540
 541     def test_nonReentrantCallbacks(self):
 542         """
 543         A callback added to a L{Deferred} by a callback on that L{Deferred}
 544         should not be executed until the running callback returns.
 545         """
 546         deferred = defer.Deferred()
 547         called = []
 548         def callback2(result):
 549             called.append(2)
 550         def callback1(result):
 551             called.append(1)
 552             deferred.addCallback(callback2)
 553             self.assertEqual(called, [1])
 554         deferred.addCallback(callback1)
 555         deferred.callback(None)
 556         self.assertEqual(called, [1, 2])
 557
 558
 559     def test_reentrantRunCallbacksWithFailure(self):
 560         """
 561         After an exception is raised by a callback which was added to a
 562         L{Deferred} by a callback on that L{Deferred}, the L{Deferred} should
 563         call the first errback with a L{Failure} wrapping that exception.
 564         """
 565         exceptionMessage = "callback raised exception"
 566         deferred = defer.Deferred()
 567         def callback2(result):
 568             raise Exception(exceptionMessage)
 569         def callback1(result):
 570             deferred.addCallback(callback2)
 571         deferred.addCallback(callback1)
 572         deferred.callback(None)
 573         self.assertFailure(deferred, Exception)
 574         def cbFailed(exception):
 575             self.assertEqual(exception.args, (exceptionMessage,))
 576         deferred.addCallback(cbFailed)
 577         return deferred
 578
 579
 580     def test_synchronousImplicitChain(self):
 581         """
 582         If a first L{Deferred} with a result is returned from a callback on a
 583         second L{Deferred}, the result of the second L{Deferred} becomes the
 584         result of the first L{Deferred} and the result of the first L{Deferred}
 585         becomes C{None}.
 586         """
 587         result = object()
 588         first = defer.succeed(result)
 589         second = defer.Deferred()
 590         second.addCallback(lambda ign: first)
 591         second.callback(None)
 592
 593         results = []
 594         first.addCallback(results.append)
 595         self.assertIdentical(results[0], None)
 596         second.addCallback(results.append)
 597         self.assertIdentical(results[1], result)
 598
 599
 600     def test_asynchronousImplicitChain(self):
 601         """
 602         If a first L{Deferred} without a result is returned from a callback on
 603         a second L{Deferred}, the result of the second L{Deferred} becomes the
 604         result of the first L{Deferred} as soon as the first L{Deferred} has
 605         one and the result of the first L{Deferred} becomes C{None}.
 606         """
 607         first = defer.Deferred()
 608         second = defer.Deferred()
 609         second.addCallback(lambda ign: first)
 610         second.callback(None)
 611
 612         firstResult = []
 613         first.addCallback(firstResult.append)
 614         secondResult = []
 615         second.addCallback(secondResult.append)
 616
 617         self.assertEqual(firstResult, [])
 618         self.assertEqual(secondResult, [])
 619
 620         result = object()
 621         first.callback(result)
 622
 623         self.assertEqual(firstResult, [None])
 624         self.assertEqual(secondResult, [result])
 625
 626
 627     def test_synchronousImplicitErrorChain(self):
 628         """
 629         If a first L{Deferred} with a L{Failure} result is returned from a
 630         callback on a second L{Deferred}, the first L{Deferred}'s result is
 631         converted to L{None} and no unhandled error is logged when it is
 632         garbage collected.
 633         """
 634         first = defer.fail(RuntimeError("First Deferred's Failure"))
 635         second = defer.Deferred()
 636         second.addCallback(lambda ign, first=first: first)
 637         self.assertFailure(second, RuntimeError)
 638         second.callback(None)
 639         firstResult = []
 640         first.addCallback(firstResult.append)
 641         self.assertIdentical(firstResult[0], None)
 642         return second
 643
 644
 645     def test_asynchronousImplicitErrorChain(self):
 646         """
 647         Let C{a} and C{b} be two L{Deferred}s.
 648
 649         If C{a} has no result and is returned from a callback on C{b} then when
 650         C{a} fails, C{b}'s result becomes the L{Failure} that was C{a}'s result,
 651         the result of C{a} becomes C{None} so that no unhandled error is logged
 652         when it is garbage collected.
 653         """
 654         first = defer.Deferred()
 655         second = defer.Deferred()
 656         second.addCallback(lambda ign: first)
 657         second.callback(None)
 658         self.assertFailure(second, RuntimeError)
 659
 660         firstResult = []
 661         first.addCallback(firstResult.append)
 662         secondResult = []
 663         second.addCallback(secondResult.append)
 664
 665         self.assertEqual(firstResult, [])
 666         self.assertEqual(secondResult, [])
 667
 668         first.errback(RuntimeError("First Deferred's Failure"))
 669
 670         self.assertEqual(firstResult, [None])
 671         self.assertEqual(len(secondResult), 1)
 672
 673
 674     def test_doubleAsynchronousImplicitChaining(self):
 675         """
 676         L{Deferred} chaining is transitive.
 677
 678         In other words, let A, B, and C be Deferreds.  If C is returned from a
 679         callback on B and B is returned from a callback on A then when C fires,
 680         A fires.
 681         """
 682         first = defer.Deferred()
 683         second = defer.Deferred()
 684         second.addCallback(lambda ign: first)
 685         third = defer.Deferred()
 686         third.addCallback(lambda ign: second)
 687
 688         thirdResult = []
 689         third.addCallback(thirdResult.append)
 690
 691         result = object()
 692         # After this, second is waiting for first to tell it to continue.
 693         second.callback(None)
 694         # And after this, third is waiting for second to tell it to continue.
 695         third.callback(None)
 696
 697         # Still waiting
 698         self.assertEqual(thirdResult, [])
 699
 700         # This will tell second to continue which will tell third to continue.
 701         first.callback(result)
 702
 703         self.assertEqual(thirdResult, [result])
 704
 705
 706     def test_nestedAsynchronousChainedDeferreds(self):
 707         """
 708         L{Deferred}s can have callbacks that themselves return L{Deferred}s.
 709         When these "inner" L{Deferred}s fire (even asynchronously), the
 710         callback chain continues.
 711         """
 712         results = []
 713         failures = []
 714
 715         # A Deferred returned in the inner callback.
 716         inner = defer.Deferred()
 717
 718         def cb(result):
 719             results.append(('start-of-cb', result))
 720             d = defer.succeed('inner')
 721
 722             def firstCallback(result):
 723                 results.append(('firstCallback', 'inner'))
 724                 # Return a Deferred that definitely has not fired yet, so we
 725                 # can fire the Deferreds out of order.
 726                 return inner
 727
 728             def secondCallback(result):
 729                 results.append(('secondCallback', result))
 730                 return result * 2
 731
 732             d.addCallback(firstCallback).addCallback(secondCallback)
 733             d.addErrback(failures.append)
 734             return d
 735
 736         # Create a synchronous Deferred that has a callback 'cb' that returns
 737         # a Deferred 'd' that has fired but is now waiting on an unfired
 738         # Deferred 'inner'.
 739         outer = defer.succeed('outer')
 740         outer.addCallback(cb)
 741         outer.addCallback(results.append)
 742         # At this point, the callback 'cb' has been entered, and the first
 743         # callback of 'd' has been called.
 744         self.assertEqual(
 745             results, [('start-of-cb', 'outer'), ('firstCallback', 'inner')])
 746
 747         # Once the inner Deferred is fired, processing of the outer Deferred's
 748         # callback chain continues.
 749         inner.callback('orange')
 750
 751         # Make sure there are no errors.
 752         inner.addErrback(failures.append)
 753         outer.addErrback(failures.append)
 754         self.assertEqual(
 755             [], failures, "Got errbacks but wasn't expecting any.")
 756
 757         self.assertEqual(
 758             results,
 759             [('start-of-cb', 'outer'),
 760              ('firstCallback', 'inner'),
 761              ('secondCallback', 'orange'),
 762              'orangeorange'])
 763
 764
 765     def test_nestedAsynchronousChainedDeferredsWithExtraCallbacks(self):
 766         """
 767         L{Deferred}s can have callbacks that themselves return L{Deferred}s.
 768         These L{Deferred}s can have other callbacks added before they are
 769         returned, which subtly changes the callback chain. When these "inner"
 770         L{Deferred}s fire (even asynchronously), the outer callback chain
 771         continues.
 772         """
 773         results = []
 774         failures = []
 775
 776         # A Deferred returned in the inner callback after a callback is
 777         # added explicitly and directly to it.
 778         inner = defer.Deferred()
 779
 780         def cb(result):
 781             results.append(('start-of-cb', result))
 782             d = defer.succeed('inner')
 783
 784             def firstCallback(ignored):
 785                 results.append(('firstCallback', ignored))
 786                 # Return a Deferred that definitely has not fired yet with a
 787                 # result-transforming callback so we can fire the Deferreds
 788                 # out of order and see how the callback affects the ultimate
 789                 # results.
 790                 return inner.addCallback(lambda x: [x])
 791
 792             def secondCallback(result):
 793                 results.append(('secondCallback', result))
 794                 return result * 2
 795
 796             d.addCallback(firstCallback)
 797             d.addCallback(secondCallback)
 798             d.addErrback(failures.append)
 799             return d
 800
 801         # Create a synchronous Deferred that has a callback 'cb' that returns
 802         # a Deferred 'd' that has fired but is now waiting on an unfired
 803         # Deferred 'inner'.
 804         outer = defer.succeed('outer')
 805         outer.addCallback(cb)
 806         outer.addCallback(results.append)
 807         # At this point, the callback 'cb' has been entered, and the first
 808         # callback of 'd' has been called.
 809         self.assertEqual(
 810             results, [('start-of-cb', 'outer'), ('firstCallback', 'inner')])
 811
 812         # Once the inner Deferred is fired, processing of the outer Deferred's
 813         # callback chain continues.
 814         inner.callback('withers')
 815
 816         # Make sure there are no errors.
 817         outer.addErrback(failures.append)
 818         inner.addErrback(failures.append)
 819         self.assertEqual(
 820             [], failures, "Got errbacks but wasn't expecting any.")
 821
 822         self.assertEqual(
 823             results,
 824             [('start-of-cb', 'outer'),
 825              ('firstCallback', 'inner'),
 826              ('secondCallback', ['withers']),
 827              ['withers', 'withers']])
 828
 829
 830     def test_chainDeferredRecordsExplicitChain(self):
 831         """
 832         When we chain a L{Deferred}, that chaining is recorded explicitly.
 833         """
 834         a = defer.Deferred()
 835         b = defer.Deferred()
 836         b.chainDeferred(a)
 837         self.assertIdentical(a._chainedTo, b)
 838
 839
 840     def test_explicitChainClearedWhenResolved(self):
 841         """
 842         Any recorded chaining is cleared once the chaining is resolved, since
 843         it no longer exists.
 844
 845         In other words, if one L{Deferred} is recorded as depending on the
 846         result of another, and I{that} L{Deferred} has fired, then the
 847         dependency is resolved and we no longer benefit from recording it.
 848         """
 849         a = defer.Deferred()
 850         b = defer.Deferred()
 851         b.chainDeferred(a)
 852         b.callback(None)
 853         self.assertIdentical(a._chainedTo, None)
 854
 855
 856     def test_chainDeferredRecordsImplicitChain(self):
 857         """
 858         We can chain L{Deferred}s implicitly by adding callbacks that return
 859         L{Deferred}s. When this chaining happens, we record it explicitly as
 860         soon as we can find out about it.
 861         """
 862         a = defer.Deferred()
 863         b = defer.Deferred()
 864         a.addCallback(lambda ignored: b)
 865         a.callback(None)
 866         self.assertIdentical(a._chainedTo, b)
 867
 868
 869     def test_repr(self):
 870         """
 871         The C{repr()} of a L{Deferred} contains the class name and a
 872         representation of the internal Python ID.
 873         """
 874         d = defer.Deferred()
 875         address = hex(unsignedID(d))
 876         self.assertEqual(
 877             repr(d), '<Deferred at %s>' % (address,))
 878
 879
 880     def test_reprWithResult(self):
 881         """
 882         If a L{Deferred} has been fired, then its C{repr()} contains its
 883         result.
 884         """
 885         d = defer.Deferred()
 886         d.callback('orange')
 887         self.assertEqual(
 888             repr(d), "<Deferred at %s current result: 'orange'>" % (
 889                 hex(unsignedID(d))))
 890
 891
 892     def test_reprWithChaining(self):
 893         """
 894         If a L{Deferred} C{a} has been fired, but is waiting on another
 895         L{Deferred} C{b} that appears in its callback chain, then C{repr(a)}
 896         says that it is waiting on C{b}.
 897         """
 898         a = defer.Deferred()
 899         b = defer.Deferred()
 900         b.chainDeferred(a)
 901         self.assertEqual(
 902             repr(a), "<Deferred at %s waiting on Deferred at %s>" % (
 903                 hex(unsignedID(a)), hex(unsignedID(b))))
 904
 905
 906     def test_boundedStackDepth(self):
 907         """
 908         The depth of the call stack does not grow as more L{Deferred} instances
 909         are chained together.
 910         """
 911         def chainDeferreds(howMany):
 912             stack = []
 913             def recordStackDepth(ignored):
 914                 stack.append(len(traceback.extract_stack()))
 915
 916             top = defer.Deferred()
 917             innerDeferreds = [defer.Deferred() for ignored in range(howMany)]
 918             originalInners = innerDeferreds[:]
 919             last = defer.Deferred()
 920
 921             inner = innerDeferreds.pop()
 922             top.addCallback(lambda ign, inner=inner: inner)
 923             top.addCallback(recordStackDepth)
 924
 925             while innerDeferreds:
 926                 newInner = innerDeferreds.pop()
 927                 inner.addCallback(lambda ign, inner=newInner: inner)
 928                 inner = newInner
 929             inner.addCallback(lambda ign: last)
 930
 931             top.callback(None)
 932             for inner in originalInners:
 933                 inner.callback(None)
 934
 935             # Sanity check - the record callback is not intended to have
 936             # fired yet.
 937             self.assertEqual(stack, [])
 938
 939             # Now fire the last thing and return the stack depth at which the
 940             # callback was invoked.
 941             last.callback(None)
 942             return stack[0]
 943
 944         # Callbacks should be invoked at the same stack depth regardless of
 945         # how many Deferreds are chained.
 946         self.assertEqual(chainDeferreds(1), chainDeferreds(2))
 947
 948
 949     def test_resultOfDeferredResultOfDeferredOfFiredDeferredCalled(self):
 950         """
 951         Given three Deferreds, one chained to the next chained to the next,
 952         callbacks on the middle Deferred which are added after the chain is
 953         created are called once the last Deferred fires.
 954
 955         This is more of a regression-style test.  It doesn't exercise any
 956         particular code path through the current implementation of Deferred, but
 957         it does exercise a broken codepath through one of the variations of the
 958         implementation proposed as a resolution to ticket #411.
 959         """
 960         first = defer.Deferred()
 961         second = defer.Deferred()
 962         third = defer.Deferred()
 963         first.addCallback(lambda ignored: second)
 964         second.addCallback(lambda ignored: third)
 965         second.callback(None)
 966         first.callback(None)
 967         third.callback(None)
 968         L = []
 969         second.addCallback(L.append)
 970         self.assertEqual(L, [None])
 971
 972
 973     def test_errbackWithNoArgsNoDebug(self):
 974         """
 975         C{Deferred.errback()} creates a failure from the current Python
 976         exception.  When Deferred.debug is not set no globals or locals are
 977         captured in that failure.
 978         """
 979         defer.setDebugging(False)
 980         d = defer.Deferred()
 981         l = []
 982         exc = GenericError("Bang")
 983         try:
 984             raise exc
 985         except:
 986             d.errback()
 987         d.addErrback(l.append)
 988         fail = l[0]
 989         self.assertEqual(fail.value, exc)
 990         localz, globalz = fail.frames[0][-2:]
 991         self.assertEqual([], localz)
 992         self.assertEqual([], globalz)
 993
 994
 995     def test_errbackWithNoArgs(self):
 996         """
 997         C{Deferred.errback()} creates a failure from the current Python
 998         exception.  When Deferred.debug is set globals and locals are captured
 999         in that failure.
1000         """
1001         defer.setDebugging(True)
1002         d = defer.Deferred()
1003         l = []
1004         exc = GenericError("Bang")
1005         try:
1006             raise exc
1007         except:
1008             d.errback()
1009         d.addErrback(l.append)
1010         fail = l[0]
1011         self.assertEqual(fail.value, exc)
1012         localz, globalz = fail.frames[0][-2:]
1013         self.assertNotEquals([], localz)
1014         self.assertNotEquals([], globalz)
1015
1016
1017     def test_errorInCallbackDoesNotCaptureVars(self):
1018         """
1019         An error raised by a callback creates a Failure.  The Failure captures
1020         locals and globals if and only if C{Deferred.debug} is set.
1021         """
1022         d = defer.Deferred()
1023         d.callback(None)
1024         defer.setDebugging(False)
1025         def raiseError(ignored):
1026             raise GenericError("Bang")
1027         d.addCallback(raiseError)
1028         l = []
1029         d.addErrback(l.append)
1030         fail = l[0]
1031         localz, globalz = fail.frames[0][-2:]
1032         self.assertEqual([], localz)
1033         self.assertEqual([], globalz)
1034
1035
1036     def test_errorInCallbackCapturesVarsWhenDebugging(self):
1037         """
1038         An error raised by a callback creates a Failure.  The Failure captures
1039         locals and globals if and only if C{Deferred.debug} is set.
1040         """
1041         d = defer.Deferred()
1042         d.callback(None)
1043         defer.setDebugging(True)
1044         def raiseError(ignored):
1045             raise GenericError("Bang")
1046         d.addCallback(raiseError)
1047         l = []
1048         d.addErrback(l.append)
1049         fail = l[0]
1050         localz, globalz = fail.frames[0][-2:]
1051         self.assertNotEquals([], localz)
1052         self.assertNotEquals([], globalz)
1053
1054
1055
1056 class FirstErrorTests(unittest.TestCase):
1057     """
1058     Tests for L{FirstError}.
1059     """
1060     def test_repr(self):
1061         """
1062         The repr of a L{FirstError} instance includes the repr of the value of
1063         the sub-failure and the index which corresponds to the L{FirstError}.
1064         """
1065         exc = ValueError("some text")
1066         try:
1067             raise exc
1068         except:
1069             f = failure.Failure()
1070
1071         error = defer.FirstError(f, 3)
1072         self.assertEqual(
1073             repr(error),
1074             "FirstError[#3, %s]" % (repr(exc),))
1075
1076
1077     def test_str(self):
1078         """
1079         The str of a L{FirstError} instance includes the str of the
1080         sub-failure and the index which corresponds to the L{FirstError}.
1081         """
1082         exc = ValueError("some text")
1083         try:
1084             raise exc
1085         except:
1086             f = failure.Failure()
1087
1088         error = defer.FirstError(f, 5)
1089         self.assertEqual(
1090             str(error),
1091             "FirstError[#5, %s]" % (str(f),))
1092
1093
1094     def test_comparison(self):
1095         """
1096         L{FirstError} instances compare equal to each other if and only if
1097         their failure and index compare equal.  L{FirstError} instances do not
1098         compare equal to instances of other types.
1099         """
1100         try:
1101             1 / 0
1102         except:
1103             firstFailure = failure.Failure()
1104
1105         one = defer.FirstError(firstFailure, 13)
1106         anotherOne = defer.FirstError(firstFailure, 13)
1107
1108         try:
1109             raise ValueError("bar")
1110         except:
1111             secondFailure = failure.Failure()
1112
1113         another = defer.FirstError(secondFailure, 9)
1114
1115         self.assertTrue(one == anotherOne)
1116         self.assertFalse(one == another)
1117         self.assertTrue(one != another)
1118         self.assertFalse(one != anotherOne)
1119
1120         self.assertFalse(one == 10)
1121
1122
1123
1124 class AlreadyCalledTestCase(unittest.TestCase):
1125     def setUp(self):
1126         self._deferredWasDebugging = defer.getDebugging()
1127         defer.setDebugging(True)
1128
1129     def tearDown(self):
1130         defer.setDebugging(self._deferredWasDebugging)
1131
1132     def _callback(self, *args, **kw):
1133         pass
1134     def _errback(self, *args, **kw):
1135         pass
1136
1137     def _call_1(self, d):
1138         d.callback("hello")
1139     def _call_2(self, d):
1140         d.callback("twice")
1141     def _err_1(self, d):
1142         d.errback(failure.Failure(RuntimeError()))
1143     def _err_2(self, d):
1144         d.errback(failure.Failure(RuntimeError()))
1145
1146     def testAlreadyCalled_CC(self):
1147         d = defer.Deferred()
1148         d.addCallbacks(self._callback, self._errback)
1149         self._call_1(d)
1150         self.failUnlessRaises(defer.AlreadyCalledError, self._call_2, d)
1151
1152     def testAlreadyCalled_CE(self):
1153         d = defer.Deferred()
1154         d.addCallbacks(self._callback, self._errback)
1155         self._call_1(d)
1156         self.failUnlessRaises(defer.AlreadyCalledError, self._err_2, d)
1157
1158     def testAlreadyCalled_EE(self):
1159         d = defer.Deferred()
1160         d.addCallbacks(self._callback, self._errback)
1161         self._err_1(d)
1162         self.failUnlessRaises(defer.AlreadyCalledError, self._err_2, d)
1163
1164     def testAlreadyCalled_EC(self):
1165         d = defer.Deferred()
1166         d.addCallbacks(self._callback, self._errback)
1167         self._err_1(d)
1168         self.failUnlessRaises(defer.AlreadyCalledError, self._call_2, d)
1169
1170
1171     def _count(self, linetype, func, lines, expected):
1172         count = 0
1173         for line in lines:
1174             if (line.startswith(' %s:' % linetype) and
1175                 line.endswith(' %s' % func)):
1176                 count += 1
1177         self.failUnless(count == expected)
1178
1179     def _check(self, e, caller, invoker1, invoker2):
1180         # make sure the debugging information is vaguely correct
1181         lines = e.args[0].split("\n")
1182         # the creator should list the creator (testAlreadyCalledDebug) but not
1183         # _call_1 or _call_2 or other invokers
1184         self._count('C', caller, lines, 1)
1185         self._count('C', '_call_1', lines, 0)
1186         self._count('C', '_call_2', lines, 0)
1187         self._count('C', '_err_1', lines, 0)
1188         self._count('C', '_err_2', lines, 0)
1189         # invoker should list the first invoker but not the second
1190         self._count('I', invoker1, lines, 1)
1191         self._count('I', invoker2, lines, 0)
1192
1193     def testAlreadyCalledDebug_CC(self):
1194         d = defer.Deferred()
1195         d.addCallbacks(self._callback, self._errback)
1196         self._call_1(d)
1197         try:
1198             self._call_2(d)
1199         except defer.AlreadyCalledError, e:
1200             self._check(e, "testAlreadyCalledDebug_CC", "_call_1", "_call_2")
1201         else:
1202             self.fail("second callback failed to raise AlreadyCalledError")
1203
1204     def testAlreadyCalledDebug_CE(self):
1205         d = defer.Deferred()
1206         d.addCallbacks(self._callback, self._errback)
1207         self._call_1(d)
1208         try:
1209             self._err_2(d)
1210         except defer.AlreadyCalledError, e:
1211             self._check(e, "testAlreadyCalledDebug_CE", "_call_1", "_err_2")
1212         else:
1213             self.fail("second errback failed to raise AlreadyCalledError")
1214
1215     def testAlreadyCalledDebug_EC(self):
1216         d = defer.Deferred()
1217         d.addCallbacks(self._callback, self._errback)
1218         self._err_1(d)
1219         try:
1220             self._call_2(d)
1221         except defer.AlreadyCalledError, e:
1222             self._check(e, "testAlreadyCalledDebug_EC", "_err_1", "_call_2")
1223         else:
1224             self.fail("second callback failed to raise AlreadyCalledError")
1225
1226     def testAlreadyCalledDebug_EE(self):
1227         d = defer.Deferred()
1228         d.addCallbacks(self._callback, self._errback)
1229         self._err_1(d)
1230         try:
1231             self._err_2(d)
1232         except defer.AlreadyCalledError, e:
1233             self._check(e, "testAlreadyCalledDebug_EE", "_err_1", "_err_2")
1234         else:
1235             self.fail("second errback failed to raise AlreadyCalledError")
1236
1237     def testNoDebugging(self):
1238         defer.setDebugging(False)
1239         d = defer.Deferred()
1240         d.addCallbacks(self._callback, self._errback)
1241         self._call_1(d)
1242         try:
1243             self._call_2(d)
1244         except defer.AlreadyCalledError, e:
1245             self.failIf(e.args)
1246         else:
1247             self.fail("second callback failed to raise AlreadyCalledError")
1248
1249
1250     def testSwitchDebugging(self):
1251         # Make sure Deferreds can deal with debug state flipping
1252         # around randomly.  This is covering a particular fixed bug.
1253         defer.setDebugging(False)
1254         d = defer.Deferred()
1255         d.addBoth(lambda ign: None)
1256         defer.setDebugging(True)
1257         d.callback(None)
1258
1259         defer.setDebugging(False)
1260         d = defer.Deferred()
1261         d.callback(None)
1262         defer.setDebugging(True)
1263         d.addBoth(lambda ign: None)
1264
1265
1266
1267 class DeferredCancellerTest(unittest.TestCase):
1268     def setUp(self):
1269         self.callbackResults = None
1270         self.errbackResults = None
1271         self.callback2Results = None
1272         self.cancellerCallCount = 0
1273
1274
1275     def tearDown(self):
1276         # Sanity check that the canceller was called at most once.
1277         self.assertTrue(self.cancellerCallCount in (0, 1))
1278
1279
1280     def _callback(self, data):
1281         self.callbackResults = data
1282         return data
1283
1284
1285     def _callback2(self, data):
1286         self.callback2Results = data
1287
1288
1289     def _errback(self, data):
1290         self.errbackResults = data
1291
1292
1293     def test_noCanceller(self):
1294         """
1295         A L{defer.Deferred} without a canceller must errback with a
1296         L{defer.CancelledError} and not callback.
1297         """
1298         d = defer.Deferred()
1299         d.addCallbacks(self._callback, self._errback)
1300         d.cancel()
1301         self.assertEqual(self.errbackResults.type, defer.CancelledError)
1302         self.assertEqual(self.callbackResults, None)
1303
1304
1305     def test_raisesAfterCancelAndCallback(self):
1306         """
1307         A L{defer.Deferred} without a canceller, when cancelled must allow
1308         a single extra call to callback, and raise
1309         L{defer.AlreadyCalledError} if callbacked or errbacked thereafter.
1310         """
1311         d = defer.Deferred()
1312         d.addCallbacks(self._callback, self._errback)
1313         d.cancel()
1314
1315         # A single extra callback should be swallowed.
1316         d.callback(None)
1317
1318         # But a second call to callback or errback is not.
1319         self.assertRaises(defer.AlreadyCalledError, d.callback, None)
1320         self.assertRaises(defer.AlreadyCalledError, d.errback, Exception())
1321
1322
1323     def test_raisesAfterCancelAndErrback(self):
1324         """
1325         A L{defer.Deferred} without a canceller, when cancelled must allow
1326         a single extra call to errback, and raise
1327         L{defer.AlreadyCalledError} if callbacked or errbacked thereafter.
1328         """
1329         d = defer.Deferred()
1330         d.addCallbacks(self._callback, self._errback)
1331         d.cancel()
1332
1333         # A single extra errback should be swallowed.
1334         d.errback(Exception())
1335
1336         # But a second call to callback or errback is not.
1337         self.assertRaises(defer.AlreadyCalledError, d.callback, None)
1338         self.assertRaises(defer.AlreadyCalledError, d.errback, Exception())
1339
1340
1341     def test_noCancellerMultipleCancelsAfterCancelAndCallback(self):
1342         """
1343         A L{Deferred} without a canceller, when cancelled and then
1344         callbacked, ignores multiple cancels thereafter.
1345         """
1346         d = defer.Deferred()
1347         d.addCallbacks(self._callback, self._errback)
1348         d.cancel()
1349         currentFailure = self.errbackResults
1350         # One callback will be ignored
1351         d.callback(None)
1352         # Cancel should have no effect.
1353         d.cancel()
1354         self.assertIdentical(currentFailure, self.errbackResults)
1355
1356
1357     def test_noCancellerMultipleCancelsAfterCancelAndErrback(self):
1358         """
1359         A L{defer.Deferred} without a canceller, when cancelled and then
1360         errbacked, ignores multiple cancels thereafter.
1361         """
1362         d = defer.Deferred()
1363         d.addCallbacks(self._callback, self._errback)
1364         d.cancel()
1365         self.assertEqual(self.errbackResults.type, defer.CancelledError)
1366         currentFailure = self.errbackResults
1367         # One errback will be ignored
1368         d.errback(GenericError())
1369         # I.e., we should still have a CancelledError.
1370         self.assertEqual(self.errbackResults.type, defer.CancelledError)
1371         d.cancel()
1372         self.assertIdentical(currentFailure, self.errbackResults)
1373
1374
1375     def test_noCancellerMultipleCancel(self):
1376         """
1377         Calling cancel multiple times on a deferred with no canceller
1378         results in a L{defer.CancelledError}. Subsequent calls to cancel
1379         do not cause an error.
1380         """
1381         d = defer.Deferred()
1382         d.addCallbacks(self._callback, self._errback)
1383         d.cancel()
1384         self.assertEqual(self.errbackResults.type, defer.CancelledError)
1385         currentFailure = self.errbackResults
1386         d.cancel()
1387         self.assertIdentical(currentFailure, self.errbackResults)
1388
1389
1390     def test_cancellerMultipleCancel(self):
1391         """
1392         Verify that calling cancel multiple times on a deferred with a
1393         canceller that does not errback results in a
1394         L{defer.CancelledError} and that subsequent calls to cancel do not
1395         cause an error and that after all that, the canceller was only
1396         called once.
1397         """
1398         def cancel(d):
1399             self.cancellerCallCount += 1
1400
1401         d = defer.Deferred(canceller=cancel)
1402         d.addCallbacks(self._callback, self._errback)
1403         d.cancel()
1404         self.assertEqual(self.errbackResults.type, defer.CancelledError)
1405         currentFailure = self.errbackResults
1406         d.cancel()
1407         self.assertIdentical(currentFailure, self.errbackResults)
1408         self.assertEqual(self.cancellerCallCount, 1)
1409
1410
1411     def test_simpleCanceller(self):
1412         """
1413         Verify that a L{defer.Deferred} calls its specified canceller when
1414         it is cancelled, and that further call/errbacks raise
1415         L{defer.AlreadyCalledError}.
1416         """
1417         def cancel(d):
1418             self.cancellerCallCount += 1
1419
1420         d = defer.Deferred(canceller=cancel)
1421         d.addCallbacks(self._callback, self._errback)
1422         d.cancel()
1423         self.assertEqual(self.cancellerCallCount, 1)
1424         self.assertEqual(self.errbackResults.type, defer.CancelledError)
1425
1426         # Test that further call/errbacks are *not* swallowed
1427         self.assertRaises(defer.AlreadyCalledError, d.callback, None)
1428         self.assertRaises(defer.AlreadyCalledError, d.errback, Exception())
1429
1430
1431     def test_cancellerArg(self):
1432         """
1433         Verify that a canceller is given the correct deferred argument.
1434         """
1435         def cancel(d1):
1436             self.assertIdentical(d1, d)
1437         d = defer.Deferred(canceller=cancel)
1438         d.addCallbacks(self._callback, self._errback)
1439         d.cancel()
1440
1441
1442     def test_cancelAfterCallback(self):
1443         """
1444         Test that cancelling a deferred after it has been callbacked does
1445         not cause an error.
1446         """
1447         def cancel(d):
1448             self.cancellerCallCount += 1
1449             d.errback(GenericError())
1450         d = defer.Deferred(canceller=cancel)
1451         d.addCallbacks(self._callback, self._errback)
1452         d.callback('biff!')
1453         d.cancel()
1454         self.assertEqual(self.cancellerCallCount, 0)
1455         self.assertEqual(self.errbackResults, None)
1456         self.assertEqual(self.callbackResults, 'biff!')
1457
1458
1459     def test_cancelAfterErrback(self):
1460         """
1461         Test that cancelling a L{Deferred} after it has been errbacked does
1462         not result in a L{defer.CancelledError}.
1463         """
1464         def cancel(d):
1465             self.cancellerCallCount += 1
1466             d.errback(GenericError())
1467         d = defer.Deferred(canceller=cancel)
1468         d.addCallbacks(self._callback, self._errback)
1469         d.errback(GenericError())
1470         d.cancel()
1471         self.assertEqual(self.cancellerCallCount, 0)
1472         self.assertEqual(self.errbackResults.type, GenericError)
1473         self.assertEqual(self.callbackResults, None)
1474
1475
1476     def test_cancellerThatErrbacks(self):
1477         """
1478         Test a canceller which errbacks its deferred.
1479         """
1480         def cancel(d):
1481             self.cancellerCallCount += 1
1482             d.errback(GenericError())
1483         d = defer.Deferred(canceller=cancel)
1484         d.addCallbacks(self._callback, self._errback)
1485         d.cancel()
1486         self.assertEqual(self.cancellerCallCount, 1)
1487         self.assertEqual(self.errbackResults.type, GenericError)
1488
1489
1490     def test_cancellerThatCallbacks(self):
1491         """
1492         Test a canceller which calls its deferred.
1493         """
1494         def cancel(d):
1495             self.cancellerCallCount += 1
1496             d.callback('hello!')
1497         d = defer.Deferred(canceller=cancel)
1498         d.addCallbacks(self._callback, self._errback)
1499         d.cancel()
1500         self.assertEqual(self.cancellerCallCount, 1)
1501         self.assertEqual(self.callbackResults, 'hello!')
1502         self.assertEqual(self.errbackResults, None)
1503
1504
1505     def test_cancelNestedDeferred(self):
1506         """
1507         Verify that a Deferred, a, which is waiting on another Deferred, b,
1508         returned from one of its callbacks, will propagate
1509         L{defer.CancelledError} when a is cancelled.
1510         """
1511         def innerCancel(d):
1512             self.cancellerCallCount += 1
1513         def cancel(d):
1514             self.assert_(False)
1515
1516         b = defer.Deferred(canceller=innerCancel)
1517         a = defer.Deferred(canceller=cancel)
1518         a.callback(None)
1519         a.addCallback(lambda data: b)
1520         a.cancel()
1521         a.addCallbacks(self._callback, self._errback)
1522         # The cancel count should be one (the cancellation done by B)
1523         self.assertEqual(self.cancellerCallCount, 1)
1524         # B's canceller didn't errback, so defer.py will have called errback
1525         # with a CancelledError.
1526         self.assertEqual(self.errbackResults.type, defer.CancelledError)
1527
1528
1529
1530 class LogTestCase(unittest.TestCase):
1531     """
1532     Test logging of unhandled errors.
1533     """
1534
1535     def setUp(self):
1536         """
1537         Add a custom observer to observer logging.
1538         """
1539         self.c = []
1540         log.addObserver(self.c.append)
1541
1542     def tearDown(self):
1543         """
1544         Remove the observer.
1545         """
1546         log.removeObserver(self.c.append)
1547
1548
1549     def _loggedErrors(self):
1550         return [e for e in self.c if e["isError"]]
1551
1552
1553     def _check(self):
1554         """
1555         Check the output of the log observer to see if the error is present.
1556         """
1557         c2 = self._loggedErrors()
1558         self.assertEqual(len(c2), 2)
1559         c2[1]["failure"].trap(ZeroDivisionError)
1560         self.flushLoggedErrors(ZeroDivisionError)
1561
1562     def test_errorLog(self):
1563         """
1564         Verify that when a L{Deferred} with no references to it is fired,
1565         and its final result (the one not handled by any callback) is an
1566         exception, that exception will be logged immediately.
1567         """
1568         defer.Deferred().addCallback(lambda x: 1 / 0).callback(1)
1569         gc.collect()
1570         self._check()
1571
1572     def test_errorLogWithInnerFrameRef(self):
1573         """
1574         Same as L{test_errorLog}, but with an inner frame.
1575         """
1576         def _subErrorLogWithInnerFrameRef():
1577             d = defer.Deferred()
1578             d.addCallback(lambda x: 1 / 0)
1579             d.callback(1)
1580
1581         _subErrorLogWithInnerFrameRef()
1582         gc.collect()
1583         self._check()
1584
1585     def test_errorLogWithInnerFrameCycle(self):
1586         """
1587         Same as L{test_errorLogWithInnerFrameRef}, plus create a cycle.
1588         """
1589         def _subErrorLogWithInnerFrameCycle():
1590             d = defer.Deferred()
1591             d.addCallback(lambda x, d=d: 1 / 0)
1592             d._d = d
1593             d.callback(1)
1594
1595         _subErrorLogWithInnerFrameCycle()
1596         gc.collect()
1597         self._check()
1598
1599
1600     def test_chainedErrorCleanup(self):
1601         """
1602         If one Deferred with an error result is returned from a callback on
1603         another Deferred, when the first Deferred is garbage collected it does
1604         not log its error.
1605         """
1606         d = defer.Deferred()
1607         d.addCallback(lambda ign: defer.fail(RuntimeError("zoop")))
1608         d.callback(None)
1609
1610         # Sanity check - this isn't too interesting, but we do want the original
1611         # Deferred to have gotten the failure.
1612         results = []
1613         errors = []
1614         d.addCallbacks(results.append, errors.append)
1615         self.assertEqual(results, [])
1616         self.assertEqual(len(errors), 1)
1617         errors[0].trap(Exception)
1618
1619         # Get rid of any references we might have to the inner Deferred (none of
1620         # these should really refer to it, but we're just being safe).
1621         del results, errors, d
1622         # Force a collection cycle so that there's a chance for an error to be
1623         # logged, if it's going to be logged.
1624         gc.collect()
1625         # And make sure it is not.
1626         self.assertEqual(self._loggedErrors(), [])
1627
1628
1629     def test_errorClearedByChaining(self):
1630         """
1631         If a Deferred with a failure result has an errback which chains it to
1632         another Deferred, the initial failure is cleared by the errback so it is
1633         not logged.
1634         """
1635         # Start off with a Deferred with a failure for a result
1636         bad = defer.fail(Exception("oh no"))
1637         good = defer.Deferred()
1638         # Give it a callback that chains it to another Deferred
1639         bad.addErrback(lambda ignored: good)
1640         # That's all, clean it up.  No Deferred here still has a failure result,
1641         # so nothing should be logged.
1642         good = bad = None
1643         gc.collect()
1644         self.assertEqual(self._loggedErrors(), [])
1645
1646
1647
1648 class DeferredTestCaseII(unittest.TestCase):
1649     def setUp(self):
1650         self.callbackRan = 0
1651
1652     def testDeferredListEmpty(self):
1653         """Testing empty DeferredList."""
1654         dl = defer.DeferredList([])
1655         dl.addCallback(self.cb_empty)
1656
1657     def cb_empty(self, res):
1658         self.callbackRan = 1
1659         self.assertEqual([], res)
1660
1661     def tearDown(self):
1662         self.failUnless(self.callbackRan, "Callback was never run.")
1663
1664 class OtherPrimitives(unittest.TestCase):
1665     def _incr(self, result):
1666         self.counter += 1
1667
1668     def setUp(self):
1669         self.counter = 0
1670
1671     def testLock(self):
1672         lock = defer.DeferredLock()
1673         lock.acquire().addCallback(self._incr)
1674         self.failUnless(lock.locked)
1675         self.assertEqual(self.counter, 1)
1676
1677         lock.acquire().addCallback(self._incr)
1678         self.failUnless(lock.locked)
1679         self.assertEqual(self.counter, 1)
1680
1681         lock.release()
1682         self.failUnless(lock.locked)
1683         self.assertEqual(self.counter, 2)
1684
1685         lock.release()
1686         self.failIf(lock.locked)
1687         self.assertEqual(self.counter, 2)
1688
1689         self.assertRaises(TypeError, lock.run)
1690
1691         firstUnique = object()
1692         secondUnique = object()
1693
1694         controlDeferred = defer.Deferred()
1695         def helper(self, b):
1696             self.b = b
1697             return controlDeferred
1698
1699         resultDeferred = lock.run(helper, self=self, b=firstUnique)
1700         self.failUnless(lock.locked)
1701         self.assertEqual(self.b, firstUnique)
1702
1703         resultDeferred.addCallback(lambda x: setattr(self, 'result', x))
1704
1705         lock.acquire().addCallback(self._incr)
1706         self.failUnless(lock.locked)
1707         self.assertEqual(self.counter, 2)
1708
1709         controlDeferred.callback(secondUnique)
1710         self.assertEqual(self.result, secondUnique)
1711         self.failUnless(lock.locked)
1712         self.assertEqual(self.counter, 3)
1713
1714         d = lock.acquire().addBoth(lambda x: setattr(self, 'result', x))
1715         d.cancel()
1716         self.assertEqual(self.result.type, defer.CancelledError)
1717
1718         lock.release()
1719         self.failIf(lock.locked)
1720
1721
1722     def test_cancelLockAfterAcquired(self):
1723         """
1724         When canceling a L{Deferred} from a L{DeferredLock} that already
1725         has the lock, the cancel should have no effect.
1726         """
1727         def _failOnErrback(_):
1728             self.fail("Unexpected errback call!")
1729         lock = defer.DeferredLock()
1730         d = lock.acquire()
1731         d.addErrback(_failOnErrback)
1732         d.cancel()
1733
1734
1735     def test_cancelLockBeforeAcquired(self):
1736         """
1737         When canceling a L{Deferred} from a L{DeferredLock} that does not
1738         yet have the lock (i.e., the L{Deferred} has not fired), the cancel
1739         should cause a L{defer.CancelledError} failure.
1740         """
1741         lock = defer.DeferredLock()
1742         lock.acquire()
1743         d = lock.acquire()
1744         self.assertFailure(d, defer.CancelledError)
1745         d.cancel()
1746
1747
1748     def testSemaphore(self):
1749         N = 13
1750         sem = defer.DeferredSemaphore(N)
1751
1752         controlDeferred = defer.Deferred()
1753         def helper(self, arg):
1754             self.arg = arg
1755             return controlDeferred
1756
1757         results = []
1758         uniqueObject = object()
1759         resultDeferred = sem.run(helper, self=self, arg=uniqueObject)
1760         resultDeferred.addCallback(results.append)
1761         resultDeferred.addCallback(self._incr)
1762         self.assertEqual(results, [])
1763         self.assertEqual(self.arg, uniqueObject)
1764         controlDeferred.callback(None)
1765         self.assertEqual(results.pop(), None)
1766         self.assertEqual(self.counter, 1)
1767
1768         self.counter = 0
1769         for i in range(1, 1 + N):
1770             sem.acquire().addCallback(self._incr)
1771             self.assertEqual(self.counter, i)
1772
1773
1774         success = []
1775         def fail(r):
1776             success.append(False)
1777         def succeed(r):
1778             success.append(True)
1779         d = sem.acquire().addCallbacks(fail, succeed)
1780         d.cancel()
1781         self.assertEqual(success, [True])
1782
1783         sem.acquire().addCallback(self._incr)
1784         self.assertEqual(self.counter, N)
1785
1786         sem.release()
1787         self.assertEqual(self.counter, N + 1)
1788
1789         for i in range(1, 1 + N):
1790             sem.release()
1791             self.assertEqual(self.counter, N + 1)
1792
1793
1794     def test_semaphoreInvalidTokens(self):
1795         """
1796         If the token count passed to L{DeferredSemaphore} is less than one
1797         then L{ValueError} is raised.
1798         """
1799         self.assertRaises(ValueError, defer.DeferredSemaphore, 0)
1800         self.assertRaises(ValueError, defer.DeferredSemaphore, -1)
1801
1802
1803     def test_cancelSemaphoreAfterAcquired(self):
1804         """
1805         When canceling a L{Deferred} from a L{DeferredSemaphore} that
1806         already has the semaphore, the cancel should have no effect.
1807         """
1808         def _failOnErrback(_):
1809             self.fail("Unexpected errback call!")
1810
1811         sem = defer.DeferredSemaphore(1)
1812         d = sem.acquire()
1813         d.addErrback(_failOnErrback)
1814         d.cancel()
1815
1816
1817     def test_cancelSemaphoreBeforeAcquired(self):
1818         """
1819         When canceling a L{Deferred} from a L{DeferredSemaphore} that does
1820         not yet have the semaphore (i.e., the L{Deferred} has not fired),
1821         the cancel should cause a L{defer.CancelledError} failure.
1822         """
1823         sem = defer.DeferredSemaphore(1)
1824         sem.acquire()
1825         d = sem.acquire()
1826         self.assertFailure(d, defer.CancelledError)
1827         d.cancel()
1828         return d
1829
1830
1831     def testQueue(self):
1832         N, M = 2, 2
1833         queue = defer.DeferredQueue(N, M)
1834
1835         gotten = []
1836
1837         for i in range(M):
1838             queue.get().addCallback(gotten.append)
1839         self.assertRaises(defer.QueueUnderflow, queue.get)
1840
1841         for i in range(M):
1842             queue.put(i)
1843             self.assertEqual(gotten, range(i + 1))
1844         for i in range(N):
1845             queue.put(N + i)
1846             self.assertEqual(gotten, range(M))
1847         self.assertRaises(defer.QueueOverflow, queue.put, None)
1848
1849         gotten = []
1850         for i in range(N):
1851             queue.get().addCallback(gotten.append)
1852             self.assertEqual(gotten, range(N, N + i + 1))
1853
1854         queue = defer.DeferredQueue()
1855         gotten = []
1856         for i in range(N):
1857             queue.get().addCallback(gotten.append)
1858         for i in range(N):
1859             queue.put(i)
1860         self.assertEqual(gotten, range(N))
1861
1862         queue = defer.DeferredQueue(size=0)
1863         self.assertRaises(defer.QueueOverflow, queue.put, None)
1864
1865         queue = defer.DeferredQueue(backlog=0)
1866         self.assertRaises(defer.QueueUnderflow, queue.get)
1867
1868
1869     def test_cancelQueueAfterSynchronousGet(self):
1870         """
1871         When canceling a L{Deferred} from a L{DeferredQueue} that already has
1872         a result, the cancel should have no effect.
1873         """
1874         def _failOnErrback(_):
1875             self.fail("Unexpected errback call!")
1876
1877         queue = defer.DeferredQueue()
1878         d = queue.get()
1879         d.addErrback(_failOnErrback)
1880         queue.put(None)
1881         d.cancel()
1882
1883
1884     def test_cancelQueueAfterGet(self):
1885         """
1886         When canceling a L{Deferred} from a L{DeferredQueue} that does not
1887         have a result (i.e., the L{Deferred} has not fired), the cancel
1888         causes a L{defer.CancelledError} failure. If the queue has a result
1889         later on, it doesn't try to fire the deferred.
1890         """
1891         queue = defer.DeferredQueue()
1892         d = queue.get()
1893         self.assertFailure(d, defer.CancelledError)
1894         d.cancel()
1895         def cb(ignore):
1896             # If the deferred is still linked with the deferred queue, it will
1897             # fail with an AlreadyCalledError
1898             queue.put(None)
1899             return queue.get().addCallback(self.assertIdentical, None)
1900         return d.addCallback(cb)
1901
1902
1903
1904 class DeferredFilesystemLockTestCase(unittest.TestCase):
1905     """
1906     Test the behavior of L{DeferredFilesystemLock}
1907     """
1908     def setUp(self):
1909         self.clock = Clock()
1910         self.lock = defer.DeferredFilesystemLock(self.mktemp(),
1911                                                  scheduler=self.clock)
1912
1913
1914     def test_waitUntilLockedWithNoLock(self):
1915         """
1916         Test that the lock can be acquired when no lock is held
1917         """
1918         d = self.lock.deferUntilLocked(timeout=1)
1919
1920         return d
1921
1922
1923     def test_waitUntilLockedWithTimeoutLocked(self):
1924         """
1925         Test that the lock can not be acquired when the lock is held
1926         for longer than the timeout.
1927         """
1928         self.failUnless(self.lock.lock())
1929
1930         d = self.lock.deferUntilLocked(timeout=5.5)
1931         self.assertFailure(d, defer.TimeoutError)
1932
1933         self.clock.pump([1] * 10)
1934
1935         return d
1936
1937
1938     def test_waitUntilLockedWithTimeoutUnlocked(self):
1939         """
1940         Test that a lock can be acquired while a lock is held
1941         but the lock is unlocked before our timeout.
1942         """
1943         def onTimeout(f):
1944             f.trap(defer.TimeoutError)
1945             self.fail("Should not have timed out")
1946
1947         self.failUnless(self.lock.lock())
1948
1949         self.clock.callLater(1, self.lock.unlock)
1950         d = self.lock.deferUntilLocked(timeout=10)
1951         d.addErrback(onTimeout)
1952
1953         self.clock.pump([1] * 10)
1954
1955         return d
1956
1957
1958     def test_defaultScheduler(self):
1959         """
1960         Test that the default scheduler is set up properly.
1961         """
1962         lock = defer.DeferredFilesystemLock(self.mktemp())
1963
1964         self.assertEqual(lock._scheduler, reactor)
1965
1966
1967     def test_concurrentUsage(self):
1968         """
1969         Test that an appropriate exception is raised when attempting
1970         to use deferUntilLocked concurrently.
1971         """
1972         self.lock.lock()
1973         self.clock.callLater(1, self.lock.unlock)
1974
1975         d = self.lock.deferUntilLocked()
1976         d2 = self.lock.deferUntilLocked()
1977
1978         self.assertFailure(d2, defer.AlreadyTryingToLockError)
1979
1980         self.clock.advance(1)
1981
1982         return d
1983
1984
1985     def test_multipleUsages(self):
1986         """
1987         Test that a DeferredFilesystemLock can be used multiple times
1988         """
1989         def lockAquired(ign):
1990             self.lock.unlock()
1991             d = self.lock.deferUntilLocked()
1992             return d
1993
1994         self.lock.lock()
1995         self.clock.callLater(1, self.lock.unlock)
1996
1997         d = self.lock.deferUntilLocked()
1998         d.addCallback(lockAquired)
1999
2000         self.clock.advance(1)
2001
2002         return d