`@overload` expands common type unions

[mhostetter]

I have noticed that when using overloads, type unions like npt.ArrayLike are expanded and become illegible. Not sure if this is a Sphinx or Sphinx Immaterial issue.

Here is a brief reproducer. Let me know if you need a full self-contained example.

from typing import Any, overload

import numpy.typing as npt

@overload
def function(x: npt.ArrayLike, return_int: bool = True) -> int:
    ...

@overload
def function(x: npt.ArrayLike, return_int: bool = False) -> float:
    ...

def function(x: Any, return_int: Any = False) -> Any:
    if return_int:
        return 42
    else:
        return 42.0

Renders as this:

With these relevant warnings:

/home/matt/repos/sdr/sdr.function:1: WARNING: py:class reference target not found: numpy._typing._array_like._SupportsArray
/home/matt/repos/sdr/sdr.function:1: WARNING: py:class reference target not found: numpy._typing._nested_sequence._NestedSequence
/home/matt/repos/sdr/sdr.function:1: WARNING: py:class reference target not found: numpy._typing._array_like._SupportsArray
/home/matt/repos/sdr/sdr.function:1: WARNING: py:class reference target not found: numpy._typing._nested_sequence._NestedSequence
/home/matt/repos/sdr/sdr.function:1: WARNING: py:class reference target not found: numpy._typing._array_like._SupportsArray
/home/matt/repos/sdr/sdr.function:1: WARNING: py:class reference target not found: numpy._typing._nested_sequence._NestedSequence
/home/matt/repos/sdr/sdr.function:1: WARNING: py:class reference target not found: numpy._typing._array_like._SupportsArray
/home/matt/repos/sdr/sdr.function:1: WARNING: py:class reference target not found: numpy._typing._nested_sequence._NestedSequence

[2bndy5]

The warnings should be satisfied when intersphinx is given URLs that define the references. Although the references named look like they're supposed to be private, so maybe they aren't included in public docs (& corresponding intersphinx inventories).

[2bndy5]

Not sure if this is a Sphinx or Sphinx Immaterial issue.

Me neither. Does this same behavior happen when using alabaster theme with autodoc?

[jbms]

I think you need to use the future annotations feature to retain type aliases.

[mhostetter]

I think you need to use the future annotations feature to retain type aliases.

I did have from __future__ import annotations at the top of my file. I forgot to include it in my reproducer.

[mhostetter]

I still run into this issue, any thoughts? I find myself changing the APIs and functionality of functions to avoid these unreadable call signatures. I appreciate the help! 🙏

Reproducer file:

from __future__ import annotations

from typing import Any, overload

import numpy.typing as npt

@overload
def function(x: npt.ArrayLike, return_int: bool = True) -> int: ...

@overload
def function(x: npt.ArrayLike, return_int: bool = False) -> float: ...

def function(x: Any, return_int: Any = False) -> Any:
    """
    Group:
        dsp-fir-filtering
    """
    if return_int:
        return 42
    else:
        return 42.0

Relevant config:

nitpicky = True
nitpick_ignore = [
    ("py:class", "numpy.typing.ArrayLike"),  # Wish this would work
    ("py:class", "numpy.typing.DTypeLike"),  # Wish this would work
    ("py:class", "numpy.typing.NDArray"),  # Wish this would work
]
intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None),
    "numpy": ("https://numpy.org/doc/stable/", None),
    "scipy": ("http://docs.scipy.org/doc/scipy/reference/", None),
    "matplotlib": ("http://matplotlib.sourceforge.net/", None),
    "galois": ("https://mhostetter.github.io/galois/latest/", None),
}
autodoc_type_aliases = {
    "npt.ArrayLike": "~numpy.typing.ArrayLike",
    "npt.DTypeLike": "~numpy.typing.DTypeLike",
    "npt.NDArray": "~numpy.typing.NDArray",
}
python_type_aliases = autodoc_type_aliases

Relevant warnings:

/home/matt/repos/sdr/sdr.function:1: WARNING: py:class reference target not found: numpy._typing._array_like._SupportsArray
/home/matt/repos/sdr/sdr.function:1: WARNING: py:class reference target not found: numpy._typing._nested_sequence._NestedSequence
/home/matt/repos/sdr/sdr.function:1: WARNING: py:class reference target not found: numpy._typing._array_like._SupportsArray
/home/matt/repos/sdr/sdr.function:1: WARNING: py:class reference target not found: numpy._typing._nested_sequence._NestedSequence
/home/matt/repos/sdr/sdr.function:1: WARNING: py:class reference target not found: numpy._typing._array_like._SupportsArray
/home/matt/repos/sdr/sdr.function:1: WARNING: py:class reference target not found: numpy._typing._nested_sequence._NestedSequence
/home/matt/repos/sdr/sdr.function:1: WARNING: py:class reference target not found: numpy._typing._array_like._SupportsArray
/home/matt/repos/sdr/sdr.function:1: WARNING: py:class reference target not found: numpy._typing._nested_sequence._NestedSequence

Output: