jenkins-bot has submitted this change and it was merged.
Change subject: Set __signature__ in decorators ......................................................................
Set __signature__ in decorators
PEP 362 introduces __signature__ for functions as a way to alter function arguments in a decorator in a way that can be reliably inspected. It is first implemented in Python 3.3, but not complete until Python 3.4, which includes inspect.unwrap. Back ports are available, and should be used before __signature__ is relied upon.
Sphinx 1.3 on Python 3.4 uses the inspect module to automatically describe function arguments, allowing documentation to be accurate even in the presence of decorators.
deprecated_args updates the signature to include the deprecated arguments, either providing a note in the default value, or a default of NotImplemented if there is no substitute argument.
Change-Id: I2aeef8c8f31cdb01f18e199834b2f1a8ef8b043c --- M pywikibot/site.py M pywikibot/tools.py 2 files changed, 39 insertions(+), 1 deletion(-)
Approvals: John Vandenberg: Looks good to me, but someone else must approve XZise: Looks good to me, approved jenkins-bot: Verified
diff --git a/pywikibot/site.py b/pywikibot/site.py index 1e6e614..2a55df6 100644 --- a/pywikibot/site.py +++ b/pywikibot/site.py @@ -30,7 +30,7 @@ from pywikibot.tools import ( itergroup, deprecated, deprecate_arg, UnicodeMixin, ComparableMixin, redirect_func, add_decorated_full_name, deprecated_args, - SelfCallDict, SelfCallString, + SelfCallDict, SelfCallString, signature, ) from pywikibot.tools import MediaWikiVersion as LV from pywikibot.throttle import Throttle @@ -973,6 +973,7 @@ if not hasattr(fn, '__full_name__'): add_decorated_full_name(fn) callee.__full_name__ = fn.__full_name__ + callee.__signature__ = signature(fn) return callee
return decorator @@ -1001,6 +1002,7 @@ callee.__name__ = fn.__name__ callee.__doc__ = fn.__doc__ callee.__module__ = fn.__module__ + callee.__signature__ = signature(fn) if not hasattr(fn, '__full_name__'): add_decorated_full_name(fn) callee.__full_name__ = fn.__full_name__ diff --git a/pywikibot/tools.py b/pywikibot/tools.py index d71ad8a..d34291d 100644 --- a/pywikibot/tools.py +++ b/pywikibot/tools.py @@ -457,6 +457,26 @@ # a deprecator without any arguments.
+def signature(obj): + """ + Safely return function Signature object (PEP 362). + + inspect.signature was introduced in 3.3, however backports are available. + In Python 3.3, it does not support all types of callables, and should + not be relied upon. Python 3.4 works correctly. + + Any exception calling inspect.signature is ignored and None is returned. + + @param obj: Function to inspect + @rtype obj: callable + @rtype: inpect.Signature or None + """ + try: + return inspect.signature(obj) + except (AttributeError, ValueError): + return None + + def add_decorated_full_name(obj): """Extract full object name, including class, and store in __full_name__.
@@ -527,6 +547,7 @@ inner_wrapper.__doc__ = obj.__doc__ inner_wrapper.__name__ = obj.__name__ inner_wrapper.__module__ = obj.__module__ + inner_wrapper.__signature__ = signature(obj)
# The decorator being decorated may have args, so both # syntax need to be supported. @@ -581,6 +602,7 @@ wrapper.__doc__ = obj.__doc__ wrapper.__name__ = obj.__name__ wrapper.__module__ = obj.__module__ + wrapper.__signature__ = signature(obj) return wrapper
without_parameters = len(args) == 1 and len(kwargs) == 0 and callable(args[0]) @@ -662,6 +684,20 @@ wrapper.__doc__ = obj.__doc__ wrapper.__name__ = obj.__name__ wrapper.__module__ = obj.__module__ + wrapper.__signature__ = signature(obj) + if wrapper.__signature__: + # Build a new signature with deprecated args added. + params = collections.OrderedDict() + for param in wrapper.__signature__.parameters.values(): + params[param.name] = param.replace() + for old_arg, new_arg in arg_pairs.items(): + params[old_arg] = inspect.Parameter( + old_arg, kind=inspect._POSITIONAL_OR_KEYWORD, + default='[deprecated name of ' + new_arg + ']' + if new_arg not in [True, False, None] + else NotImplemented) + wrapper.__signature__ = inspect.Signature() + wrapper.__signature__._parameters = params if not hasattr(obj, '__full_name__'): add_decorated_full_name(obj) wrapper.__full_name__ = obj.__full_name__