comtypes 1.1.14__zip → 1.2.1__zip

{comtypes-1.1.14 → comtypes-1.2.1}/comtypes/automation.py

@@ -7,10 +7,12 @@ import sys
 from ctypes import *
 from ctypes import _Pointer
 from _ctypes import CopyComPointer
-from comtypes import IUnknown, GUID, IID, STDMETHOD, BSTR, COMMETHOD, COMError
+from comtypes import (
+    BSTR, COMError, COMMETHOD, GUID, IID, IUnknown, STDMETHOD, TYPE_CHECKING,
+)
 from comtypes.hresult import *
 import comtypes.patcher
-from comtypes import npsupport
+import comtypes
 try:
     from comtypes import _safearray
 except (ImportError, AttributeError):
@@ -19,6 +21,12 @@ except (ImportError, AttributeError):
 
 from ctypes.wintypes import DWORD, LONG, UINT, VARIANT_BOOL, WCHAR, WORD
 
+if TYPE_CHECKING:
+    from typing import (
+        Any, Callable, ClassVar, List, Optional, Tuple, Union as _UnionT,
+    )
+    from comtypes import hints
+
 
 if sys.version_info >= (3, 0):
     int_types = (int, )
@@ -149,6 +157,13 @@ DECIMAL = tagDEC
 # The VARIANT structure is a good candidate for implementation in a C
 # helper extension.  At least the get/set methods.
 class tagVARIANT(Structure):
+    if TYPE_CHECKING:
+        vt = hints.AnnoField()  # type: int
+        _ = hints.AnnoField()  # type: U_VARIANT1.__tagVARIANT.U_VARIANT2
+        null = hints.AnnoField()  # type: ClassVar[VARIANT]
+        empty = hints.AnnoField()  # type: ClassVar[VARIANT]
+        missing = hints.AnnoField()  # type: ClassVar[VARIANT]
+
     class U_VARIANT1(Union):
         class __tagVARIANT(Structure):
             # The C Header file defn of VARIANT is much more complicated, but
@@ -205,6 +220,12 @@ class tagVARIANT(Structure):
     def __repr__(self):
         if self.vt & VT_BYREF:
             return "VARIANT(vt=0x%x, byref(%r))" % (self.vt, self[0])
+        elif self is type(self).null:
+            return "VARIANT.null"
+        elif self is type(self).empty:
+            return "VARIANT.empty"
+        elif self is type(self).missing:
+            return "VARIANT.missing"
         return "VARIANT(vt=0x%x, %r)" % (self.vt, self.value)
 
     @classmethod
@@ -284,9 +305,9 @@ class tagVARIANT(Structure):
             com_days = delta.days + (delta.seconds + delta.microseconds * 1e-6) / 86400.
             self.vt = VT_DATE
             self._.VT_R8 = com_days
-        elif npsupport.isdatetime64(value):
-            com_days = value - npsupport.com_null_date64
-            com_days /= npsupport.numpy.timedelta64(1, 'D')
+        elif comtypes.npsupport.isdatetime64(value):
+            com_days = value - comtypes.npsupport.com_null_date64
+            com_days /= comtypes.npsupport.numpy.timedelta64(1, 'D')
             self.vt = VT_DATE
             self._.VT_R8 = com_days
         elif decimal is not None and isinstance(value, decimal.Decimal):
@@ -308,10 +329,10 @@ class tagVARIANT(Structure):
             obj = _midlSAFEARRAY(typ).create(value)
             memmove(byref(self._), byref(obj), sizeof(obj))
             self.vt = VT_ARRAY | obj._vartype_
-        elif npsupport.isndarray(value):
+        elif comtypes.npsupport.isndarray(value):
             # Try to convert a simple array of basic types.
             descr = value.dtype.descr[0][1]
-            typ = npsupport.typecodes.get(descr)
+            typ = comtypes.npsupport.typecodes.get(descr)
             if typ is None:
                 # Try for variant
                 obj = _midlSAFEARRAY(VARIANT).create(value)
@@ -553,7 +574,7 @@ v._.VT_I4 = 0x80020004
 del v
 
 _carg_obj = type(byref(c_int()))
-from _ctypes import Array as _CArrayType
+from ctypes import Array as _CArrayType
 
 @comtypes.patcher.Patch(POINTER(VARIANT))
 class _(object):
