feat: Add method to functions and classes to build and return a stringified signature

Discussion-376: #376
PR-381: #381
Co-authored-by: Timothée Mazzucotelli <[email protected]>

Author: ISOR3X

src/_griffe/models.py

@@ -1654,6 +1654,18 @@ def mro(self) -> list[Class]:
         """Return a list of classes in order corresponding to Python's MRO."""
         return cast("Class", self.final_target).mro()
 
+    def signature(self, *, return_type: bool = False, name: str | None = None) -> str:
+        """Construct the class/function signature.
+
+        Parameters:
+            return_type: Whether to include the return type in the signature.
+            name: The name of the class/function to use in the signature.
+
+        Returns:
+            A string representation of the class/function signature.
+        """
+        return cast("Union[Class, Function]", self.final_target).signature(return_type=return_type, name=name)
+
     # SPECIFIC ALIAS METHOD AND PROPERTIES -----------------
     # These methods and properties do not exist on targets,
     # they are specific to aliases.
@@ -1976,6 +1988,23 @@ def parameters(self) -> Parameters:
         except KeyError:
             return Parameters()
 
+    def signature(self, *, return_type: bool = False, name: str | None = None) -> str:
+        """Construct the class signature.
+
+        Parameters:
+            return_type: Whether to include the return type in the signature.
+            name: The name of the class to use in the signature.
+
+        Returns:
+            A string representation of the class signature.
+        """
+        all_members = self.all_members
+        if "__init__" in all_members:
+            init = all_members["__init__"]
+            if isinstance(init, Function):
+                return init.signature(return_type=return_type, name=name or self.name)
+        return ""
+
     @property
     def resolved_bases(self) -> list[Object]:
         """Resolved class bases.
@@ -2125,6 +2154,80 @@ def as_dict(self, **kwargs: Any) -> dict[str, Any]:
         base["returns"] = self.returns
         return base
 
+    def signature(self, *, return_type: bool = True, name: str | None = None) -> str:
+        """Construct the function signature.
+
+        Parameters:
+            return_type: Whether to include the return type in the signature.
+            name: The name of the function to use in the signature.
+
+        Returns:
+            A string representation of the function signature.
+        """
+        signature = f"{name or self.name}("
+
+        has_pos_only = any(p.kind == ParameterKind.positional_only for p in self.parameters)
+        render_pos_only_separator = True
+        render_kw_only_separator = True
+
+        param_strs = []
+
+        for index, param in enumerate(self.parameters):
+            # Skip 'self' or 'cls' for class methods if it's the first parameter.
+            if index == 0 and param.name in ("self", "cls") and self.parent and self.parent.is_class:
+                continue
+
+            param_str = ""
+
+            # Handle parameter kind and separators.
+            if param.kind != ParameterKind.positional_only:
+                if has_pos_only and render_pos_only_separator:
+                    render_pos_only_separator = False
+                    param_strs.append("/")
+
+                if param.kind == ParameterKind.keyword_only and render_kw_only_separator:
+                    render_kw_only_separator = False
+                    param_strs.append("*")
+
+            # Handle variadic parameters.
+            if param.kind == ParameterKind.var_positional:
+                param_str = "*"
+                render_kw_only_separator = False
+            elif param.kind == ParameterKind.var_keyword:
+                param_str = "**"
+
+            # Add parameter name.
+            param_str += param.name
+
+            # Handle type annotation
+            if param.annotation is not None:
+                param_str += f": {param.annotation}"
+                equal = " = "  # Space around equal when annotation is present.
+            else:
+                equal = "="  # No space when no annotation.
+
+            # Handle default value.
+            if param.default is not None and param.kind not in {
+                ParameterKind.var_positional,
+                ParameterKind.var_keyword,
+            }:
+                param_str += f"{equal}{param.default}"
+
+            param_strs.append(param_str)
+
+        # If we have positional-only parameters but no '/' was added yet
+        if has_pos_only and render_pos_only_separator:
+            param_strs.append("/")
+
+        signature += ", ".join(param_strs)
+        signature += ")"
+
+        # Add return type if present.
+        if return_type and self.annotation:
+            signature += f" -> {self.annotation}"
+
+        return signature
+
 
 class Attribute(Object):
     """The class representing a Python module/class/instance attribute."""

tests/test_models.py

@@ -9,11 +9,14 @@
 
 from griffe import (
     Attribute,
+    Class,
     Docstring,
+    Function,
     GriffeLoader,
     Module,
     NameResolutionError,
     Parameter,
+    ParameterKind,
     Parameters,
     module_vtree,
     temporary_inspected_module,
@@ -557,3 +560,36 @@ def __init__(self):
         },
     ) as module:
         assert module["A.__init__"].resolve("pd") == "package.mod.pd"
+
+
+def test_building_function_and_class_signatures() -> None:
+    """Test the construction of a class/function signature."""
+    # Test simple function signatures.
+    simple_params = Parameters(
+        Parameter("x", annotation="int"),
+        Parameter("y", annotation="int", default="0"),
+    )
+    simple_func = Function("simple_function", parameters=simple_params, returns="int")
+    assert simple_func.signature() == "simple_function(x: int, y: int = 0) -> int"
+
+    # Test class signatures.
+    init = Function("__init__", parameters=simple_params, returns="None")
+    cls = Class("TestClass")
+    cls.set_member("__init__", init)
+    assert cls.signature() == "TestClass(x: int, y: int = 0)"
+
+    # Create a more complex function with various parameter types.
+    params = Parameters(
+        Parameter("a", kind=ParameterKind.positional_only),
+        Parameter("b", kind=ParameterKind.positional_only, annotation="int", default="0"),
+        Parameter("c", kind=ParameterKind.positional_or_keyword),
+        Parameter("d", kind=ParameterKind.positional_or_keyword, annotation="str", default="''"),
+        Parameter("args", kind=ParameterKind.var_positional),
+        Parameter("e", kind=ParameterKind.keyword_only),
+        Parameter("f", kind=ParameterKind.keyword_only, annotation="bool", default="False"),
+        Parameter("kwargs", kind=ParameterKind.var_keyword),
+    )
+
+    func = Function("test_function", parameters=params, returns="None")
+    expected = "test_function(a, b: int = 0, /, c, d: str = '', *args, e, f: bool = False, **kwargs) -> None"
+    assert func.signature() == expected