comtypes 1.4.0__zip → 1.4.2__zip

{comtypes-1.4.0 → comtypes-1.4.2}/CHANGES.txt

@@ -1,6 +1,19 @@
 Comtypes CHANGELOG
 ==================
 
+Release 1.4.2
+--------------
+
+* Improve the stability of module generation by ``GetModule``. By @junkmd.
+* Define ``c_int`` aliases earlier than others in wrapper modules. By @junkmd.
+* Remove trailing newlines generated by ``codegenerator`` and ``typeannotator``. By @junkmd.
+* Determine whether a interface is one of the known symbols not only by its name but also by using its iid. By @junkmd.
+* Add ``Incomplete`` and ``Hresult`` to ``hints.pyi``. By @junkmd.
+
+Release 1.4.1
+--------------
+* Fix `TypeError` when defining enumeration types
+
 Release 1.4.0
 --------------
 * Add enumeration definitions in generated friendly modules. By @junkmd.

{comtypes-1.4.0/comtypes.egg-info → comtypes-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: comtypes
-Version: 1.4.0
+Version: 1.4.2
 Summary: Pure Python COM package
 Home-page: https://github.com/enthought/comtypes
 Download-URL: https://github.com/enthought/comtypes/releases

{comtypes-1.4.0 → comtypes-1.4.2}/comtypes/__init__.py

@@ -1,5 +1,5 @@
 # comtypes version numbers follow semver (http://semver.org/) and PEP 440
-__version__ = "1.4.0"
+__version__ = "1.4.2"
 
 import atexit
 from ctypes import *

{comtypes-1.4.0 → comtypes-1.4.2}/comtypes/client/_generate.py

@@ -1,11 +1,12 @@
 from __future__ import print_function
 import ctypes
 import importlib
+import inspect
 import logging
 import os
 import sys
 import types
-from typing import Any, Tuple, List, Optional, Dict, Union as _UnionT
+from typing import Any, Tuple, List, Mapping, Optional, Dict, Union as _UnionT
 import winreg
 
 from comtypes import GUID, typeinfo
@@ -121,7 +122,10 @@ def GetModule(tlib: _UnionT[Any, typeinfo.ITypeLib]) -> types.ModuleType:
         pathname = None
         tlib = _load_tlib(tlib)
     logger.debug("GetModule(%s)", tlib.GetLibAttr())
-    return ModuleGenerator().generate(tlib, pathname)
+    mod = _get_existing_module(tlib)
+    if mod is not None:
+        return mod
+    return ModuleGenerator(tlib, pathname).generate()
 
 
 def _load_tlib(obj: Any) -> typeinfo.ITypeLib:
@@ -160,94 +164,110 @@ def _load_tlib(obj: Any) -> typeinfo.ITypeLib:
     raise TypeError("'%r' is not supported type for loading typelib" % obj)
 
 
-def _create_module_in_file(modulename: str, code: str) -> types.ModuleType:
-    """create module in file system, and import it"""
+def _get_existing_module(tlib: typeinfo.ITypeLib) -> Optional[types.ModuleType]:
+    def _get_friendly(name: str) -> Optional[types.ModuleType]:
+        try:
+            mod = _my_import(name)
+        except Exception as details:
+            logger.info("Could not import %s: %s", friendly_name, details)
+        else:
+            return mod
+
+    def _get_wrapper(name: str) -> Optional[types.ModuleType]:
+        if name in sys.modules:
+            return sys.modules[name]
+        try:
+            return _my_import(name)
+        except Exception as details:
+            logger.info("Could not import %s: %s", name, details)
+
+    wrapper_name = codegenerator.name_wrapper_module(tlib)
+    friendly_name = codegenerator.name_friendly_module(tlib)
+    wrapper_module = _get_wrapper(wrapper_name)
+    if wrapper_module is not None:
+        if friendly_name is None:
+            return wrapper_module
+        else:
+            friendly_module = _get_friendly(friendly_name)
+            if friendly_module is not None:
+                return friendly_module
+    return None
+
+
+def _create_module(modulename: str, code: str) -> types.ModuleType:
+    """Creates the module, then imports it."""
     # `modulename` is 'comtypes.gen.xxx'
-    filename = "%s.py" % modulename.split(".")[-1]
-    with open(os.path.join(comtypes.client.gen_dir, filename), "w") as ofi:
+    stem = modulename.split(".")[-1]
+    if comtypes.client.gen_dir is None:
+        # in memory system
+        import comtypes.gen as g
+
+        mod = types.ModuleType(modulename)
+        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(g, stem, mod)
+        return mod
+    # in file system
+    with open(os.path.join(comtypes.client.gen_dir, f"{stem}.py"), "w") as ofi:
         print(code, file=ofi)
     # clear the import cache to make sure Python sees newly created modules
-    if hasattr(importlib, "invalidate_caches"):
-        importlib.invalidate_caches()
+    importlib.invalidate_caches()
     return _my_import(modulename)
 
 
-def _create_module_in_memory(modulename: str, code: 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(g.__path__[0])  # type: ignore
-    mod.__file__ = os.path.join(abs_gen_path, "<memory>")
-    exec(code, mod.__dict__)
-    sys.modules[modulename] = mod
-    setattr(g, modulename.split(".")[-1], mod)
-    return mod
-
-
 class ModuleGenerator(object):
-    def __init__(self) -> None:
-        self.codegen = codegenerator.CodeGenerator(_get_known_symbols())
-
-    def generate(
-        self, tlib: typeinfo.ITypeLib, pathname: Optional[str]
-    ) -> types.ModuleType:
-        # create and import the real typelib wrapper module
-        mod = self._create_wrapper_module(tlib, pathname)
-        # try to get the friendly-name, if not, returns the real typelib wrapper module
-        modulename = codegenerator.name_friendly_module(tlib)
-        if modulename is None:
-            return mod
-        # create and import the friendly-named module
-        return self._create_friendly_module(tlib, modulename)
-
-    def _create_friendly_module(
-        self, tlib: typeinfo.ITypeLib, modulename: str
-    ) -> types.ModuleType:
-        """helper which creates and imports the friendly-named module."""
-        try:
-            mod = _my_import(modulename)
-        except Exception as details:
-            logger.info("Could not import %s: %s", modulename, details)
-        else:
-            return mod
-        # the module is always regenerated if the import fails
-        logger.info("# Generating %s", modulename)
-        # determine the Python module name
-        modname = codegenerator.name_wrapper_module(tlib)
-        code = self.codegen.generate_friendly_code(modname)
-        if comtypes.client.gen_dir is None:
-            return _create_module_in_memory(modulename, code)
-        return _create_module_in_file(modulename, code)
-
-    def _create_wrapper_module(
-        self, tlib: typeinfo.ITypeLib, pathname: 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:
-            return sys.modules[modulename]
-        try:
-            return _my_import(modulename)
-        except Exception as details:
-            logger.info("Could not import %s: %s", modulename, details)
-        # generate the module since it doesn't exist or is out of date
-        logger.info("# Generating %s", modulename)
-        p = tlbparser.TypeLibParser(tlib)
+    def __init__(self, tlib: typeinfo.ITypeLib, pathname: Optional[str]) -> None:
+        self.wrapper_name = codegenerator.name_wrapper_module(tlib)
+        self.friendly_name = codegenerator.name_friendly_module(tlib)
         if pathname is None:
-            pathname = tlbparser.get_tlib_filename(tlib)
-        items = list(p.parse().values())
-        code = self.codegen.generate_wrapper_code(items, filename=pathname)
-        for ext_tlib in self.codegen.externals:  # generates dependency COM-lib modules
+            self.pathname = tlbparser.get_tlib_filename(tlib)
+        else:
+            self.pathname = pathname
+        self.tlib = tlib
+
+    def generate(self) -> types.ModuleType:
+        """Generates wrapper and friendly modules."""
+        known_symbols, known_interfaces = _get_known_namespaces()
+        codegen = codegenerator.CodeGenerator(known_symbols, known_interfaces)
+        codebases: List[Tuple[str, str]] = []
+        logger.info("# Generating %s", self.wrapper_name)
+        items = list(tlbparser.TypeLibParser(self.tlib).parse().values())
+        wrp_code = codegen.generate_wrapper_code(items, filename=self.pathname)
+        codebases.append((self.wrapper_name, wrp_code))
+        if self.friendly_name is not None:
+            logger.info("# Generating %s", self.friendly_name)
+            frd_code = codegen.generate_friendly_code(self.wrapper_name)
+            codebases.append((self.friendly_name, frd_code))
+        for ext_tlib in codegen.externals:  # generates dependency COM-lib modules
             GetModule(ext_tlib)
-        if comtypes.client.gen_dir is None:
-            return _create_module_in_memory(modulename, code)
-        return _create_module_in_file(modulename, code)
+        return [_create_module(name, code) for (name, code) in codebases][-1]
+
 
+_SymbolName = str
+_ModuleName = str
+_ItfName = str
+_ItfIid = str
 
-def _get_known_symbols() -> Dict[str, str]:
-    known_symbols: Dict[str, str] = {}
+
+def _get_known_namespaces() -> Tuple[
+    Mapping[_SymbolName, _ModuleName], Mapping[_ItfName, _ItfIid]
+]:
+    """Returns symbols and interfaces that are already statically defined in `ctypes`
+    and `comtypes`.
+    From `ctypes`, all the names are obtained.
+    From `comtypes`, only the names in each module's `__known_symbols__` are obtained.
+
+    Note:
+        The interfaces that should be included in `__known_symbols__` should be limited
+        to those that can be said to be bound to the design concept of COM, such as
+        `IUnknown`, and those defined in `objidl` and `oaidl`.
+        `comtypes` does NOT aim to statically define all COM object interfaces in
+        its repository.
+    """
+    known_symbols: Dict[_SymbolName, _ModuleName] = {}
+    known_interfaces: Dict[_ItfName, _ItfIid] = {}
     for mod_name in (
         "comtypes.persist",
         "comtypes.typeinfo",
@@ -259,11 +279,16 @@ def _get_known_symbols() -> Dict[str, str]:
         mod = importlib.import_module(mod_name)
         if hasattr(mod, "__known_symbols__"):
             names: List[str] = mod.__known_symbols__
+            for name in names:
+                tgt = getattr(mod, name)
+                if inspect.isclass(tgt) and issubclass(tgt, comtypes.IUnknown):
+                    assert name not in known_interfaces
+                    known_interfaces[name] = str(tgt._iid_)
         else:
             names = list(mod.__dict__)
         for name in names:
             known_symbols[name] = mod.__name__
-    return known_symbols
+    return known_symbols, known_interfaces
 
 
 ################################################################

{comtypes-1.4.0 → comtypes-1.4.2}/comtypes/hints.pyi

@@ -22,9 +22,11 @@ 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
+    from typing import TypeGuard as TypeGuard
 else:
-    from typing_extensions import Concatenate, ParamSpec
+    from typing_extensions import Concatenate, ParamSpec, TypeAlias
+    from typing_extensions import TypeGuard as TypeGuard
 if sys.version_info >= (3, 11):
     from typing import Self
 else:
@@ -34,6 +36,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-1.4.0 → comtypes-1.4.2}/comtypes/test/test_client.py

@@ -59,12 +59,17 @@ class Test_GetModule(ut.TestCase):
         mod = comtypes.client.GetModule(typeinfo.LoadTypeLibEx("scrrun.dll"))
         self.assertIs(mod, Scripting)
 
-    def test_imports_IEnumVARIANT_from_other_generated_modules(self):
+    def test_mscorlib(self):
         # NOTE: `codegenerator` generates code that contains unused imports,
         # but removing them are attracting wierd bugs in library-wrappers
         # which depend on externals.
-        # NOTE: `mscorlib`, which imports `IEnumVARIANT` from `stdole`.
-        comtypes.client.GetModule(("{BED7F4EA-1A96-11D2-8F08-00A0C9A6186D}",))
+        # `mscorlib` imports `stdole` wrapper module and refers`IEnumVARIANT` from it.
+        mod = comtypes.client.GetModule(("{BED7F4EA-1A96-11D2-8F08-00A0C9A6186D}",))
+        # NOTE: `ModuleGenerator` treats the `ctypes._Pointer` base class for pointers
+        # as one of the known symbols, but `mscorlib` has the `_Pointer` com interface.
+        # Even though they have the same name, `codegenerator` generates code to define
+        # the `_Pointer` interface, rather than importing `_Pointer` from `ctypes`.
+        self.assertTrue(issubclass(mod._Pointer, comtypes.IUnknown))
 
     def test_no_replacing_Patch_namespace(self):
         # NOTE: An object named `Patch` is defined in some dll.
@@ -74,6 +79,21 @@ class Test_GetModule(ut.TestCase):
         # NOTE: `WindowsInstaller`, which has `Patch` definition in dll.
         comtypes.client.GetModule("msi.dll")
 
+    def test_the_name_of_the_enum_member_and_the_coclass_are_duplicated(self):
+        # NOTE: In `MSHTML`, the name `htmlInputImage` is used both as a member of
+        # the `_htmlInput` enum type and as a CoClass that has `IHTMLElement` and
+        # others as interfaces.
+        # If a CoClass is assigned where an integer should be assigned, such as in
+        # the definition of an enumeration, the generation of the module will fail.
+        # See also https://github.com/enthought/comtypes/issues/524
+        with contextlib.redirect_stdout(None):  # supress warnings
+            mshtml = comtypes.client.GetModule("mshtml.tlb")
+        # When the member of an enumeration and a CoClass have the same name,
+        # the defined later one is assigned to the name in the module.
+        # By asserting whether the CoClass is assigned to that name, it ensures
+        # that the member of the enumeration is defined earlier.
+        self.assertTrue(issubclass(mshtml.htmlInputImage, comtypes.CoClass))
+
     def test_abstracted_wrapper_module_in_friendly_module(self):
         mod = comtypes.client.GetModule("scrrun.dll")
         self.assertTrue(hasattr(mod, "__wrapper_module__"))

comtypes-1.4.2/comtypes/test/test_client_regenerate_modules.py

@@ -0,0 +1,158 @@
+import contextlib
+import importlib
+from pathlib import Path
+import shutil
+import sys
+import tempfile
+import types
+from typing import Iterator
+import unittest as ut
+from unittest import mock
+
+import comtypes
+import comtypes.client
+import comtypes.gen
+
+comtypes.client.GetModule("scrrun.dll")
+from comtypes.gen import Scripting  # noqa
+from comtypes.gen import stdole  # noqa
+
+
+SCRRUN_FRIENDLY = Path(Scripting.__file__)
+SCRRUN_WRAPPER = Path(Scripting.__wrapper_module__.__file__)
+STDOLE_FRIENDLY = Path(stdole.__file__)
+STDOLE_WRAPPER = Path(stdole.__wrapper_module__.__file__)
+
+
+@contextlib.contextmanager
+def _mkdtmp_gen_dir() -> Iterator[Path]:
+    with tempfile.TemporaryDirectory() as t:
+        tmp_dir = Path(t)
+        tmp_comtypes_dir = tmp_dir / "comtypes"
+        tmp_comtypes_dir.mkdir()
+        (tmp_comtypes_dir / "__init__.py").touch()
+        tmp_comtypes_gen_dir = tmp_comtypes_dir / "gen"
+        tmp_comtypes_gen_dir.mkdir()
+        (tmp_comtypes_gen_dir / "__init__.py").touch()
+        yield tmp_comtypes_gen_dir
+
+
+@contextlib.contextmanager
+def _patch_gen_pkg(new_path: Path) -> Iterator[types.ModuleType]:
+    new_comtypes_init = (new_path / "comtypes" / "__init__.py").resolve()
+    assert new_comtypes_init.exists()
+    new_comtypes_gen_init = (new_path / "comtypes" / "gen" / "__init__.py").resolve()
+    assert new_comtypes_gen_init.exists()
+    orig_comtypes = sys.modules["comtypes"]
+    orig_gen_names = list(filter(lambda k: k.startswith("comtypes.gen"), sys.modules))
+    tmp_sys_path = list(sys.path)  # copy
+    with mock.patch.object(sys, "path", tmp_sys_path):
+        sys.path.insert(0, str(new_path))
+        with mock.patch.dict(sys.modules):
+            # The reason for removing the parent module (in this case, `comtypes`)
+            # from `sys.modules` is because the child module (in this case,
+            # `comtypes.gen`) refers to the namespace of the parent module.
+            # If the parent module exists in `sys.modules`, Python uses that cache
+            # to import the child module. Therefore, in order to import a new version
+            # of the child module, it is necessary to temporarily remove the parent
+            # module from `sys.modules`.
+            del sys.modules["comtypes"]
+            for k in orig_gen_names:
+                del sys.modules[k]
+            # The module that is imported here is not the one cached in `sys.modules`
+            # before the patch, but the module that is newly loaded from
+            # `new_path / 'comtypes' / 'gen' / '__init__.py'`.
+            new_comtypes_gen = importlib.import_module("comtypes.gen")
+            assert new_comtypes_gen.__file__ is not None
+            assert Path(new_comtypes_gen.__file__).resolve() == new_comtypes_gen_init
+            # The `comtypes` module cached in `sys.modules` as a side effect of
+            # executing the above line is empty because it is the one loaded from
+            # `new_path / 'comtypes' / '__init__.py'`.
+            # If we call the test target as it is, an error will occur due to
+            # referencing an empty module, so we restore the original `comtypes`
+            # to `sys.modules`.
+            sys.modules["comtypes"] = orig_comtypes
+            assert sys.modules["comtypes.gen"] is new_comtypes_gen
+            # By making the empty `comtypes.gen` package we created earlier to be
+            # referenced as the `gen` attribute of `comtypes`, the original
+            # `comtypes.gen` will not be referenced within the context.
+            with mock.patch.object(orig_comtypes, "gen", new_comtypes_gen):
+                yield new_comtypes_gen
+
+
+@contextlib.contextmanager
+def patch_gen_dir() -> Iterator[Path]:
+    with _mkdtmp_gen_dir() as tmp_gen_dir:
+        with mock.patch.object(comtypes.client, "gen_dir", str(tmp_gen_dir)):
+            try:
+                with _patch_gen_pkg(tmp_gen_dir.parent.parent):
+                    yield tmp_gen_dir
+            finally:
+                importlib.invalidate_caches()
+                importlib.reload(comtypes.gen)
+                importlib.reload(stdole)
+                importlib.reload(Scripting)
+
+
+class Test(ut.TestCase):
+    def test_all_modules_are_missing(self):
+        with patch_gen_dir() as gen_dir:
+            # ensure `gen_dir` and `sys.modules` are patched.
+            with self.assertRaises(ImportError):
+                from comtypes.gen import Scripting as _  # noqa
+            self.assertFalse((gen_dir / SCRRUN_FRIENDLY.name).exists())
+            self.assertFalse((gen_dir / SCRRUN_WRAPPER.name).exists())
+            self.assertFalse((gen_dir / STDOLE_FRIENDLY.name).exists())
+            self.assertFalse((gen_dir / STDOLE_WRAPPER.name).exists())
+            # generate new files and modules.
+            comtypes.client.GetModule("scrrun.dll")
+            self.assertTrue((gen_dir / SCRRUN_FRIENDLY.name).exists())
+            self.assertTrue((gen_dir / SCRRUN_WRAPPER.name).exists())
+            self.assertTrue((gen_dir / STDOLE_FRIENDLY.name).exists())
+            self.assertTrue((gen_dir / STDOLE_WRAPPER.name).exists())
+
+    def test_friendly_module_is_missing(self):
+        with patch_gen_dir() as gen_dir:
+            shutil.copy2(SCRRUN_WRAPPER, gen_dir / SCRRUN_WRAPPER.name)
+            wrp_mtime = (gen_dir / SCRRUN_WRAPPER.name).stat().st_mtime_ns
+            shutil.copy2(STDOLE_FRIENDLY, gen_dir / STDOLE_FRIENDLY.name)
+            shutil.copy2(STDOLE_WRAPPER, gen_dir / STDOLE_WRAPPER.name)
+            comtypes.client.GetModule("scrrun.dll")
+            self.assertTrue((gen_dir / SCRRUN_FRIENDLY.name).exists())
+            # Check the most recent content modification time to confirm whether
+            # the module file has been regenerated.
+            self.assertGreater(
+                (gen_dir / SCRRUN_WRAPPER.name).stat().st_mtime_ns, wrp_mtime
+            )
+
+    def test_wrapper_module_is_missing(self):
+        with patch_gen_dir() as gen_dir:
+            shutil.copy2(SCRRUN_WRAPPER, gen_dir / SCRRUN_FRIENDLY.name)
+            frd_mtime = (gen_dir / SCRRUN_FRIENDLY.name).stat().st_mtime_ns
+            shutil.copy2(STDOLE_FRIENDLY, gen_dir / STDOLE_FRIENDLY.name)
+            shutil.copy2(STDOLE_WRAPPER, gen_dir / STDOLE_WRAPPER.name)
+            comtypes.client.GetModule("scrrun.dll")
+            self.assertTrue((gen_dir / SCRRUN_WRAPPER.name).exists())
+            self.assertGreater(
+                (gen_dir / SCRRUN_FRIENDLY.name).stat().st_mtime_ns, frd_mtime
+            )
+
+    def test_dependency_modules_are_missing(self):
+        with patch_gen_dir() as gen_dir:
+            shutil.copy2(SCRRUN_WRAPPER, gen_dir / SCRRUN_FRIENDLY.name)
+            frd_mtime = (gen_dir / SCRRUN_FRIENDLY.name).stat().st_mtime_ns
+            shutil.copy2(SCRRUN_WRAPPER, gen_dir / SCRRUN_WRAPPER.name)
+            wrp_mtime = (gen_dir / SCRRUN_WRAPPER.name).stat().st_mtime_ns
+            comtypes.client.GetModule("scrrun.dll")
+            self.assertTrue((gen_dir / STDOLE_FRIENDLY.name).exists())
+            self.assertTrue((gen_dir / STDOLE_WRAPPER.name).exists())
+            self.assertGreater(
+                (gen_dir / SCRRUN_FRIENDLY.name).stat().st_mtime_ns, frd_mtime
+            )
+            self.assertGreater(
+                (gen_dir / SCRRUN_WRAPPER.name).stat().st_mtime_ns, wrp_mtime
+            )
+
+
+if __name__ == "__main__":
+    ut.main()