'Call a function that should have been deprecated at a specific version
and in favor of a specific alternative, and assert that it was thusly
deprecated.
@param version: A 2-sequence of (since, replacement), where C{since} is
a the first L{version<incremental.Version>} that C{f}
should have been deprecated since, and C{replacement} is a suggested
replacement for the deprecated functionality, as described by
L{twisted.python.deprecate.deprecated}.  If there is no suggested
replacement, this parameter may also be simply a
L{version<incremental.Version>} by itself.
@param f: The deprecated function to call.
@param args: The arguments to pass to C{f}.
@param kwargs: The keyword arguments to pass to C{f}.
@return: Whatever C{f} returns.
@raise: Whatever C{f} raises.  If any exception is
raised by C{f}, though, no assertions will be made about emitted
deprecations.
@raise FailTest: if no warnings were emitted by C{f}, or if the
L{DeprecationWarning} emitted did not produce the canonical
please-use-something-else message that is standard for Twisted
deprecations according to the given version and replacement.'

def callDeprecated(self, version, f, *args, **kwargs):

    result = f(*args, **kwargs)
    warningsShown = self.flushWarnings([self.callDeprecated])
    try:
        info = list(version)
    except TypeError:
        since = version
        replacement = None
    else:
        [since, replacement] = info
    if (len(warningsShown) == 0):
        self.fail(('%r    is    not    deprecated.' % (f,)))
    observedWarning = warningsShown[0]['message']
    expectedWarning = getDeprecationWarningString(f, since, replacement=replacement)
    self.assertEqual(expectedWarning, observedWarning)
    return result
