Introducing type annotations

[junkmd]

Before my summer vacation, I'd like to share my proposal.

Lately, I've been providing responses like "That method is only available in FooWrapper, not in the BarWrapper you're using" for recent discussions and issues.

I think that part of the reasons are it's not always clear what backend one is using and what wrapper classes are available for it.

With type annotations, during development using an IDE, we can refer to types from tooltips and use "jump to the definition".

For example, adding type annotations to BackEnd, WindowSpecification and Desktop would make it easy to understand what each method of Desktop.

# pywinauto/backend.py

from .element_info import ElementInfo
from .base_wrapper import BaseWrapper

_T_ElmInfo = TypeVar("_T_ElmInfo", bound=ElementInfo)
_T_Wrapper = TypeVar("_T_Wrapper", bound=BaseWrapper)


class BackEnd(Generic[_T_ElmInfo, _T_Wrapper]):

    element_info_class: Type[_T_ElmInfo]
    generic_wrapper_class: Type[_T_Wrapper]

# pywinauto/base_application.py

class WindowSpecification(Generic[_T_ElmInfo, _T_Wrapper]):
    ...

# pywinauto/__init__.py

class Desktop(Generic[_T_ElmInfo, _T_Wrapper]):

    backend: backends.BackEnd[_T_ElmInfo, _T_Wrapper]

    if TYPE_CHECKING:
        from typing import Literal
        from .controls.hwndwrapper import HwndElementInfo, HwndWrapper
        from .controls.uiawrapper import UIAElementInfo, UIAWrapper
        from .controls.atspiwrapper import AtspiElementInfo, AtspiWrapper
        @overload  # noqa: E301
        def __new__(  # noqa: E704
            cls, backend: Literal["win32"], allow_magic_lookup: bool = ...
        ) -> "Desktop[HwndElementInfo, HwndWrapper]": ...
        @overload  # noqa: E301
        def __new__(  # noqa: E704
            cls, backend: Literal["uia"], allow_magic_lookup: bool = ...
        ) -> "Desktop[UIAElementInfo, UIAWrapper]": ...
        @overload  # noqa: E301
        def __new__(  # noqa: E704
            cls, backend: Literal["atspi"], allow_magic_lookup: bool = ...
        ) -> "Desktop[AtspiElementInfo, AtspiWrapper]": ...
        def __new__(cls, backend=..., allow_magic_lookup=...) -> "Desktop":  # noqa: E301
            ...


    def __init__(self, backend: Optional[str] = None, allow_magic_lookup: bool = True) -> None:
        ...

    def window(self, **kwargs: Any) -> WindowSpecification[_T_ElmInfo, _T_Wrapper]:
        ...

    def windows(self, **kwargs: Any) -> List[_T_Wrapper]:
        ...

    def __getitem__(self, key: Any) -> WindowSpecification[_T_ElmInfo, _T_Wrapper]:
        ...

    def from_point(self, x: int, y: int) -> _T_Wrapper:
        ...

    def top_from_point(self, x: int, y: int) -> _T_Wrapper:
        ...

    def get_active(self) -> _T_Wrapper:
        ...

Of course, I'm aware that there are ongoing challenges with pywinauto and there are more prioritized tasks ahead.

However, I believe introducing type annotations will undoubtedly make this package more user and developer friendly.

Once the "next version" is released, I think I'll be able to dedicate resources to type annotations.

Any opinions would be appreciated.

[junkmd]

Even developers who do not use Application or Desktop can benefit from type hints.

By defining overloads for each control_type Literals, static type checkers can constrain argument types and infer return types.

# pywinauto/controls/uiawrapper.py

...

from typing import TYPE_CHECKING

...

