comtypes 1.1.14__zip → 1.2.1__zip

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

@@ -1,16 +1,106 @@
-import types
-import sys
+# comtypes version numbers follow semver (http://semver.org/) and PEP 440
+__version__ = "1.2.1"
+
+import atexit
+from ctypes import *
+from ctypes import _SimpleCData
+from _ctypes import COMError
+import logging
 import os
+import sys
+import types
 
-# comtypes version numbers follow semver (http://semver.org/) and PEP 440
-__version__ = "1.1.14"
+################################################################
+
+def add_metaclass(metaclass):
+    """Class decorator from six.py for creating a class with a metaclass.
+
+    Copyright (c) 2010-2020 Benjamin Peterson
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy of
+    this software and associated documentation files (the "Software"), to deal in
+    the Software without restriction, including without limitation the rights to
+    use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+    the Software, and to permit persons to whom the Software is furnished to do so,
+    subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
 
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+    FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+    COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+    IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+    CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+    """
+    def wrapper(cls):
+        orig_vars = cls.__dict__.copy()
+        slots = orig_vars.get('__slots__')
+        if slots is not None:
+            if isinstance(slots, text_type):
+                slots = [slots]
+            for slots_var in slots:
+                orig_vars.pop(slots_var)
+        orig_vars.pop('__dict__', None)
+        orig_vars.pop('__weakref__', None)
+        if hasattr(cls, '__qualname__'):
+            orig_vars['__qualname__'] = cls.__qualname__
+        return metaclass(cls.__name__, cls.__bases__, orig_vars)
+    return wrapper
+
+################################################################
+
+# type hinting symbols
+#
+# `if TYPE_CHECKING:` code block must not be executed because `TYPE_CHECKING`
+# is always `False` in runtime.
+# see https://peps.python.org/pep-0484/#runtime-or-type-checking
+#
+if sys.version_info >= (3, 5):
+    from typing import TYPE_CHECKING
+else:  # typehints in this package don't support Py<3.5 due to importing symbols.
+    TYPE_CHECKING = False
+#
+# Annotations must be placed in a `# type:` comment in according to PEP484.
+# see https://peps.python.org/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
+# - `NameError` never raises by using those symbols.
+# - It is not able to use any runtime introspections, such as
+#   `typing.get_type_hints` or `typing.get_origin`.
+#
+if TYPE_CHECKING:
+    from ctypes import _CData  # only in `typeshed`, private in runtime
+    # _CData = _SimpleCData.__mro__[:-1][-1]  # defining in runtime
+    from ctypes import _Pointer
+    from typing import Any, ClassVar, overload, TypeVar
+    # XXX: symbols for backward compatibility.
+    # instead of `builtins`. see PEP585.
+    from typing import Dict, List, Tuple, Type
+    # instead of `collections.abc`. see PEP585.
+    from typing import Callable, Iterable, Iterator
+    # instead of `A | B` and `None | A`. see PEP604.
+    from typing import Union as _UnionT  #  avoiding confusion with `ctypes.Union`
+    from typing import Optional
+    # utilities or workarounds for annotations.
+    from comtypes import hints as hints
+
+################################################################
+
+from comtypes.GUID import GUID
+from comtypes import patcher
+from comtypes._npsupport import interop as npsupport
+from comtypes._memberspec import (
+    ComMemberGenerator, _ComMemberSpec, DispMemberGenerator, _DispMemberSpec,
+    _encode_idl, _resolve_argspec,
+)
+
+################################################################
 if sys.version_info >= (3, 0):
     text_type = str
 else:
     text_type = unicode
+_all_slice = slice(None, None, None)
 
-import logging
 class NullHandler(logging.Handler):
     """A Handler that does nothing."""
     def emit(self, record):
@@ -24,9 +114,6 @@ logger = logging.getLogger(__name__)
 # when logging is not configured and logger.error() is called.
 logger.addHandler(NullHandler())
 
-from ctypes import *
-from _ctypes import COMError
-from comtypes import patcher
 
 def _check_version(actual, tlib_cached_mtime=None):
     from comtypes.tools.codegenerator import version as required
@@ -42,25 +129,6 @@ def _check_version(actual, tlib_cached_mtime=None):
         if not tlib_cached_mtime or abs(tlib_curr_mtime - tlib_cached_mtime) >= 1:
             raise ImportError("Typelib different than module")
 
-try:
-    COMError()
-except TypeError:
-    pass
-else:
-    # Python 2.5 and 2.5.1 have a bug in the COMError implementation:
-    # The type has no __init__ method, and no hresult, text, and
-    # details instance vars.  Work around this bug by monkeypatching
-    # COMError.
-    def monkeypatch_COMError():
-        def __init__(self, hresult, text, details):
-            self.hresult = hresult
-            self.text = text
-            self.details = details
-            super(COMError, self).__init__(hresult, text, details)
-        COMError.__init__ = __init__
-    monkeypatch_COMError()
-    del monkeypatch_COMError
-
 if sys.version_info >= (3, 0):
     pythonapi.PyInstanceMethod_New.argtypes = [py_object]
     pythonapi.PyInstanceMethod_New.restype = py_object
@@ -85,7 +153,6 @@ class ReturnHRESULT(Exception):
 ##class IDLWarning(UserWarning):
 ##    "Warn about questionable type information"
 
