Turtle.dot() stubs do not accurately reflect runtime signature

[JanEricNitschke]

Turtle.dot() is currently stubbed like:

from typing import TypeAlias
_Color: TypeAlias = str | tuple[float, float, float]

class Turtle:
    def dot(self, size: int | None = None, *color: _Color) -> None: ...

Which for this code:

turtle = Turtle()
turtle.dot()
turtle.dot(10)
turtle.dot(size=10)
turtle.dot((0, 0, 0))
turtle.dot("blue")
turtle.dot(20, "blue")
turtle.dot(20, "blue")
turtle.dot(20, (0, 0, 0))
turtle.dot(20, 0, 0, 0)

Leads to these errors with pyright:

Argument of type "tuple[Literal[0], Literal[0], Literal[0]]" cannot be assigned to parameter "size" of type "int | None" in function "dot"
  Type "tuple[Literal[0], Literal[0], Literal[0]]" is not assignable to type "int | None"
    "tuple[Literal[0], Literal[0], Literal[0]]" is not assignable to "int"
    "tuple[Literal[0], Literal[0], Literal[0]]" is not assignable to "None"  (reportArgumentType)
Argument of type "Literal['blue']" cannot be assigned to parameter "size" of type "int | None" in function "dot"
  Type "Literal['blue']" is not assignable to type "int | None"
    "Literal['blue']" is not assignable to "int"
    "Literal['blue']" is not assignable to "None"  (reportArgumentType)
Argument of type "Literal[0]" cannot be assigned to parameter "color" of type "_Color" in function "dot"
  Type "Literal[0]" is not assignable to type "_Color"
    "Literal[0]" is not assignable to "str"
    "Literal[0]" is not assignable to "tuple[float, float, float]"  (reportArgumentType)
Argument of type "Literal[0]" cannot be assigned to parameter "color" of type "_Color" in function "dot"
  Type "Literal[0]" is not assignable to type "_Color"
    "Literal[0]" is not assignable to "str"
    "Literal[0]" is not assignable to "tuple[float, float, float]"  (reportArgumentType)
Argument of type "Literal[0]" cannot be assigned to parameter "color" of type "_Color" in function "dot"
  Type "Literal[0]" is not assignable to type "_Color"
    "Literal[0]" is not assignable to "str"
    "Literal[0]" is not assignable to "tuple[float, float, float]"  (reportArgumentType)

However they all work at runtime: https://github.com/python/cpython/pull/138773/files

[JanEricNitschke]

I think this would probably more closely match the actual signature:

    @overload
    def dot(self, size: int | None = None) -> None: ...
    @overload
    def dot(self, color: _Color, /) -> None: ...
    @overload
    def dot(self, size: int | None, color: _Color, /) -> None: ...
    @overload
    def dot(self, size: int | None, r: float, g: float, b: float, /) -> None: ...

Although with the actual code:

        if not color:
            if isinstance(size, (str, tuple)):
                color = self._colorstr(size)
                size = self._pensize + max(self._pensize, 4)
            else:
                color = self._pencolor
                if not size:
                    size = self._pensize + max(self._pensize, 4)
        else:
            if size is None:
                size = self._pensize + max(self._pensize, 4)
            color = self._colorstr(color)

this would also work:

        self.turtle.dot(size=(0, 0, 0))
        self.turtle.dot(size="blue")

[srittau]

What a messy signature, but this is clearly wrong in the stubs (and it also applies to the standalone dot function further down in the stubs). PR welcome!

It's probably a better idea to merge the first two overloads, though:

    @overload
    def dot(self, size: int | _Color | None = None) -> None: ...

[JanEricNitschke]

It's probably a better idea to merge the first two overloads, though:

@overload
def dot(self, size: int | _Color | None = None) -> None: ...

Yeah, also more correct actually. I was just thinking of not allowing "dot(size="blue") but it definitely is allowed at runtime and makes the overloads simpler.

Will adjust this + add your other suggestions later today.