if TYPE_CHECKING:
    from typing import Iterator, List, Optional, overload
    from typing_extensions import Literal, TypeAlias, TypedDict, Unpack

    class _ChildrenConditions(TypedDict, total=False):
        process: Optional[int]
        class_name: Optional[str]
        name: Optional[str]
        content_only: Optional[bool]

    _ChKw: TypeAlias = _ChildrenConditions

    class _DescendantsConditions(TypedDict, total=False):
        depth: Optional[int]

    _DeKw: TypeAlias = _DescendantsConditions

    _WindowTypeStr: TypeAlias = Literal["Window"]
    _ButtonTypeStr: TypeAlias = Literal["Button", "CheckBox", "RadioButton"]
    _ComboBoxTypeStr: TypeAlias = Literal["ComboBox"]
    _EditTypeStr: TypeAlias = Literal["Edit"]
    _TabControlTypeStr: TypeAlias = Literal["Tab"]
    _SliderTypeStr: TypeAlias = Literal["Slider"]
    _HeaderTypeStr: TypeAlias = Literal["Header"]
    _HeaderItemTypeStr: TypeAlias = Literal["HeaderItem"]
    _ListItemTypeStr: TypeAlias = Literal["DataItem", "ListItem"]
    _ListViewTypeStr: TypeAlias = Literal["DataGrid", "List", "Table"]
    _MenuItemTypeStr: TypeAlias = Literal["MenuItem"]
    _MenuTypeStr: TypeAlias = Literal["MenuBar", "Menu"]
    _TooltipTypeStr: TypeAlias = Literal["ToolTip"]
    _ToolbarTypeStr: TypeAlias = Literal["ToolBar"]
    _TreeItemTypeStr: TypeAlias = Literal["TreeItem"]
    _TreeViewTypeStr: TypeAlias = Literal["Tree"]
    _StaticTypeStr: TypeAlias = Literal["Text"]
    _UndefinedTypeStr: TypeAlias = Literal[
        "AppBar", "Calendar", "Custom", "Document", "Group", "Hyperlink",
        "Image", "Pane", "ProgressBar", "ScrollBar", "SemanticZoom",
        "Separator", "Spinner", "SplitButton", "StatusBar", "TabItem",
        "Text", "Thumb", "TitleBar",
    ]
    from pywinauto.controls import uia_controls as _uia_ctrls

...