-from comtypes.GUID import GUID
 _GUID = GUID
 IID = GUID
 DWORD = c_ulong
@@ -192,7 +259,6 @@ def _shutdown(func=_ole32_nohresult.CoUninitialize,
         _cominterface_meta._com_shutting_down = True
     _debug("CoUninitialize() done.")
 
-import atexit
 atexit.register(_shutdown)
 
 ################################################################
@@ -225,6 +291,11 @@ class _cominterface_meta(type):
     """Metaclass for COM interfaces.  Automatically creates high level
     methods from COMMETHOD lists.
     """
+    if TYPE_CHECKING:
+        _case_insensitive_ = hints.AnnoField()  # type: bool
+        _iid_ = hints.AnnoField()  # type: GUID
+        _methods_ = hints.AnnoField()  # type: List[_ComMemberSpec]
+        _disp_methods_ = hints.AnnoField()  # type: List[_DispMemberSpec]
 
     # This flag is set to True by the atexit handler which calls
     # CoUninitialize.
@@ -443,135 +514,28 @@ class _cominterface_meta(type):
             self.__map_case__ = d
 
     def _make_dispmethods(self, methods):
+        # type: (List[_DispMemberSpec]) -> None
         if self._case_insensitive_:
             self._make_case_insensitive()
-
         # create dispinterface methods and properties on the interface 'self'
-        properties = {}
+        member_gen = DispMemberGenerator(self.__name__)
         for m in methods:
-            what, name, idlflags, restype, argspec = m
-
-            # is it a property set or property get?
-            is_prop = False
-
-            # argspec is a sequence of tuples, each tuple is:
-            # ([paramflags], type, name)
-            try:
-                memid = [x for x in idlflags if isinstance(x, int)][0]
-            except IndexError:
-                raise TypeError("no dispid found in idlflags")
-            if what == "DISPPROPERTY": # DISPPROPERTY
-                assert not argspec # XXX does not yet work for properties with parameters
-                accessor = self._disp_property(memid, idlflags)
-                is_prop = True
-                setattr(self, name, accessor)
-            elif what == "DISPMETHOD": # DISPMETHOD
-                # argspec is a tuple of (idlflags, type, name[,
-                # defval]) items.
-                method = self._disp_method(memid, name, idlflags, restype, argspec)
-## not in 2.3                method.__name__ = name
-                if 'propget' in idlflags:
-                    nargs = len(argspec)
-                    properties.setdefault((name, nargs), [None, None, None])[0] = method
-                    is_prop = True
-                elif 'propput' in idlflags:
-                    nargs = len(argspec)-1
-                    properties.setdefault((name, nargs), [None, None, None])[1] = method
-                    is_prop = True
-                elif 'propputref' in idlflags:
-                    nargs = len(argspec)-1
-                    properties.setdefault((name, nargs), [None, None, None])[2] = method
-                    is_prop = True
-                else:
-                    setattr(self, name, method)
+            member_gen.add(m)
+        for name, func_or_prop, is_prop in member_gen.items():
+            setattr(self, name, func_or_prop)
             # COM is case insensitive.
-            #
             # For a method, this is the real name.  For a property,
             # this is the name WITHOUT the _set_ or _get_ prefix.
             if self._case_insensitive_:
                 self.__map_case__[name.lower()] = name
                 if is_prop:
                     self.__map_case__[name[5:].lower()] = name[5:]
-
-        for (name, nargs), methods in properties.items():
-            # methods contains [propget or None, propput or None, propputref or None]
-            if methods[1] is not None and methods[2] is not None:
-                # both propput and propputref.
-                #
-                # Create a setter method that examines the argument type
-                # and calls 'propputref' if it is an Object (in the VB
-                # sense), or call 'propput' otherwise.
-                propput = methods[1]
-                propputref = methods[2]
-                def put_or_putref(self, *args):
-                    if _is_object(args[-1]):
-                        return propputref(self, *args)
-                    else:
-                        return propput(self, *args)
-                methods[1] = put_or_putref
-                del methods[2]
-            elif methods[2] is not None:
-                # use propputref
-                del methods[1]
-            else:
-                # use propput (if any)
-                del methods[2]
-            if nargs:
-                setattr(self, name, named_property("%s.%s" % (self.__name__, name), *methods))
-            else:
-                assert len(methods) <= 2
-                setattr(self, name, property(*methods))
-
+        for name, accessor in member_gen.properties():
+            setattr(self, name, accessor)
             # COM is case insensitive
             if self._case_insensitive_:
                 self.__map_case__[name.lower()] = name
 
-    # Some ideas, (not only) related to disp_methods:
-    #
-    # Should the functions/methods we create have restype and/or
-    # argtypes attributes?
-
-    def _disp_method(self, memid, name, idlflags, restype, argspec):
-        if 'propget' in idlflags:
-            def getfunc(obj, *args, **kw):
-                return self.Invoke(obj, memid, _invkind=2, *args, **kw) # DISPATCH_PROPERTYGET
-            return getfunc
-        elif 'propput' in idlflags:
-            def putfunc(obj, *args, **kw):
-                return self.Invoke(obj, memid, _invkind=4, *args, **kw) # DISPATCH_PROPERTYPUT
-            return putfunc
-        elif 'propputref' in idlflags:
-            def putfunc(obj, *args, **kw):
-                return self.Invoke(obj, memid, _invkind=8, *args, **kw) # DISPATCH_PROPERTYPUTREF
-            return putfunc
-        # a first attempt to make use of the restype.  Still, support
-        # for named arguments and default argument values should be
-        # added.
-        if hasattr(restype, "__com_interface__"):
-            interface = restype.__com_interface__
-            def func(s, *args, **kw):
-                result = self.Invoke(s, memid, _invkind=1, *args, **kw)
-                if result is None:
-                    return
-                return result.QueryInterface(interface)
-        else:
-            def func(obj, *args, **kw):
-                return self.Invoke(obj, memid, _invkind=1, *args, **kw) # DISPATCH_METHOD
-        return func
-
-    def _disp_property(self, memid, idlflags):
-        # XXX doc string missing in property
-        def _get(obj):
-            return obj.Invoke(memid, _invkind=2) # DISPATCH_PROPERTYGET
-        if "readonly" in idlflags:
-            return property(_get)
-        def _set(obj, value):
-            # Detect whether to use DISPATCH_PROPERTYPUT or
-            # DISPATCH_PROPERTYPUTREF
-            invkind = 8 if _is_object(value) else 4
-            return obj.Invoke(memid, value, _invkind=invkind)
-        return property(_get, _set)
-
     def __get_baseinterface_methodcount(self):
         "Return the number of com methods in the base interfaces"
         try:
@@ -585,353 +549,47 @@ class _cominterface_meta(type):
                 raise TypeError("baseinterface '%s' has no _methods_" % itf.__name__)
             raise
 
-    def _fix_inout_args(self, func, argtypes, paramflags):
-        # This function provides a workaround for a bug in ctypes.
-        # [in, out] parameters must be converted with the argtype's
-        # .from_param() method BEFORE they are passed to the _ctypes
-        # build_callargs() function in Modules/_ctypes/_ctypes.c.
-        #
-        # For details see below.
-        #
-        # TODO: The workaround should be disabled when a ctypes
-        # version is used where the bug is fixed.
-        SIMPLETYPE = type(c_int)
-        BYREFTYPE = type(byref(c_int()))
-        def call_with_inout(self_, *args, **kw):
-            args = list(args)
-            # Indexed by order in the output
-            outargs = {}
-            outnum = 0
-            for i, info in enumerate(paramflags):
-                direction = info[0]
-                if direction & 3 == 3:
-                    # This is an [in, out] parameter.
-                    #
-                    # Determine name and required type of the parameter.
-                    name = info[1]
-                    # [in, out] parameters are passed as pointers,
-                    # this is the pointed-to type:
-                    atyp = argtypes[i]._type_
-
-                    # Get the actual parameter, either as positional or
-                    # keyword arg.
-                    try:
-                        try:
-                            v = args[i]
-                        except IndexError:
-                            v = kw[name]
-                    except KeyError:
-                        # no parameter was passed, make an empty one
-                        # of the required type
-                        v = atyp()
-                    else:
-                        # parameter was passed, call .from_param() to
-                        # convert it to a ctypes type.
-                        if getattr(v, "_type_", None) is atyp:
-                            # Array of or pointer to type 'atyp' was
-                            # passed, pointer to 'atyp' expected.
-                            pass
-                        elif type(atyp) is SIMPLETYPE:
-                            # The from_param method of simple types
-                            # (c_int, c_double, ...) returns a byref()
-                            # object which we cannot use since later
-                            # it will be wrapped in a pointer.  Simply
-                            # call the constructor with the argument
-                            # in that case.
-                            v = atyp(v)
-                        else:
-                            v = atyp.from_param(v)
-                            assert not isinstance(v, BYREFTYPE)
-                    outargs[outnum] = v
-                    outnum += 1
-                    if len(args) > i:
-                        args[i] = v
-                    else:
-                        kw[name] = v
-                elif direction & 2 == 2:
-                    outnum += 1
-
-            rescode = func(self_, *args, **kw)
-            # If there is only a single output value, then do not expect it to
-            # be iterable.
-            if outnum == 1:  # rescode is not iterable
-                if len(outargs) == 1:
-                    rescode = rescode.__ctypes_from_outparam__()
-                return rescode
-
-            rescode = list(rescode)
-            for outnum, o in outargs.items():
-                rescode[outnum] = o.__ctypes_from_outparam__()
-            return rescode
-        return call_with_inout
-
     def _make_methods(self, methods):
+        # type: (List[_ComMemberSpec]) -> None
         if self._case_insensitive_:
             self._make_case_insensitive()
-
-        # we insist on an _iid_ in THIS class!
+        # register com interface. we insist on an _iid_ in THIS class!
         try:
             iid = self.__dict__["_iid_"]
         except KeyError:
             raise AttributeError("this class must define an _iid_")
         else:
-            iid = text_type(iid)
-##            if iid in com_interface_registry:
-##                # Warn when multiple interfaces are defined with identical iids.
-##                # This would also trigger if we reload() a module that contains
-##                # interface types, so suppress the warning in this case.
-##                other = com_interface_registry[iid]
-##                if self.__name__ != other.__name__ or self.__module__ != other.__module__:
-##                    text = "Multiple interface defn: %s, %s" % (self, other)
-##                    warnings.warn(text, UserWarning)
-            com_interface_registry[iid] = self
-            del iid
+            com_interface_registry[text_type(iid)] = self
+        # create members
         vtbl_offset = self.__get_baseinterface_methodcount()
-
-        properties = {}
-
+        member_gen = ComMemberGenerator(self.__name__, vtbl_offset, self._iid_)
         # create private low level, and public high level methods
-        for i, item in enumerate(methods):
-            restype, name, argtypes, paramflags, idlflags, doc = item
-            # the function prototype
-            prototype = WINFUNCTYPE(restype, *argtypes)
-
-            # a low level unbound method calling the com method.
-            # attach it with a private name (__com_AddRef, for example),
-            # so that custom method implementations can call it.
-
-            # If the method returns a HRESULT, we pass the interface iid,
-            # so that we can request error info for the interface.
-            if restype == HRESULT:
-##                print "%s.%s" % (self.__name__, name)
-                raw_func = prototype(i + vtbl_offset, name, None, self._iid_)
-                func = prototype(i + vtbl_offset, name, paramflags, self._iid_)
-            else:
-                raw_func = prototype(i + vtbl_offset, name, None, None)
-                func = prototype(i + vtbl_offset, name, paramflags, None)
-            setattr(self,
-                    "_%s__com_%s" % (self.__name__, name),
-                    instancemethod(raw_func, None, self))
-
-            if paramflags:
-                # see comment in the _fix_inout_args method
-                dirflags = [(p[0]&3) for p in paramflags]
-                if 3 in dirflags:
-##                    fullname = "%s::%s" % (self.__name__, name)
-##                    print "FIX %s" % fullname
-                    func = self._fix_inout_args(func, argtypes, paramflags)
-
-            # 'func' is a high level function calling the COM method
-            func.__doc__ = doc
-            try:
-                func.__name__ = name # for pyhelp
-            except TypeError:
-                # In Python 2.3, __name__ is a readonly attribute
-                pass
-            # make it an unbound method.  Remember, 'self' is a type here.
+        for m in methods:
+            member_gen.add(m)
+        for name, func, raw_func, is_prop in member_gen.methods():
+            raw_mth = instancemethod(raw_func, None, self)
+            setattr(self, "_%s__com_%s" % (self.__name__, name), raw_mth)
             mth = instancemethod(func, None, self)
-
-            # is it a property set or property get?
-            is_prop = False
-
-            # XXX Hm.  What, when paramflags is None?
-            # Or does have '0' values?
-            # Seems we loose then, at least for properties...
-
-            # The following code assumes that the docstrings for
-            # propget and propput are identical.
-            if "propget" in idlflags:
-                assert name.startswith("_get_")
-                nargs = len([flags for flags in paramflags
-                             if flags[0] & 7 in (0, 1)])
-                # XXX or should we do this?
-                # nargs = len([flags for flags in paramflags
-                #             if (flags[0] & 1) or (flags[0] == 0)])
-                propname = name[len("_get_"):]
-                properties.setdefault((propname, doc, nargs), [None, None, None])[0] = func
-                is_prop = True
-            elif "propput" in idlflags:
-                assert name.startswith("_set_")
-                nargs = len([flags for flags in paramflags
-                              if flags[0] & 7 in (0, 1)]) - 1
-                propname = name[len("_set_"):]
-                properties.setdefault((propname, doc, nargs), [None, None, None])[1] = func
-                is_prop = True
-            elif "propputref" in idlflags:
-                assert name.startswith("_setref_")
-                nargs = len([flags for flags in paramflags
-                              if flags[0] & 7 in (0, 1)]) - 1
-                propname = name[len("_setref_"):]
-                properties.setdefault((propname, doc, nargs), [None, None, None])[2] = func
-                is_prop = True
-
-            # We install the method in the class, except when it's a
-            # property accessor.  And we make sure we don't overwrite
-            # a property that's already present in the class.
             if not is_prop:
-                if hasattr(self, name):
-                    setattr(self, "_" + name, mth)
-                else:
-                    setattr(self, name, mth)
-
-            # COM is case insensitive.
-            #
-            # For a method, this is the real name.  For a property,
-            # this is the name WITHOUT the _set_ or _get_ prefix.
+                # We install the method in the class, except when it's a property.
+                # And we make sure we don't overwrite a property that's already present.
+                mthname = name if not hasattr(self, name) else ("_%s" % name)
+                setattr(self, mthname, mth)
+            # For a method, this is the real name.
+            # For a property, this is the name WITHOUT the _set_ or _get_ prefix.
             if self._case_insensitive_:
                 self.__map_case__[name.lower()] = name
                 if is_prop:
                     self.__map_case__[name[5:].lower()] = name[5:]
-
         # create public properties / attribute accessors
-        for (name, doc, nargs), methods in properties.items():
-            # methods contains [propget or None, propput or None, propputref or None]
-            if methods[1] is not None and methods[2] is not None:
-                # both propput and propputref.
-                #
-                # Create a setter method that examines the argument type
-                # and calls 'propputref' if it is an Object (in the VB
-                # sense), or call 'propput' otherwise.
-                propput = methods[1]
-                propputref = methods[2]
-                def put_or_putref(self, *args):
-                    if _is_object(args[-1]):
-                        return propputref(self, *args)
-                    else:
-                        return propput(self, *args)
-                methods[1] = put_or_putref
-                del methods[2]
-            elif methods[2] is not None:
-                # use propputref
-                del methods[1]
-            else:
-                # use propput (if any)
-                del methods[2]
-            if nargs == 0:
-                prop = property(*methods + [None, doc])
-            else:
-                # Hm, must be a descriptor where the __get__ method
-                # returns a bound object having __getitem__ and
-                # __setitem__ methods.
-                prop = named_property("%s.%s" % (self.__name__, name), *methods + [doc])
-            # Again, we should not overwrite class attributes that are
-            # already present.
-            if hasattr(self, name):
-                setattr(self, "_" + name, prop)
-            else:
-                setattr(self, name, prop)
-
+        for name, accessor in member_gen.properties():
+            # Again, we should not overwrite class attributes that are already present.
+            propname = name if not hasattr(self, name) else ("_%s" % name)
+            setattr(self, propname, accessor)
             # COM is case insensitive
             if self._case_insensitive_:
                 self.__map_case__[name.lower()] = name
 
-
-################################################################
-# helper classes for COM propget / propput
-# Should they be implemented in C for speed?
-
-_all_slice = slice(None, None, None)
-
-
-class bound_named_property(object):
-    def __init__(self, name, fget, fset, instance):
-        self.name = name
-        self.instance = instance
-        self.fget = fget
-        self.fset = fset
-
-    def __getitem__(self, index):
-        if self.fget is None:
-            raise TypeError("unsubscriptable object")
-        if isinstance(index, tuple):
-            return self.fget(self.instance, *index)
-        elif index == _all_slice:
-            return self.fget(self.instance)
-        else:
-            return self.fget(self.instance, index)
-
-    def __call__(self, *args):
-        if self.fget is None:
-            raise TypeError("object is not callable")
-        return self.fget(self.instance, *args)
-
-    def __setitem__(self, index, value):
-        if self.fset is None:
-            raise TypeError("object does not support item assignment")
-        if isinstance(index, tuple):
-            self.fset(self.instance, *(index + (value,)))
-        elif index == _all_slice:
-            self.fset(self.instance, value)
-        else:
-            self.fset(self.instance, index, value)
-
-    def __repr__(self):
-        return "<bound_named_property %r at %x>" % (self.name, id(self))
-
-    def __iter__(self):
-        """ Explicitly disallow iteration. """
-        msg = "%r is not iterable" % self.name
-        raise TypeError(msg)
-
-
-class named_property(object):
-    def __init__(self, name, fget=None, fset=None, doc=None):
-        self.name = name
-        self.fget = fget
-        self.fset = fset
-        self.__doc__ = doc
-
-    def __get__(self, instance, owner=None):
-        if instance is None:
-            return self
-        return bound_named_property(self.name, self.fget, self.fset, instance)
-
-    # Make this a data descriptor
-    def __set__(self, instance):
-        raise AttributeError("Unsettable attribute")
-
-    def __repr__(self):
-        return "<named_property %r at %x>" % (self.name, id(self))
-
-################################################################
-
-def add_metaclass(metaclass):
-    """Class decorator from six.py for creating a class with a metaclass.
-
-    Copyright (c) 2010-2020 Benjamin Peterson
-
-    Permission is hereby granted, free of charge, to any person obtaining a copy of
-    this software and associated documentation files (the "Software"), to deal in
-    the Software without restriction, including without limitation the rights to
-    use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
-    the Software, and to permit persons to whom the Software is furnished to do so,
-    subject to the following conditions:
-
-    The above copyright notice and this permission notice shall be included in all
-    copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-    FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-    COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-    IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-    CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-    """
-    def wrapper(cls):
-        orig_vars = cls.__dict__.copy()
-        slots = orig_vars.get('__slots__')
-        if slots is not None:
-            if isinstance(slots, text_type):
-                slots = [slots]
-            for slots_var in slots:
-                orig_vars.pop(slots_var)
-        orig_vars.pop('__dict__', None)
-        orig_vars.pop('__weakref__', None)
-        if hasattr(cls, '__qualname__'):
-            orig_vars['__qualname__'] = cls.__qualname__
-        return metaclass(cls.__name__, cls.__bases__, orig_vars)
-    return wrapper
-
 ################################################################
 
 class _compointer_meta(type(c_void_p), _cominterface_meta):
@@ -1027,8 +685,6 @@ class _compointer_base(c_void_p):
 
 ################################################################
 
-from ctypes import _SimpleCData
-
 class BSTR(_SimpleCData):
     "The windows BSTR data type"
     _type_ = "X"
@@ -1072,102 +728,74 @@ class dispid(int):
     "Specifies the DISPID of a method or property."
 
 # XXX STDMETHOD, COMMETHOD, DISPMETHOD, and DISPPROPERTY should return
-# instances with methods, or at least accessors instead of tuple.
+# instances with more methods or properties, and should not behave as an unpackable.
 
 def STDMETHOD(restype, name, argtypes=()):
     "Specifies a COM method slot without idlflags"
-    # restype, name, argtypes, paramflags, idlflags, docstring
-    return restype, name, argtypes, None, (), None
+    return _ComMemberSpec(restype, name, argtypes, None, (), None)
 
 def DISPMETHOD(idlflags, restype, name, *argspec):
     "Specifies a method of a dispinterface"
-    return "DISPMETHOD", name, idlflags, restype, argspec
+    return _DispMemberSpec("DISPMETHOD", name, tuple(idlflags), restype, argspec)
 
 def DISPPROPERTY(idlflags, proptype, name):
     "Specifies a property of a dispinterface"
-    return "DISPPROPERTY", name, idlflags, proptype, ()#, argspec
+    return _DispMemberSpec("DISPPROPERTY", name, tuple(idlflags), proptype, ())
 
-# COMMETHOD returns:
-# restype, methodname, tuple(argtypes), tuple(paramflags), tuple(idlflags), helptext
-#
-# paramflags is a sequence of (flags (integer), paramname (string)
 # tuple(idlflags) is for the method itself: (dispid, 'readonly')
-#
-# Example: (HRESULT, 'Width', (c_long,), (2, 'rhs'), (4, 'readonly'), None)
-
-## sample generated code:
-##    DISPPROPERTY([5, 'readonly'], OLE_YSIZE_HIMETRIC, 'Height'),
-##    DISPMETHOD([6], None, 'Render',
-##               ( [], c_int, 'hdc' ),
-##               ( [], c_int, 'x' ),
-##               ( [], c_int, 'y' ))
-
-################################################################
 
-_PARAMFLAGS = {
-    "in": 1,
-    "out": 2,
-    "lcid": 4,
-    "retval": 8,
-    "optional": 16,
-    }
-
-def _encode_idl(names):
-    # sum up all values found in _PARAMFLAGS, ignoring all others.
-    return sum([_PARAMFLAGS.get(n, 0) for n in names])
-
-_NOTHING = object()
-def _unpack_argspec(idl, typ, name=None, defval=_NOTHING):
-    return idl, typ, name, defval
+# 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):
     """Specifies a COM method slot with idlflags.
 
     XXX should explain the sematics of the arguments.
     """
-    paramflags = []
-    argtypes = []
-
     # collect all helpstring instances
     # We should suppress docstrings when Python is started with -OO
-    helptext = [t for t in idlflags if isinstance(t, helpstring)]
     # join them together(does this make sense?) and replace by None if empty.
-    helptext = "".join(helptext) or None
-
-    from comtypes.automation import VARIANT
-
-    for item in argspec:
-        idl, typ, argname, defval = _unpack_argspec(*item)
-        pflags = _encode_idl(idl)
-        if "optional" in idl:
-            if defval is _NOTHING:
-                if typ is VARIANT:
-                    defval = VARIANT.missing
-                elif typ is POINTER(VARIANT):
-                    defval = pointer(VARIANT.missing)
-                else:
-##                    msg = ("'optional' only allowed for VARIANT and VARIANT*, not for %s"
-##                           % typ.__name__)
-##                    warnings.warn(msg, IDLWarning, stacklevel=2)
-                    defval = typ()
-        if defval is _NOTHING:
-            paramflags.append((pflags, argname))
-        else:
-            paramflags.append((pflags, argname, defval))
-        argtypes.append(typ)
+    helptext = "".join(t for t in idlflags if isinstance(t, helpstring)) or None
+    paramflags, argtypes = _resolve_argspec(argspec)
     if "propget" in idlflags:
-        methodname = "_get_%s" % methodname
+        name = "_get_%s" % methodname
     elif "propput" in idlflags:
-        methodname = "_set_%s" % methodname
+        name = "_set_%s" % methodname
     elif "propputref" in idlflags:
-        methodname = "_setref_%s" % methodname
-    return restype, methodname, tuple(argtypes), tuple(paramflags), tuple(idlflags), helptext
+        name = "_setref_%s" % methodname
+    else:
+        name = methodname
+    return _ComMemberSpec(
+        restype, name, argtypes, paramflags, tuple(idlflags), helptext
+    )
+
 
 ################################################################
 # IUnknown, the root of all evil...
 
+if TYPE_CHECKING:
+    _T_IUnknown = TypeVar("_T_IUnknown", bound="IUnknown")
+
+    class _IUnknown_Base(c_void_p):
+        """This is workaround to avoid false-positive of static type checking.
+
+        `IUnknown` behaves as a ctypes type, and `POINTER` can take it.
+        This behavior is defined by some metaclasses in runtime.
+
+        In runtime, this symbol in the namespace is just alias for
+        `builtins.object`.
+        """
+        __com_QueryInterface = hints.AnnoField()  # type: Callable[[Any, Any], int]
+        __com_AddRef = hints.AnnoField()  # type: Callable[[], int]
+        __com_Release = hints.AnnoField()  # type: Callable[[], int]
+else:
+    _IUnknown_Base = object
+
 @add_metaclass(_cominterface_meta)
-class IUnknown(object):
+class IUnknown(_IUnknown_Base):
     """The most basic COM interface.
 
     Each subclasses of IUnknown must define these class attributes:
@@ -1179,18 +807,24 @@ class IUnknown(object):
     The _methods_ list must in VTable order.  Methods are specified
     with STDMETHOD or COMMETHOD calls.
     """
-    _case_insensitive_ = False
-    _iid_ = GUID("{00000000-0000-0000-C000-000000000046}")
+    _case_insensitive_ = False  # type: ClassVar[bool]
+    _iid_ = GUID("{00000000-0000-0000-C000-000000000046}")  # type: ClassVar[GUID]
 
     _methods_ = [
         STDMETHOD(HRESULT, "QueryInterface",
                   [POINTER(GUID), POINTER(c_void_p)]),
         STDMETHOD(c_ulong, "AddRef"),
         STDMETHOD(c_ulong, "Release")
-    ]
+    ]  # type: ClassVar[List[_ComMemberSpec]]
 
