autodoc.typehints can accurately represent overloads

[AWhetter]

Feature or Bugfix

• Feature
• Bugfix

Purpose

Let's say we have the following method (adapted from https://www.python.org/dev/peps/pep-0484/#function-method-overloading):

from typing import Callable, Iterable, Iterator, Tuple, TypeVar, overload

T1 = TypeVar('T1')
T2 = TypeVar('T2')
S = TypeVar('S')

@overload
def map(func: Callable[[T1], S], iter1: Iterable[T1]) -> Iterator[S]: ...
@overload
def map(func: Callable[[T1, T2], S],
        iter1: Iterable[T1], iter2: Iterable[T2]) -> Iterator[S]: ...
def map(func, *iterables):
    """Do a map.

    :param func: The function.
    :param iter1: An iterable.
    :param iter2: Another iterable.

    :returns: A new iterable.
    """

Currently, when autotype_typehints is set to description, this method would be displayed as though the following ReST were typed.

.. py::method: map(func, *iterables)

      Do a map.

      :param func: The function.
      :param iter1: An iterable.
      :param iter2: Another iterable.
      :param iterables:

      :returns: A new iterable.

Note the addition of the new parameter, and the lack of parameter types and return types. However it is impossible to represent this overload purely as a list of parameters. So there is no behaviour that we can give to 'description' so that it can accurately represent all overloads. Trying to display any type (even of Union of all possible types) would misguide a user.

Therefore this pull request introduces two changes to allow users to choose how to solve this problem. Firstly, overloads will never try to be displayed in the description, even when autodoc_typehints is set to 'description', because we cannot accurately represent overloads in this way. This is mentioned in the documentation to make it clear why we have to do this.

The second change is that autodoc_typehints can be set to 'both' to allow type hints to be included both in the signature and in the description. The typehints for overloads will still never try to be displayed in the description.

When autodoc_typehints is set to 'both', 'description', or 'signature' the above function will now display as:

.. py::method: map(func: Callable[[T1], S], iter1: Iterable[T1]) -> Iterator[S]
               map(func: Callable[[T1, T2], S], iter1: Iterable[T1], iter2: Iterable[T2]) -> Iterator[S]

      Do a map.

      :param func: The function.
      :param iter1: An iterable.
      :param iter2: Another iterable.

      :returns: A new iterable.

[tk0miya]

LGTM!