gh-112139: Add `inspect.Signature.format` and use it in `pydoc` (#112143)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

1 files changed, 12 insertions, 0 deletions

diff --git a/Lib/inspect.py b/Lib/inspect.py
index aaa22be..079385a 100644
--- a/Lib/inspect.py
+++ b/Lib/inspect.py
@@ -3316,6 +3316,16 @@ class Signature:
         return '<{} {}>'.format(self.__class__.__name__, self)
 
     def __str__(self):
+        return self.format()
+
+    def format(self, *, max_width=None):
+        """Convert signature object to string.
+
+        If *max_width* integer is passed,
+        signature will try to fit into the *max_width*.
+        If signature is longer than *max_width*,
+        all parameters will be on separate lines.
+        """
         result = []
         render_pos_only_separator = False
         render_kw_only_separator = True
@@ -3353,6 +3363,8 @@ class Signature:
             result.append('/')
 
         rendered = '({})'.format(', '.join(result))
+        if max_width is not None and len(rendered) > max_width:
+            rendered = '(\n    {}\n)'.format(',\n    '.join(result))
 
         if self.return_annotation is not _empty:
             anno = formatannotation(self.return_annotation)