Do @overloads require an implementation in .pyi stubs ?

[Josverl]

When using @overload in a .py module, there is a need for the implementation of the method / function be present.

Is this also the case for a .pyi file, or can the implementation be omitted ?
That seems logical, as the code is not intended to be executed , but I could not find a clear answer, yet.

# Pin.pyi 
# No overloading
class Pin_naive:

    def __init__(self, number: int) -> None:
        self.number = number

    def value(self, x: Optional[Any] = None) -> int:
        """
        This method allows to set and get the value of the pin, depending on whether
        the argument ``x`` is supplied or not.
        """
        ...

# Overload for get and set
class Pin:
    def __init__(self, number: int) -> None:
        self.number = number
    @overload
    def value(self, x: bool | int ) -> None:
        """Set output state of the pin."""
    @overload
    def value(self, x: None ) -> int:
        """Get the value of the pin"""
        ...
    def value(self, x: Optional[Any] = None) -> int:
        """
        Is this implementation required in a .pyi file ?.
        """
        ...

[Akuli]

No, the implementation is not required in .pyi files. Look at any reasonably complex file in typeshed to find examples of overloads in .pyi files.

[Josverl]

Empirical evidence can be tricky , especially when there is a PEP that seems to say that the implementation is required even in a .pyi file , but I agree it does not make sense, I must be reading to much into MUST in the below sentence.

https://peps.python.org/pep-0484/#function-method-overloading

Uses of the @overload decorator as shown above are suitable for stub files. In regular modules, a series of @overload-decorated definitions MUST be followed by exactly one non-@overload-decorated definition (for the same function/method). The @overload-decorated definitions are for the benefit of the type checker only, since they will be overwritten by the non-@overload-decorated definition, while the latter is used at runtime but should be ignored by a type checker.

(CAPS are mine)

Thanks for confirming

[JelleZijlstra]

The PEP is no longer normative. The current spec is https://typing.readthedocs.io/en/latest/spec/overload.html and it says pretty clearly that the implementation is required only in .py files.