comtypes 1.4.2__zip → 1.4.4__zip

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

@@ -1,9 +1,29 @@
 Comtypes CHANGELOG
 ==================
 
-Release 1.4.2
+Release 1.4.4
+--------------
+* Stop mentioning the last version supporting Windows CE in ``README.md``. By @forderud.
+* Declare the minimum Python version as 3.7. By @jaraco.
+* Move package configuration to declarative config. By @jaraco.
+
+Release 1.4.3
 --------------
+* Refactor ``test_findgendir``. By @junkmd.
+* Update ``test_GUID``. By @junkmd.
+* Add a feature to ``typeannotator`` that interprets the return value. By @junkmd.
+* Update type annotations for ``_IUnknown_Base`` and ``IUnknown``. By @junkmd.
+* Add ``groupby_impltypeflags``. By @junkmd.
+* Add static typing for when a ``CoClass`` is assigned as the return value type. By @junkmd.
+* Improve ``EnumerationNamespaces`` and ``CodeGenerator.enum_aliases``. By @junkmd.
+* Modernize constructor arguments and attributes of each stuff in ``typedesc``. By @junkmd.
+* Split ``codegenerator`` into some modules in the sub-package directory. By @junkmd.
+* Implement record pointers as method parameters of a Dispatch Interface. By @geppi.
+* Add ``npsupport`` to CI pipeline matrix. By @junkmd.
+* Add "Frequently Asked Questions" to ``README.md``. By @junkmd.
 
+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.
@@ -12,7 +32,7 @@ Release 1.4.2
 
 Release 1.4.1
 --------------
-* Fix `TypeError` when defining enumeration types
+* Fix ``TypeError`` when defining enumeration types. By @junkmd.
 
 Release 1.4.0
 --------------

{comtypes-1.4.2/comtypes.egg-info → comtypes-1.4.4}/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}/README.md

