Add method annotations (all args and return-values are Any)

[junkmd]

#400

Type annotations in the codebase of modules generated in the gen directory that can be interpreted by the static type checker are defined under the if TYPE_CHECKING: block.

Changes in generated modules

The IDictionary in the module generated by GetModule("scrrun.dll") is defined as shown below.

class IDictionary(comtypes.gen._00020430_0000_0000_C000_000000000046_0_2_0.IDispatch):
    """Scripting.Dictionary Interface"""
    _case_insensitive_ = True
    _iid_ = GUID('{42C642C1-97E1-11CF-978F-00A02463E06F}')
    _idlflags_ = ['hidden', 'dual', 'oleautomation']

    if TYPE_CHECKING:  # commembers
        def _get_Item(self, Key: Any) -> Any: ...
        def _set_Item(self, Key: Any, pRetItem: Any) -> Any: ...
        def _setref_Item(self, Key: Any, pRetItem: Any) -> Any: ...
        Item = hints.named_property('Item', _get_Item, hints.put_or_putref(_set_Item, _setref_Item))
        __call__ = hints.to_dunder_call(Item)
        __getitem__ = hints.to_dunder_getitem(Item)
        __setitem__ = hints.to_dunder_setitem(Item)
        def Add(self, Key: Any, Item: Any) -> Any: ...
        def _get_Count(self) -> Any: ...
        Count = hints.normal_property(_get_Count)
        __len__ = hints.to_dunder_len(Count)
        def Exists(self, Key: Any) -> Any: ...
        def Items(self) -> Any: ...
        def _set_Key(self, Key: Any, rhs: Any) -> Any: ...
        Key = hints.named_property('Key', fset=_set_Key)
        def Keys(self) -> Any: ...
        def Remove(self, Key: Any) -> Any: ...
        def RemoveAll(self) -> Any: ...
        def _get_CompareMode(self) -> Any: ...
        def _set_CompareMode(self, pcomp: Any) -> Any: ...
        CompareMode = hints.normal_property(_get_CompareMode, _set_CompareMode)
        def _NewEnum(self) -> Any: ...
        __iter__ = hints.to_dunder_iter(_NewEnum)
        def _get_HashVal(self, Key: Any) -> Any: ...
        HashVal = hints.named_property('HashVal', _get_HashVal)

The Picture in the module generated by GetModule("stdole2.tlb") is defined as shown below.

class Picture(IDispatch):
    _case_insensitive_ = True
    _iid_ = GUID('{7BF80981-BF32-101A-8BBB-00AA00300CAB}')
    _idlflags_ = []
    _methods_ = []

    if TYPE_CHECKING:  # dispmembers
        @property  # dispprop
        def Handle(self) -> Any: ...
        @property  # dispprop
        def hPal(self) -> Any: ...
        @property  # dispprop
        def Type(self) -> Any: ...
        @property  # dispprop
        def Width(self) -> Any: ...
        @property  # dispprop
        def Height(self) -> Any: ...
        def Render(self, hdc: Any, x: Any, y: Any, cx: Any, cy: Any, xSrc: Any, ySrc: Any, cxSrc: Any, cySrc: Any, prcWBounds: Any) -> Any: ...

Changes in hints.pyi

I have added a lot of type inference magic tools to hints.pyi!

The following type information is conveyed to the static type checker by helpers...

• Type information about descriptor behavior that could not be expressed by the built-in property or _memberspec.named_property
• Type information about the behavior of dunder methods patched to com interfaces by metaclasses

These tools use the functionality of the third-party typing_extensions, depending on the version of Python.
They are used in the stub file and under the if TYPE_CHECKING: block, so NOT need to install typing_extensions as runtime prerequisite.

Addition of typeannotator.py

Initially, type annotation stuffs were defined in codegenerator.py.
However, the amount of codebase I added grew so large that it became difficult to see the changes.
So I decided to add a new module with an appropriate name based on responsibility.

Why all args and return-values are Any?

Initially, I tried to do detailed type annotations for return values and arguments as well. However, the process of deriving Python-friendly type annotations from typedesc would require several hundred additional lines of codebase and possibly refactoring/adding functionality to typedesc and tlbparser.
I plan to add functionality for more detailed type annotations than Any after the 1.3.0 release, according to the feedback from the community.

Workarounds

Some COM libraries have implementations that are not compatible with the Python language specifications. These include having required arguments that come after optional arguments, using argument names that conflict with reserved words in Python.

Such method definitions causes SyntaxError even if under the if TYPE_CHECKING: block. To prevent those problems, using *args: Any or **kwargs: Any instead of using the arguments defined by the COM libraries.

# class CLASSNAME_Impl: comments

Since the beginning of this package, the codebase of the modules generated in the gen directory also generates comments, starting with # code template for CLASSNAME implementation, which would have been there to help with a simple wrapper class implementation.

Currently, the mix of comments and type annotations may confuse newcomers.

However, even if there are lack of informations on the behavior of some properties and default arguments, and they are not generated for classes that implement the dispatch method, there may be some projects that rely on the comments to do something.

Therefore, this PR does not eliminate this comment.
The future of the comment should be decided from the community feedback.

[junkmd]

CIs are passed.

memo

https://ci.appveyor.com/project/cfarrow/comtypes/builds/47606694
https://github.com/enthought/comtypes/actions/runs/5624064937/job/15240085370?pr=490
https://ci.appveyor.com/project/pywinauto/pywinauto/builds/47606833

previous e5268b6

https://ci.appveyor.com/project/cfarrow/comtypes/builds/47384206
https://github.com/enthought/comtypes/actions/runs/5362505450/jobs/9729429611?pr=490
https://ci.appveyor.com/project/pywinauto/pywinauto/builds/47384231

[junkmd]

@vasily-v-ryabov
Would you agree to include this in the 1.3.0 release?

The large amount of changes and using Python's latest type annotation feature.

Please feel free to ask questions, and any opinions would be appreciated.