add Incomplete and Hresult to hints.pyi (enthought#532)

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

* fix grammars

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]

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)