Verbose type annotations in help panel

[thangleiter]

Issue Report Checklist

• [x] Searched the issues page for similar reports
• [x] Read the relevant sections of the Spyder Troubleshooting Guide and followed its advice
• [x] Reproduced the issue after updating with conda update spyder (or pip, if not using Anaconda)
• [ ] Could not reproduce inside jupyter qtconsole (if console-related)
• [ ] Tried basic troubleshooting (if a bug/error)
  • [ ] Restarted Spyder
  • [ ] Reset preferences with spyder --reset
  • [ ] Reinstalled the latest version of Anaconda
  • [ ] Tried the other applicable steps from the Troubleshooting Guide
• [x] Completed the Problem Description, Steps to Reproduce and Version sections below

Problem Description

The help panel in my opinion is one of the nicest features in Spyder. With the introduction and proliferation of type annotations in Python, it became even more useful if developers did not document expected parameter types in their docstrings. More recently though, with Python making the typing system more complex as well as NumPy introducing typing to their codebase, function signatures become more and more bloated when annotated with complex union types. Note that this is of course a quite general issue that does not affect Spyder alone; the IPython tooltip help for example behaves the same way.

An example:

from collections.abc import Sequence
type_alias = Sequence[int | str] | int | str

def my_fun(x: type_alias) -> type_alias:
    do_whatever_with(x)

Rendered help

Now, one can argue if type aliases defined in such a way are the way to go. The most relevant situation in my case is when using numpy.typing to annotate functions:

import numpy.typing as npt

def my_np_fun(x: npt.ArrayLike, axis: int) -> npt.NDArray[float]:
    return np.asarray(x, np.float64).sum(axis)

Rendered help

In this case, it becomes really quite hard to figure out even that the axis argument exists because it is hard to visually distinguish it from the extremely long type annotation of the previous argument. Again, it may be argued that this is an upstream issue, either with Sphinx and the way it handles verbose annotations or with the way the type aliases are implented. Still, the current situation makes the help explorer much less useful to me.

As far as I can tell, the only way to prevent this level of verbosity in Sphinx is to manually specify type alias substitutions for the autodoc extension* in conf.py as documented here. This is not very user-friendly, but at least it could cover the most extreme cases like npt.ArrayLike.

*If it is even used? How else does Spyder/sphinx render type annotations?

That would look something like this:

autodoc_type_aliases = {
    'ArrayLike': 'numpy.typing.ArrayLike',
    'DTypeLike': 'numpy.typing.DTypeLike',
    'NBitBase': 'numpy.typing.NBitBase',
    'NDArray': 'numpy.typing.NDArray',
}

Since users might not use relative imports, one might also want to add the common alias:

autodoc_type_aliases |= {f"npt.{key}": value for key, value in autodoc_type_aliases.items()}

One might also imagine this to be configured through a settings page where users can add custom aliases they don't want explicitly resolved.