comtypes 1.4.2__zip → 1.4.3__zip

{comtypes-1.4.2/comtypes/tools → comtypes-1.4.3/comtypes/tools/codegenerator}/typeannotator.py

@@ -216,6 +216,21 @@ class _MethodsAnnotator(abc.ABC, Generic[_T_MTD]):
             self._define_normal_prop(name, setter=setter)
 
 
+def _to_outtype(typ: Any) -> str:
+    if isinstance(typ, typedesc.PointerType):
+        return _to_outtype(typ.typ)
+    elif isinstance(typ, typedesc.DispInterface):
+        return f"'{typ.name}'"
+    elif isinstance(typ, typedesc.ComInterface):
+        return f"'{typ.name}'"
+    elif isinstance(typ, typedesc.CoClass):
+        impl, _ = typedesc.groupby_impltypeflags(typ.interfaces)
+        if impl:
+            meta = f"hints.FirstComItfOf['{typ.name}']"
+            return f"hints.Annotated[{_to_outtype(impl[0])}, {meta}]"
+    return "hints.Incomplete"
+
+
 class ComMethodAnnotator(_MethodAnnotator[typedesc.ComMethod]):
     def _iter_outarg_specs(self) -> Iterator[Tuple[Any, str]]:
         for typ, name, flags, _ in self.method.arguments:
@@ -240,7 +255,7 @@ class ComMethodAnnotator(_MethodAnnotator[typedesc.ComMethod]):
             else:
                 inargs.append(f"{argname}: hints.Incomplete = ...")
                 has_optional = True
-        outargs = ["hints.Incomplete" for _ in self._iter_outarg_specs()]
+        outargs = [_to_outtype(ot) for ot, _ in self._iter_outarg_specs()]
         if not outargs:
             out = "hints.Hresult"
         elif len(outargs) == 1:
@@ -283,7 +298,7 @@ class DispMethodAnnotator(_MethodAnnotator[typedesc.DispMethod]):
             else:
                 inargs.append(f"{argname}: hints.Incomplete = ...")
                 has_optional = True
-        out = "hints.Incomplete"
+        out = _to_outtype(self.method.returns)
         in_ = ("self, " + ", ".join(inargs)) if inargs else "self"
         return f"def {name}({in_}) -> {out}: ..."
 
@@ -314,7 +329,7 @@ class DispInterfaceMembersAnnotator(object):
         property_lines: List[str] = []
         for mem in props:
             property_lines.append("@property  # dispprop")
-            out = "hints.Incomplete"
+            out = _to_outtype(mem.typ)
             property_lines.append(f"def {mem.name}(self) -> {out}: ...")
         dispprops = "\n".join(f"        {p}" for p in property_lines)
         dispmethods = DispMethodsAnnotator().generate(methods)

{comtypes-1.4.2 → comtypes-1.4.3}/comtypes/tools/tlbparser.py

@@ -1,20 +1,10 @@
-from __future__ import print_function
 import os
 import sys
-from typing import (
-    Any,
-    Callable,
-    Dict,
-    List,
-    Optional,
-    Type,
-    TypeVar,
-    Tuple,
-    Union as _UnionT,
-)
-from ctypes import alignment, c_void_p, _Pointer, sizeof, windll
+from typing import Any
+from typing import Dict, List, Optional, Tuple
+from ctypes import alignment, byref, c_void_p, sizeof, windll
 
-from comtypes import automation, _CData, COMError, typeinfo
+from comtypes import automation, BSTR, COMError, typeinfo
 from comtypes.tools import typedesc
 from comtypes.client._code_cache import _get_module_filename
 
@@ -267,10 +257,8 @@ class Parser(object):
             assert vd.varkind == typeinfo.VAR_CONST
             typ = self.make_type(vd.elemdescVar.tdesc, tinfo)
             var_value = vd._.lpvarValue[0].value
-            v = typedesc.Constant(name, typ, var_value)
+            v = typedesc.Constant(name, typ, var_value, var_doc)
             self._register(name, v)