+    # NOTE: Why not `QueryInterface(T) -> _Pointer[T]`?
+    # Any static type checkers is not able to provide members of `T` from `_Pointer[T]`,
+    # regardless of the pointer is able to access members of contents in runtime.
+    # And if `isinstance(p, POINTER(T))` is `True`, then `isinstance(p, T)` is also `True`.
+    # So returning `T` is not a lie, and good way to know what members the class has.
     def QueryInterface(self, interface, iid=None):
-        "QueryInterface(interface) -> instance"
+        # type: (Type[_T_IUnknown], Optional[GUID]) -> _T_IUnknown
+        """QueryInterface(interface) -> instance"""
         p = POINTER(interface)()
         if iid is None:
             iid = interface._iid_
@@ -1198,18 +832,22 @@ class IUnknown(object):
         clsid = self.__dict__.get('__clsid')
         if clsid is not None:
             p.__dict__['__clsid'] = clsid
-        return p
+        return p  # type: ignore
 
     # these are only so that they get a docstring.
     # XXX There should be other ways to install a docstring.
     def AddRef(self):
-        "Increase the internal refcount by one and return it."
+        # type: () -> int
+        """Increase the internal refcount by one and return it."""
         return self.__com_AddRef()
 
     def Release(self):
-        "Decrease the internal refcount by one and return it."
+        # type: () -> int
+        """Decrease the internal refcount by one and return it."""
         return self.__com_Release()
 
