help(): Display complex signatures in multiple lines

[JelleZijlstra]

Feature or enhancement

Proposal:

Here's the help() output for a reasonably complex typed method (link):

Help on function __init__ in module pyanalyze.name_check_visitor:

__init__(self, filename: str, contents: str, tree: ast.Module, *, settings: Optional[Mapping[pyanalyze.error_code.ErrorCode, bool]] = None, fail_after_first: bool = False, verbosity: int = 50, unused_finder: Optional[pyanalyze.find_unused.UnusedObjectFinder] = None, module: Optional[module] = None, attribute_checker: Optional[pyanalyze.name_check_visitor.ClassAttributeChecker] = None, collector: Optional[pyanalyze.name_check_visitor.CallSiteCollector] = None, annotate: bool = False, add_ignores: bool = False, checker: pyanalyze.checker.Checker, is_code_only: bool = False) -> None
    Constructor.
    
    filename: name of the file to run on (to show in error messages)
    contents: code that the visitor is run on
    fail_after_first: whether to throw an error after the first problem is detected
    verbosity: controls how much logging is emitted

It would be much easier to read if each parameter was on its own line, something like this:

Help on function __init__ in module pyanalyze.name_check_visitor:

__init__(
    self,
    filename: str,
    contents: str,
    tree: ast.Module,
    *,
    settings: Optional[Mapping[pyanalyze.error_code.ErrorCode, bool]] = None,
    fail_after_first: bool = False,
    verbosity: int = 50,
    unused_finder: Optional[pyanalyze.find_unused.UnusedObjectFinder] = None,
    module: Optional[module] = None,
    attribute_checker: Optional[pyanalyze.name_check_visitor.ClassAttributeChecker] = None,
    collector: Optional[pyanalyze.name_check_visitor.CallSiteCollector] = None,
    annotate: bool = False,
    add_ignores: bool = False,
    checker: pyanalyze.checker.Checker,
    is_code_only: bool = False,
) -> None
    Constructor.
    
    filename: name of the file to run on (to show in error messages)
    contents: code that the visitor is run on
    fail_after_first: whether to throw an error after the first problem is detected
    verbosity: controls how much logging is emitted

help() should switch to this output format only for reasonably complex signatures, perhaps if the signature line would otherwise be >80 characters.

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

Linked PRs

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

[sobolevn]

It is quite easy to do:

I modified __str__ to be def __str__(self, *, pretty=False): and then called it directly from pydoc.

I've also changed how we render the annotation: rendered = '(\n {}\n)'.format(',\n '.join(result)) in case of pretty

I guess that __str__ with custom params might be unusual, however pydecimal does the same.