Unsolvable error with method decorated with "overload".

[KelSolaar]

Given this class:

class NestedSequence(Protocol[_T_co]):
    """A protocol for representing nested sequences.

    Warning
    -------
    `NestedSequence` currently does not work in combination with typevars,
    *e.g.* ``def func(a: _NestedSequnce[T]) -> T: ...``.

    See Also
    --------
    collections.abc.Sequence
        ABCs for read-only and mutable :term:`sequences`.

    Examples
    --------
    .. code-block:: python

        >>> from __future__ import annotations

        >>> from typing import TYPE_CHECKING
        >>> import numpy as np

        >>> def get_dtype(seq: NestedSequence[float]) -> np.dtype[np.float64]:
        ...     return np.asarray(seq).dtype

        >>> a = get_dtype([1.0])
        >>> b = get_dtype([[1.0]])
        >>> c = get_dtype([[[1.0]]])
        >>> d = get_dtype([[[[1.0]]]])

        >>> if TYPE_CHECKING:
        ...     reveal_locals()
        ...     # note: Revealed local types are:
        ...     # note:     a: numpy.dtype[numpy.floating[numpy._typing._64Bit]]
        ...     # note:     b: numpy.dtype[numpy.floating[numpy._typing._64Bit]]
        ...     # note:     c: numpy.dtype[numpy.floating[numpy._typing._64Bit]]
        ...     # note:     d: numpy.dtype[numpy.floating[numpy._typing._64Bit]]

    """

    def __len__(self, /) -> int:
        """Implement ``len(self)``."""
        raise NotImplementedError

    @overload
    def __getitem__(self, index: int, /) -> _T_co | NestedSequence[_T_co]:
        ...

    @overload
    def __getitem__(self, index: slice, /) -> NestedSequence[_T_co]:
        ...

    def __getitem__(self, index, /):
        """Implement ``self[x]``."""
        raise NotImplementedError

    def __contains__(self, x: object, /) -> bool:
        """Implement ``x in self``."""
        raise NotImplementedError

    def __iter__(self, /) -> Iterator[_T_co | NestedSequence[_T_co]]:
        """Implement ``iter(self)``."""
        raise NotImplementedError

    def __reversed__(self, /) -> Iterator[_T_co | NestedSequence[_T_co]]:
        """Implement ``reversed(self)``."""
        raise NotImplementedError

    def count(self, value: Any, /) -> int:
        """Return the number of occurrences of `value`."""
        raise NotImplementedError

    def index(self, value: Any, /) -> int:
        """Return the first index of `value`."""
        raise NotImplementedError

pydocstyle reports that the two first __getitem__ overloads are missing docstrings:

colour/hints/__init__.py:223 in public method `__getitem__`:
        D105: Missing docstring in magic method
colour/hints/__init__.py:227 in public method `__getitem__`:
        D105: Missing docstring in magic method

But then if I add docstrings:

colour/hints/__init__.py:224 in public method `__getitem__`:
        D418: Function/ Method decorated with @overload shouldn't contain a docstring
colour/hints/__init__.py:229 in public method `__getitem__`:
        D418: Function/ Method decorated with @overload shouldn't contain a docstring

[odashi]

I encountered the same problem. A smaller reproduction should be:

"""Test."""

from collections.abc import Sequence
from typing import overload

class MySeq(Sequence[int]):
    """Test."""

    @overload
    def __getitem__(self, i: int) -> int:
        """Test."""
        ...
    @overload
    def __getitem__(self, i: slice) -> Sequence[int]:
        ...
    def __getitem__(self, i: int | slice) -> int | Sequence[int]:
        """Test."""
        raise NotImplementedError

Then,

$ pydocstyle --select=D105,D418 test.py
temp.py:11 in public method `__getitem__`:
        D418: Function/ Method decorated with @overload shouldn't contain a docstring
temp.py:14 in public method `__getitem__`:
        D105: Missing docstring in magic method

[odashi]

Duplicate of #525

[jenstroeger]

Duplicated by #635

Also related to functions decorated with @overload:

@typing.overload
def encrypt(cipher: Cipher, data: str) -> str:  # noqa: D103
    ...

@typing.overload
def encrypt(cipher: Cipher, data: bytes) -> str:  # noqa: D103
    ...

def encrypt(cipher, data):
    """Encrypt data using the given ``cipher``.

    More blah.
    """
    # Implementation follows.

Silencing the two D103 warnings shouldn’t be necessary because the implementation of the two overloaded functions provides the docstring.