+
+################################################################
 # IPersist is a trivial interface, which allows to ask an object about
 # its clsid.
 class IPersist(IUnknown):
@@ -1219,16 +857,23 @@ class IPersist(IUnknown):
         COMMETHOD([], HRESULT, 'GetClassID',
                   ( ['out'], POINTER(GUID), 'pClassID' )),
         ]
+    if TYPE_CHECKING:
+        # Returns the CLSID that uniquely represents an object class that
+        # defines the code that can manipulate the object's data.
+        GetClassID = hints.AnnoField()  # type: Callable[[], GUID]
+
 
 class IServiceProvider(IUnknown):
     _iid_ = GUID('{6D5140C1-7436-11CE-8034-00AA006009FA}')
-
+    if TYPE_CHECKING:
+        _QueryService = hints.AnnoField()  # type: Callable[[Any, Any, Any], int]
     # Overridden QueryService to make it nicer to use (passing it an
     # interface and it returns a pointer to that interface)
     def QueryService(self, serviceIID, interface):
+        # type: (GUID, Type[_T_IUnknown]) -> _T_IUnknown
         p = POINTER(interface)()
         self._QueryService(byref(serviceIID), byref(interface._iid_), byref(p))
-        return p
+        return p  # type: ignore
 
     _methods_ = [
         COMMETHOD([], HRESULT, 'QueryService',
@@ -1238,7 +883,19 @@ class IServiceProvider(IUnknown):
         ]
 
 ################################################################
+
+if TYPE_CHECKING:
+    @overload
+    def CoGetObject(displayname, interface):  # `interface` can't be missing
+        # type: (str, None) -> IUnknown
+        pass
+    @overload
+    def CoGetObject(displayname, interface):  # it should be called this way
+        # type: (str, Type[_T_IUnknown]) -> _T_IUnknown
+        pass
+
 def CoGetObject(displayname, interface):
+    # type: (str, Optional[Type[IUnknown]]) -> IUnknown
     """Convert a displayname to a moniker, then bind and return the object
     identified by the moniker."""
     if interface is None:
@@ -1249,9 +906,23 @@ def CoGetObject(displayname, interface):
                        None,
                        byref(interface._iid_),
                        byref(punk))
