Generate introspection signatures for classes too

Author: brianschubert

mypyc/codegen/emitclass.py

@@ -5,6 +5,7 @@
 from collections.abc import Mapping
 from typing import Callable
 
+from mypyc.codegen.cstring import c_string_initializer
 from mypyc.codegen.emit import Emitter, HeaderDeclaration, ReturnHandler
 from mypyc.codegen.emitfunc import native_function_doc_initializer, native_function_header
 from mypyc.codegen.emitwrapper import (
@@ -21,7 +22,13 @@
 )
 from mypyc.common import BITMAP_BITS, BITMAP_TYPE, NATIVE_PREFIX, PREFIX, REG_PREFIX
 from mypyc.ir.class_ir import ClassIR, VTableEntries
-from mypyc.ir.func_ir import FUNC_CLASSMETHOD, FUNC_STATICMETHOD, FuncDecl, FuncIR
+from mypyc.ir.func_ir import (
+    FUNC_CLASSMETHOD,
+    FUNC_STATICMETHOD,
+    FuncDecl,
+    FuncIR,
+    get_text_signature,
+)
 from mypyc.ir.rtypes import RTuple, RType, object_rprimitive
 from mypyc.namegen import NameGenerator
 from mypyc.sametype import is_same_type
@@ -345,6 +352,8 @@ def emit_line() -> None:
         flags.append("Py_TPFLAGS_MANAGED_DICT")
     fields["tp_flags"] = " | ".join(flags)
 
+    fields["tp_doc"] = native_class_doc_initializer(cl)
+
     emitter.emit_line(f"static PyTypeObject {emitter.type_struct_name(cl)}_template_ = {{")
     emitter.emit_line("PyVarObject_HEAD_INIT(NULL, 0)")
     for field, value in fields.items():
@@ -1100,3 +1109,16 @@ def has_managed_dict(cl: ClassIR, emitter: Emitter) -> bool:
         and cl.has_dict
         and cl.builtin_base != "PyBaseExceptionObject"
     )
+
+
+def native_class_doc_initializer(cl: ClassIR) -> str:
+    init_fn = cl.get_method("__init__")
+    if init_fn is not None:
+        text_sig = get_text_signature(init_fn, bound=True)
+        if text_sig is None:
+            return "NULL"
+        text_sig = text_sig.replace("__init__", cl.name, 1)
+    else:
+        text_sig = f"{cl.name}()"
+    docstring = f"{text_sig}\n--\n\n"
+    return c_string_initializer(docstring.encode("ascii", errors="backslashreplace"))

mypyc/ir/func_ir.py

