More types for tkinter.Treeview (#5584)

stdlib/tkinter/ttk.pyi

@@ -3,7 +3,7 @@ import sys
 import tkinter
 from tkinter.font import _FontDescription
 from typing import Any, Callable, Dict, List, Optional, Tuple, Union, overload
-from typing_extensions import Literal
+from typing_extensions import Literal, TypedDict
 
 def tclobjs_to_py(adict): ...
 def setup_master(master: Optional[Any] = ...): ...
@@ -871,6 +871,36 @@ if sys.version_info >= (3, 7):
         config = configure  # type: ignore
         def set(self, value: Any) -> None: ...
 
+class _TreeviewItemDict(TypedDict):
+    text: str
+    image: Literal[""] | list[str]  # no idea why it's wrapped in list
+    values: list[Any]
+    open: bool  # actually 0 or 1
+    tags: list[str]
+
+class _TreeviewTagDict(TypedDict):
+    text: str
+    image: Literal[""] | str  # not wrapped in list :D
+    anchor: tkinter._Anchor
+    background: tkinter._Color
+    foreground: tkinter._Color
+
+class _TreeviewHeaderDict(TypedDict):
+    text: str
+    image: list[str]
+    anchor: tkinter._Anchor
+    command: str
+    state: str  # Doesn't seem to appear anywhere else than in these dicts
+
+class _TreeviewColumnDict(TypedDict):
+    width: int
+    minwidth: int
+    stretch: bool  # actually 0 or 1
+    anchor: tkinter._Anchor
+    id: str
+
+_TreeviewColumnId = Union[int, str]  # manual page: "COLUMN IDENTIFIERS"
+
 class Treeview(Widget, tkinter.XView, tkinter.YView):
     def __init__(
         self,
@@ -914,38 +944,122 @@ class Treeview(Widget, tkinter.XView, tkinter.YView):
     @overload
     def configure(self, cnf: str) -> Tuple[str, str, str, Any, Any]: ...
     config = configure
-    def bbox(self, item, column: Optional[Any] = ...): ...  # type: ignore
-    def get_children(self, item: Optional[Any] = ...): ...
-    def set_children(self, item, *newchildren): ...
-    def column(self, column, option: Optional[Any] = ..., **kw): ...
-    def delete(self, *items): ...
-    def detach(self, *items): ...
-    def exists(self, item): ...
-    def focus(self, item: Optional[Any] = ...): ...
-    def heading(self, column, option: Optional[Any] = ..., **kw): ...
+    def bbox(self, item, column: _TreeviewColumnId | None = ...) -> Tuple[int, int, int, int] | Literal[""]: ...  # type: ignore
+    def get_children(self, item: str | None = ...) -> Tuple[str, ...]: ...
+    def set_children(self, item: str, *newchildren: str) -> None: ...
+    @overload
+    def column(self, column: _TreeviewColumnId, option: Literal["width", "minwidth"]) -> int: ...
+    @overload
+    def column(self, column: _TreeviewColumnId, option: Literal["stretch"]) -> bool: ...  # actually 0 or 1
+    @overload
+    def column(self, column: _TreeviewColumnId, option: Literal["anchor"]) -> _tkinter.Tcl_Obj: ...
+    @overload
+    def column(self, column: _TreeviewColumnId, option: Literal["id"]) -> str: ...
+    @overload
+    def column(self, column: _TreeviewColumnId, option: str) -> Any: ...
+    @overload
+    def column(
+        self,
+        column: _TreeviewColumnId,
+        option: None = ...,
+        *,
+        width: int = ...,
+        minwidth: int = ...,
+        stretch: bool = ...,
+        anchor: tkinter._Anchor = ...,
+        # id is read-only
+    ) -> _TreeviewColumnDict | None: ...
+    def delete(self, *items: str) -> None: ...
+    def detach(self, *items: str) -> None: ...
+    def exists(self, item: str) -> bool: ...
+    @overload  # type: ignore
+    def focus(self, item: None = ...) -> str: ...  # can return empty string
+    @overload
+    def focus(self, item: str) -> Literal[""]: ...
+    @overload
+    def heading(self, column: _TreeviewColumnId, option: Literal["text"]) -> str: ...
+    @overload
+    def heading(self, column: _TreeviewColumnId, option: Literal["image"]) -> Tuple[str]: ...
+    @overload
+    def heading(self, column: _TreeviewColumnId, option: Literal["anchor"]) -> _tkinter.Tcl_Obj: ...
+    @overload
+    def heading(self, column: _TreeviewColumnId, option: Literal["command"]) -> str: ...
+    @overload
+    def heading(self, column: _TreeviewColumnId, option: str) -> Any: ...
+    @overload
+    def heading(
+        self,
+        column: _TreeviewColumnId,
+        option: None = ...,
+        *,
+        text: str = ...,
+        image: tkinter._ImageSpec = ...,
+        anochor: tkinter._Anchor = ...,
+        command: str | Callable[[], Any] = ...,
+    ) -> _TreeviewHeaderDict | None: ...
     def identify(self, component, x, y): ...
-    def identify_row(self, y): ...
-    def identify_column(self, x): ...
-    def identify_region(self, x, y): ...
-    def identify_element(self, x, y): ...
-    def index(self, item): ...
-    def insert(self, parent, index, iid: Optional[Any] = ..., **kw): ...
-    def item(self, item, option: Optional[Any] = ..., **kw): ...
-    def move(self, item, parent, index): ...
-    reattach: Any
-    def next(self, item): ...
-    def parent(self, item): ...
-    def prev(self, item): ...
-    def see(self, item): ...
+    def identify_row(self, y: int) -> str: ...
+    def identify_column(self, x: int) -> str: ...
+    def identify_region(self, x: int, y: int) -> Literal["heading", "separator", "tree", "cell", "nothing"]: ...
+    def identify_element(self, x: int, y: int) -> str: ...  # don't know what possible return values are
+    def index(self, item: str) -> int: ...
+    def insert(
+        self,
+        parent: str,
+        index: int | Literal["end"],
+        iid: str | None = ...,
+        *,
+        id: str = ...,  # same as iid
+        text: str = ...,
+        image: tkinter._ImageSpec = ...,
+        values: tkinter._TkinterSequence[Any] = ...,
+        open: bool = ...,
+        tags: str | tkinter._TkinterSequence[str] = ...,
+    ) -> str: ...
+    @overload
+    def item(self, item: str, option: Literal["text"]) -> str: ...
+    @overload
+    def item(self, item: str, option: Literal["image"]) -> Literal[""] | Tuple[str]: ...
+    @overload
+    def item(self, item: str, option: Literal["values"]) -> Literal[""] | Tuple[Any, ...]: ...
+    @overload
+    def item(self, item: str, option: Literal["open"]) -> bool: ...  # actually 0 or 1
+    @overload
+    def item(self, item: str, option: Literal["tags"]) -> Literal[""] | Tuple[str, ...]: ...
+    @overload
+    def item(self, item: str, option: str) -> Any: ...
+    @overload
+    def item(
+        self,
+        item: str,
+        option: None = ...,
+        *,
+        text: str = ...,
+        image: tkinter._ImageSpec = ...,
+        values: tkinter._TkinterSequence[Any] = ...,
+        open: bool = ...,
+        tags: str | tkinter._TkinterSequence[str] = ...,
+    ) -> _TreeviewItemDict | None: ...
+    def move(self, item: str, parent: str, index: int) -> None: ...
+    reattach = move
+    def next(self, item: str) -> str: ...  # returning empty string means last item
+    def parent(self, item: str) -> str: ...
+    def prev(self, item: str) -> str: ...  # returning empty string means first item
+    def see(self, item: str) -> None: ...
     if sys.version_info >= (3, 8):
         def selection(self) -> Tuple[str, ...]: ...
     else:
         def selection(self, selop: Optional[Any] = ..., items: Optional[Any] = ...) -> Tuple[str, ...]: ...
-    def selection_set(self, items): ...
-    def selection_add(self, items): ...
-    def selection_remove(self, items): ...
-    def selection_toggle(self, items): ...
-    def set(self, item, column: Optional[Any] = ..., value: Optional[Any] = ...): ...
+    def selection_set(self, items: str | tkinter._TkinterSequence[str]) -> None: ...
+    def selection_add(self, items: str | tkinter._TkinterSequence[str]) -> None: ...
+    def selection_remove(self, items: str | tkinter._TkinterSequence[str]) -> None: ...
+    def selection_toggle(self, items: str | tkinter._TkinterSequence[str]) -> None: ...
+    @overload
+    def set(self, item: str, column: None = ..., value: None = ...) -> dict[str, Any]: ...
+    @overload
+    def set(self, item: str, column: _TreeviewColumnId, value: None = ...) -> Any: ...
+    @overload
+    def set(self, item: str, column: _TreeviewColumnId, value: Any) -> Literal[""]: ...
     # There's no tag_unbind() or 'add' argument for whatever reason.
     # Also, it's 'callback' instead of 'func' here.
     @overload
@@ -956,8 +1070,32 @@ class Treeview(Widget, tkinter.XView, tkinter.YView):
     def tag_bind(self, tagname: str, sequence: Optional[str], callback: str) -> None: ...
     @overload
     def tag_bind(self, tagname: str, *, callback: str) -> None: ...
-    def tag_configure(self, tagname, option: Optional[Any] = ..., **kw): ...
-    def tag_has(self, tagname, item: Optional[Any] = ...): ...
+    @overload
+    def tag_configure(self, tagname: str, option: Literal["text"]) -> str: ...
+    @overload
+    def tag_configure(self, tagname: str, option: Literal["image"]) -> str: ...
+    @overload
+    def tag_configure(self, tagname: str, option: Literal["anchor"]) -> tkinter._Anchor | Literal[""]: ...
+    @overload
+    def tag_configure(self, tagname: str, option: Literal["foreground", "background"]) -> tkinter._Color: ...
+    @overload
+    def tag_configure(self, tagname: str, option: str) -> Any: ...
+    @overload
+    def tag_configure(
+        self,
+        tagname: str,
+        option: None = ...,
+        *,
+        text: str = ...,
+        image: tkinter._ImageSpec = ...,
+        anchor: tkinter._Anchor = ...,
+        background: tkinter._Color = ...,
+        foreground: tkinter._Color = ...,
+    ) -> _TreeviewTagDict | None: ...
+    @overload
+    def tag_has(self, tagname: str, item: None = ...) -> Tuple[str, ...]: ...
+    @overload
+    def tag_has(self, tagname: str, item: str) -> bool: ...
 
 class LabeledScale(Frame):
     label: Any