Enhance type hints and make type containers generic for compatibility in tools.

comtypes/hints.pyi

@@ -12,16 +12,18 @@ from typing import Union as _UnionT
 
 if sys.version_info >= (3, 10):
     from typing import Concatenate, ParamSpec, TypeAlias
-    from typing import TypeGuard as TypeGuard
 else:
     from typing_extensions import Concatenate, ParamSpec, TypeAlias
-    from typing_extensions import TypeGuard as TypeGuard
 if sys.version_info >= (3, 11):
     from typing import Self as Self
     from typing import Unpack as Unpack
 else:
     from typing_extensions import Self as Self
     from typing_extensions import Unpack as Unpack
+if sys.version_info >= (3, 13):
+    from typing import TypeIs as TypeIs
+else:
+    from typing_extensions import TypeIs as TypeIs
 
 import comtypes
 from comtypes import IUnknown as IUnknown, COMObject as COMObject, GUID as GUID

comtypes/tools/codegenerator/codegenerator.py

@@ -8,7 +8,7 @@
 import textwrap
 import warnings
 from collections.abc import Iterable, Iterator, Mapping, Sequence
-from typing import Any, Literal, Optional
+from typing import TYPE_CHECKING, Any, Literal, Optional
 from typing import Union as _UnionT
 
 import comtypes
@@ -25,6 +25,10 @@
 )
 from comtypes.tools.codegenerator.modulenamer import name_wrapper_module
 
+if TYPE_CHECKING:
+    from comtypes import hints  # type: ignore
+
+
 version = comtypes.__version__
 
 logger = logging.getLogger(__name__)
@@ -569,9 +573,7 @@ def CoClass(self, coclass: typedesc.CoClass) -> None:
 
         self.names.add(coclass.name)
 
-    def _is_interface_typedesc(
-        self, item: Any
-    ) -> "comtypes.hints.TypeGuard[_InterfaceTypeDesc]":
+    def _is_interface_typedesc(self, item: Any) -> "hints.TypeIs[_InterfaceTypeDesc]":
         return isinstance(
             item,
             (

comtypes/tools/codegenerator/helpers.py

@@ -1,11 +1,13 @@
 import keyword
 from collections.abc import Iterator
-from typing import Any
+from typing import Any, TypeVar, overload
 from typing import Union as _UnionT
 
 from comtypes.tools import typedesc
 from comtypes.tools.codegenerator.modulenamer import name_wrapper_module
 
+_TD = TypeVar("_TD")
+
 
 class lcid:
     def __repr__(self):
@@ -53,6 +55,10 @@ def __repr__(self):
 }
 
 
+@overload
+def get_real_type(tp: typedesc.Typedef[_TD]) -> _TD: ...
+@overload
+def get_real_type(tp: _TD) -> _TD: ...
 def get_real_type(tp):
     if type(tp) is typedesc.Typedef:
         return get_real_type(tp.typ)

comtypes/tools/tlbparser.py

@@ -4,7 +4,7 @@
 from collections.abc import Mapping
 from ctypes import alignment, c_void_p, sizeof, windll
 from ctypes.wintypes import MAX_PATH
-from typing import Any, Optional
+from typing import Any, Optional, TypeVar, overload
 from typing import Union as _UnionT
 
 from comtypes import automation, typeinfo
@@ -15,8 +15,14 @@
 
 
 ################################
+_PT = TypeVar("_PT", bound=_UnionT["ParsedType", "SpecType"])
+_TypeDefNone = typedesc.Typedef[None]
 
 
+@overload
+def PTR(typ: _PT) -> typedesc.PointerType[_PT]: ...
+@overload
+def PTR(typ: _TypeDefNone) -> typedesc.PointerType[_TypeDefNone]: ...
 def PTR(typ):
     return typedesc.PointerType(typ, sizeof(c_void_p) * 8, alignment(c_void_p) * 8)
 
@@ -62,7 +68,7 @@ def PTR(typ):
 )
 
 
-def midlSAFEARRAY(typ):
+def midlSAFEARRAY(typ: _PT) -> typedesc.SAFEARRAYType[_PT]:
     return typedesc.SAFEARRAYType(typ)
 
 
@@ -116,17 +122,18 @@ def midlSAFEARRAY(typ):
     typedesc.CoClass,
     typedesc.ComInterface,
     typedesc.DispInterface,
-    typedesc.Typedef,
+    typedesc.Typedef["_UnionT[ParsedType, SpecType]"],
+    _TypeDefNone,
     typedesc.Structure,
     typedesc.Union,
     typedesc.Enumeration,
 ]
 
 SpecType = _UnionT[
     typedesc.FundamentalType,
-    typedesc.PointerType,
-    typedesc.ArrayType,
-    typedesc.SAFEARRAYType,
+    typedesc.PointerType["_UnionT[ParsedType, SpecType]"],
+    typedesc.ArrayType["_UnionT[ParsedType, SpecType]"],
+    typedesc.SAFEARRAYType["_UnionT[ParsedType, SpecType]"],
 ]
 ################################################################
 

comtypes/tools/typedesc.py

@@ -3,7 +3,7 @@
 
 import ctypes
 from collections.abc import Sequence
-from typing import Any, Optional
+from typing import Any, Generic, Optional, TypeVar
 from typing import Union as _UnionT
 
 from comtypes import typeinfo
@@ -31,6 +31,8 @@
 from comtypes.tools.typedesc_base import Variable as Variable
 from comtypes.typeinfo import TLIBATTR, ITypeLib
 
+_TD = TypeVar("_TD")
+
 
 class TypeLib:
     def __init__(
@@ -83,8 +85,8 @@ def get_head(self) -> "External":
         return self
 
 
-class SAFEARRAYType:
-    def __init__(self, typ: Any) -> None:
+class SAFEARRAYType(Generic[_TD]):
+    def __init__(self, typ: _TD) -> None:
         self.typ = typ
         self.align = self.size = ctypes.sizeof(ctypes.c_void_p) * 8
 

comtypes/tools/typedesc_base.py

@@ -1,7 +1,9 @@
 # typedesc.py - classes representing C type descriptions
-from typing import Any, Optional, SupportsInt
+from typing import Any, Generic, Optional, SupportsInt, TypeVar
 from typing import Union as _UnionT
 
+_TD = TypeVar("_TD")
+
 
 class Argument:
     "a Parameter in the argument list of a callable (Function, Method, ...)"
@@ -114,27 +116,27 @@ def __init__(self, name: str, size: int, align: int) -> None:
         self.align = int(align)
 
 
-class PointerType:
+class PointerType(Generic[_TD]):
     location = None
 
-    def __init__(self, typ, size, align):
+    def __init__(self, typ: _TD, size: int, align: int) -> None:
         self.typ = typ
         self.size = int(size)
         self.align = int(align)
 
 
-class Typedef:
+class Typedef(Generic[_TD]):
     location = None
 
-    def __init__(self, name, typ):
+    def __init__(self, name: str, typ: _TD) -> None:
         self.name = name
         self.typ = typ
 
 
-class ArrayType:
+class ArrayType(Generic[_TD]):
     location = None
 
-    def __init__(self, typ: Any, min: int, max: int) -> None:
+    def __init__(self, typ: _TD, min: int, max: int) -> None:
         self.typ = typ
         self.min = min
         self.max = max