-    return punk
+    return punk  # type: ignore
+
+
+if TYPE_CHECKING:
+    pUnkOuter = Type[_Pointer[IUnknown]]
+
+    @overload
+    def CoCreateInstance(clsid, interface=None, clsctx=None, punkouter=None):
+        # type: (GUID, None, Optional[int], Optional[pUnkOuter]) -> IUnknown
+        pass
+    @overload
+    def CoCreateInstance(clsid, interface, clsctx=None, punkouter=None):
+        # type: (GUID, Type[_T_IUnknown], Optional[int], Optional[pUnkOuter]) -> _T_IUnknown
+        pass
 
 def CoCreateInstance(clsid, interface=None, clsctx=None, punkouter=None):
+    # type: (GUID, Optional[Type[IUnknown]], Optional[int], Optional[pUnkOuter]) -> IUnknown
     """The basic windows api to create a COM class object and return a
     pointer to an interface.
     """
@@ -1262,9 +933,21 @@ def CoCreateInstance(clsid, interface=None, clsctx=None, punkouter=None):
     p = POINTER(interface)()
     iid = interface._iid_
     _ole32.CoCreateInstance(byref(clsid), punkouter, clsctx, byref(iid), byref(p))
-    return p
+    return p  # type: ignore
+
+
+if TYPE_CHECKING:
+    @overload
+    def CoGetClassObject(clsid, clsctx=None, pServerInfo=None, interface=None):
+        # type: (GUID, Optional[int], Optional[COSERVERINFO], None) -> hints.IClassFactory
+        pass
+    @overload
+    def CoGetClassObject(clsid, clsctx=None, pServerInfo=None, interface=None):
+        # type: (GUID, Optional[int], Optional[COSERVERINFO], Type[_T_IUnknown]) -> _T_IUnknown
+        pass
 
 def CoGetClassObject(clsid, clsctx=None, pServerInfo=None, interface=None):
