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.
--
To view, visit
https://gerrit.wikimedia.org/r/c/pywikibot/core/+/1033192?usp=email
To unsubscribe, or for help writing mail filters, visit
https://gerrit.wikimedia.org/r/settings
Gerrit-Project: pywikibot/core
Gerrit-Branch: master
Gerrit-Change-Id: I292bb7a3dc7a2804a77ce84dcf228848fc3239a4
Gerrit-Change-Number: 1033192
Gerrit-PatchSet: 1
Gerrit-Owner: Xqt <[email protected]>
Gerrit-Reviewer: Xqt <[email protected]>
Gerrit-Reviewer: jenkins-bot
Gerrit-MessageType: merged
_______________________________________________
Pywikibot-commits mailing list -- [email protected]
To unsubscribe send an email to [email protected]
