add type annotations to client._generate and revise docstrings (#376)

* add typehints and revise docstrings

* fix imports

* fix imports

Author: junkmd

comtypes/client/_generate.py

@@ -1,41 +1,43 @@
 from __future__ import print_function
-import types
-import os
-import sys
-
-import comtypes
-from comtypes import GUID
-import comtypes.client
-from comtypes.tools import codegenerator, tlbparser
-from comtypes.typeinfo import LoadRegTypeLib, LoadTypeLibEx
+import ctypes
 import importlib
-
 import logging
-logger = logging.getLogger(__name__)
-
+import os
+import sys
+import types
 if sys.version_info >= (3, 0):
     base_text_type = str
     import winreg
 else:
     base_text_type = basestring
     import _winreg as winreg
 
+from comtypes import GUID, TYPE_CHECKING, typeinfo
+import comtypes.client
+from comtypes.tools import codegenerator, tlbparser
+
+if TYPE_CHECKING:
+    from typing import Any, Tuple, List, Optional, Union as _UnionT
+
+
+logger = logging.getLogger(__name__)
 
 PATH = os.environ["PATH"].split(os.pathsep)
 
 
 def _my_import(fullname):
+    # type: (str) -> types.ModuleType
     """helper function to import dotted modules"""
-    import comtypes.gen
-    if comtypes.client.gen_dir \
-           and comtypes.client.gen_dir not in comtypes.gen.__path__:
-        comtypes.gen.__path__.append(comtypes.client.gen_dir)
+    import comtypes.gen as g
+    if comtypes.client.gen_dir and comtypes.client.gen_dir not in g.__path__:
+        g.__path__.append(comtypes.client.gen_dir)  # type: ignore
     return importlib.import_module(fullname)
 
 
 def _resolve_filename(tlib_string, dirpath):
+    # type: (str, str) -> Tuple[str, bool]
     """Tries to make sense of a type library specified as a string.
-    
+
     Args:
         tlib_string: type library designator
         dirpath: a directory to relativize the location
@@ -63,57 +65,59 @@ def _resolve_filename(tlib_string, dirpath):
 
 
 def GetModule(tlib):
+    # type: (_UnionT[Any, typeinfo.ITypeLib]) -> types.ModuleType
     """Create a module wrapping a COM typelibrary on demand.
 
-    'tlib' must be an ITypeLib COM pointer instance, the pathname of a
-    type library, a COM CLSID GUID, or a tuple/list specifying the
-    arguments to a comtypes.typeinfo.LoadRegTypeLib call:
-
-      (libid, wMajorVerNum, wMinorVerNum, lcid=0)
-
-    Or it can be an object with _reg_libid_ and _reg_version_
-    attributes.
-
-    A relative pathname is interpreted as relative to the callers
-    __file__, if this exists.
+    'tlib' must be ...
+    - an `ITypeLib` COM pointer instance
+    - an absolute pathname of a type library
+    - a relative pathname of a type library
+      - interpreted as relative to the callers `__file__`, if this exists
+    - a COM CLSID `GUID`
+    - a `tuple`/`list` specifying the typelib
+      - `List[_UnionT[str, int]]`
+      - `(libid: str[, wMajorVerNum: int, wMinorVerNum: int[, lcid: int]])`
+    - an object with `_reg_libid_: str` and `_reg_version_: Iterable[int]`
 
     This function determines the module name from the typelib
     attributes, then tries to import it.  If that fails because the
     module doesn't exist, the module is generated into the
-    comtypes.gen package.
+    `comtypes.gen` package.
 
     It is possible to delete the whole `comtypes/gen` directory to
-    remove all generated modules, the directory and the __init__.py
+    remove all generated modules, the directory and the `__init__.py`
     file in it will be recreated when needed.
 
-    If comtypes.gen __path__ is not a directory (in a frozen
+    If `comtypes.gen.__path__` is not a directory (in a frozen
     executable it lives in a zip archive), generated modules are only
     created in memory without writing them to the file system.
 
     Example:
-
-        GetModule("shdocvw.dll")
+        GetModule("UIAutomationCore.dll")
 
     would create modules named
 
-       comtypes.gen._EAB22AC0_30C1_11CF_A7EB_0000C05BAE0B_0_1_1
-       comtypes.gen.SHDocVw
+        `comtypes.gen._944DE083_8FB8_45CF_BCB7_C477ACB2F897_L_M_m`
+          - typelib wrapper module
+          - where L, M, m are numbers of Lcid, Major-ver, minor-ver
+        `comtypes.gen.UIAutomationClient`
+          - friendly named module
 
     containing the Python wrapper code for the type library used by
-    Internet Explorer.  The former module contains all the code, the
+    UIAutomation.  The former module contains all the code, the
     latter is a short stub loading the former.
     """
     if isinstance(tlib, base_text_type):
         tlib_string = tlib
-        # if a relative pathname is used, we try to interpret it relative to the 
-        # directory of the calling module (if not from command line)
+        # if a relative pathname is used, we try to interpret it relative to
+        # the directory of the calling module (if not from command line)
         frame = sys._getframe(1)
-        _file_ = frame.f_globals.get("__file__", None)
+        _file_ = frame.f_globals.get("__file__", None)  # type: str
         pathname, is_abs = _resolve_filename(tlib_string, _file_ and os.path.dirname(_file_))
         logger.debug("GetModule(%s), resolved: %s", pathname, is_abs)
         tlib = _load_tlib(pathname)  # don't register
         if not is_abs:
-            # try to get path after loading, but this only works if already registered            
+            # try to get path after loading, but this only works if already registered
             pathname = tlbparser.get_tlib_filename(tlib)
             if pathname is None:
                 logger.info("GetModule(%s): could not resolve to a filename", tlib)
@@ -137,36 +141,40 @@ def GetModule(tlib):
 
 
 def _load_tlib(obj):
+    # type: (Any) -> typeinfo.ITypeLib
     """Load a pointer of ITypeLib on demand."""
     # obj is a filepath or a ProgID
     if isinstance(obj, base_text_type):
         # in any case, attempt to load and if tlib_string is not valid, then raise
         # as "OSError: [WinError -2147312566] Error loading type library/DLL"
-        return LoadTypeLibEx(obj)
+        return typeinfo.LoadTypeLibEx(obj)
     # obj is a tlib GUID contain a clsid
     elif isinstance(obj, GUID):
         clsid = str(obj)
         # lookup associated typelib in registry
         with winreg.OpenKey(winreg.HKEY_CLASSES_ROOT, r"CLSID\%s\TypeLib" % clsid) as key:
             libid = winreg.EnumValue(key, 0)[1]
         with winreg.OpenKey(winreg.HKEY_CLASSES_ROOT, r"CLSID\%s\Version" % clsid) as key:
-            version = winreg.EnumValue(key, 0)[1].split(".")
-        return LoadRegTypeLib(GUID(libid), int(version[0]), int(version[1]), 0)
+            ver = winreg.EnumValue(key, 0)[1].split(".")
+        return typeinfo.LoadRegTypeLib(GUID(libid), int(ver[0]), int(ver[1]), 0)
     # obj is a sequence containing libid
     elif isinstance(obj, (tuple, list)):
-        libid, version = obj[0], obj[1:]
-        if not version:  # case of version numbers are not containing
+        libid, ver = obj[0], obj[1:]
+        if not ver:  # case of version numbers are not containing
             with winreg.OpenKey(winreg.HKEY_CLASSES_ROOT, r"TypeLib\%s" % libid) as key:
-                version = [int(v, base=16) for v in winreg.EnumKey(key, 0).split(".")]
-        return LoadRegTypeLib(GUID(libid), *version)
+                ver = [int(v, base=16) for v in winreg.EnumKey(key, 0).split(".")]
+        return typeinfo.LoadRegTypeLib(GUID(libid), *ver)
     # obj is a COMObject implementation
     elif hasattr(obj, "_reg_libid_"):
-        return LoadRegTypeLib(GUID(obj._reg_libid_), *obj._reg_version_)
-    # perhaps obj is a pointer of ITypeLib
-    return obj
+        return typeinfo.LoadRegTypeLib(GUID(obj._reg_libid_), *obj._reg_version_)
+    # obj is a pointer of ITypeLib
+    elif isinstance(obj, ctypes.POINTER(typeinfo.ITypeLib)):
+        return obj  # type: ignore
+    raise TypeError("'%r' is not supported type for loading typelib" % obj)
 
 
 def _create_module_in_file(modulename, code):
+    # type: (str, str) -> types.ModuleType
     """create module in file system, and import it"""
     # `modulename` is 'comtypes.gen.xxx'
     filename = "%s.py" % modulename.split(".")[-1]
@@ -179,18 +187,21 @@ def _create_module_in_file(modulename, code):
 
 
 def _create_module_in_memory(modulename, code):
+    # type: (str, str) -> types.ModuleType
     """create module in memory system, and import it"""
     # `modulename` is 'comtypes.gen.xxx'
+    import comtypes.gen as g
     mod = types.ModuleType(modulename)
-    abs_gen_path = os.path.abspath(comtypes.gen.__path__[0])
+    abs_gen_path = os.path.abspath(g.__path__[0])  # type: ignore
     mod.__file__ = os.path.join(abs_gen_path, "<memory>")
     exec(code, mod.__dict__)
     sys.modules[modulename] = mod
-    setattr(comtypes.gen, modulename.split(".")[-1], mod)
+    setattr(g, modulename.split(".")[-1], mod)
     return mod
 
 
 def _create_friendly_module(tlib, modulename):
+    # type: (typeinfo.ITypeLib, str) -> types.ModuleType
     """helper which creates and imports the friendly-named module."""
     try:
         mod = _my_import(modulename)
@@ -211,6 +222,7 @@ def _create_friendly_module(tlib, modulename):
 
 
 def _create_wrapper_module(tlib, pathname):
+    # type: (typeinfo.ITypeLib, Optional[str]) -> types.ModuleType
     """helper which creates and imports the real typelib wrapper module."""
     modulename = codegenerator.name_wrapper_module(tlib)
     if modulename in sys.modules:
@@ -235,13 +247,16 @@ def _create_wrapper_module(tlib, pathname):
 
 
 def _get_known_symbols():
+    # type: () -> dict[str, str]
     known_symbols = {}  # type: dict[str, str]
-    for mod_name in ("comtypes.persist",
-                 "comtypes.typeinfo",
-                 "comtypes.automation",
-                 "comtypes",
-                 "ctypes.wintypes",
-                 "ctypes"):
+    for mod_name in (
+        "comtypes.persist",
+        "comtypes.typeinfo",
+        "comtypes.automation",
+        "comtypes",
+        "ctypes.wintypes",
+        "ctypes"
+    ):
         mod = importlib.import_module(mod_name)
         if hasattr(mod, "__known_symbols__"):
             names = mod.__known_symbols__  # type: list[str]

comtypes/test/test_client.py

@@ -69,6 +69,11 @@ def test_clsid(self):
         mod = comtypes.client.GetModule(clsid)
         self.assertEqual(mod.MediaPlayer._reg_clsid_, clsid)
 
+    def test_ptr_itypelib(self):
+        from comtypes import typeinfo
+        mod = comtypes.client.GetModule(typeinfo.LoadTypeLibEx("scrrun.dll"))
+        self.assertIs(mod, Scripting)
+
     def test_imports_IEnumVARIANT_from_other_generated_modules(self):
         # NOTE: `codegenerator` generates code that contains unused imports,
         # but removing them are attracting wierd bugs in library-wrappers
@@ -84,6 +89,10 @@ def test_no_replacing_Patch_namespace(self):
         # NOTE: `WindowsInstaller`, which has `Patch` definition in dll.
         comtypes.client.GetModule("msi.dll")
 
+    def test_raises_typerror_if_takes_unsupported(self):
+        with self.assertRaises(TypeError):
+            comtypes.client.GetModule(object())
+
 
 class Test_KnownSymbols(ut.TestCase):
     # It is guaranteed that each element of `__known_symbols__` is in