add types to tkinter.Text methods (#4460)

Author: Akuli

stdlib/3/tkinter/__init__.pyi

@@ -2479,6 +2479,7 @@ class Scrollbar(Widget):
     def get(self): ...
     def set(self, first, last): ...
 
+_TextIndex = Union[_tkinter.Tcl_Obj, str, float]
 _TextOptionName = Literal[
     "autoseparators",
     "background",
@@ -2638,52 +2639,106 @@ class Text(Widget, XView, YView):
     def configure(self, cnf: _TextOptionName) -> Tuple[str, str, str, Any, Any]: ...
     config = configure
     def cget(self, key: _TextOptionName) -> Any: ...
-    def bbox(self, index): ...
-    def compare(self, index1, op, index2): ...
-    def count(self, index1, index2, *args): ...
-    def debug(self, boolean: Optional[Any] = ...): ...
-    def delete(self, index1, index2: Optional[Any] = ...): ...
-    def dlineinfo(self, index): ...
-    def dump(self, index1, index2: Optional[Any] = ..., command: Optional[Any] = ..., **kw): ...
-    def edit(self, *args): ...
-    def edit_modified(self, arg: Optional[Any] = ...): ...
-    def edit_redo(self): ...
-    def edit_reset(self): ...
-    def edit_separator(self): ...
-    def edit_undo(self): ...
-    def get(self, index1, index2: Optional[Any] = ...): ...
+    def bbox(self, index: _TextIndex) -> Optional[Tuple[int, int, int, int]]: ...
+    def compare(self, index1: _TextIndex, op: Literal["<", "<=", "==", ">=", ">", "!="], index2: _TextIndex) -> bool: ...
+    def count(self, index1, index2, *args): ...  # TODO
+    @overload
+    def debug(self, boolean: None = ...) -> bool: ...
+    @overload
+    def debug(self, boolean: bool) -> None: ...
+    def delete(self, index1: _TextIndex, index2: Optional[_TextIndex] = ...) -> None: ...
+    def dlineinfo(self, index: _TextIndex) -> Optional[Tuple[int, int, int, int, int]]: ...
+    @overload
+    def dump(
+        self,
+        index1: _TextIndex,
+        index2: Optional[_TextIndex] = ...,
+        command: None = ...,
+        *,
+        all: bool = ...,
+        image: bool = ...,
+        mark: bool = ...,
+        tag: bool = ...,
+        text: bool = ...,
+        window: bool = ...,
+    ) -> List[Tuple[str, str, str]]: ...
+    @overload
+    def dump(
+        self,
+        index1: _TextIndex,
+        index2: Optional[_TextIndex],
+        command: Union[Callable[[str, str, str], None], str],
+        *,
+        all: bool = ...,
+        image: bool = ...,
+        mark: bool = ...,
+        tag: bool = ...,
+        text: bool = ...,
+        window: bool = ...,
+    ) -> None: ...
+    @overload
+    def dump(
+        self,
+        index1: _TextIndex,
+        index2: Optional[_TextIndex] = ...,
+        *,
+        command: Union[Callable[[str, str, str], None], str],
+        all: bool = ...,
+        image: bool = ...,
+        mark: bool = ...,
+        tag: bool = ...,
+        text: bool = ...,
+        window: bool = ...,
+    ) -> None: ...
+    def edit(self, *args): ...  # docstring says "Internal method"
+    @overload
+    def edit_modified(self, arg: None = ...) -> bool: ...  # actually returns Literal[0, 1]
+    @overload
+    def edit_modified(self, arg: bool) -> None: ...  # actually returns empty string
+    def edit_redo(self) -> None: ...  # actually returns empty string
+    def edit_reset(self) -> None: ...  # actually returns empty string
+    def edit_separator(self) -> None: ...  # actually returns empty string
+    def edit_undo(self) -> None: ...  # actually returns empty string
+    def get(self, index1: _TextIndex, index2: Optional[_TextIndex] = ...) -> str: ...
+    # TODO: image_* methods
     def image_cget(self, index, option): ...
     def image_configure(self, index, cnf: Optional[Any] = ..., **kw): ...
     def image_create(self, index, cnf=..., **kw): ...
     def image_names(self): ...
-    def index(self, index): ...
-    def insert(self, index, chars, *args): ...
-    def mark_gravity(self, markName, direction: Optional[Any] = ...): ...
-    def mark_names(self): ...
-    def mark_set(self, markName, index): ...
-    def mark_unset(self, *markNames): ...
-    def mark_next(self, index): ...
-    def mark_previous(self, index): ...
-    def peer_create(self, newPathName, cnf=..., **kw): ...
-    def peer_names(self): ...
-    def replace(self, index1, index2, chars, *args): ...
-    def scan_mark(self, x, y): ...
-    def scan_dragto(self, x, y): ...
+    def index(self, index: _TextIndex) -> str: ...
+    def insert(self, index: _TextIndex, chars: str, *args: Union[_TextIndex, str, _TkinterSequence[str]]) -> None: ...
+    @overload
+    def mark_gravity(self, markName: str, direction: None = ...) -> Literal["left", "right"]: ...
+    @overload
+    def mark_gravity(self, markName: str, direction: Literal["left", "right"]) -> None: ...  # actually returns empty string
+    def mark_names(self) -> Tuple[str, ...]: ...
+    def mark_set(self, markName: str, index: _TextIndex) -> None: ...
+    def mark_unset(self, *markNames: str) -> None: ...
+    def mark_next(self, index: _TextIndex) -> Optional[str]: ...
+    def mark_previous(self, index: _TextIndex): ...
+    # **kw of peer_create is same as the kwargs of Text.__init__
+    def peer_create(self, newPathName: Union[str, Text], cnf: Dict[str, Any] = ..., **kw: Any) -> None: ...
+    def peer_names(self) -> Tuple[_tkinter.Tcl_Obj, ...]: ...
+    def replace(
+        self, index1: _TextIndex, index2: _TextIndex, chars: str, *args: Union[_TextIndex, str, _TkinterSequence[str]]
+    ) -> None: ...
+    def scan_mark(self, x: int, y: int) -> None: ...
+    def scan_dragto(self, x: int, y: int) -> None: ...
     def search(
         self,
-        pattern,
-        index,
-        stopindex: Optional[Any] = ...,
-        forwards: Optional[Any] = ...,
-        backwards: Optional[Any] = ...,
-        exact: Optional[Any] = ...,
-        regexp: Optional[Any] = ...,
-        nocase: Optional[Any] = ...,
-        count: Optional[Any] = ...,
-        elide: Optional[Any] = ...,
-    ): ...
-    def see(self, index): ...
-    def tag_add(self, tagName, index1, *args): ...
+        pattern: str,
+        index: _TextIndex,
+        stopindex: Optional[_TextIndex] = ...,
+        forwards: Optional[bool] = ...,
+        backwards: Optional[bool] = ...,
+        exact: Optional[bool] = ...,
+        regexp: Optional[bool] = ...,
+        nocase: Optional[bool] = ...,
+        count: Optional[Variable] = ...,
+        elide: Optional[bool] = ...,
+    ) -> str: ...  # returns empty string for not found
+    def see(self, index: _TextIndex) -> None: ...
+    def tag_add(self, tagName: str, index1: _TextIndex, *args: _TextIndex) -> None: ...
     # tag_bind stuff is very similar to Canvas
     @overload
     def tag_bind(
@@ -2696,23 +2751,66 @@ class Text(Widget, XView, YView):
     @overload
     def tag_bind(self, tagName: str, sequence: Optional[str], func: str, add: Optional[bool] = ...) -> None: ...
     def tag_unbind(self, tagName: str, sequence: str, funcid: Optional[str] = ...) -> None: ...
-    def tag_cget(self, tagName, option): ...
-    def tag_configure(self, tagName, cnf: Optional[Any] = ..., **kw): ...
-    tag_config: Any
-    def tag_delete(self, *tagNames): ...
-    def tag_lower(self, tagName, belowThis: Optional[Any] = ...): ...
-    def tag_names(self, index: Optional[Any] = ...): ...
-    def tag_nextrange(self, tagName, index1, index2: Optional[Any] = ...): ...
-    def tag_prevrange(self, tagName, index1, index2: Optional[Any] = ...): ...
-    def tag_raise(self, tagName, aboveThis: Optional[Any] = ...): ...
-    def tag_ranges(self, tagName): ...
-    def tag_remove(self, tagName, index1, index2: Optional[Any] = ...): ...
+    # allowing any string for cget instead of just Literals because there's no other way to look up tag options
+    def tag_cget(self, tagName: str, option: str) -> Any: ...
+    @overload
+    def tag_configure(
+        self,
+        tagName: str,
+        cnf: Optional[Dict[str, Any]] = ...,
+        *,
+        background: _Color = ...,
+        bgstipple: _Bitmap = ...,
+        borderwidth: _ScreenUnits = ...,
+        border: _ScreenUnits = ...,  # alias for borderwidth
+        elide: bool = ...,
+        fgstipple: _Bitmap = ...,
+        font: _FontDescription = ...,
+        foreground: _Color = ...,
+        justify: Literal["left", "right", "center"] = ...,
+        lmargin1: _ScreenUnits = ...,
+        lmargin2: _ScreenUnits = ...,
+        lmargincolor: _Color = ...,
+        offset: _ScreenUnits = ...,
+        overstrike: bool = ...,
+        overstrikefg: _Color = ...,
+        relief: _Relief = ...,
+        rmargin: _ScreenUnits = ...,
+        rmargincolor: _Color = ...,
+        selectbackground: _Color = ...,
+        selectforeground: _Color = ...,
+        spacing1: _ScreenUnits = ...,
+        spacing2: _ScreenUnits = ...,
+        spacing3: _ScreenUnits = ...,
+        tabs: Any = ...,  # the exact type is kind of complicated, see manual page
+        tabstyle: Literal["tabular", "wordprocessor"] = ...,
+        underline: bool = ...,
+        underlinefg: _Color = ...,
+        wrap: Literal["none", "char", "word"] = ...,  # be careful with "none" vs None
+    ) -> Optional[Dict[str, Tuple[str, str, str, Any, Any]]]: ...
+    @overload
+    def tag_configure(self, tagName: str, cnf: str) -> Tuple[str, str, str, Any, Any]: ...
+    tag_config = tag_configure
+    def tag_delete(self, __first_tag_name: str, *tagNames: str) -> None: ...  # error if no tag names given
+    def tag_lower(self, tagName: str, belowThis: Optional[str] = ...) -> None: ...
+    def tag_names(self, index: Optional[_TextIndex] = ...) -> Tuple[str, ...]: ...
+    def tag_nextrange(
+        self, tagName: str, index1: _TextIndex, index2: Optional[_TextIndex] = ...
+    ) -> Union[Tuple[str, str], Tuple[()]]: ...
+    def tag_prevrange(
+        self, tagName: str, index1: _TextIndex, index2: Optional[_TextIndex] = ...
+    ) -> Union[Tuple[str, str], Tuple[()]]: ...
+    def tag_raise(self, tagName: str, aboveThis: Optional[str] = ...) -> None: ...
+    def tag_ranges(self, tagName: str) -> Tuple[_tkinter.Tcl_Obj, ...]: ...
+    # tag_remove and tag_delete are different
+    def tag_remove(self, tagName: str, index1: _TextIndex, index2: Optional[_TextIndex] = ...) -> None: ...
+    # TODO: window_* methods
     def window_cget(self, index, option): ...
     def window_configure(self, index, cnf: Optional[Any] = ..., **kw): ...
-    window_config: Any
+    window_config = window_configure
     def window_create(self, index, cnf=..., **kw): ...
     def window_names(self): ...
-    def yview_pickplace(self, *what): ...
+    def yview_pickplace(self, *what): ...  # deprecated
 
 class _setit:
     def __init__(self, var, value, callback: Optional[Any] = ...): ...