@@ -406,20 +406,21 @@ def all_values_full(args: list[Register], blocks: list[BasicBlock]) -> list[Valu
 _NOT_REPRESENTABLE = object()
 
 
-def get_text_signature(fn: FuncIR) -> str | None:
+def get_text_signature(fn: FuncIR, *, bound: bool = False) -> str | None:
     """Return a text signature in CPython's internal doc format, or None
     if the function's signature cannot be represented.
     """
     parameters = []
-    mark_self = fn.class_name is not None and fn.decl.kind != FUNC_STATICMETHOD
+    mark_self = fn.class_name is not None and fn.decl.kind != FUNC_STATICMETHOD and not bound
     # Pre-scan for end of positional-only parameters.
     # This is needed to handle signatures like 'def foo(self, __x)', where mypy
     # currently sees 'self' as being positional-or-keyword and '__x' as positional-only.
     pos_only_idx = -1
-    for idx, arg in enumerate(fn.decl.sig.args):
+    sig = fn.decl.bound_sig if bound and fn.decl.bound_sig is not None else fn.decl.sig
+    for idx, arg in enumerate(sig.args):
         if arg.pos_only and arg.kind in (ArgKind.ARG_POS, ArgKind.ARG_OPT):
             pos_only_idx = idx
-    for idx, arg in enumerate(fn.decl.sig.args):
+    for idx, arg in enumerate(sig.args):
         if arg.name.startswith("__bitmap") or arg.name == "__mypyc_self__":
             continue
         kind = (
@@ -440,8 +441,7 @@ def get_text_signature(fn: FuncIR) -> str | None:
             # Parameter.__init__/Parameter.replace do not accept $
             curr_param._name = f"${arg.name}"  # type: ignore[attr-defined]
             mark_self = False
-    sig = inspect.Signature(parameters)
-    return f"{fn.name}{sig}"
+    return f"{fn.name}{inspect.Signature(parameters)}"
 
 
 def _find_default_argument(name: str, blocks: list[BasicBlock]) -> object:

mypyc/test-data/run-signatures.test

@@ -1,6 +1,4 @@
 [case testSignaturesBasic]
-import inspect
-
 def f1(): pass
 def f2(x): pass
 def f3(x, /): pass
@@ -12,21 +10,25 @@ def f8(x=None, /): pass
 def f9(*, x=None): pass
 def f10(a, /, b, c=None, *args, d=None, **h): pass
 
-def test_basic() -> None:
-    assert str(inspect.signature(f1)) == "()"
-    assert str(inspect.signature(f2)) == "(x)"
-    assert str(inspect.signature(f3)) == "(x, /)"
-    assert str(inspect.signature(f4)) == "(*, x)"
-    assert str(inspect.signature(f5)) == "(*x)"
-    assert str(inspect.signature(f6)) == "(**x)"
-    assert str(inspect.signature(f7)) == "(x=None)"
-    assert str(inspect.signature(f8)) == "(x=None, /)"
-    assert str(inspect.signature(f9)) == "(*, x=None)"
-    assert str(inspect.signature(f10)) == "(a, /, b, c=None, *args, d=None, **h)"
-
-[case testSignaturesValidDefaults]
+[file driver.py]
 import inspect
+from native import *
+
+assert str(inspect.signature(f1)) == "()"
+assert str(inspect.signature(f2)) == "(x)"
+assert str(inspect.signature(f3)) == "(x, /)"
+assert str(inspect.signature(f4)) == "(*, x)"
+assert str(inspect.signature(f5)) == "(*x)"
+assert str(inspect.signature(f6)) == "(**x)"
+assert str(inspect.signature(f7)) == "(x=None)"
+assert str(inspect.signature(f8)) == "(x=None, /)"
+assert str(inspect.signature(f9)) == "(*, x=None)"
+assert str(inspect.signature(f10)) == "(a, /, b, c=None, *args, d=None, **h)"
+
+for fn in [f1, f2, f3, f4, f5, f6, f7, f8, f9, f10]:
+    assert getattr(fn, "__doc__") is None
 
+[case testSignaturesValidDefaults]
 def default_int(x=1): pass
 def default_str(x="a"): pass
 def default_float(x=1.0): pass
@@ -37,44 +39,43 @@ def default_tuple_empty(x=()): pass
 def default_tuple_literals(x=(1, "a", 1.0, False, True, None, (), (1,2,(3,4)))): pass
 def default_tuple_singleton(x=(1,)): pass
 
-def test_valid_defaults() -> None:
-    assert str(inspect.signature(default_int)) == "(x=1)"
-    assert str(inspect.signature(default_str)) == "(x='a')"
-    assert str(inspect.signature(default_float)) == "(x=1.0)"
-    assert str(inspect.signature(default_true)) == "(x=True)"
-    assert str(inspect.signature(default_false)) == "(x=False)"
-    assert str(inspect.signature(default_none)) == "(x=None)"
-    assert str(inspect.signature(default_tuple_empty)) == "(x=())"
-    assert str(inspect.signature(default_tuple_literals)) == "(x=(1, 'a', 1.0, False, True, None, (), (1, 2, (3, 4))))"
-
-    # Check __text_signature__ directly since inspect.signature produces
-    # an incorrect signature for 1-tuple default arguments prior to
-    # Python 3.12 (cpython#102379).
-    # assert str(inspect.signature(default_tuple_singleton)) == "(x=(1,))"
-    assert getattr(default_tuple_singleton, "__text_signature__") == "(x=(1,))"
-
-[case testSignaturesStringDefaults]
+[file driver.py]
 import inspect
+from native import *
+
+assert str(inspect.signature(default_int)) == "(x=1)"
+assert str(inspect.signature(default_str)) == "(x='a')"
+assert str(inspect.signature(default_float)) == "(x=1.0)"
+assert str(inspect.signature(default_true)) == "(x=True)"
+assert str(inspect.signature(default_false)) == "(x=False)"
+assert str(inspect.signature(default_none)) == "(x=None)"
+assert str(inspect.signature(default_tuple_empty)) == "(x=())"
+assert str(inspect.signature(default_tuple_literals)) == "(x=(1, 'a', 1.0, False, True, None, (), (1, 2, (3, 4))))"
+
+# Check __text_signature__ directly since inspect.signature produces
+# an incorrect signature for 1-tuple default arguments prior to
+# Python 3.12 (cpython#102379).
+# assert str(inspect.signature(default_tuple_singleton)) == "(x=(1,))"
+assert getattr(default_tuple_singleton, "__text_signature__") == "(x=(1,))"
 
+[case testSignaturesStringDefaults]
 def f1(x="'foo"): pass
 def f2(x='"foo'): pass
 def f3(x=""""Isn\'t," they said."""): pass
 def f4(x="\\ \a \b \f \n \r \t \v \x00"): pass
 def f5(x="\N{BANANA}sv"): pass
 
-def test_string_defaults() -> None:
-    assert str(inspect.signature(f1)) == """(x="'foo")"""
-    assert str(inspect.signature(f2)) == """(x='"foo')"""
-    assert str(inspect.signature(f3)) == r"""(x='"Isn\'t," they said.')"""
-    assert str(inspect.signature(f4)) == r"""(x='\\ \x07 \x08 \x0c \n \r \t \x0b \x00')"""
-    assert str(inspect.signature(f5)) == """(x='\U0001F34Csv')"""
-
-[case testSignaturesIrrepresentableDefaults]
+[file driver.py]
 import inspect
-from typing import Any
+from native import *
 
-from testutil import assertRaises
+assert str(inspect.signature(f1)) == """(x="'foo")"""
+assert str(inspect.signature(f2)) == """(x='"foo')"""
+assert str(inspect.signature(f3)) == r"""(x='"Isn\'t," they said.')"""
+assert str(inspect.signature(f4)) == r"""(x='\\ \x07 \x08 \x0c \n \r \t \x0b \x00')"""
+assert str(inspect.signature(f5)) == """(x='\N{BANANA}sv')"""
 
+[case testSignaturesIrrepresentableDefaults]
 def bad1(x=[]): pass
 def bad2(x={}): pass
 def bad3(x=set()): pass
@@ -88,16 +89,17 @@ def bad9(x=1|2): pass
 def bad10(x=float("nan")): pass
 def bad11(x=([],)): pass
 
-def test_irrepresentable_defaults() -> None:
-    bad: Any
-    for bad in [bad1, bad2, bad3, bad4, bad5, bad6, bad7, bad8, bad9, bad10, bad11]:
-        assert bad.__text_signature__ is None, f"{bad.__name__} has unexpected __text_signature__"
-        with assertRaises(ValueError, "no signature found for builtin"):
-            inspect.signature(bad)
-
-[case testSignaturesMethods]
+[file driver.py]
 import inspect
+from testutil import assertRaises
+from native import *
 
+for bad in [bad1, bad2, bad3, bad4, bad5, bad6, bad7, bad8, bad9, bad10, bad11]:
+    assert bad.__text_signature__ is None, f"{bad.__name__} has unexpected __text_signature__"
+    with assertRaises(ValueError, "no signature found for builtin"):
+        inspect.signature(bad)
+
+[case testSignaturesMethods]
 class Foo:
     def f1(self, x): pass
     @classmethod
@@ -106,26 +108,59 @@ class Foo:
     def f3(x): pass
     def __eq__(self, x: object): pass
 
-def test_methods() -> None:
-    assert getattr(Foo.f1, "__text_signature__") == "($self, x)"
-    assert getattr(Foo().f1, "__text_signature__") == "($self, x)"
-    assert str(inspect.signature(Foo.f1)) == "(self, /, x)"
-    assert str(inspect.signature(Foo().f1)) == "(x)"
-
-    assert getattr(Foo.f2, "__text_signature__") == "($cls, x)"
-    assert getattr(Foo().f2, "__text_signature__") == "($cls, x)"
-    assert str(inspect.signature(Foo.f2)) == "(x)"
-    assert str(inspect.signature(Foo().f2)) == "(x)"
-
-    assert getattr(Foo.f3, "__text_signature__") == "(x)"
-    assert getattr(Foo().f3, "__text_signature__") == "(x)"
-    assert str(inspect.signature(Foo.f3)) == "(x)"
-    assert str(inspect.signature(Foo().f3)) == "(x)"
-
-    assert getattr(Foo.__eq__, "__text_signature__") == "($self, value, /)"
-    assert getattr(Foo().__eq__, "__text_signature__") == "($self, value, /)"
-    assert str(inspect.signature(Foo.__eq__)) == "(self, value, /)"
-    assert str(inspect.signature(Foo().__eq__)) == "(value, /)"
+[file driver.py]
+import inspect
+from native import *
+
+assert str(inspect.signature(Foo.f1)) == "(self, /, x)"
+assert str(inspect.signature(Foo().f1)) == "(x)"
+
+assert str(inspect.signature(Foo.f2)) == "(x)"
+assert str(inspect.signature(Foo().f2)) == "(x)"
+
+assert str(inspect.signature(Foo.f3)) == "(x)"
+assert str(inspect.signature(Foo().f3)) == "(x)"
+
+assert str(inspect.signature(Foo.__eq__)) == "(self, value, /)"
+assert str(inspect.signature(Foo().__eq__)) == "(value, /)"
+
+[case testSignaturesConstructors]
+class Empty: pass
+
+class HasInit:
+    def __init__(self, x) -> None: pass
+
+class InheritedInit(HasInit): pass
+
+class HasInitBad:
+    def __init__(self, x=[]) -> None: pass
+
+[file driver.py]
+import inspect
+from testutil import assertRaises
+from native import *
+
+assert str(inspect.signature(Empty)) == "()"
+assert str(inspect.signature(Empty.__init__)) == "(self, /, *args, **kwargs)"
+
+assert str(inspect.signature(HasInit)) == "(x)"
+assert str(inspect.signature(HasInit.__init__)) == "(self, /, *args, **kwargs)"
+
+assert str(inspect.signature(InheritedInit)) == "(x)"
+assert str(inspect.signature(InheritedInit.__init__)) == "(self, /, *args, **kwargs)"
+
+assert getattr(HasInitBad, "__text_signature__") is None
+with assertRaises(ValueError, "no signature found for builtin"):
+    inspect.signature(HasInitBad)
+
+# CPython detail note: type objects whose tp_doc contains only a text signature behave
+# differently from method objects whose ml_doc contains only a test signature: type
+# objects will have __doc__="" whereas method objects will have __doc__=None. This
+# difference stems from the former using _PyType_GetDocFromInternalDoc(...) and the
+# latter using PyUnicode_FromString(_PyType_DocWithoutSignature(...)).
+for cls in [Empty, HasInit, InheritedInit]:
+    assert getattr(cls, "__doc__") == ""
+assert getattr(HasInitBad, "__doc__") is None
 
 [case testSignaturesHistoricalPositionalOnly]
 import inspect