-            if var_doc is not None:
-                v.doc = var_doc
 
     # TKIND_INTERFACE = 3
     def ParseInterface(
@@ -289,15 +277,9 @@ class Parser(object):
                 warnings.warn(message, UserWarning)
             return None
 
-        itf = typedesc.ComInterface(
-            itf_name,
-            members=[],
-            base=None,
-            iid=str(ta.guid),
-            idlflags=self.interface_type_flags(ta.wTypeFlags),
-        )
-        if itf_doc:
-            itf.doc = itf_doc
+        iid = str(ta.guid)
+        idlflags = self.interface_type_flags(ta.wTypeFlags)
+        itf = typedesc.ComInterface(itf_name, None, iid, idlflags, itf_doc)
         self._register(itf_name, itf)
 
         if ta.cImplTypes:
@@ -307,7 +289,7 @@ class Parser(object):
 
         assert ta.cVars == 0, "vars on an Interface?"
 
-        members = []
+        members: List[Tuple[int, typedesc.ComMethod]] = []
         for i in range(ta.cFuncs):
             fd = tinfo.GetFuncDesc(i)
             func_name, func_doc = tinfo.GetDocumentation(fd.memid)[:2]
@@ -341,7 +323,7 @@ class Parser(object):
         # Sort the methods by oVft (VTable offset): Some typeinfo
         # don't list methods in VTable order.
         members.sort()
-        itf.members.extend([m[1] for m in members])
+        itf.extend_members([m for _, m in members])
 
         return itf
 
@@ -351,20 +333,13 @@ class Parser(object):
     ) -> typedesc.DispInterface:
         itf_name, doc = tinfo.GetDocumentation(-1)[0:2]
         assert ta.cImplTypes == 1
-
         hr = tinfo.GetRefTypeOfImplType(0)
         tibase = tinfo.GetRefTypeInfo(hr)
         base = self.parse_typeinfo(tibase)
-        members = []
-        itf = typedesc.DispInterface(
-            itf_name,
-            members=members,
-            base=base,
-            iid=str(ta.guid),
-            idlflags=self.interface_type_flags(ta.wTypeFlags),
-        )
-        if doc is not None:
-            itf.doc = str(doc.split("\0")[0])
+        iid = str(ta.guid)
+        idlflags = self.interface_type_flags(ta.wTypeFlags)
+        doc = str(doc.split("\0")[0]) if doc is not None else doc
+        itf = typedesc.DispInterface(itf_name, base, iid, idlflags, doc)
         self._register(itf_name, itf)
 
         # This code can only handle pure dispinterfaces.  Dual
@@ -379,7 +354,7 @@ class Parser(object):
             mth = typedesc.DispProperty(
                 vd.memid, var_name, typ, self.var_flags(vd.wVarFlags), var_doc
             )
-            itf.members.append(mth)
+            itf.add_member(mth)
 
         # At least the EXCEL typelib lists the IUnknown and IDispatch
         # methods even for this kind of interface.  I didn't find any
@@ -430,7 +405,7 @@ class Parser(object):
                 else:
                     default = None
                 mth.add_argument(typ, name, self.param_flags(flags), default)
-            itf.members.append(mth)
+            itf.add_member(mth)
         return itf
 
     def inv_kind(self, invkind: int) -> List[str]:
@@ -548,11 +523,9 @@ class Parser(object):
         #        version, control, hidden, and appobject
         coclass_name, doc = tinfo.GetDocumentation(-1)[0:2]
         tlibattr = tinfo.GetContainingTypeLib()[0].GetLibAttr()
-        coclass = typedesc.CoClass(
-            coclass_name, str(ta.guid), self.coclass_type_flags(ta.wTypeFlags), tlibattr
-        )
-        if doc is not None:
-            coclass.doc = doc
+        clsid = str(ta.guid)
+        idlflags = self.coclass_type_flags(ta.wTypeFlags)
+        coclass = typedesc.CoClass(coclass_name, clsid, idlflags, tlibattr, doc)
         self._register(coclass_name, coclass)
 
         for i in range(ta.cImplTypes):
@@ -763,9 +736,6 @@ class TypeLibParser(Parser):
 def get_tlib_filename(tlib):
     # seems if the typelib is not registered, there's no way to
     # determine the filename.