+    # type: (GUID, Optional[int], Optional[COSERVERINFO], Optional[Type[IUnknown]]) -> IUnknown
     if clsctx is None:
         clsctx = CLSCTX_SERVER
     if interface is None:
@@ -1276,20 +959,37 @@ def CoGetClassObject(clsid, clsctx=None, pServerInfo=None, interface=None):
                       pServerInfo,
                       interface._iid_,
                       byref(p))
-    return p
+    return p  # type: ignore
+
+
+if TYPE_CHECKING:
+    @overload
+    def GetActiveObject(clsid, interface=None):
+        # type: (GUID, None) -> IUnknown
+        pass
+    @overload
+    def GetActiveObject(clsid, interface):
+        # type: (GUID, Type[_T_IUnknown]) -> _T_IUnknown
+        pass
 
 def GetActiveObject(clsid, interface=None):
+    # type: (GUID, Optional[Type[IUnknown]]) -> IUnknown
     """Retrieves a pointer to a running object"""
     p = POINTER(IUnknown)()
     oledll.oleaut32.GetActiveObject(byref(clsid), None, byref(p))
     if interface is not None:
-        p = p.QueryInterface(interface)
-    return p
+        p = p.QueryInterface(interface)  # type: ignore
+    return p  # type: ignore
+
 
 class MULTI_QI(Structure):
     _fields_ = [("pIID", POINTER(GUID)),
                 ("pItf", POINTER(c_void_p)),
                 ("hr", HRESULT)]
