From b046b46d2ed5bcad1029602528f4082cfdbf9bbc Mon Sep 17 00:00:00 2001
From: Jun Komoda <45822440+junkmd@users.noreply.github.com>
Date: Tue, 23 Apr 2024 09:54:44 +0900
Subject: [PATCH] add `Incomplete` and `Hresult` to `hints.pyi` (#532)

* add `Incomplete` and `Hresult` to `hints.pyi`

* fix grammars
---
 comtypes/hints.pyi              | 14 ++++++++++++--
 comtypes/tools/typeannotator.py | 17 +++++++++--------
 2 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/comtypes/hints.pyi b/comtypes/hints.pyi
index 522e0673..30fb4906 100644
--- a/comtypes/hints.pyi
+++ b/comtypes/hints.pyi
@@ -22,9 +22,9 @@ if sys.version_info >= (3, 8):
 else:
     from typing_extensions import Protocol
 if sys.version_info >= (3, 10):
-    from typing import Concatenate, ParamSpec
+    from typing import Concatenate, ParamSpec, TypeAlias
 else:
-    from typing_extensions import Concatenate, ParamSpec
+    from typing_extensions import Concatenate, ParamSpec, TypeAlias
 if sys.version_info >= (3, 11):
     from typing import Self
 else:
@@ -34,6 +34,16 @@ from comtypes.automation import IDispatch as IDispatch, VARIANT as VARIANT
 from comtypes.server import IClassFactory as IClassFactory
 from comtypes.typeinfo import ITypeInfo as ITypeInfo
 
+Incomplete: TypeAlias = Any
+"""The type symbol is used temporarily until the COM library parsers or
+code generators are enhanced to annotate detailed type hints.
+"""
+
+Hresult: TypeAlias = int
+"""The value returned when calling a method with no `[out]` or `[out, retval]`
+arguments and with `HRESULT` as its return type in its COM method definition.
+"""
+
 class _MethodTypeDesc(Protocol):
     arguments: List[Tuple[Any, str, List[str], Optional[Any]]]
     idlflags: List[str]
diff --git a/comtypes/tools/typeannotator.py b/comtypes/tools/typeannotator.py
index d2326b3f..db38690d 100644
--- a/comtypes/tools/typeannotator.py
+++ b/comtypes/tools/typeannotator.py
@@ -236,13 +236,13 @@ def getvalue(self, name: str) -> str:
                     #       should be a special callback.
                     inargs.append("**kwargs: Any")
                     break
-                inargs.append(f"{argname}: Any")
+                inargs.append(f"{argname}: hints.Incomplete")
             else:
-                inargs.append(f"{argname}: Any = ...")
+                inargs.append(f"{argname}: hints.Incomplete = ...")
                 has_optional = True
-        outargs = ["Any" for _ in self._iter_outarg_specs()]
+        outargs = ["hints.Incomplete" for _ in self._iter_outarg_specs()]
         if not outargs:
-            out = "Any"
+            out = "hints.Hresult"
         elif len(outargs) == 1:
             out = outargs[0]
         else:
@@ -279,11 +279,11 @@ def getvalue(self, name: str) -> str:
                     #       should be a special callback.
                     inargs.append("**kwargs: Any")
                     break
-                inargs.append(f"{argname}: Any")
+                inargs.append(f"{argname}: hints.Incomplete")
             else:
-                inargs.append(f"{argname}: Any = ...")
+                inargs.append(f"{argname}: hints.Incomplete = ...")
                 has_optional = True
-        out = "Any"
+        out = "hints.Incomplete"
         in_ = ("self, " + ", ".join(inargs)) if inargs else "self"
         return f"def {name}({in_}) -> {out}: ..."
 
@@ -314,7 +314,8 @@ def generate(self) -> str:
         property_lines: List[str] = []
         for mem in props:
             property_lines.append("@property  # dispprop")
-            property_lines.append(f"def {mem.name}(self) -> Any: ...")
+            out = "hints.Incomplete"
+            property_lines.append(f"def {mem.name}(self) -> {out}: ...")
         dispprops = "\n".join(f"        {p}" for p in property_lines)
         dispmethods = DispMethodsAnnotator().generate(methods)
         return "\n".join(d for d in (dispprops, dispmethods) if d)