comtypes 1.4.4__zip → 1.4.6__zip

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

@@ -1,6 +1,30 @@
 Comtypes CHANGELOG
 ==================
 
+Release 1.4.6
+--------------
+* Add tests and method annotations for ``IRecordInfo``. By @junkmd.
+* Improve static typings in ``automation``. By @junkmd.
+* Tidy up import part in some modules. By @junkmd.
+* Refer to ``Any`` and ``Tuple`` from the ``hints`` stub instead of directly importing them in generated modules. By @junkmd.
+* Modernize ``GUID.py``. By @junkmd.
+* Improve ``codegenerator.modulenamer`` static typing. By @junkmd.
+* Avoid using keywords in ``TYPE_CHECKING`` blocks. By @junkmd.
+* Improve member defining parts of ``ParseInterface`` and ``ParseDispatch``. By @junkmd.
+* Fix Annoying SyntaxWarning. By @v01d-gh.
+
+Release 1.4.5
+--------------
+* Split ``__init__.py`` into some modules. By @junkmd.
+* Fix importing ``_DispMemberSpec`` in ``automation``. By @junkmd.
+* Fix importing ``_encode_idl`` in ``_comobject``. By @junkmd.
+* Change the name of the component that implements the interface for record parameter testing. By @geppi.
+* Implement ``SAFEARRAY`` pointers and ``SAFEARRAY``s as method parameters of a Dispatch Interface. By @geppi.
+* Change the default value of the ``extra`` parameter in the ``create`` method of ``tagSAFEARRAY`` subtypes. By @geppi.
+* Implement static import for ``ISequentialStream``. By @jonschz.
+* Modernize ``test_wmi``. By @junkmd.
+* Add static typing for ``_midlSAFEARRAY``. By @junkmd.
+
 Release 1.4.4
 --------------
 * Stop mentioning the last version supporting Windows CE in ``README.md``. By @forderud.

{comtypes-1.4.4/comtypes.egg-info → comtypes-1.4.6}/PKG-INFO

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

{comtypes-1.4.4 → comtypes-1.4.6}/comtypes/GUID.py

@@ -1,8 +1,12 @@
-from ctypes import *
-import sys
+from ctypes import oledll, windll
+from ctypes import byref, c_byte, c_ushort, c_ulong, c_wchar_p, Structure
+from typing import Any, TYPE_CHECKING
 
+if TYPE_CHECKING:
+    from comtypes import hints  # type: ignore
 
-def binary(obj):
+
+def binary(obj: "GUID") -> bytes:
     return bytes(obj)
 
 
@@ -31,37 +35,32 @@ class GUID(Structure):
             _CLSIDFromString(str(name), byref(self))
 
     def __repr__(self):
-        return 'GUID("%s")' % str(self)
+        return f'GUID("{str(self)}")'
 
-    def __unicode__(self):
+    def __str__(self) -> str:
         p = c_wchar_p()
         _StringFromCLSID(byref(self), byref(p))
         result = p.value
         _CoTaskMemFree(p)
-        return result
-
-    __str__ = __unicode__
-
-    def __cmp__(self, other):
-        if isinstance(other, GUID):
-            return cmp(binary(self), binary(other))
-        return -1
+        # stringified `GUID_null` would be '{00000000-0000-0000-0000-000000000000}'
+        # Should we do `assert result is not None`?
+        return result  # type: ignore
 
-    def __bool__(self):
+    def __bool__(self) -> bool:
         return self != GUID_null
 
-    def __eq__(self, other):
+    def __eq__(self, other) -> bool:
         return isinstance(other, GUID) and binary(self) == binary(other)
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         # We make GUID instances hashable, although they are mutable.
         return hash(binary(self))
 
-    def copy(self):
+    def copy(self) -> "GUID":
         return GUID(str(self))
 
     @classmethod
-    def from_progid(cls, progid):
+    def from_progid(cls, progid: Any) -> "hints.Self":
         """Get guid from progid, ..."""
         if hasattr(progid, "_reg_clsid_"):
             progid = progid._reg_clsid_
@@ -74,19 +73,20 @@ class GUID(Structure):
             _CLSIDFromProgID(str(progid), byref(inst))
             return inst
         else:
-            raise TypeError("Cannot construct guid from %r" % progid)
+            raise TypeError(f"Cannot construct guid from {progid!r}")
 