-    from ctypes import windll, byref
-    from comtypes import BSTR
-
     la = tlib.GetLibAttr()
     name = BSTR()
     try:

{comtypes-1.4.2 → comtypes-1.4.3}/comtypes/tools/typedesc.py

@@ -2,8 +2,9 @@
 # in typedesc_base
 
 import ctypes
-from typing import Any, List, Optional, Tuple, Union as _UnionT
+from typing import Any, List, Optional, Sequence, Tuple, Union as _UnionT
 
+from comtypes import typeinfo
 from comtypes.typeinfo import ITypeLib, TLIBATTR
 from comtypes.tools.typedesc_base import *
 
@@ -29,11 +30,16 @@ class TypeLib(object):
 
 class Constant(object):
     def __init__(
-        self, name: str, typ: _UnionT[Typedef, FundamentalType], value: Any
+        self,
+        name: str,
+        typ: _UnionT[Typedef, FundamentalType],
+        value: Any,
+        doc: Optional[str],
     ) -> None:
         self.name = name
         self.typ = typ
         self.value = value
+        self.doc = doc
 
 
 class External(object):
@@ -141,18 +147,22 @@ class DispInterface(object):
     def __init__(
         self,
         name: str,
-        members: List[_UnionT[DispMethod, DispProperty]],
         base: Any,
         iid: str,
         idlflags: List[str],
+        doc: Optional[str],
     ) -> None:
         self.name = name
-        self.members = members
+        self.members: List[_UnionT[DispMethod, DispProperty]] = []
         self.base = base
         self.iid = iid
         self.idlflags = idlflags
         self.itf_head = DispInterfaceHead(self)
         self.itf_body = DispInterfaceBody(self)
+        self.doc = doc
+
+    def add_member(self, member: _UnionT[DispMethod, DispProperty]) -> None:
+        self.members.append(member)
 
     def get_body(self) -> DispInterfaceBody:
         return self.itf_body
@@ -175,18 +185,22 @@ class ComInterface(object):
     def __init__(
         self,
         name: str,
-        members: List[ComMethod],
         base: "Optional[ComInterface]",
         iid: str,
         idlflags: List[str],
+        doc: Optional[str],
     ) -> None:
         self.name = name
-        self.members = members
+        self.members: List[ComMethod] = []
         self.base = base
         self.iid = iid
         self.idlflags = idlflags
         self.itf_head = ComInterfaceHead(self)
         self.itf_body = ComInterfaceBody(self)
+        self.doc = doc
+
+    def extend_members(self, members: Sequence[ComMethod]) -> None:
+        self.members.extend(members)
 
     def get_body(self) -> ComInterfaceBody:
         return self.itf_body
@@ -195,15 +209,49 @@ class ComInterface(object):
         return self.itf_head
 
 
+_ImplTypeFlags = int
+_Interface = _UnionT[ComInterface, DispInterface]
+
+
 class CoClass(object):
     def __init__(
-        self, name: str, clsid: str, idlflags: List[str], tlibattr: TLIBATTR
+        self,
+        name: str,
+        clsid: str,
+        idlflags: List[str],
+        tlibattr: TLIBATTR,
+        doc: Optional[str],
     ) -> None:
         self.name = name
         self.clsid = clsid
         self.idlflags = idlflags
         self.tlibattr = tlibattr
-        self.interfaces: List[Tuple[Any, int]] = []
+        self.interfaces: List[Tuple[_Interface, _ImplTypeFlags]] = []
+        self.doc = doc
 
-    def add_interface(self, itf: Any, idlflags: int) -> None:
+    def add_interface(self, itf: _Interface, idlflags: _ImplTypeFlags) -> None:
         self.interfaces.append((itf, idlflags))
