Documentation should mention that it is unnecessary to release returned objects

[bytesized]

Coming from C++ COM, where very simple COM usage looks like

IFoo* foo;
HRESULT hr = CoCreateInstance(rclsid, pUnkOuter, dwClsContext, riid, (void**) &foo);
if (SUCCEEDED(hr)) {
  // do something with foo...
  foo->Release()
}

it was highly confusing to try out this library for the first time and do something like this

>>> try:
...   foo = CreateObject(progid)
... except:
...   pass
... else:
...   # Do something with foo
...   foo.Release()
...
0
>>> foo = None
Exception ignored in: <function _compointer_base.__del__ at 0x0000020D7D3FC3A0>
Traceback (most recent call last):
  File "C:\Users\bytesized\sandbox\python\venv\lib\site-packages\comtypes\_post_coinit\unknwn.py", line 386, in __del__
    self.Release()
  File "C:\Users\bytesized\sandbox\python\venv\lib\site-packages\comtypes\_post_coinit\unknwn.py", line 534, in Release
    return self.__com_Release()  # type: ignore
OSError: exception: access violation writing 0x0000000000000000

I tried looking through the documentation for CreateObject and using the search bar to look for "Release" and a few similar search terms, but couldn't find anything related.

This feels weird since AddRef and Release are standard COM methods and are made available to the interface consumer. They just don't quite seem to work as expected. Normally, things are handed to you (by CoCreateInstance, for example) already AddRefed. So you have to Release them, plus an additional Release for every additional AddRef. But this implementation does not match this; it's strictly one Release per AddRef.

It seems like if this COM library is going to differ from the usual COM conventions, the documentation should at least mention it.

[junkmd]

Hi, @bytesized.

Indeed, those who are familiar with COM and are used to explicitly releasing COM interface pointers that are no longer in use might find this package's implementation weird.

The originator of this package likely aimed to make it easier for users to work with the COM framework by using atexit and __del__ to trigger cleanup operations, so that users would not need to manually release COM pointers that are no longer in use.

Through the functionality of metaclasses, when an instance of an IUnknown Python object is destroyed and __del__ is called, Release is automatically triggered. https://github.com/enthought/comtypes/blob/3e3977d868e21b2b1f17c55c53434349b846ffc8/comtypes/_post_coinit/unknwn.py#L371-L386

Additionally, it's worth mentioning that when the _shutdown callback function registered with atexit is invoked, comtypes not only calls the Release method on each COM interface pointer but also calls CoUninitialize. https://github.com/enthought/comtypes/blob/3e3977d868e21b2b1f17c55c53434349b846ffc8/comtypes/init.py#L180 https://github.com/enthought/comtypes/blob/3e3977d868e21b2b1f17c55c53434349b846ffc8/comtypes/_post_coinit/unknwn.py#L25-L47 https://github.com/enthought/comtypes/blob/3e3977d868e21b2b1f17c55c53434349b846ffc8/comtypes/_post_coinit/unknwn.py#L54-L66

It is true that there is no documentation indicating that users generally do not need to manually call Release, CoInitialize at startup, or CoUninitialize at shutdown. We welcome PRs to add explanations about these behaviors, so please feel free to contribute.

[junkmd]

In the past, changes were made in #215 to define _shutdown as a private function, allowing cleanup operations to be unregistered from atexit. By temporarily modifying IUnknown._com_shutting_down manually, it is also possible to prevent Release from being called when __del__ is invoked.

However, I should mention that if alternative cleanup operations are not performed or the modified class attributes are not restored, it will be necessary to manually and properly release the COM pointers present in the running Python interpreter.

[junkmd]

As a byproduct of investigating the issues with Python 3.13 and metaclasses in #618, I came across several projects that apply workarounds to _compointer_base for handling pointer release.

Some of these projects used super(_compointer_base, obj).value to retrieve the raw pointer, while others patched _compointer_base.__del__.

Since version 1.4.5, the definition of _compointer_base was moved to comtypes._post_coinit.unknwn, making these imports and references a bit tricky.

• https://github.com/nvaccess/nvda/pull/17061 (https://github.com/nvaccess/nvda/pull/17061/commits/7660567cc9c1f8f2b3a870ca37a7c6e4a36e8d9e)
• https://github.com/dshikashio/Pybag/issues/22 (https://github.com/dshikashio/Pybag/commit/3b2751e4f4d5041eb5ca38b0d4c63f1d2d34ec46)

In #215, the behavior at shutdown was made customizable for users by turning the function hooked to atexit into a private function, instead of removing it from the comtypes/__init__.py namespace.

Similarly, it might benefit users if _compointer_base were imported into comtypes/__init__.py, making it accessible via from comtypes import _compointer_base or comtypes._compointer_base.