@@ -650,6 +671,17 @@ IEnumVARIANT._methods_ = [
 
 
 class tagEXCEPINFO(Structure):
+    if TYPE_CHECKING:
+        wCode = hints.AnnoField()  # type: int
+        wReserved = hints.AnnoField()  # type: int
+        bstrSource = hints.AnnoField()  # type: str
+        bstrDescription = hints.AnnoField()  # type: str
+        bstrHelpFile = hints.AnnoField()  # type: str
+        dwHelpContext = hints.AnnoField()  # type: int
+        pvReserved = hints.AnnoField()  # type: Optional[int]
+        pfnDeferredFillIn = hints.AnnoField()  # type: Optional[int]
+        scode = hints.AnnoField()  # type: int
+
     def __repr__(self):
         return "<EXCEPINFO %s>" % \
                ((self.wCode, self.bstrSource, self.bstrDescription, self.bstrHelpFile, self.dwHelpContext,
@@ -669,6 +701,11 @@ tagEXCEPINFO._fields_ = [
 EXCEPINFO = tagEXCEPINFO
 
 class tagDISPPARAMS(Structure):
+    if TYPE_CHECKING:
+        rgvarg = hints.AnnoField()  # type: Array[VARIANT]
+        rgdispidNamedArgs = hints.AnnoField()  # type: _Pointer[DISPID]
+        cArgs = hints.AnnoField()  # type: int
+        cNamedArgs = hints.AnnoField()  # type: int
     _fields_ = [
         # C:/Programme/gccxml/bin/Vc71/PlatformSDK/oaidl.h 696
         ('rgvarg', POINTER(VARIANTARG)),
@@ -691,7 +728,29 @@ DISPID_CONSTRUCTOR = -6
 DISPID_DESTRUCTOR = -7
 DISPID_COLLECT = -8
 
+
+if TYPE_CHECKING:
+    RawGetIDsOfNamesFunc = Callable[
+        [_byref_type, Array[c_wchar_p], int, int, Array[DISPID]], int,
+    ]
+    RawInvokeFunc = Callable[
+        [
+            int, _byref_type, int, int,  # dispIdMember, riid, lcid, wFlags
+            _UnionT[_byref_type, DISPPARAMS],  # *pDispParams
+            _UnionT[_byref_type, VARIANT],  # pVarResult
+            _UnionT[_byref_type, EXCEPINFO, None],  # pExcepInfo
+            _UnionT[_byref_type, c_uint],  # puArgErr
+        ],
+        int
+    ]
+
 class IDispatch(IUnknown):
+    if TYPE_CHECKING:
+        _disp_methods_ = hints.AnnoField()  # type: ClassVar[List[comtypes._DispMemberSpec]]
+        _GetTypeInfo = hints.AnnoField()  # type: Callable[[int, int], IUnknown]
+        __com_GetIDsOfNames = hints.AnnoField()  # type: RawGetIDsOfNamesFunc
+        __com_Invoke = hints.AnnoField()  # type: RawInvokeFunc
+
     _iid_ = GUID("{00020400-0000-0000-C000-000000000046}")
     _methods_ = [
         COMMETHOD([], HRESULT, 'GetTypeInfoCount',
@@ -699,9 +758,9 @@ class IDispatch(IUnknown):
         COMMETHOD([], HRESULT, 'GetTypeInfo',
                   (['in'], UINT, 'index'),
                   (['in'], LCID, 'lcid', 0),
-## Normally, we would declare this parameter in this way:
-##                  (['out'], POINTER(POINTER(ITypeInfo)) ) ),
-## but we cannot import comtypes.typeinfo at the top level (recursive imports!).
+                # Normally, we would declare this parameter in this way:
+                # (['out'], POINTER(POINTER(ITypeInfo)) ) ),
+                # but we cannot import comtypes.typeinfo at the top level (recursive imports!).
                   (['out'], POINTER(POINTER(IUnknown)) ) ),
         STDMETHOD(HRESULT, 'GetIDsOfNames', [POINTER(IID), POINTER(c_wchar_p),
                                              UINT, LCID, POINTER(DISPID)]),
@@ -711,12 +770,14 @@ class IDispatch(IUnknown):
     ]
 
     def GetTypeInfo(self, index, lcid=0):
+        # type: (int, int) -> hints.ITypeInfo
         """Return type information.  Index 0 specifies typeinfo for IDispatch"""
         import comtypes.typeinfo
         result = self._GetTypeInfo(index, lcid)
         return result.QueryInterface(comtypes.typeinfo.ITypeInfo)
 
     def GetIDsOfNames(self, *names, **kw):
+        # type: (str, Any) -> List[int]
         """Map string names to integer ids."""
         lcid = kw.pop("lcid", 0)
         assert not kw
@@ -726,6 +787,7 @@ class IDispatch(IUnknown):
         return ids[:]
 
     def _invoke(self, memid, invkind, lcid, *args):
+        # type: (int, int, int, Any) -> Any
         var = VARIANT()
         argerr = c_uint()
         dp = DISPPARAMS()
@@ -747,6 +809,7 @@ class IDispatch(IUnknown):
         return var._get_value(dynamic=True)
 
     def Invoke(self, dispid, *args, **kw):
+        # type: (int, Any, Any) -> Any
         """Invoke a method or property."""
 
         # Memory management in Dispatch::Invoke calls:
@@ -896,3 +959,28 @@ try:
     from comtypes.safearray import _midlSAFEARRAY
 except (ImportError, AttributeError):
     pass
+
+
+__known_symbols__ = [
+    'CURRENCY', 'CY', 'tagCY', 'DECIMAL', 'tagDEC', 'DISPATCH_METHOD',
+    'DISPATCH_PROPERTYGET', 'DISPATCH_PROPERTYPUT', 'DISPATCH_PROPERTYPUTREF',
+    'DISPID', 'DISPID_COLLECT', 'DISPID_CONSTRUCTOR', 'DISPID_DESTRUCTOR',
+    'DISPID_EVALUATE', 'DISPID_NEWENUM', 'DISPID_PROPERTYPUT',
+    'DISPID_UNKNOWN', 'DISPID_VALUE', 'DISPPARAMS', 'tagDISPPARAMS',
+    'EXCEPINFO', 'tagEXCEPINFO', 'IDispatch', 'IEnumVARIANT', 'IID_NULL',
+    'INVOKE_FUNC', 'INVOKE_PROPERTYGET', 'INVOKE_PROPERTYPUT',
+    'INVOKE_PROPERTYPUTREF', 'INVOKEKIND', 'tagINVOKEKIND', '_midlSAFEARRAY',
+    'SCODE', '_SysAllocStringLen', 'VARENUM', 'VARIANT','tagVARIANT', 
+    'VARIANTARG', '_VariantChangeType', '_VariantClear', '_VariantCopy',
+    '_VariantCopyInd', 'VARTYPE', 'VT_ARRAY', 'VT_BLOB', 'VT_BLOB_OBJECT',
+    'VT_BOOL', 'VT_BSTR', 'VT_BSTR_BLOB', 'VT_BYREF', 'VT_CARRAY', 'VT_CF',
+    'VT_CLSID', 'VT_CY', 'VT_DATE', 'VT_DECIMAL', 'VT_DISPATCH', 'VT_EMPTY',
+    'VT_ERROR', 'VT_FILETIME', 'VT_HRESULT', 'VT_I1', 'VT_I2', 'VT_I4',
+    'VT_I8', 'VT_ILLEGAL', 'VT_ILLEGALMASKED', 'VT_INT', 'VT_INT_PTR',
+    'VT_LPSTR', 'VT_LPWSTR', 'VT_NULL', 'VT_PTR', 'VT_R4', 'VT_R8',
+    'VT_RECORD', 'VT_RESERVED', 'VT_SAFEARRAY', 'VT_STORAGE',
+    'VT_STORED_OBJECT', 'VT_STREAM', 'VT_STREAMED_OBJECT', 'VT_TYPEMASK',
+    'VT_UI1', 'VT_UI2', 'VT_UI4', 'VT_UI8', 'VT_UINT', 'VT_UINT_PTR',
+    'VT_UNKNOWN', 'VT_USERDEFINED', 'VT_VARIANT', 'VT_VECTOR',
+    'VT_VERSIONED_STREAM', 'VT_VOID',
+]

{comtypes-1.1.14 → comtypes-1.2.1}/comtypes/client/__init__.py

@@ -9,43 +9,47 @@
 #
 ################################################################
 
-import sys, os
 import ctypes
+import logging
+import os
+import sys
 
 import comtypes
 from comtypes.hresult import *
-import comtypes.automation
-import comtypes.typeinfo
+from comtypes import (
+    automation, CoClass, GUID, IUnknown, TYPE_CHECKING, typeinfo,
+)
 import comtypes.client.dynamic
-
 from comtypes.client._constants import Constants
 from comtypes.client._events import GetEvents, ShowEvents, PumpEvents
 from comtypes.client._generate import GetModule
-
-import logging
-logger = logging.getLogger(__name__)
-
-__all__ = ["CreateObject", "GetActiveObject", "CoGetObject",
-           "GetEvents", "ShowEvents", "PumpEvents", "GetModule",
-           "GetClassObject"]
-
 from comtypes.client._code_cache import _find_gen_dir
 
 gen_dir = _find_gen_dir()
 import comtypes.gen
-
 ### for testing
 ##gen_dir = None
 
+if TYPE_CHECKING:
+    from typing import Any, Optional, overload, Type, TypeVar, Union as _UnionT
+    from comtypes import hints
+    _T_IUnknown = TypeVar("_T_IUnknown", bound=IUnknown)
+
+logger = logging.getLogger(__name__)
+
+
 def wrap_outparam(punk):
+    # type: (Any) -> Any
     logger.debug("wrap_outparam(%s)", punk)
     if not punk:
         return None
-    if punk.__com_interface__ == comtypes.automation.IDispatch:
+    if punk.__com_interface__ == automation.IDispatch:
         return GetBestInterface(punk)
     return punk
 
+
 def GetBestInterface(punk):
+    # type: (Any) -> Any
     """Try to QueryInterface a COM pointer to the 'most useful'
     interface.
 
@@ -60,13 +64,13 @@ def GetBestInterface(punk):
     logger.debug("GetBestInterface(%s)", punk)
     try:
         try:
-            pci = punk.QueryInterface(comtypes.typeinfo.IProvideClassInfo)
+            pci = punk.QueryInterface(typeinfo.IProvideClassInfo)
             logger.debug("Does implement IProvideClassInfo")
         except comtypes.COMError:
             # Some COM objects support IProvideClassInfo2, but not IProvideClassInfo.
             # These objects are broken, but we support them anyway.
             logger.debug("Does NOT implement IProvideClassInfo, trying IProvideClassInfo2")
-            pci = punk.QueryInterface(comtypes.typeinfo.IProvideClassInfo2)
+            pci = punk.QueryInterface(typeinfo.IProvideClassInfo2)
             logger.debug("Does implement IProvideClassInfo2")
         tinfo = pci.GetClassInfo() # TypeInfo for the CoClass
         # find the interface marked as default
@@ -86,7 +90,7 @@ def GetBestInterface(punk):
     except comtypes.COMError:
         logger.debug("Does NOT implement IProvideClassInfo/IProvideClassInfo2")
         try:
-            pdisp = punk.QueryInterface(comtypes.automation.IDispatch)
+            pdisp = punk.QueryInterface(automation.IDispatch)
         except comtypes.COMError:
             logger.debug("No Dispatch interface: %s", punk)
             return punk
@@ -131,13 +135,23 @@ def GetBestInterface(punk):
 wrap = GetBestInterface
 
 # Should we do this for POINTER(IUnknown) also?
-ctypes.POINTER(comtypes.automation.IDispatch).__ctypes_from_outparam__ = wrap_outparam
+ctypes.POINTER(automation.IDispatch).__ctypes_from_outparam__ = wrap_outparam  # type: ignore
 
 ################################################################
 #
 # Object creation
 #
+if comtypes.TYPE_CHECKING:
+    @overload
+    def GetActiveObject(progid):
+        # type: (_UnionT[str, CoClass, GUID]) -> Any
+        pass
+    @overload
+    def GetActiveObject(progid, interface):
+        # type: (_UnionT[str, CoClass, GUID], Type[_T_IUnknown]) -> _T_IUnknown
+        pass
 def GetActiveObject(progid, interface=None, dynamic=False):
+    # type: (_UnionT[str, CoClass, GUID], Optional[Any], bool) -> Any
     """Return a pointer to a running COM object that has been
     registered with COM.
 
@@ -147,11 +161,11 @@ def GetActiveObject(progid, interface=None, dynamic=False):
     'interface' allows to force a certain interface.
     'dynamic=True' will return a dynamic dispatch object.
     """
-    clsid = comtypes.GUID.from_progid(progid)
+    clsid = GUID.from_progid(progid)
     if dynamic:
         if interface is not None:
             raise ValueError("interface and dynamic are mutually exclusive")
-        interface = comtypes.automation.IDispatch
+        interface = automation.IDispatch
     elif interface is None:
         interface = getattr(progid, "_com_interfaces_", [None])[0]
     obj = comtypes.GetActiveObject(clsid, interface=interface)
@@ -159,32 +173,55 @@ def GetActiveObject(progid, interface=None, dynamic=False):
         return comtypes.client.dynamic.Dispatch(obj)
     return _manage(obj, clsid, interface=interface)
 
+
 def _manage(obj, clsid, interface):
+    # type: (Any, Optional[GUID], Optional[Type[IUnknown]]) -> Any
     obj.__dict__['__clsid'] = str(clsid)
     if interface is None:
         obj = GetBestInterface(obj)
     return obj
 
+
+if TYPE_CHECKING:
+    @overload
+    def GetClassObject(progid, clsctx=None, pServerInfo=None):
+        # type: (_UnionT[str, CoClass, GUID], Optional[int], Optional[comtypes.COSERVERINFO]) -> hints.IClassFactory
+        pass
+    @overload
+    def GetClassObject(progid, clsctx=None, pServerInfo=None, interface=None):
+        # type: (_UnionT[str, CoClass, GUID], Optional[int], Optional[comtypes.COSERVERINFO], Optional[Type[_T_IUnknown]]) -> _T_IUnknown
+        pass
 def GetClassObject(progid,
                    clsctx=None,
                    pServerInfo=None,
                    interface=None):
+    # type: (_UnionT[str, CoClass, GUID], Optional[int], Optional[comtypes.COSERVERINFO], Optional[Type[IUnknown]]) -> IUnknown
     """Create and return the class factory for a COM object.
 
     'clsctx' specifies how to create the object, use the CLSCTX_... constants.
     'pServerInfo', if used, must be a pointer to a comtypes.COSERVERINFO instance
     'interface' may be used to request an interface other than IClassFactory
     """
-    clsid = comtypes.GUID.from_progid(progid)
-    return comtypes.CoGetClassObject(clsid,
-                                     clsctx, pServerInfo, interface)
+    clsid = GUID.from_progid(progid)
+    return comtypes.CoGetClassObject(clsid, clsctx, pServerInfo, interface)
 
+
+if TYPE_CHECKING:
+    @overload
+    def CreateObject(progid):
+        # type: (_UnionT[str, CoClass, GUID]) -> Any
+        pass
+    @overload
+    def CreateObject(progid, clsctx=None, machine=None, interface=None, dynamic=False, pServerInfo=None):
+        # type: (_UnionT[str, CoClass, GUID], Optional[int], Optional[str], Optional[Type[_T_IUnknown]], bool, Optional[comtypes.COSERVERINFO]) -> _T_IUnknown
+        pass
 def CreateObject(progid,                  # which object to create
                  clsctx=None,             # how to create the object
                  machine=None,            # where to create the object
                  interface=None,          # the interface we want
                  dynamic=False,           # use dynamic dispatch
                  pServerInfo=None):       # server info struct for remoting
+    # type: (_UnionT[str, CoClass, GUID], Optional[int], Optional[str], Optional[Type[IUnknown]], bool, Optional[comtypes.COSERVERINFO]) -> Any
     """Create a COM object from 'progid', and try to QueryInterface()
     it to the most useful interface, generating typelib support on
     demand.  A pointer to this interface is returned.
@@ -201,12 +238,12 @@ def CreateObject(progid,                  # which object to create
 
     You can also later request to receive events with GetEvents().
     """
-    clsid = comtypes.GUID.from_progid(progid)
+    clsid = GUID.from_progid(progid)
     logger.debug("%s -> %s", progid, clsid)
     if dynamic:
         if interface:
             raise ValueError("interface and dynamic are mutually exclusive")
-        interface = comtypes.automation.IDispatch
+        interface = automation.IDispatch
     elif interface is None:
         interface = getattr(progid, "_com_interfaces_", [None])[0]
     if machine is None and pServerInfo is None:
@@ -226,7 +263,18 @@ def CreateObject(progid,                  # which object to create
         return comtypes.client.dynamic.Dispatch(obj)
     return _manage(obj, clsid, interface=interface)
 
+
+if TYPE_CHECKING:
+    @overload
+    def CoGetObject(displayname, interface):
+        # type: (str, Type[_T_IUnknown]) -> _T_IUnknown
+        pass
+    @overload
+    def CoGetObject(displayname, interface=None, dynamic=False):
+        # type: (str, None, bool) -> Any
+        pass
 def CoGetObject(displayname, interface=None, dynamic=False):
+    # type: (str, Optional[Type[comtypes.IUnknown]], bool) -> Any
     """Create an object by calling CoGetObject(displayname).
 
     Additional parameters have the same meaning as in CreateObject().
@@ -234,10 +282,16 @@ def CoGetObject(displayname, interface=None, dynamic=False):
     if dynamic:
         if interface is not None:
             raise ValueError("interface and dynamic are mutually exclusive")
-        interface = comtypes.automation.IDispatch
+        interface = automation.IDispatch
     punk = comtypes.CoGetObject(displayname, interface)
     if dynamic:
         return comtypes.client.dynamic.Dispatch(punk)
     return _manage(punk,
                    clsid=None,
                    interface=interface)
+
+
+__all__ = [
+    "CreateObject", "GetActiveObject", "CoGetObject", "GetEvents",
+    "ShowEvents", "PumpEvents", "GetModule", "GetClassObject",
+]