+
+
+_ImplementedInterfaces = Sequence[_Interface]
+_SourceInterfaces = Sequence[_Interface]
+
+
+def groupby_impltypeflags(
+    seq: Sequence[Tuple[_Interface, _ImplTypeFlags]]
+) -> Tuple[_ImplementedInterfaces, _SourceInterfaces]:
+    implemented = []
+    sources = []
+    for itf, impltypeflags in seq:
+        if impltypeflags & typeinfo.IMPLTYPEFLAG_FSOURCE:
+            # source interface
+            where = sources
+        else:
+            # sink interface
+            where = implemented
+        if impltypeflags & typeinfo.IMPLTYPEFLAG_FDEFAULT:
+            # The default interface should be the first item on the list
+            where.insert(0, itf)
+        else:
+            where.append(itf)
+    return implemented, sources

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: comtypes
-Version: 1.4.2
+Version: 1.4.3
 Summary: Pure Python COM package
 Home-page: https://github.com/enthought/comtypes
 Download-URL: https://github.com/enthought/comtypes/releases
@@ -75,6 +75,34 @@ This project and the maintainers of thousands of other packages are working with
 
 [Learn more](https://tidelift.com/subscription/pkg/pypi-comtypes?utm_source=pypi-comtypes&utm_medium=referral&utm_campaign=github).
 
+## Frequently Asked Questions
+
+### Q: Why does this package not support platforms other than Windows?
+**A:** [The Microsoft Component Object Model (COM)](https://learn.microsoft.com/en-us/windows/win32/com/com-technical-overview) is a technology that is unique to Windows and is not supported on other platforms.
+
+[The phrase _"COM is a platform-independent"_ in the MS documentation](https://learn.microsoft.com/en-us/windows/win32/com/component-object-model--com--portal) means that COM maintains compatibility across different versions of Windows, and does NOT imply that it is supported on Linux or Mac.
+
+As long as COM is not supported outside of Windows, this project does not plan to port to other platforms.
+
+### Q: Why does `cannot import name 'COMError' from '_ctypes'` error occur when using this package on platforms other than Windows?
+**A:** The [`_ctypes`](https://github.com/python/cpython/blob/main/Modules/_ctypes/_ctypes.c) is part of the internal implementation of the [`ctypes`](https://github.com/python/cpython/blob/main/Lib/ctypes/) standard library that exists for Python on all platforms.  
+However, `COMError` and COM-related features are implemented only in Python for Windows.
+
+In cross-platform software development, care must be taken to ensure that codebase dependent on `comtypes` does not execute in environments other than Windows.
+
+### Q: Despite a script that depends on `comtypes` having run successfully before, a error (`ImportError`, `NameError`, or `SyntaxError`) is raised now, and the same error occurs again and again.
+
+**A:** Executing `py -m comtypes.clear_cache` and then running the script again might resolve the problem.
+
+When `comtypes.client.GetModule` is called (either directly or indirectly), `comtypes` generates Python module files.  
+If Python is forced to terminate or crashes in the middle of file generation, the codebase written to the file becomes partial.  
+When Python tries to import this unexecutable partial codebase module, an error occurs.
+
+Executing `py -m comtypes.clear_cache` identifies the directories where the "cache module files" are stored and deletes them.  
+After deleting these partial modules and running the script again, `comtypes.client.GetModule` is called and executable modules are generated anew.
+
+However, if the script implementation does not use `comtypes.client.GetModule` or processes generated files, it may not be a solution.
+
 ## Documentation:
 
 The documentation is currently hosted on pythonhosted at:

{comtypes-1.4.2 → comtypes-1.4.3}/comtypes.egg-info/SOURCES.txt

@@ -73,6 +73,7 @@ comtypes/test/test_collections.py
 comtypes/test/test_comserver.py
 comtypes/test/test_createwrappers.py
 comtypes/test/test_dict.py
+comtypes/test/test_dispifc_records.py
 comtypes/test/test_dispinterface.py
 comtypes/test/test_dyndispatch.py
 comtypes/test/test_excel.py
@@ -100,8 +101,13 @@ comtypes/test/test_win32com_interop.py
 comtypes/test/test_wmi.py
 comtypes/test/test_word.py
 comtypes/tools/__init__.py
-comtypes/tools/codegenerator.py
 comtypes/tools/tlbparser.py
-comtypes/tools/typeannotator.py
 comtypes/tools/typedesc.py
-comtypes/tools/typedesc_base.py
+comtypes/tools/typedesc_base.py
+comtypes/tools/codegenerator/__init__.py
+comtypes/tools/codegenerator/codegenerator.py
+comtypes/tools/codegenerator/helpers.py
+comtypes/tools/codegenerator/modulenamer.py
+comtypes/tools/codegenerator/namespaces.py
+comtypes/tools/codegenerator/packing.py
+comtypes/tools/codegenerator/typeannotator.py

{comtypes-1.4.2 → comtypes-1.4.3}/setup.py

@@ -160,6 +160,7 @@ setup_params = dict(
         "comtypes.client",
         "comtypes.server",
         "comtypes.tools",
+        "comtypes.tools.codegenerator",
         "comtypes.test",
     ],
 )

comtypes-1.4.2/comtypes/test/test_findgendir.py

@@ -1,94 +0,0 @@
-import os
-import sys
-import tempfile
-import types
-import unittest
-
-import comtypes
-import comtypes.client
-import comtypes.gen
-
-if sys.version_info >= (3, 4):
-    from importlib import reload
-else:
-    from imp import reload
-
-imgbase = os.path.splitext(os.path.basename(sys.executable))[0]
-
-
-class Test(unittest.TestCase):
-    """Test the comtypes.client._find_gen_dir() function in several
-    simulated environments.
-    """
-
-    def setUp(self):
-        # save the original comtypes.gen modules and create a
-        # substitute with an empty __path__.
-        self.orig_comtypesgen = sys.modules["comtypes.gen"]
-        del sys.modules["comtypes.gen"]
-        del comtypes.gen
-        mod = sys.modules["comtypes.gen"] = types.ModuleType("comtypes.gen")
-        mod.__path__ = []
-        comtypes.gen = mod
-
-    def tearDown(self):
-        # Delete py2exe-attributes that we have attached to the sys module
-        for name in "frozen frozendllhandle".split():
-            try:
-                delattr(sys, name)
-            except AttributeError:
-                pass
-        # restore the original comtypes.gen module
-        comtypes.gen = self.orig_comtypesgen
-        sys.modules["comtypes.gen"] = self.orig_comtypesgen
-        reload(comtypes.gen)
-
-    def test_script(self):
-        # %APPDATA%\Python\Python25\comtypes_cache
-        template = r"$APPDATA\Python\Python%d%d\comtypes_cache"
-        path = os.path.expandvars(template % sys.version_info[:2])
-        gen_dir = comtypes.client._find_gen_dir()
-        self.assertEqual(path, gen_dir)
-
-    def test_frozen_dll(self):
-        sys.frozen = "dll"
-        sys.frozendllhandle = sys.dllhandle
-        ma, mi = sys.version_info[:2]
-        # %TEMP%\comtypes_cache\<imagebasename>-25
-        # the image is python25.dll
-        path = os.path.join(
-            tempfile.gettempdir(),
-            r"comtypes_cache\%s%d%d-%d%d" % (imgbase, ma, mi, ma, mi),
-        )
-        gen_dir = comtypes.client._find_gen_dir()
-        self.assertEqual(path, gen_dir)
-
-    def test_frozen_console_exe(self):
-        sys.frozen = "console_exe"
-        # %TEMP%\comtypes_cache\<imagebasename>-25
-        path = os.path.join(
-            tempfile.gettempdir(),
-            r"comtypes_cache\%s-%d%d"
-            % (imgbase, sys.version_info[0], sys.version_info[1]),
-        )
-        gen_dir = comtypes.client._find_gen_dir()
-        self.assertEqual(path, gen_dir)
-
-    def test_frozen_windows_exe(self):
-        sys.frozen = "windows_exe"
-        # %TEMP%\comtypes_cache\<imagebasename>-25
-        path = os.path.join(
-            tempfile.gettempdir(),
-            r"comtypes_cache\%s-%d%d"
-            % (imgbase, sys.version_info[0], sys.version_info[1]),
-        )
-        gen_dir = comtypes.client._find_gen_dir()
-        self.assertEqual(path, gen_dir)
-
-
-def main():
-    unittest.main()
-
-
-if __name__ == "__main__":
-    main()