+    if TYPE_CHECKING:
+        pIID = hints.AnnoField()  # type: GUID
+        pItf = hints.AnnoField()  # type: _Pointer[c_void_p]
+        hr = hints.AnnoField()  # type: HRESULT
 
 class _COAUTHIDENTITY(Structure):
     _fields_ = [
@@ -1322,6 +1022,11 @@ class _COSERVERINFO(Structure):
         ('pAuthInfo', POINTER(_COAUTHINFO)),
         ('dwReserved2', c_ulong),
     ]
+    if TYPE_CHECKING:
+        dwReserved1 = hints.AnnoField()  # type: int
+        pwszName = hints.AnnoField()  # type: Optional[str]
+        pAuthInfo = hints.AnnoField()  # type: _COAUTHINFO
+        dwReserved2 = hints.AnnoField()  # type: int
 COSERVERINFO = _COSERVERINFO
 _CoGetClassObject = _ole32.CoGetClassObject
 _CoGetClassObject.argtypes = [POINTER(GUID), DWORD, POINTER(COSERVERINFO),
@@ -1380,10 +1085,24 @@ class _SOLE_AUTHENTICATION_LIST(Structure):
     ]
 SOLE_AUTHENTICATION_LIST = _SOLE_AUTHENTICATION_LIST
 