@six.add_metaclass(UiaMeta)
class UIAWrapper(WinBaseWrapper):
    if TYPE_CHECKING:
        # children
        @overload  # type: ignore
        def children(self, *, control_type: Optional[int] = ..., **kwargs: Unpack[_ChKw]) -> List["UIAWrapper"]: ...  # type: ignore  # noqa: E501 E704
        @overload
        def children(self, *, control_type: _WindowTypeStr, **kwargs: Unpack[_ChKw]) -> List[_uia_ctrls.WindowWrapper]: ...  # noqa: E501 E704
        @overload
        def children(self, *, control_type: _ButtonTypeStr, **kwargs: Unpack[_ChKw]) -> List[_uia_ctrls.ButtonWrapper]: ...  # noqa: E501 E704
        @overload
        def children(self, *, control_type: _ComboBoxTypeStr, **kwargs: Unpack[_ChKw]) -> List[_uia_ctrls.ComboBoxWrapper]: ...  # noqa: E501 E704
        @overload
        def children(self, *, control_type: _EditTypeStr, **kwargs: Unpack[_ChKw]) -> List[_uia_ctrls.EditWrapper]: ...  # noqa: E501 E704
        @overload
        def children(self, *, control_type: _TabControlTypeStr, **kwargs: Unpack[_ChKw]) -> List[_uia_ctrls.TabControlWrapper]: ...  # noqa: E501 E704
        @overload
        def children(self, *, control_type: _SliderTypeStr, **kwargs: Unpack[_ChKw]) -> List[_uia_ctrls.SliderWrapper]: ...  # noqa: E501 E704
        @overload
        def children(self, *, control_type: _HeaderTypeStr, **kwargs: Unpack[_ChKw]) -> List[_uia_ctrls.HeaderWrapper]: ...  # noqa: E501 E704
        @overload
        def children(self, *, control_type: _HeaderItemTypeStr, **kwargs: Unpack[_ChKw]) -> List[_uia_ctrls.HeaderItemWrapper]: ...  # noqa: E501 E704
        @overload
        def children(self, *, control_type: _ListItemTypeStr, **kwargs: Unpack[_ChKw]) -> List[_uia_ctrls.ListItemWrapper]: ...  # noqa: E501 E704
        @overload
        def children(self, *, control_type: _ListViewTypeStr, **kwargs: Unpack[_ChKw]) -> List[_uia_ctrls.ListViewWrapper]: ...  # noqa: E501 E704
        @overload
        def children(self, *, control_type: _MenuItemTypeStr, **kwargs: Unpack[_ChKw]) -> List[_uia_ctrls.MenuItemWrapper]: ...  # noqa: E501 E704
        @overload
        def children(self, *, control_type: _MenuTypeStr, **kwargs: Unpack[_ChKw]) -> List[_uia_ctrls.MenuWrapper]: ...  # noqa: E501 E704
        @overload
        def children(self, *, control_type: _TooltipTypeStr, **kwargs: Unpack[_ChKw]) -> List[_uia_ctrls.TooltipWrapper]: ...  # noqa: E501 E704
        @overload
        def children(self, *, control_type: _ToolbarTypeStr, **kwargs: Unpack[_ChKw]) -> List[_uia_ctrls.ToolbarWrapper]: ...  # noqa: E501 E704
        @overload
        def children(self, *, control_type: _TreeItemTypeStr, **kwargs: Unpack[_ChKw]) -> List[_uia_ctrls.TreeItemWrapper]: ...  # noqa: E501 E704
        @overload
        def children(self, *, control_type: _TreeViewTypeStr, **kwargs: Unpack[_ChKw]) -> List[_uia_ctrls.TreeViewWrapper]: ...  # noqa: E501 E704
        @overload
        def children(self, *, control_type: _StaticTypeStr, **kwargs: Unpack[_ChKw]) -> List[_uia_ctrls.StaticWrapper]: ...  # noqa: E501 E704
        @overload
        def children(self, *, control_type: _UndefinedTypeStr, **kwargs: Unpack[_ChKw]) -> List["UIAWrapper"]: ...  # noqa: E501 E704
        # # iter_children
        # @overload  # type: ignore
        # def iter_children(self, *, control_type: Optional[int] = ..., **kwargs: Unpack[_ChKw]) -> Iterator["UIAWrapper"]: ...  # type: ignore  # noqa: E501 E704
        # ...
        # @overload
        # def iter_children(self, *, control_type: _UndefinedTypeStr, **kwargs: Unpack[_ChKw]) -> Iterator["UIAWrapper"]: ...  # noqa: E501 E704
        # # descendants
        # @overload  # type: ignore
        # def descendants(self, *, control_type: Optional[int] = ..., **kwargs: Unpack[_DeKw]) -> List["UIAWrapper"]: ...  # type: ignore  # noqa: E501 E704
        # ...
        # @overload
        # def descendants(self, *, control_type: _UndefinedTypeStr, **kwargs: Unpack[_DeKw]) -> List["UIAWrapper"]: ...  # noqa: E501 E704
        # # iter_descendants
        # @overload  # type: ignore
        # def iter_descendants(self, *, control_type: Optional[int] = ..., **kwargs: Unpack[_DeKw]) -> Iterator["UIAWrapper"]: ...  # type: ignore  # noqa: E501 E704
        # ...
        # @overload
        # def iter_descendants(self, *, control_type: _UndefinedTypeStr, **kwargs: Unpack[_DeKw]) -> Iterator["UIAWrapper"]: ...  # noqa: E501 E704
    ...

...

# simple usecases...
root = UIAWrapper(UIAElementInfo())

root.children()  # List[UIAWrapper]
root.children(control_type="Button")  # List[ButtonWrapper]
root.children(control_type="DataGrid")  # List[ListViewWrapper]
root.children(control_type="List")  # List[ListViewWrapper]
root.children(control_type="Table")  # List[ListViewWrapper]
root.children(control_type="Custom")  # List[UIAWrapper]
root.children(process=1234)  # List[UIAWrapper]
root.children(process=None)  # List[UIAWrapper]

root.children(control_type="Spam")  # Invalid
root.children(foo=...)  # Invalid