@@ -12,7 +12,6 @@
 `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.
@@ -56,6 +55,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/__init__.py

@@ -1,5 +1,5 @@
 # comtypes version numbers follow semver (http://semver.org/) and PEP 440
-__version__ = "1.4.2"
+__version__ = "1.4.4"
 
 import atexit
 from ctypes import *
@@ -774,7 +774,7 @@ _T_IUnknown = TypeVar("_T_IUnknown", bound="IUnknown")
 
 if TYPE_CHECKING:
 
-    class _IUnknown_Base(c_void_p, metaclass=_cominterface_meta):
+    class _IUnknown_Base(c_void_p, metaclass=_cominterface_meta):  # type: ignore
         """This is workaround to avoid false-positive of static type checking.
 
         `IUnknown` behaves as a ctypes type, and `POINTER` can take it.
@@ -784,9 +784,7 @@ if TYPE_CHECKING:
         `builtins.object`.
         """
 
-        __com_QueryInterface: Callable[[Any, Any], int]
-        __com_AddRef: Callable[[], int]
-        __com_Release: Callable[[], int]
+        ...
 
 else:
     _IUnknown_Base = object
@@ -825,7 +823,7 @@ class IUnknown(_IUnknown_Base, metaclass=_cominterface_meta):
         p = POINTER(interface)()
         if iid is None:
             iid = interface._iid_
-        self.__com_QueryInterface(byref(iid), byref(p))
+        self.__com_QueryInterface(byref(iid), byref(p))  # type: ignore
         clsid = self.__dict__.get("__clsid")
         if clsid is not None:
             p.__dict__["__clsid"] = clsid
@@ -835,11 +833,11 @@ class IUnknown(_IUnknown_Base, metaclass=_cominterface_meta):
     # XXX There should be other ways to install a docstring.
     def AddRef(self) -> int:
         """Increase the internal refcount by one and return it."""
-        return self.__com_AddRef()
+        return self.__com_AddRef()  # type: ignore
 
     def Release(self) -> int:
         """Decrease the internal refcount by one and return it."""
-        return self.__com_Release()
+        return self.__com_Release()  # type: ignore
 
 
 ################################################################

{comtypes-1.4.2 → comtypes-1.4.4}/comtypes/automation.py

@@ -393,12 +393,36 @@ class tagVARIANT(Structure):
             ref = value._obj
             self._.c_void_p = addressof(ref)
             self.__keepref = value
-            self.vt = _ctype_to_vartype[type(ref)] | VT_BYREF
+            if isinstance(ref, Structure) and hasattr(ref, "_recordinfo_"):
+                guids = ref._recordinfo_
+                from comtypes.typeinfo import GetRecordInfoFromGuids
+
+                ri = GetRecordInfoFromGuids(*guids)
+                self.vt = VT_RECORD | VT_BYREF
+                # Assigning a COM pointer to a structure field does NOT
+                # call AddRef(), have to call it manually:
+                ri.AddRef()
+                self._.pRecInfo = ri
+                self._.pvRecord = cast(value, c_void_p)
+            else:
+                self.vt = _ctype_to_vartype[type(ref)] | VT_BYREF
         elif isinstance(value, _Pointer):
             ref = value.contents
             self._.c_void_p = addressof(ref)
             self.__keepref = value
-            self.vt = _ctype_to_vartype[type(ref)] | VT_BYREF
+            if isinstance(ref, Structure) and hasattr(ref, "_recordinfo_"):
+                guids = ref._recordinfo_
+                from comtypes.typeinfo import GetRecordInfoFromGuids
+
+                ri = GetRecordInfoFromGuids(*guids)
+                self.vt = VT_RECORD | VT_BYREF
+                # Assigning a COM pointer to a structure field does NOT
+                # call AddRef(), have to call it manually:
+                ri.AddRef()
+                self._.pRecInfo = ri
+                self._.pvRecord = cast(value, c_void_p)
+            else:
+                self.vt = _ctype_to_vartype[type(ref)] | VT_BYREF
         else:
             raise TypeError("Cannot put %r in VARIANT" % value)
         # buffer ->  SAFEARRAY of VT_UI1 ?

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

@@ -21,6 +21,10 @@ if sys.version_info >= (3, 8):
     from typing import Protocol
 else:
     from typing_extensions import Protocol
+if sys.version_info >= (3, 9):
+    from typing import Annotated as Annotated
+else:
+    from typing_extensions import Annotated as Annotated
 if sys.version_info >= (3, 10):
     from typing import Concatenate, ParamSpec, TypeAlias
     from typing import TypeGuard as TypeGuard
@@ -32,6 +36,7 @@ if sys.version_info >= (3, 11):
 else:
     from typing_extensions import Self
 
+import comtypes
 from comtypes.automation import IDispatch as IDispatch, VARIANT as VARIANT
 from comtypes.server import IClassFactory as IClassFactory
 from comtypes.typeinfo import ITypeInfo as ITypeInfo
@@ -46,6 +51,16 @@ Hresult: TypeAlias = int
 arguments and with `HRESULT` as its return type in its COM method definition.
 """
 
+_T_coclass = TypeVar("_T_coclass", bound=comtypes.CoClass)
+
+class FirstComItfOf(Generic[_T_coclass]):
+    """When the type assigned to the parameter marked as `'out'` is `CoClass`,
+    the return type of that method at runtime becomes `_com_interface_[0]`
+    due to the metaclass.
+    This is used as `Annotated` metadata for such parameters, taking `CoClass`
+    as an argument.
+    """
+
 class _MethodTypeDesc(Protocol):
     arguments: List[Tuple[Any, str, List[str], Optional[Any]]]
     idlflags: List[str]

{comtypes-1.4.2 → comtypes-1.4.4}/comtypes/test/test_GUID.py

@@ -1,34 +1,55 @@
-import os
 import unittest
 from comtypes import GUID
 
 
 class Test(unittest.TestCase):
-    def test(self):
+    def test_GUID_null(self):
         self.assertEqual(GUID(), GUID())
+        self.assertEqual(
+            str(GUID()),
+            "{00000000-0000-0000-0000-000000000000}",
+        )
+
+    def test_dunder_eq(self):
         self.assertEqual(
             GUID("{00000000-0000-0000-C000-000000000046}"),
             GUID("{00000000-0000-0000-C000-000000000046}"),
         )
 
+    def test_duner_str(self):
         self.assertEqual(
             str(GUID("{0002DF01-0000-0000-C000-000000000046}")),
             "{0002DF01-0000-0000-C000-000000000046}",
         )
+
+    def test_dunder_repr(self):
         self.assertEqual(
             repr(GUID("{0002DF01-0000-0000-C000-000000000046}")),
             'GUID("{0002DF01-0000-0000-C000-000000000046}")',
         )
 
+    def test_invalid_constructor_arg(self):
         self.assertRaises(WindowsError, GUID, "abc")
+
+    def test_from_progid(self):
+        self.assertEqual(
+            GUID.from_progid("Scripting.FileSystemObject"),
+            GUID("{0D43FE01-F093-11CF-8940-00A0C9054228}"),
+        )
         self.assertRaises(WindowsError, GUID.from_progid, "abc")
 
+    def test_as_progid(self):
+        self.assertEqual(
+            GUID("{0D43FE01-F093-11CF-8940-00A0C9054228}").as_progid(),
+            "Scripting.FileSystemObject",
+        )
         self.assertRaises(
             WindowsError,
             lambda guid: guid.as_progid(),
             GUID("{00000000-0000-0000-C000-000000000046}"),
         )
 
+    def test_create_new(self):
         self.assertNotEqual(GUID.create_new(), GUID.create_new())
 
 

comtypes-1.4.4/comtypes/test/test_dispifc_records.py

@@ -0,0 +1,90 @@
+# coding: utf-8
+
+import unittest
+
+from comtypes import CLSCTX_LOCAL_SERVER
+from comtypes.client import CreateObject, GetModule
+from ctypes import byref, pointer
+
+ComtypesCppTestSrvLib_GUID = "{07D2AEE5-1DF8-4D2C-953A-554ADFD25F99}"
+
+try:
+    GetModule((ComtypesCppTestSrvLib_GUID, 1, 0, 0))
+    import comtypes.gen.ComtypesCppTestSrvLib as ComtypesCppTestSrvLib
+
+    IMPORT_FAILED = False
+except (ImportError, OSError):
+    IMPORT_FAILED = True
+
+
+@unittest.skipIf(IMPORT_FAILED, "This depends on the out of process COM-server.")
+class Test_DispMethods(unittest.TestCase):
+    """Test dispmethods with record and record pointer parameters."""
+
+    EXPECTED_INITED_QUESTIONS = "The meaning of life, the universe and everything?"
+
+    def _create_dispifc(self) -> "ComtypesCppTestSrvLib.IDispRecordParamTest":
+        # Explicitely ask for the dispinterface of the component.
+        return CreateObject(
+            "Comtypes.DispIfcParamTests",
+            clsctx=CLSCTX_LOCAL_SERVER,
+            interface=ComtypesCppTestSrvLib.IDispRecordParamTest,
+        )
+
+    def test_inout_byref(self):
+        dispifc = self._create_dispifc()
+        # Passing a record by reference to a method that has declared the parameter
+        # as [in, out] we expect modifications of the record on the server side to
+        # also change the record on the client side.
+        test_record = ComtypesCppTestSrvLib.StructRecordParamTest()
+        self.assertEqual(test_record.question, None)
+        self.assertEqual(test_record.answer, 0)
+        self.assertEqual(test_record.needs_clarification, False)
+        dispifc.InitRecord(byref(test_record))
+        self.assertEqual(test_record.question, self.EXPECTED_INITED_QUESTIONS)
+        self.assertEqual(test_record.answer, 42)
+        self.assertEqual(test_record.needs_clarification, True)
+
+    def test_inout_pointer(self):
+        dispifc = self._create_dispifc()
+        # Passing a record pointer to a method that has declared the parameter
+        # as [in, out] we expect modifications of the record on the server side to
+        # also change the record on the client side.
+        test_record = ComtypesCppTestSrvLib.StructRecordParamTest()
+        self.assertEqual(test_record.question, None)
+        self.assertEqual(test_record.answer, 0)
+        self.assertEqual(test_record.needs_clarification, False)
+        dispifc.InitRecord(pointer(test_record))
+        self.assertEqual(test_record.question, self.EXPECTED_INITED_QUESTIONS)
+        self.assertEqual(test_record.answer, 42)
+        self.assertEqual(test_record.needs_clarification, True)
+
+    def test_in_record(self):
+        # Passing a record to a method that has declared the parameter just as [in]
+        # we expect modifications of the record on the server side NOT to change
+        # the record on the client side.
+        # We also need to test if the record gets properly passed to the method on
+        # the server side. For this, the 'VerifyRecord' method returns 'True' if
+        # all record fields have values equivalent to the initialization values
+        # provided by 'InitRecord'.
+        inited_record = ComtypesCppTestSrvLib.StructRecordParamTest()
+        inited_record.question = self.EXPECTED_INITED_QUESTIONS
+        inited_record.answer = 42
+        inited_record.needs_clarification = True
+        for rec, expected, (q, a, nc) in [
+            (inited_record, True, (self.EXPECTED_INITED_QUESTIONS, 42, True)),
+            # Also perform the inverted test. For this, create a blank record.
+            (ComtypesCppTestSrvLib.StructRecordParamTest(), False, (None, 0, False)),
+        ]:
+            with self.subTest(expected=expected, q=q, a=a, nc=nc):
+                # Perform the check on initialization values.
+                self.assertEqual(self._create_dispifc().VerifyRecord(rec), expected)
+                self.assertEqual(rec.question, q)
+                # Check if the 'answer' field is unchanged although the method
+                # modifies this field on the server side.
+                self.assertEqual(rec.answer, a)
+                self.assertEqual(rec.needs_clarification, nc)
+
+
+if __name__ == "__main__":
+    unittest.main()

comtypes-1.4.4/comtypes/test/test_findgendir.py

@@ -0,0 +1,87 @@
+import contextlib
+import importlib
+import os
+import sys
+import tempfile
+import types
+from typing import Iterator
+import unittest
+from unittest import mock
+
+import comtypes
+import comtypes.client
+import comtypes.gen
+
+
+IMGBASE = os.path.splitext(os.path.basename(sys.executable))[0]
+
+
+@contextlib.contextmanager
+def patch_empty_module_to_comtypes_gen() -> Iterator[types.ModuleType]:
+    with mock.patch.dict(sys.modules):
+        del sys.modules["comtypes.gen"]
+        mod = sys.modules["comtypes.gen"] = types.ModuleType("comtypes.gen")
+        mod.__path__ = []
+        with mock.patch.object(comtypes, "gen", mod):
+            try:
+                yield mod
+            finally:
+                importlib.reload(comtypes.gen)
+
+
+class Test(unittest.TestCase):
+    """Test the comtypes.client._find_gen_dir() function in several
+    simulated environments.
+    """
+
+    def test_script(self):
+        # %APPDATA%\Python\Python25\comtypes_cache
+        ma, mi = sys.version_info[:2]
+        cache = rf"$APPDATA\Python\Python{ma:d}{mi:d}\comtypes_cache"
+        path = os.path.expandvars(cache)
+        with patch_empty_module_to_comtypes_gen():
+            gen_dir = comtypes.client._find_gen_dir()
+            self.assertEqual(path, gen_dir)
+
+    # patch py2exe-attributes to `sys` modules
+    @mock.patch.object(sys, "frozen", "dll", create=True)
+    @mock.patch.object(sys, "frozendllhandle", sys.dllhandle, create=True)
+    def test_frozen_dll(self):
+        # %TEMP%\comtypes_cache\<imagebasename>25-25
+        # the image is python25.dll
+        ma, mi = sys.version_info[:2]
+        cache = rf"comtypes_cache\{IMGBASE}{ma:d}{mi:d}-{ma:d}{mi:d}"
+        path = os.path.join(tempfile.gettempdir(), cache)
+        with patch_empty_module_to_comtypes_gen():
+            gen_dir = comtypes.client._find_gen_dir()
+            self.assertEqual(path, gen_dir)
+
+    # patch py2exe-attributes to `sys` modules
+    @mock.patch.object(sys, "frozen", "console_exe", create=True)
+    def test_frozen_console_exe(self):
+        # %TEMP%\comtypes_cache\<imagebasename>-25
+        ma, mi = sys.version_info[:2]
+        cache = rf"comtypes_cache\{IMGBASE}-{ma:d}{mi:d}"
+        path = os.path.join(tempfile.gettempdir(), cache)
+        with patch_empty_module_to_comtypes_gen():
+            gen_dir = comtypes.client._find_gen_dir()
+            self.assertEqual(path, gen_dir)
+
+    # patch py2exe-attributes to `sys` modules
+    @mock.patch.object(sys, "frozen", "windows_exe", create=True)
+    def test_frozen_windows_exe(self):
+        # %TEMP%\comtypes_cache\<imagebasename>-25
+        ma, mi = sys.version_info[:2]
+        cache = rf"comtypes_cache\{IMGBASE}-{ma:d}{mi:d}"
+        path = os.path.join(tempfile.gettempdir(), cache)
+        with patch_empty_module_to_comtypes_gen():
+            gen_dir = comtypes.client._find_gen_dir()
+            self.assertEqual(path, gen_dir)
+
+
+def main():
+    unittest.main()
+
+
+if __name__ == "__main__":
+    main()

comtypes-1.4.4/comtypes/tools/codegenerator/__init__.py

@@ -0,0 +1,5 @@
+from comtypes.tools.codegenerator.modulenamer import (  # noqa
+    name_friendly_module,
+    name_wrapper_module,
+)
+from comtypes.tools.codegenerator.codegenerator import CodeGenerator, version  # noqa