ESPNow.send argument types / @overloads

[Josverl]

@glenn20 , I hope you can assist in improving the type-stubs for this.

I am in process of adding parameter types to the type-stubs, and I use the examples from the documentation to help verify the level of correctness of the stubs.

#espnow.pyi 

_MACAddress: TypeAlias = bytes
_PeerInfo: TypeAlias = Tuple[_MACAddress, bytes, int, int, bool]

class ESPNow(ESPNowBase, Iterator):
    #....
    def send(
        self,
        peer: _MACAddress,
        msg: str | bytes,
        mac: _MACAddress | None = None,
        sync: bool = True,
    ) -> bool:
        """Send the data contained in ``msg`` to the peer with given network ``mac`` address."""
   ...

If I check this with the Sender: example on https://docs.micropython.org/en/latest/library/espnow.html#module-espnow
then both pyright and mypy report an error on the e.send in:

for i in range(100):
    e.send(peer, str(i) * 20, True)

• pyright: error: Argument of type "Literal[True]" cannot be assigned to parameter "mac" of type "_MACAddress | None" in function "send"
• mypy: error: Argument 3 to "send" of "ESPNow" has incompatible type "bool"; expected "bytes | None" [arg-type]

before digging deeper I wanted to check if I have understood the documentation correctly, this is a documentation bug, or that this is a form that the typecheckers cannot handle by default.

Code sample in pyright playground

[glenn20]

@Josverl , sorry for the slow response.

Thanks again for your work on the stubs... they make coding in micropython so much more productive :).

I believe, you should change

class ESPNow(ESPNowBase, Iterator):
    #....
    def send(
        self,
        peer: _MACAddress,
        msg: str | bytes,
        mac: _MACAddress | None = None,
        sync: bool = True,
    ) -> bool:

to

class ESPNow(ESPNowBase, Iterator):
    #....
    def send(
        self,
        peer: _MACAddress,
        msg: str | bytes,
        sync: bool = True,
    ) -> bool:

ie. remove the mac argument. In the docs, I use the name mac for the first argument (that you have called peer). I started with peer, but found that most users more intuitively grasped that the peer was just a mac address and not some handle that needed to be generated.

There is still a gotcha in the api, in that if only one argument is provided, it is expected to be a string (the message). I supported that as a convenience to send broadcast messages.

[Josverl]

thanks, ill give that a try , for the single argument version , I should be able to declare that as an @overload.

[Josverl]

With these overloads the samples check out well.
Ill add them to a future update of the stubs.

Should it be msg: str | bytes, or msg: str , ?

    @overload
    def send(
        self,
        mac: _MACAddress,
        msg: str | bytes,
        sync:bool=True,
    ) -> bool: 
        """
        Send the data contained in ``msg`` to the peer with given network ``mac``
        address. 
        """
        ...
    @overload
    def send(
        self,
        msg: str | bytes,
    ) -> bool:
        """
        In the second form, ``mac=None`` and ``sync=True``. The peer must
        be registered with `ESPNow.add_peer()<ESPNow.add_peer()>` before the
        message can be sent.