def test_failsWithIncorrectDeprecation(self):
"""
callDeprecated raises a test failure if the callable was deprecated
at a different version to the one expected.
"""
differentVersion = Version('Foo', 1, 2, 3)
exception = self.assertRaises(self.failureException,
self.callDeprecated, differentVersion,
oldMethod, 'foo')
self.assertIn(getVersionString(self.version), str(exception))
self.assertIn(getVersionString(differentVersion), str(exception))
def test_failsWithIncorrectDeprecation(self):
"""
callDeprecated raises a test failure if the callable was deprecated
at a different version to the one expected.
"""
differentVersion = Version('Foo', 1, 2, 3)
exception = self.assertRaises(
self.failureException,
self.callDeprecated,
differentVersion, oldMethod, 'foo')
self.assertIn(getVersionString(self.version), str(exception))
self.assertIn(getVersionString(differentVersion), str(exception))
def _getDeprecationWarningString(fqpn, version, format=None, replacement=None):
"""
Return a string indicating that the Python name was deprecated in the given
version.
@param fqpn: Fully qualified Python name of the thing being deprecated
@type fqpn: C{str}
@param version: Version that C{fqpn} was deprecated in.
@type version: L{incremental.Version}
@param format: A user-provided format to interpolate warning values into, or
L{DEPRECATION_WARNING_FORMAT
<twisted.python.deprecate.DEPRECATION_WARNING_FORMAT>} if L{None} is
given.
@type format: C{str}
@param replacement: what should be used in place of C{fqpn}. Either pass in
a string, which will be inserted into the warning message, or a
callable, which will be expanded to its full import path.
@type replacement: C{str} or callable
@return: A textual description of the deprecation
@rtype: C{str}
"""
if format is None:
format = DEPRECATION_WARNING_FORMAT
warningString = format % {
'fqpn': fqpn,
'version': getVersionString(version)}
if replacement:
warningString = "%s; %s" % (
warningString, _getReplacementString(replacement))
return warningString
def wrapper(wrappee: _Tc) -> _Tc:
warningString = _getDeprecationWarningString(
'The %r parameter to %s' % (name, _fullyQualifiedName(wrappee)),
version,
replacement=replacement)
doc = 'The %r parameter was deprecated in %s' % (
name, getVersionString(version))
if replacement:
doc = doc + '; ' + _getReplacementString(replacement)
doc += '.'
params = inspect.signature(wrappee).parameters
if name in params and \
params[name].kind == inspect.Parameter.POSITIONAL_OR_KEYWORD:
parameterIndex = list(params).index(name)
def checkDeprecatedParameter(*args, **kwargs):
if len(args) > parameterIndex or name in kwargs:
warn(warningString, DeprecationWarning, stacklevel=2)
return wrappee(*args, **kwargs)
else:
def checkDeprecatedParameter(*args, **kwargs):
if name in kwargs:
warn(warningString, DeprecationWarning, stacklevel=2)
return wrappee(*args, **kwargs)
decorated = typing.cast(_Tc, wraps(wrappee)(checkDeprecatedParameter))
_appendToDocstring(decorated, doc)
return decorated
def test_getVersionStringWithPost(self):
"""
L{getVersionString} includes the postrelease, if any.
"""
self.assertEqual(
getVersionString(Version("whatever", 8, 0, 0, post=1)),
"whatever 8.0.0post1")
def test_getVersionString(self):
"""
L{getVersionString} returns a string with the package name and the
short version number.
"""
self.assertEqual(
'Twisted 8.0.0', getVersionString(Version('Twisted', 8, 0, 0)))
def wrapper(wrappee: _Tc) -> _Tc:
warningString = _getDeprecationWarningString(
f"The {name!r} parameter to {_fullyQualifiedName(wrappee)}",
version,
replacement=replacement,
)
doc = "The {!r} parameter was deprecated in {}".format(
name,
getVersionString(version),
)
if replacement:
doc = doc + "; " + _getReplacementString(replacement)
doc += "."
params = inspect.signature(wrappee).parameters
if (name in params and params[name].kind
== inspect.Parameter.POSITIONAL_OR_KEYWORD):
parameterIndex = list(params).index(name)
def checkDeprecatedParameter(*args, **kwargs):
if len(args) > parameterIndex or name in kwargs:
warn(warningString, DeprecationWarning, stacklevel=2)
return wrappee(*args, **kwargs)
else:
def checkDeprecatedParameter(*args, **kwargs):
if name in kwargs:
warn(warningString, DeprecationWarning, stacklevel=2)
return wrappee(*args, **kwargs)
decorated = cast(_Tc, wraps(wrappee)(checkDeprecatedParameter))
_appendToDocstring(decorated, doc)
return decorated
def test_getVersionString(self):
"""
L{getVersionString} returns a string with the package name and the
short version number.
"""
self.assertEqual('Twisted 8.0.0',
getVersionString(Version('Twisted', 8, 0, 0)))
def _getDeprecationWarningString(fqpn, version, format=None, replacement=None):
"""
Return a string indicating that the Python name was deprecated in the given
version.
@param fqpn: Fully qualified Python name of the thing being deprecated
@type fqpn: C{str}
@param version: Version that C{fqpn} was deprecated in.
@type version: L{incremental.Version}
@param format: A user-provided format to interpolate warning values into, or
L{DEPRECATION_WARNING_FORMAT
<twisted.python.deprecate.DEPRECATION_WARNING_FORMAT>} if L{None} is
given.
@type format: C{str}
@param replacement: what should be used in place of C{fqpn}. Either pass in
a string, which will be inserted into the warning message, or a
callable, which will be expanded to its full import path.
@type replacement: C{str} or callable
@return: A textual description of the deprecation
@rtype: C{str}
"""
if format is None:
format = DEPRECATION_WARNING_FORMAT
warningString = format % {
"fqpn": fqpn,
"version": getVersionString(version)
}
if replacement:
warningString = "{}; {}".format(warningString,
_getReplacementString(replacement))
return warningString
def test_getVersionStringWithDevAndPost(self):
"""
L{getVersionString} includes the dev release and postrelease, if
any.
"""
self.assertEqual(
getVersionString(Version("whatever", 8, 0, 0, post=2, dev=1)),
"whatever 8.0.0post2dev1")
def test_getVersionStringWithReleaseCandidate(self):
"""
L{getVersionString} includes the release candidate, if any.
"""
self.assertEqual(
getVersionString(Version("whatever", 8, 0, 0,
release_candidate=1)),
"whatever 8.0.0rc1")
def test_getVersionStringWithDevAndRC(self):
"""
L{getVersionString} includes the dev release and release candidate, if
any.
"""
self.assertEqual(
getVersionString(Version("whatever", 8, 0, 0, release_candidate=2, dev=1)), "whatever 8.0.0rc2dev1"
)
def test_getVersionStringWithDev(self):
"""
L{getVersionString} includes the dev release, if any.
"""
self.assertEqual(
getVersionString(Version("whatever", 8, 0, 0,
dev=1)),
"whatever 8.0.0dev1")
def test_getVersionStringWithReleaseCandidate(self):
"""
L{getVersionString} includes the release candidate, if any.
"""
self.assertEqual(
getVersionString(Version("whatever", 8, 0, 0,
release_candidate=1)),
"whatever 8.0.0rc1")
def test_getVersionStringWithPrerelease(self):
"""
L{getVersionString} includes the prerelease as a release candidate, if
any.
"""
self.assertEqual(
getVersionString(Version("whatever", 8, 0, 0, prerelease=1)),
"whatever 8.0.0.rc1",
)
def test_getVersionStringWithRevision(self):
"""
L{getVersionString} includes the discovered revision number.
"""
self.svnEntries.child("format").setContent(b"9\n")
self.svnEntries.child("entries").setContent(VERSION_10_ENTRIES)
version = getVersionString(self.getVersion())
self.assertEqual("incremental_test_package 1.0.0+r22715", version)
self.assertTrue(isinstance(version, type("")))
def test_getVersionStringWithDevAndRC(self):
"""
L{getVersionString} includes the dev release and release candidate, if
any.
"""
self.assertEqual(
getVersionString(
Version("whatever", 8, 0, 0, release_candidate=2, dev=1)),
"whatever 8.0.0rc2dev1")
def test_getVersionStringWithRevision(self):
"""
L{getVersionString} includes the discovered revision number.
"""
self.svnEntries.child("format").setContent(b"9\n")
self.svnEntries.child("entries").setContent(VERSION_10_ENTRIES)
version = getVersionString(self.getVersion())
self.assertEqual("incremental_test_package 1.0.0+r22715", version)
self.assertTrue(isinstance(version, type("")))
def test_callDeprecationWithWrongMessage(self):
"""
If the message passed to L{callDeprecated} doesn't match,
L{callDeprecated} raises a test failure.
"""
exception = self.assertRaises(self.failureException,
self.callDeprecated,
(self.version, "something.wrong"),
oldMethodReplaced, 1)
self.assertIn(getVersionString(self.version), str(exception))
self.assertIn("please use newMethod instead", str(exception))
def test_callDeprecationWithWrongMessage(self):
"""
If the message passed to L{callDeprecated} doesn't match,
L{callDeprecated} raises a test failure.
"""
exception = self.assertRaises(
self.failureException,
self.callDeprecated,
(self.version, "something.wrong"),
oldMethodReplaced, 1)
self.assertIn(getVersionString(self.version), str(exception))
self.assertIn("please use newMethod instead", str(exception))
def _getDeprecationDocstring(version, replacement=None):
"""
Generate an addition to a deprecated object's docstring that explains its
deprecation.
@param version: the version it was deprecated.
@type version: L{incremental.Version}
@param replacement: The replacement, if specified.
@type replacement: C{str} or callable
@return: a string like "Deprecated in Twisted 27.2.0; please use
twisted.timestream.tachyon.flux instead."
"""
doc = "Deprecated in {}".format(getVersionString(version))
if replacement:
doc = "{}; {}".format(doc, _getReplacementString(replacement))
return doc + "."
def _getDeprecationDocstring(version, replacement=None):
"""
Generate an addition to a deprecated object's docstring that explains its
deprecation.
@param version: the version it was deprecated.
@type version: L{incremental.Version}
@param replacement: The replacement, if specified.
@type replacement: C{str} or callable
@return: a string like "Deprecated in Twisted 27.2.0; please use
twisted.timestream.tachyon.flux instead."
"""
doc = "Deprecated in %s" % (getVersionString(version),)
if replacement:
doc = "%s; %s" % (doc, _getReplacementString(replacement))
return doc + "."
def test_getVersionStringWithDev(self):
"""
L{getVersionString} includes the dev release, if any.
"""
self.assertEqual(getVersionString(Version("whatever", 8, 0, 0, dev=1)),
"whatever 8.0.0dev1")