Add sphinx.util.inspect:signature_from_str()

sphinx/util/inspect.py

@@ -8,6 +8,7 @@
     :license: BSD, see LICENSE for details.
 """
 
+import ast
 import builtins
 import enum
 import inspect
@@ -16,10 +17,11 @@
 import typing
 from functools import partial, partialmethod
 from inspect import (  # NOQA
-    isclass, ismethod, ismethoddescriptor, isroutine
+    Parameter, isclass, ismethod, ismethoddescriptor, isroutine
 )
 from io import StringIO
 from typing import Any, Callable, Mapping, List, Tuple
+from typing import cast
 
 from sphinx.util import logging
 from sphinx.util.typing import NoneType
@@ -313,6 +315,98 @@ def is_builtin_class_method(obj: Any, attr_name: str) -> bool:
     return getattr(builtins, safe_getattr(cls, '__name__', '')) is cls
 
 
+def ast_unparse(node: ast.AST) -> str:
+    """Unparse an AST to string."""
+    if node is None:
+        return None
+    elif isinstance(node, ast.Attribute):
+        return '%s.%s' % (ast_unparse(node.value), node.attr)
+    elif isinstance(node, ast.Bytes):
+        return repr(node.s)
+    elif isinstance(node, ast.Call):
+        args = ([ast_unparse(e) for e in node.args] +
+                ['%s=%s' % (k.arg, ast_unparse(k.value)) for k in node.keywords])
+        return '%s(%s)' % (ast_unparse(node.func), ', '.join(args))
+    elif isinstance(node, ast.Dict):
+        keys = (ast_unparse(k) for k in node.keys)
+        values = (ast_unparse(v) for v in node.values)
+        items = (k + ': ' + v for k, v in zip(keys, values))
+        return '{' + ', '.join(items) + '}'
+    elif isinstance(node, ast.Ellipsis):
+        return '...'
+    elif sys.version_info > (3, 6) and isinstance(node, ast.Constant):
+        return repr(node.value)
+    elif isinstance(node, ast.Index):
+        return ast_unparse(node.value)
+    elif isinstance(node, ast.Lambda):
+        return '<function <lambda>>'  # TODO
+    elif isinstance(node, ast.List):
+        return '[' + ', '.join(ast_unparse(e) for e in node.elts) + ']'
+    elif isinstance(node, ast.Name):
+        return node.id
+    elif isinstance(node, ast.NameConstant):
+        return repr(node.value)
+    elif isinstance(node, ast.Num):
+        return repr(node.n)
+    elif isinstance(node, ast.Set):
+        return "{" + ', '.join(ast_unparse(e) for e in node.elts) + "}"
+    elif isinstance(node, ast.Str):
+        return repr(node.s)
+    elif isinstance(node, ast.Subscript):
+        return "%s[%s]" % (ast_unparse(node.value), ast_unparse(node.slice))
+    elif isinstance(node, ast.Tuple):
+        return ', '.join(ast_unparse(e) for e in node.elts)
+    else:
+        # TODO: f-string
+        raise NotImplementedError('Unable to render %s instance' % type(node).__name__)
+
+
+def signature_from_str(signature: str) -> inspect.Signature:
+    """Create a Signature object from string."""
+    module = ast.parse('def func' + signature + ': pass')
+    definition = cast(ast.FunctionDef, module.body[0])
+
+    # parameters
+    args = definition.args
+    params = []
+
+    if hasattr(args, "posonlyargs"):  # for py38+
+        for arg in args.posonlyargs:  # type: ignore
+            annotation = ast_unparse(arg.annotation) or Parameter.empty
+            params.append(Parameter(arg.arg, Parameter.POSITIONAL_ONLY,
+                                    annotation=annotation))
+
+    for i, arg in enumerate(args.args):
+        if len(args.args) - i <= len(args.defaults):
+            default = ast_unparse(args.defaults[-len(args.args) + i])
+        else:
+            default = Parameter.empty
+
+        annotation = ast_unparse(arg.annotation) or Parameter.empty
+        params.append(Parameter(arg.arg, Parameter.POSITIONAL_OR_KEYWORD,
+                                default=default, annotation=annotation))
+
+    if args.vararg:
+        annotation = ast_unparse(args.vararg.annotation) or Parameter.empty
+        params.append(Parameter(args.vararg.arg, Parameter.VAR_POSITIONAL,
+                                annotation=annotation))
+
+    for i, arg in enumerate(args.kwonlyargs):
+        default = ast_unparse(args.kw_defaults[i])
+        annotation = ast_unparse(arg.annotation) or Parameter.empty
+        params.append(Parameter(arg.arg, Parameter.KEYWORD_ONLY, default=default,
+                                annotation=annotation))
+
+    if args.kwarg:
+        annotation = ast_unparse(args.kwarg.annotation) or Parameter.empty
+        params.append(Parameter(args.kwarg.arg, Parameter.VAR_KEYWORD,
+                                annotation=annotation))
+
+    return_annotation = ast_unparse(definition.returns) or Parameter.empty
+
+    return inspect.Signature(params, return_annotation=return_annotation)
+
+
 class Signature:
     """The Signature object represents the call signature of a callable object and
     its return annotation.

