jenkins-bot submitted this change.
[cleanup] drop bool values of deprecate_arg and deprecated_args
bool values and None values were implemented to throw a
DeprecationWarning, PendingDeprecationWarning or FutureWarning but we
only used the later since years and never used the
PendingDeprecationWarning. Also update tests and backport types.NoneType.
Change-Id: I10ca6346525e71998d839e696b5e088242c76600
---
M pywikibot/backports.py
M pywikibot/tools/_deprecate.py
M tests/tools_deprecate_tests.py
3 files changed, 44 insertions(+), 32 deletions(-)
diff --git a/pywikibot/backports.py b/pywikibot/backports.py
index 8b9d989..815f7d3 100644
--- a/pywikibot/backports.py
+++ b/pywikibot/backports.py
@@ -116,10 +116,12 @@
removesuffix = str.removesuffix # type: ignore[assignment]
-# bpo-38200
if PYTHON_VERSION < (3, 10) or SPHINX_RUNNING:
from itertools import tee
+ NoneType = type(None)
+
+ # bpo-38200
def pairwise(iterable):
"""Return successive overlapping pairs taken from the input iterable.
@@ -132,6 +134,7 @@
next(b, None)
return zip(a, b)
else:
+ from types import NoneType
from itertools import pairwise # type: ignore[no-redef]
diff --git a/pywikibot/tools/_deprecate.py b/pywikibot/tools/_deprecate.py
index 9bbc133..571aad1 100644
--- a/pywikibot/tools/_deprecate.py
+++ b/pywikibot/tools/_deprecate.py
@@ -19,7 +19,7 @@
deprecation decorators moved to _deprecate submodule
"""
#
-# (C) Pywikibot team, 2008-2023
+# (C) Pywikibot team, 2008-2024
#
# Distributed under the terms of the MIT license.
#
@@ -36,6 +36,7 @@
from typing import Any
from warnings import warn
+from pywikibot.backports import NoneType
from pywikibot.tools import SPHINX_RUNNING
@@ -309,10 +310,12 @@
deprecated = add_full_name(deprecated)
-def deprecate_arg(old_arg: str, new_arg: str | bool | None):
+def deprecate_arg(old_arg: str, new_arg: str | None = None):
"""Decorator to declare old_arg deprecated and replace it with new_arg.
- Usage:
+ **Usage:**
+
+ .. code-block:: python
@deprecate_arg('foo', 'bar')
def my_function(bar='baz'): pass
@@ -323,9 +326,12 @@
# ignores 'foo' keyword no longer used by my_function
:func:`deprecated_args` decorator should be used in favour of this
- ``deprecate_arg`` decorator but it is held to deprecate args which
- become a reserved word in future Python releases and to prevent
- syntax errors.
+ ``deprecate_arg`` decorator but it is held to deprecate args of
+ reserved words even for future Python releases and to prevent syntax
+ errors.
+
+ .. versionchanged:: 9.2
+ bool type of *new_arg* is no longer supported.
:param old_arg: old keyword
:param new_arg: new keyword
@@ -333,21 +339,29 @@
return deprecated_args(**{old_arg: new_arg})
-def deprecated_args(**arg_pairs):
+def deprecated_args(**arg_pairs: str | None):
"""Decorator to declare multiple args deprecated.
- Usage:
+ **Usage:**
+
+ .. code-block:: python
@deprecated_args(foo='bar', baz=None)
def my_function(bar='baz'): pass
# replaces 'foo' keyword by 'bar' and ignores 'baz' keyword
+ .. versionchanged:: 3.0.20200703
+ show a FutureWarning if the *arg_pairs* value is True; don't show
+ a warning if the value is an empty string.
+ .. versionchanged:: 6.4
+ show a FutureWarning for renamed arguments
+ .. versionchanged:: 9.2
+ bool type argument is no longer supported.
+
:param arg_pairs: Each entry points to the new argument name. If an
- argument is to be removed, the value may be one of the following:
- - None: shows a DeprecationWarning
- - False: shows a PendingDeprecationWarning
- - True: shows a FutureWarning (only once)
- - empty string: no warning is printed
+ argument is to be removed, the value may be either an empty str
+ or ``None``; the later also shows a `FutureWarning` once.
+ :raises TypeError: *arg_pairs* value is neither str nor None or
"""
def decorator(obj):
"""Outer wrapper.
@@ -376,15 +390,18 @@
if old_arg not in __kw:
continue
- if new_arg not in [True, False, None, '']:
+ if not isinstance(new_arg, (str, NoneType)):
+ raise TypeError(
+ f'deprecated_arg value for {old_arg} of {name} must '
+ f'be either str or None, not {type(new_arg).__name__}')
+
+ if new_arg:
if new_arg in __kw:
warn('{new_arg} argument of {name} '
'replaces {old_arg}; cannot use both.'
.format_map(output_args),
RuntimeWarning, depth)
else:
- # If the value is positionally given this will
- # cause a TypeError, which is intentional
warn('{old_arg} argument of {name} '
'is deprecated; use {new_arg} instead.'
.format_map(output_args),
@@ -393,15 +410,9 @@
elif new_arg == '':
pass
else:
- if new_arg is False:
- cls = PendingDeprecationWarning
- elif new_arg is True:
- cls = FutureWarning
- else: # new_arg is None
- cls = DeprecationWarning
warn('{old_arg} argument of {name} is deprecated.'
.format_map(output_args),
- cls, depth)
+ FutureWarning, depth)
del __kw[old_arg]
return obj(*__args, **__kw)
diff --git a/tests/tools_deprecate_tests.py b/tests/tools_deprecate_tests.py
index fd5cc21..c4a6895 100755
--- a/tests/tools_deprecate_tests.py
+++ b/tests/tools_deprecate_tests.py
@@ -135,7 +135,7 @@
return foo
-@deprecated_args(bah='foo', silent=False, loud=True, old=None)
+@deprecated_args(bah='foo', silent=None, loud=None, old='')
def deprecated_func_arg3(foo=None):
"""Test deprecated_args with three drops and one rename."""
return foo
@@ -459,6 +459,7 @@
def test_deprecate_and_remove_function_args(self):
"""Test @deprecated and removed function argument."""
+ deprecation_msg = f' argument of {__name__ }.deprecated_func_arg3'
rv = deprecated_func_arg3()
self.assertIsNone(rv)
self.assertNoDeprecation()
@@ -469,19 +470,16 @@
rv = deprecated_func_arg3(foo=1, silent=42)
self.assertEqual(rv, 1)
- self.assertDeprecationClass(PendingDeprecationWarning)
- self.assertOneDeprecationParts(
- 'silent argument of ' + __name__ + '.deprecated_func_arg3')
+ self.assertDeprecationClass(FutureWarning)
+ self.assertOneDeprecationParts('silent' + deprecation_msg)
rv = deprecated_func_arg3(3, loud='3')
self.assertEqual(rv, 3)
- self.assertOneDeprecationParts(
- 'loud argument of ' + __name__ + '.deprecated_func_arg3')
+ self.assertOneDeprecationParts('loud' + deprecation_msg)
rv = deprecated_func_arg3(4, old='4')
self.assertEqual(rv, 4)
- self.assertOneDeprecationParts(
- 'old argument of ' + __name__ + '.deprecated_func_arg3')
+ self.assertNoDeprecation()
def test_function_remove_last_args(self):
"""Test @remove_last_args on functions."""
To view, visit change 1033038. To unsubscribe, or for help writing mail filters, visit settings.