jenkins-bot has submitted this change. ( https://gerrit.wikimedia.org/r/c/pywikibot/core/+/1033192?usp=email )
Change subject: [fix] show the right docstring with tools.deprecated ......................................................................
[fix] show the right docstring with tools.deprecated
Previously the docstring of the outer wrapper of add_full_name decorator was shown as the docstring of deprecated function. Now remove the add_full_name when Sphinx is running.
Use the same technique with allow_asynchronous decorator.
Bug: T365286 Change-Id: I292bb7a3dc7a2804a77ce84dcf228848fc3239a4 --- M pywikibot/page/_decorators.py M pywikibot/tools/_deprecate.py 2 files changed, 24 insertions(+), 21 deletions(-)
Approvals: jenkins-bot: Verified Xqt: Looks good to me, approved
diff --git a/pywikibot/page/_decorators.py b/pywikibot/page/_decorators.py index 9108cc8..38c2d1f 100644 --- a/pywikibot/page/_decorators.py +++ b/pywikibot/page/_decorators.py @@ -1,6 +1,6 @@ """Decorators for Page objects.""" # -# (C) Pywikibot team, 2017-2022 +# (C) Pywikibot team, 2017-2024 # # Distributed under the terms of the MIT license. # @@ -12,20 +12,17 @@ OtherPageSaveError, PageSaveRelatedError, ) -from pywikibot.tools import add_full_name, manage_wrapping +from pywikibot.tools import SPHINX_RUNNING, add_full_name, manage_wrapping
-# decorating this function leads sphinx to hide it -def _allow_asynchronous(func): - """ - Decorator to make it possible to run a BasePage method asynchronously. +def allow_asynchronous(func): + """Decorator to make it possible to run a BasePage method asynchronously.
- This is done when the method is called with kwarg asynchronous=True. - Optionally, you can also provide kwarg callback, which, if provided, is - a callable that gets the page as the first and a possible exception that - occurred during saving in the second thread or None as the second argument. - - :meta public: + This is done when the method is called with kwarg + :code:`asynchronous=True`. Optionally, you can also provide kwarg + callback, which, if provided, is a callable that gets the page as + the first and a possible exception that occurred during saving in + the second thread or None as the second argument. """ def handle(func, self, *args, **kwargs): do_async = kwargs.pop('asynchronous', False) @@ -59,5 +56,6 @@ return wrapper
-#: `_allow_asynchronous` decorated with :func:`tools.add_full_name` -allow_asynchronous = add_full_name(_allow_asynchronous) +if not SPHINX_RUNNING: + # T365286: decorate allow_asynchronous function with add_full_name + allow_asynchronous = add_full_name(allow_asynchronous) diff --git a/pywikibot/tools/_deprecate.py b/pywikibot/tools/_deprecate.py index 58409ac..d8c56d3 100644 --- a/pywikibot/tools/_deprecate.py +++ b/pywikibot/tools/_deprecate.py @@ -36,6 +36,8 @@ from typing import Any from warnings import warn
+from pywikibot.tools import SPHINX_RUNNING +
class _NotImplementedWarning(RuntimeWarning):
@@ -211,20 +213,18 @@ warn(msg.format(name, instead), warning_class, depth + 1)
-@add_full_name def deprecated(*args, **kwargs): """Decorator to output a deprecation warning.
.. versionchanged:: 7.0 `since` keyword must be a release number, not a timestamp.
- :keyword instead: if provided, will be used to specify the replacement - :type instead: str - :keyword since: a version string string when the method was deprecated - :type since: str - :keyword future_warning: if True a FutureWarning will be thrown, + :keyword str instead: if provided, will be used to specify the + replacement + :keyword str since: a version string string when the method was + deprecated + :keyword bool future_warning: if True a FutureWarning will be thrown, otherwise it provides a DeprecationWarning - :type future_warning: bool """ def decorator(obj): """Outer wrapper. @@ -304,6 +304,11 @@ return decorator
+if not SPHINX_RUNNING: + # T365286: decorate deprecated function with add_full_name + deprecated = add_full_name(deprecated) + + def deprecate_arg(old_arg: str, new_arg: str | bool | None): """Decorator to declare old_arg deprecated and replace it with new_arg.