-    def as_progid(self):
-        "Convert a GUID into a progid"
+    def as_progid(self) -> str:
+        """Convert a GUID into a progid"""
         progid = c_wchar_p()
         _ProgIDFromCLSID(byref(self), byref(progid))
         result = progid.value
         _CoTaskMemFree(progid)
-        return result
+        # Should we do `assert result is not None`?
+        return result  # type: ignore
 
     @classmethod
-    def create_new(cls):
-        "Create a brand new guid"
+    def create_new(cls) -> "hints.Self":
+        """Create a brand new guid"""
         guid = cls()
         _CoCreateGuid(byref(guid))
         return guid

comtypes-1.4.6/comtypes/__init__.py

@@ -0,0 +1,268 @@
+# comtypes version numbers follow semver (http://semver.org/) and PEP 440
+__version__ = "1.4.6"
+
+try:
+    from _ctypes import COMError  # noqa
+except ImportError as e:
+    msg = "\n".join(
+        (
+            "COM technology not available (maybe it's the wrong platform).",
+            "Note that COM is only supported on Windows.",
+            "For more details, please check: "
+            "https://learn.microsoft.com/en-us/windows/win32/com",
+        )
+    )
+    raise ImportError(msg) from e
+
+import atexit
+
+# HACK: Workaround for projects that depend on this package
+# There should be several projects around the world that depend on this package
+# and indirectly reference the symbols of `ctypes` from `comtypes`.
+# If we remove the wildcard import from `ctypes`, they might break. So it is
+# left in the following line.
+from ctypes import *  # noqa
+from ctypes import HRESULT  # noqa
+from ctypes import _Pointer, _SimpleCData  # noqa
+from ctypes import c_int, c_ulong, oledll, windll
+import logging
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ctypes import _CData  # only in `typeshed`, private in runtime
+    from comtypes import hints as hints  # noqa  # type: ignore
+else:
+    _CData = _SimpleCData.__mro__[:-1][-1]
+
+from comtypes.GUID import GUID
+from comtypes import patcher  # noqa
+from comtypes._npsupport import interop as npsupport  # noqa
+from comtypes._tlib_version_checker import _check_version  # noqa
+from comtypes._py_instance_method import instancemethod  # noqa
+from comtypes._idl_stuff import defaultvalue, helpstring, dispid  # noqa
+from comtypes._idl_stuff import STDMETHOD, DISPMETHOD, DISPPROPERTY, COMMETHOD  # noqa
+
+_all_slice = slice(None, None, None)
+
+
+class NullHandler(logging.Handler):
+    """A Handler that does nothing."""
+
+    def emit(self, record):
+        pass
+
+
+logger = logging.getLogger(__name__)
+
+# Add a NULL handler to the comtypes logger.  This prevents getting a
+# message like this:
+#    No handlers could be found for logger "comtypes"
+# when logging is not configured and logger.error() is called.
+logger.addHandler(NullHandler())
+
+
+class ReturnHRESULT(Exception):
+    """ReturnHRESULT(hresult, text)
+
+    Return a hresult code from a COM method implementation
+    without logging an error.
+    """
+
+
+# class IDLWarning(UserWarning):
+#    "Warn about questionable type information"
+
+_GUID = GUID
+IID = GUID
+DWORD = c_ulong
+
+wireHWND = c_ulong
+
+################################################################
+# About COM apartments:
+# http://blogs.msdn.com/larryosterman/archive/2004/04/28/122240.aspx
+################################################################
+
+################################################################
+# constants for object creation
+CLSCTX_INPROC_SERVER = 1
+CLSCTX_INPROC_HANDLER = 2
+CLSCTX_LOCAL_SERVER = 4
+
+CLSCTX_INPROC = 3
+CLSCTX_SERVER = 5
+CLSCTX_ALL = 7
+
+CLSCTX_INPROC_SERVER16 = 8
+CLSCTX_REMOTE_SERVER = 16
+CLSCTX_INPROC_HANDLER16 = 32
+CLSCTX_RESERVED1 = 64
+CLSCTX_RESERVED2 = 128
+CLSCTX_RESERVED3 = 256
+CLSCTX_RESERVED4 = 512
+CLSCTX_NO_CODE_DOWNLOAD = 1024
+CLSCTX_RESERVED5 = 2048
+CLSCTX_NO_CUSTOM_MARSHAL = 4096
+CLSCTX_ENABLE_CODE_DOWNLOAD = 8192
+CLSCTX_NO_FAILURE_LOG = 16384
+CLSCTX_DISABLE_AAA = 32768
+CLSCTX_ENABLE_AAA = 65536
+CLSCTX_FROM_DEFAULT_CONTEXT = 131072
+
+tagCLSCTX = c_int  # enum
+CLSCTX = tagCLSCTX
+
+# Constants for security setups
+SEC_WINNT_AUTH_IDENTITY_UNICODE = 0x2
+RPC_C_AUTHN_WINNT = 10
+RPC_C_AUTHZ_NONE = 0
+RPC_C_AUTHN_LEVEL_CONNECT = 2
+RPC_C_IMP_LEVEL_IMPERSONATE = 3
+EOAC_NONE = 0
+
+
+################################################################
+# Initialization and shutdown
+_ole32 = oledll.ole32
+_ole32_nohresult = windll.ole32  # use this for functions that don't return a HRESULT
+
+COINIT_MULTITHREADED = 0x0
+COINIT_APARTMENTTHREADED = 0x2
+COINIT_DISABLE_OLE1DDE = 0x4
+COINIT_SPEED_OVER_MEMORY = 0x8
+
+
+def CoInitialize():
+    return CoInitializeEx(COINIT_APARTMENTTHREADED)
+
+
+def CoInitializeEx(flags=None):
+    if flags is None:
+        flags = getattr(sys, "coinit_flags", COINIT_APARTMENTTHREADED)
+    logger.debug("CoInitializeEx(None, %s)", flags)
+    _ole32.CoInitializeEx(None, flags)
+
+
+# COM is initialized automatically for the thread that imports this
+# module for the first time.  sys.coinit_flags is passed as parameter
+# to CoInitializeEx, if defined, otherwise COINIT_APARTMENTTHREADED
+# (COINIT_MULTITHREADED on Windows CE) is used.
+#
+# A shutdown function is registered with atexit, so that
+# CoUninitialize is called when Python is shut down.
+CoInitializeEx()
+
+
+# We need to have CoUninitialize for multithreaded model where we have
+# to initialize and uninitialize COM for every new thread (except main)
+# in which we are using COM
+def CoUninitialize():
+    logger.debug("CoUninitialize()")
+    _ole32_nohresult.CoUninitialize()
+
+
+################################################################
+# global registries.
+
+# allows to find interface classes by guid strings (iid)
+com_interface_registry = {}
+
+# allows to find coclasses by guid strings (clsid)
+com_coclass_registry = {}
+
+
+################################################################
+# IUnknown, the root of all evil...
+from comtypes._post_coinit import _shutdown
+from comtypes._post_coinit.unknwn import IUnknown  # noqa
+
+atexit.register(_shutdown)
+
+################################################################
+
+from comtypes._post_coinit.bstr import BSTR  # noqa
+
+
+################################################################
+# IPersist is a trivial interface, which allows to ask an object about
+# its clsid.
+from comtypes._post_coinit.misc import IPersist, IServiceProvider  # noqa
+
+
+################################################################
+
+
+from comtypes._post_coinit.misc import (  # noqa
+    _is_object,
+    CoGetObject,
+    CoCreateInstance,
+    CoGetClassObject,
+    GetActiveObject,
+    MULTI_QI,
+    _COAUTHIDENTITY,
+    COAUTHIDENTITY,
+    _COAUTHINFO,
+    COAUTHINFO,
+    _COSERVERINFO,
+    COSERVERINFO,
+    _CoGetClassObject,
+    tagBIND_OPTS,
+    BIND_OPTS,
+    tagBIND_OPTS2,
+    BINDOPTS2,
+    _SEC_WINNT_AUTH_IDENTITY,
+    SEC_WINNT_AUTH_IDENTITY,
+    _SOLE_AUTHENTICATION_INFO,
+    SOLE_AUTHENTICATION_INFO,
+    _SOLE_AUTHENTICATION_LIST,
+    SOLE_AUTHENTICATION_LIST,
+    CoCreateInstanceEx,
+)
+
+
+################################################################
+from comtypes._comobject import COMObject
+
+# What's a coclass?
+# a POINTER to a coclass is allowed as parameter in a function declaration:
+# http://msdn.microsoft.com/library/en-us/midl/midl/oleautomation.asp
+
+from comtypes._meta import _coclass_meta
+
+
+class CoClass(COMObject, metaclass=_coclass_meta):
+    pass
+
+
+################################################################
+
+
+# fmt: off
+__known_symbols__ = [
+    "BIND_OPTS", "tagBIND_OPTS", "BINDOPTS2", "tagBIND_OPTS2", "BSTR",
+    "_check_version", "CLSCTX", "tagCLSCTX", "CLSCTX_ALL",
+    "CLSCTX_DISABLE_AAA", "CLSCTX_ENABLE_AAA", "CLSCTX_ENABLE_CODE_DOWNLOAD",
+    "CLSCTX_FROM_DEFAULT_CONTEXT", "CLSCTX_INPROC", "CLSCTX_INPROC_HANDLER",
+    "CLSCTX_INPROC_HANDLER16", "CLSCTX_INPROC_SERVER",
+    "CLSCTX_INPROC_SERVER16", "CLSCTX_LOCAL_SERVER", "CLSCTX_NO_CODE_DOWNLOAD",
+    "CLSCTX_NO_CUSTOM_MARSHAL", "CLSCTX_NO_FAILURE_LOG",
+    "CLSCTX_REMOTE_SERVER", "CLSCTX_RESERVED1", "CLSCTX_RESERVED2",
+    "CLSCTX_RESERVED3", "CLSCTX_RESERVED4", "CLSCTX_RESERVED5",
+    "CLSCTX_SERVER", "_COAUTHIDENTITY", "COAUTHIDENTITY", "_COAUTHINFO",
+    "COAUTHINFO", "CoClass", "CoCreateInstance", "CoCreateInstanceEx",
+    "_CoGetClassObject", "CoGetClassObject", "CoGetObject",
+    "COINIT_APARTMENTTHREADED", "COINIT_DISABLE_OLE1DDE",
+    "COINIT_MULTITHREADED", "COINIT_SPEED_OVER_MEMORY", "CoInitialize",
+    "CoInitializeEx", "COMError", "COMMETHOD", "COMObject", "_COSERVERINFO",
+    "COSERVERINFO", "CoUninitialize", "dispid", "DISPMETHOD", "DISPPROPERTY",
+    "DWORD", "EOAC_NONE", "GetActiveObject", "_GUID", "GUID", "helpstring",
+    "IID", "IPersist", "IServiceProvider", "IUnknown", "MULTI_QI",
+    "ReturnHRESULT", "RPC_C_AUTHN_LEVEL_CONNECT", "RPC_C_AUTHN_WINNT",
+    "RPC_C_AUTHZ_NONE", "RPC_C_IMP_LEVEL_IMPERSONATE",
+    "_SEC_WINNT_AUTH_IDENTITY", "SEC_WINNT_AUTH_IDENTITY",
+    "SEC_WINNT_AUTH_IDENTITY_UNICODE", "_SOLE_AUTHENTICATION_INFO",
+    "SOLE_AUTHENTICATION_INFO", "_SOLE_AUTHENTICATION_LIST",
+    "SOLE_AUTHENTICATION_LIST", "STDMETHOD", "wireHWND",
+]
+# fmt: on

