comtypes 1.4.2__zip → 1.4.4__zip

{comtypes-1.4.2/comtypes/tools → comtypes-1.4.4/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.4}/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.4}/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.4/comtypes.egg-info}/PKG-INFO

@@ -1,12 +1,11 @@
 Metadata-Version: 2.1
 Name: comtypes
-Version: 1.4.2
+Version: 1.4.4
 Summary: Pure Python COM package
 Home-page: https://github.com/enthought/comtypes
 Download-URL: https://github.com/enthought/comtypes/releases
 Author: Thomas Heller
 Author-email: theller@python.net
-License: MIT License
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -14,6 +13,7 @@ Classifier: Operating System :: Microsoft :: Windows
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 
@@ -31,7 +31,6 @@ License-File: LICENSE.txt
 `comtypes` allows to define, call, and implement custom and dispatch-based COM interfaces in pure `Python`.
 
 This package works on Windows only.
-- [`comtypes==1.1.7`](https://pypi.org/project/comtypes/1.1.7/) is the last version supporting Windows CE.
 
 Available on `Python` 3.7-3.12.
 - [`comtypes==1.2.1`](https://pypi.org/project/comtypes/1.2.1/) is the last version supporting `Python` 2.7 and 3.3-3.6.
@@ -75,6 +74,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.4}/comtypes.egg-info/SOURCES.txt

@@ -2,6 +2,8 @@ CHANGES.txt
 LICENSE.txt
 MANIFEST.in
 README.md
+pyproject.toml
+setup.cfg
 setup.py
 comtypes/GUID.py
 comtypes/__init__.py
@@ -54,6 +56,7 @@ comtypes/test/TestDispServer.tlb
 comtypes/test/__init__.py
 comtypes/test/find_memleak.py
 comtypes/test/mylib.idl
+comtypes/test/mylib.tlb
 comtypes/test/mytypelib.idl
 comtypes/test/runtests.py
 comtypes/test/setup.py
@@ -73,6 +76,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
@@ -99,9 +103,15 @@ comtypes/test/test_variant.py
 comtypes/test/test_win32com_interop.py
 comtypes/test/test_wmi.py
 comtypes/test/test_word.py
+comtypes/test/urlhist.tlb
 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.4/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=61.2"]
+build-backend = "setuptools.build_meta"

comtypes-1.4.4/setup.cfg

@@ -0,0 +1,51 @@
+[metadata]
+name = comtypes
+description = Pure Python COM package
+author = Thomas Heller
+author_email = theller@python.net
+url = https://github.com/enthought/comtypes
+download_url = https://github.com/enthought/comtypes/releases
+version = attr:comtypes.__version__
+long_description = file:README.md
+long_description_content_type = text/markdown
+classifiers = 
+	Development Status :: 5 - Production/Stable
+	Intended Audience :: Developers
+	License :: OSI Approved :: MIT License
+	Operating System :: Microsoft :: Windows
+	Programming Language :: Python
+	Programming Language :: Python :: 3
+	Topic :: Software Development :: Libraries :: Python Modules
+
+[options]
+python_requires = >=3.7
+packages = 
+	comtypes
+	comtypes.client
+	comtypes.server
+	comtypes.tools
+	comtypes.tools.codegenerator
+	comtypes.test
+
+[options.package_data]
+comtypes.test = 
+	TestComServer.idl
+	TestComServer.tlb
+	TestDispServer.idl
+	TestDispServer.tlb
+	mytypelib.idl
+	mylib.idl
+	mylib.tlb
+	urlhist.tlb
+	test_jscript.js
+comtypes = 
+	hints.pyi
+
+[options.entry_points]
+console_scripts = 
+	clear_comtypes_cache = comtypes.clear_cache:main
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

comtypes-1.4.4/setup.py

@@ -0,0 +1,117 @@
+"""comtypes package install script"""
+
+import sys
+import os
+import subprocess
+
+from setuptools import Command, setup
+from setuptools.command.install import install
+
+
+class test(Command):
+    # Original version of this class posted
+    # by Berthold Hoellmann to distutils-sig@python.org
+    description = "run tests"
+
+    user_options = [
+        ('tests=', 't', "comma-separated list of packages that contain test modules"),
+        (
+            'use-resources=',
+            'u',
+            "resources to use - resource names are defined by tests",
+        ),
+        (
+            'refcounts',
+            'r',
+            "repeat tests to search for refcount leaks (requires "
+            "'sys.gettotalrefcount')",
+        ),
+    ]
+
+    boolean_options = ["refcounts"]
+
+    def initialize_options(self):
+        self.use_resources = ""
+        self.refcounts = False
+        self.tests = "comtypes.test"
+        self.failure = False
+
+    def finalize_options(self):
+        if self.refcounts and not hasattr(sys, "gettotalrefcount"):
+            raise Exception("refcount option requires Python debug build")
+        self.tests = self.tests.split(",")
+        self.use_resources = self.use_resources.split(",")
+
+    def run(self):
+        build = self.reinitialize_command('build')
+        build.run()
+        if build.build_lib is not None:
+            sys.path.insert(0, build.build_lib)
+
+        # Register our ATL COM tester dll
+        import comtypes.test
+
+        script_path = os.path.dirname(__file__)
+        source_dir = os.path.abspath(os.path.join(script_path, "source"))
+        comtypes.test.register_server(source_dir)
+
+        comtypes.test.use_resources.extend(self.use_resources)
+        for name in self.tests:
+            package = __import__(name, globals(), locals(), ['*'])
+            sys.stdout.write(
+                "Testing package %s %s\n" % (name, (sys.version, sys.platform, os.name))
+            )
+            package_failure = comtypes.test.run_tests(
+                package, "test_*.py", self.verbose, self.refcounts
+            )
+            self.failure = self.failure or package_failure
+
+
+class post_install(install):
+    # both this static variable and method initialize_options() help to avoid
+    # weird setuptools error with "pip install comtypes", details are here:
+    # https://github.com/enthought/comtypes/issues/155
+    # the working solution was found here:
+    # https://github.com/pypa/setuptools/blob/3b90be7bb6323eb44d0f28864509c1d47aa098de/setuptools/command/install.py
+    user_options = install.user_options + [
+        ('old-and-unmanageable', None, "Try not to use this!"),
+        (
+            'single-version-externally-managed',
+            None,
+            "used by system package builders to create 'flat' eggs",
+        ),
+    ]
+
+    def initialize_options(self):
+        install.initialize_options(self)
+        self.old_and_unmanageable = None
+        self.single_version_externally_managed = None
+
+    def run(self):
+        install.run(self)
+        # Custom script we run at the end of installing
+        if not self.dry_run and not self.root:
+            print("Executing post install script...")
+            print(f'"{sys.executable}" -m comtypes.clear_cache -y')
+            try:
+                subprocess.check_call([
+                    sys.executable,
+                    "-m",
+                    "comtypes.clear_cache",
+                    '-y',
+                ])
+            except subprocess.CalledProcessError:
+                print("Failed to run post install script!")
+
+
+if __name__ == '__main__':
+    dist = setup(
+        cmdclass={
+            'test': test,
+            'install': post_install,
+        },
+    )
+    # Exit with a failure code if only running the tests and they failed
+    if dist.commands == ['test']:
+        command = dist.command_obj['test']
+        sys.exit(command.failure)