tests/test_util_inspect.py

@@ -13,6 +13,7 @@
 import functools
 import sys
 import types
+from inspect import Parameter
 
 import pytest
 
@@ -89,6 +90,90 @@ def wrapped_bound_method(*args, **kwargs):
     assert expected_bound == inspect.getargspec(wrapped_bound_method)
 
 
+def test_signature_from_str_basic():
+    signature = '(a, b, *args, c=0, d="blah", **kwargs)'
+    sig = inspect.signature_from_str(signature)
+    assert list(sig.parameters.keys()) == ['a', 'b', 'args', 'c', 'd', 'kwargs']
+    assert sig.parameters['a'].name == 'a'
+    assert sig.parameters['a'].kind == Parameter.POSITIONAL_OR_KEYWORD
+    assert sig.parameters['a'].default == Parameter.empty
+    assert sig.parameters['a'].annotation == Parameter.empty
+    assert sig.parameters['b'].name == 'b'
+    assert sig.parameters['b'].kind == Parameter.POSITIONAL_OR_KEYWORD
+    assert sig.parameters['b'].default == Parameter.empty
+    assert sig.parameters['b'].annotation == Parameter.empty
+    assert sig.parameters['args'].name == 'args'
+    assert sig.parameters['args'].kind == Parameter.VAR_POSITIONAL
+    assert sig.parameters['args'].default == Parameter.empty
+    assert sig.parameters['args'].annotation == Parameter.empty
+    assert sig.parameters['c'].name == 'c'
+    assert sig.parameters['c'].kind == Parameter.KEYWORD_ONLY
+    assert sig.parameters['c'].default == '0'
+    assert sig.parameters['c'].annotation == Parameter.empty
+    assert sig.parameters['d'].name == 'd'
+    assert sig.parameters['d'].kind == Parameter.KEYWORD_ONLY
+    assert sig.parameters['d'].default == "'blah'"
+    assert sig.parameters['d'].annotation == Parameter.empty
+    assert sig.parameters['kwargs'].name == 'kwargs'
+    assert sig.parameters['kwargs'].kind == Parameter.VAR_KEYWORD
+    assert sig.parameters['kwargs'].default == Parameter.empty
+    assert sig.parameters['kwargs'].annotation == Parameter.empty
+    assert sig.return_annotation == Parameter.empty
+
+
+def test_signature_from_str_default_values():
+    signature = ('(a=0, b=0.0, c="str", d=b"bytes", e=..., f=True, '
+                 'g=[1, 2, 3], h={"a": 1}, i={1, 2, 3}, '
+                 'j=lambda x, y: None, k=None, l=object(), m=foo.bar.CONSTANT)')
+    sig = inspect.signature_from_str(signature)
+    assert sig.parameters['a'].default == '0'
+    assert sig.parameters['b'].default == '0.0'
+    assert sig.parameters['c'].default == "'str'"
+    assert sig.parameters['d'].default == "b'bytes'"
+    assert sig.parameters['e'].default == '...'
+    assert sig.parameters['f'].default == 'True'
+    assert sig.parameters['g'].default == '[1, 2, 3]'
+    assert sig.parameters['h'].default == "{'a': 1}"
+    assert sig.parameters['i'].default == '{1, 2, 3}'
+    assert sig.parameters['j'].default == '<function <lambda>>'
+    assert sig.parameters['k'].default == 'None'
+    assert sig.parameters['l'].default == 'object()'
+    assert sig.parameters['m'].default == 'foo.bar.CONSTANT'
+
+
+def test_signature_from_str_annotations():
+    signature = '(a: int, *args: bytes, b: str = "blah", **kwargs: float) -> None'
+    sig = inspect.signature_from_str(signature)
+    assert list(sig.parameters.keys()) == ['a', 'args', 'b', 'kwargs']
+    assert sig.parameters['a'].annotation == "int"
+    assert sig.parameters['args'].annotation == "bytes"
+    assert sig.parameters['b'].annotation == "str"
+    assert sig.parameters['kwargs'].annotation == "float"
+    assert sig.return_annotation == 'None'
+
+
+def test_signature_from_str_complex_annotations():
+    sig = inspect.signature_from_str('() -> Tuple[str, int, ...]')
+    assert sig.return_annotation == 'Tuple[str, int, ...]'
+
+    sig = inspect.signature_from_str('() -> Callable[[int, int], int]')
+    assert sig.return_annotation == 'Callable[[int, int], int]'
+
+
+@pytest.mark.skipif(sys.version_info < (3, 8),
+                    reason='python-3.8 or above is required')
+def test_signature_from_str_positionaly_only_args():
+    sig = inspect.signature_from_str('(a, /, b)')
+    assert list(sig.parameters.keys()) == ['a', 'b']
+    assert sig.parameters['a'].kind == Parameter.POSITIONAL_ONLY
+    assert sig.parameters['b'].kind == Parameter.POSITIONAL_OR_KEYWORD
+
+
+def test_signature_from_str_invalid():
+    with pytest.raises(SyntaxError):
+        inspect.signature_from_str('')
+
+
 def test_Signature():
     # literals
     with pytest.raises(TypeError):