{comtypes-1.4.4 → comtypes-1.4.6}/comtypes/_comobject.py

@@ -16,7 +16,8 @@ import os
 import queue
 import sys
 
-from comtypes import COMError, ReturnHRESULT, instancemethod, _encode_idl
+from comtypes import COMError, ReturnHRESULT, instancemethod
+from comtypes._memberspec import _encode_idl
 from comtypes.errorinfo import ISupportErrorInfo, ReportException, ReportError
 from comtypes import IPersist
 from comtypes.hresult import (

comtypes-1.4.6/comtypes/_idl_stuff.py

@@ -0,0 +1,67 @@
+from comtypes._memberspec import _ComMemberSpec, _DispMemberSpec, _resolve_argspec
+
+
+class helpstring(str):
+    "Specifies the helpstring for a COM method or property."
+
+
+class defaultvalue(object):
+    "Specifies the default value for parameters marked optional."
+
+    def __init__(self, value):
+        self.value = value
+
+
+class dispid(int):
+    "Specifies the DISPID of a method or property."
+
+
+# XXX STDMETHOD, COMMETHOD, DISPMETHOD, and DISPPROPERTY should return
+# instances with more methods or properties, and should not behave as an unpackable.
+
+
+def STDMETHOD(restype, name, argtypes=()) -> _ComMemberSpec:
+    "Specifies a COM method slot without idlflags"
+    return _ComMemberSpec(restype, name, argtypes, None, (), None)
+
+
+def DISPMETHOD(idlflags, restype, name, *argspec) -> _DispMemberSpec:
+    "Specifies a method of a dispinterface"
+    return _DispMemberSpec("DISPMETHOD", name, tuple(idlflags), restype, argspec)
+
+
+def DISPPROPERTY(idlflags, proptype, name) -> _DispMemberSpec:
+    "Specifies a property of a dispinterface"
+    return _DispMemberSpec("DISPPROPERTY", name, tuple(idlflags), proptype, ())
+
+
+# tuple(idlflags) is for the method itself: (dispid, 'readonly')
+
+# sample generated code:
+#     DISPPROPERTY([5, 'readonly'], OLE_YSIZE_HIMETRIC, 'Height'),
+#     DISPMETHOD(
+#         [6], None, 'Render', ([], c_int, 'hdc'), ([], c_int, 'x'), ([], c_int, 'y')
+#     )
+
+
+def COMMETHOD(idlflags, restype, methodname, *argspec) -> _ComMemberSpec:
+    """Specifies a COM method slot with idlflags.
+
+    XXX should explain the sematics of the arguments.
+    """
+    # collect all helpstring instances
+    # We should suppress docstrings when Python is started with -OO
+    # join them together(does this make sense?) and replace by None if empty.
+    helptext = "".join(t for t in idlflags if isinstance(t, helpstring)) or None
+    paramflags, argtypes = _resolve_argspec(argspec)
+    if "propget" in idlflags:
+        name = "_get_%s" % methodname
+    elif "propput" in idlflags:
+        name = "_set_%s" % methodname
+    elif "propputref" in idlflags:
+        name = "_setref_%s" % methodname
+    else:
+        name = methodname
+    return _ComMemberSpec(
+        restype, name, argtypes, paramflags, tuple(idlflags), helptext
+    )

{comtypes-1.4.4 → comtypes-1.4.6}/comtypes/_memberspec.py

@@ -1,16 +1,8 @@
 import ctypes
-from typing import (
-    Any,
-    Callable,
-    Dict,
-    Iterator,
-    List,
-    NamedTuple,
-    Optional,
-    Tuple,
-    Type,
-    Union as _UnionT,
-)
+from typing import Any, NamedTuple
+from typing import Dict, List, Tuple, Type
+from typing import Optional, Union as _UnionT
+from typing import Callable, Iterator
 
 from comtypes import _CData
 import comtypes

comtypes-1.4.6/comtypes/_post_coinit/__init__.py

@@ -0,0 +1,15 @@
+"""comtypes._post_coinit
+
+This subpackage contains symbols that should be imported into `comtypes/__init__.py`
+after `CoInitializeEx` is defined and called, and symbols that can be defined in
+any order during the initialization of the `comtypes` package.
+
+These were previously defined in `comtypes/__init__.py`, but due to the codebase
+of the file becoming bloated, reducing the ease of changes and increasing
+cognitive load, they have been moved here.
+
+This subpackage is called simultaneously with the initialization of `comtypes`.
+So it is necessary to maintain minimal settings to keep the lightweight action
+when the package is initialized.
+"""
+from comtypes._post_coinit.unknwn import _shutdown  # noqa

comtypes-1.4.6/comtypes/_post_coinit/bstr.py

@@ -0,0 +1,30 @@
+from ctypes import _SimpleCData, windll
+
+
+class BSTR(_SimpleCData):
+    "The windows BSTR data type"
+    _type_ = "X"
+    _needsfree = False
+
+    def __repr__(self):
+        return "%s(%r)" % (self.__class__.__name__, self.value)
+
+    def __ctypes_from_outparam__(self):
+        self._needsfree = True
+        return self.value
+
+    def __del__(self, _free=windll.oleaut32.SysFreeString):
+        # Free the string if self owns the memory
+        # or if instructed by __ctypes_from_outparam__.
+        if self._b_base_ is None or self._needsfree:
+            _free(self)
+
+    @classmethod
+    def from_param(cls, value):
+        """Convert into a foreign function call parameter."""
+        if isinstance(value, cls):
+            return value
+        # Although the builtin SimpleCData.from_param call does the
+        # right thing, it doesn't ensure that SysFreeString is called
+        # on destruction.
+        return cls(value)