unused-argument, pointless-statement, and function-redefined with recommended use of typing.overload

[mwchase]

Code to reproduce

# pylint: disable=missing-docstring

import typing


@typing.overload
def double_with_docstring(arg: str) -> str:
    """Return arg, concatenated with itself."""


@typing.overload
def double_with_docstring(arg: int) -> int:
    """Return twice arg."""


def double_with_docstring(arg):
    """Return 2 * arg."""
    return 2 * arg


@typing.overload
def double_with_ellipsis(arg: str) -> str:
    ...


@typing.overload
def double_with_ellipsis(arg: int) -> int:
    ...


def double_with_ellipsis(arg):
    return 2 * arg


@typing.overload
def double_with_pass(arg: str) -> str:
    pass


@typing.overload
def double_with_pass(arg: int) -> int:
    pass


def double_with_pass(arg):
    return 2 * arg

Current behavior

W:  7,26: Unused argument 'arg' (unused-argument)
E: 12, 0: function already defined line 7 (function-redefined)
W: 12,26: Unused argument 'arg' (unused-argument)
E: 16, 0: function already defined line 7 (function-redefined)
W: 23, 4: Statement seems to have no effect (pointless-statement)
W: 22,25: Unused argument 'arg' (unused-argument)
E: 27, 0: function already defined line 22 (function-redefined)
W: 28, 4: Statement seems to have no effect (pointless-statement)
W: 27,25: Unused argument 'arg' (unused-argument)
E: 31, 0: function already defined line 22 (function-redefined)
W: 36,21: Unused argument 'arg' (unused-argument)
E: 41, 0: function already defined line 36 (function-redefined)
W: 41,21: Unused argument 'arg' (unused-argument)
E: 45, 0: function already defined line 36 (function-redefined)

Expected behavior

The first form, which uses docstrings (sadly only visible in the code) to describe the specific overload, should be equivalent to the version with pass, and is included for completeness.

The mypy documentation recommends using a pass statement in the body of overloads, while the typing module documentation uses ....

In either case, it seems to me that the expected behavior/context of a function decorated with typing.overload should be that it returns None and has no side effects, and it should later be overridden.

If possible, it may be worth including a message for uses of an overloaded function before it is overridden, because that will error at runtime.

Things I'm not sure about: Are full annotations required on each definition? Should there be a message for only one overloaded version? The mypy documentation annotates the actual implementation (with unions of all the relevant types), the Python documentation does not, and both appear acceptable to mypy from the testing that led me to this issue; should pylint care?

pylint --version output

pylint 1.7.2,
astroid 1.5.3
Python 3.6.2 (default, Jul 17 2017, 16:44:45)
[GCC 4.2.1 Compatible Apple LLVM 8.1.0 (clang-802.0.42)]