+
+if TYPE_CHECKING:
+    @overload
+    def CoCreateInstanceEx(
+        clsid, interface=None, clsctx=None, machine=None, pServerInfo=None):
+        # type: (GUID, None, Optional[int], Optional[str], Optional[COSERVERINFO]) -> IUnknown
+        pass
+    @overload
+    def CoCreateInstanceEx(
+        clsid, interface=None, clsctx=None, machine=None, pServerInfo=None):
+        # type: (GUID, Type[_T_IUnknown], Optional[int], Optional[str], Optional[COSERVERINFO]) -> _T_IUnknown
+        pass
+
 def CoCreateInstanceEx(clsid, interface=None,
                        clsctx=None,
                        machine=None,
                        pServerInfo=None):
+    # type: (GUID, Optional[Type[IUnknown]], Optional[int], Optional[str], Optional[COSERVERINFO]) -> IUnknown
     """The basic windows api to create a COM class object and return a
     pointer to an interface, possibly on another machine.
 
@@ -1400,19 +1119,19 @@ def CoCreateInstanceEx(clsid, interface=None,
     elif machine is not None:
         serverinfo = COSERVERINFO()
         serverinfo.pwszName = machine
-        pServerInfo = byref(serverinfo)
+        pServerInfo = byref(serverinfo)  # type: ignore
 
     if interface is None:
         interface = IUnknown
     multiqi = MULTI_QI()
-    multiqi.pIID = pointer(interface._iid_)
+    multiqi.pIID = pointer(interface._iid_)  # type: ignore
     _ole32.CoCreateInstanceEx(byref(clsid),
                              None,
                              clsctx,
                              pServerInfo,
                              1,
                              byref(multiqi))
-    return cast(multiqi.pItf, POINTER(interface))
+    return cast(multiqi.pItf, POINTER(interface))  # type: ignore
 
 
 ################################################################
@@ -1428,3 +1147,31 @@ from comtypes._meta import _coclass_meta
 class CoClass(COMObject):
     pass
 ################################################################
+
+
+__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',
+]