jenkins-bot has submitted this change. ( https://gerrit.wikimedia.org/r/c/pywikibot/core/+/1033038?usp=email )

Change subject: [cleanup] drop bool values of deprecate_arg and deprecated_args ......................................................................

[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(-)

Approvals: jenkins-bot: Verified Xqt: Looks good to me, approved

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."""