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.