Implementation of 'com_record' as a subclassable Python type. (#2437)

* Implementation of 'com_record' as a subclassable Python type.

A 'tp_new' method was added to the 'PyTypeObject' slots of 'com_record'.
Replacement new is now used to create an instance of a 'com_record' type,
i.e. in 'tp_new' as well as in the factory functions. The 'tp_dealloc'
method explicitely calls the destructor before finally calling 'tp_free'.

Records returned from a call to a COM method do get the subclass type
according to the GUID in the COM RecordInfo. If no subclass with that
GUID is found, the generic 'com_record' base class is used.

The algorithm that retrieves the list of subclasses of 'com_record'
only uses methods and data structures of the public Python API.
This is important because in Python 3.12 the type of the 'tp_subclasses'
slot of a 'PyTypeObject' was changed to 'void*' to indicate that for some
types it does not hold a valid 'PyObject*'.

The 'PyRecord_Check' function was modified to test if the object is an
instance of 'com_record' or a derived type.

The implementation does not break existing code.
It is not required to define 'com_record' subclasses, i.e. it is possible
to work with the generic 'com_record' type as before using the factory
function.

* Removed an unnecessary type cast and unreferenced local variables.

* Added a global dictionary for 'pythoncom.com_record' subclass registration.

* The algorithm that identifies the subclass of 'pythoncom.com_record'
from which a COM Record instance will be created now looks up the Record GUID
in a global map, to only create instances of subclasses that have explicitely
been registered in this map.

* Added the function 'register_record_class' to add proper subclasses of
'pythoncom.com_record' to the global map 'pythoncom.RecordClasses'.
The function does only add instantiable subclasses of 'pythoncom.com_record'
to the map if their GUID is not already contained in the map.

* Added a check for the record type name in the 'register_record_class'
Python function.

Also added another dunder attribute '__record_type_name__' to the
'PyRecord::getattro' function that retrieves the record type name
via 'IRecordInfo::GetName'.

* Update com/win32com/client/__init__.py

Co-authored-by: Avasam <samuel.06@hotmail.com>

* Code cleanup.

* Reverted the part of commit cd1c2fc
that added a check for the record type name in the 'register_record_class'
Python function.

* Added the dunder attribute '__record_type_guid__' to the
'PyRecord::getattro' function that retrieves the record
type GUID via 'IRecordInfo::GetGuid'.

* Added a NULL check for 'PyRecord::new_record' before calling
'PyTuple_SET_ITEM' in the 'PyObject_FromSAFEARRAYRecordInfo' function.

Also enhanced the treatment of NULL return values in several other
places in 'PyRecord.cpp'.

* Added tests for the 'pythoncom.com_record' subclassing functionality.

* Added a NULL check for 'PyRecord::new_record' before calling
'PyTuple_SET_ITEM' in the 'PyRecord::getattro' function.

Also 'PyRecord::new_record' will now raise a 'PyErr_NoMemory'
exception when the call to 'tp_alloc' returns NULL.

* Added a method for the 'tp_init' slot of 'com_record' to enable
instance initialization.

Also changed the com_record base class to be only instantiable via
the Record factory function and subclasses of com_record only if
they are registered.

Modified the test in 'testPyComTest.py' to reflect this.

Added a test for the initialization of com_record subclasses.

* Added a changelog entry.

* Added changes from code review.

---------

Co-authored-by: Avasam <samuel.06@hotmail.com>

Author: geppi

CHANGES.txt

@@ -14,9 +14,11 @@ https://mhammond.github.io/pywin32_installers.html .
 Coming in build 309, as yet unreleased
 --------------------------------------
 
+* Changed the implementation of 'com_record' to a subclassable Python type (2437#, #2361, @geppi)
 * Removed param `hIcon` from `win32comext.shell.ShellExecuteEx`. It was unusable since Windows Vista (#2423, @Avasam)
 * Fixed `nbios.NCBStruct` packing (#2406, @Avasam)
 * Restored axdebug builds on Python 3.10 (#2416, @Avasam)
+* Fix for Python 3.12 interpreter crashes when accessing a COM Record field (#2415, @geppi)
 * Pythonwin: Bumped Scintilla from 1.77 to 4.4.6. The full changelog can be found here: https://www.scintilla.org/ScintillaHistory.html
 * Fixed Pythonwin's editor failing due to invalid regex import (#2419, @Avasam)
 * Last error wrongly set by some modules (#2302, @CristiFati)

com/win32com/client/__init__.py

@@ -487,6 +487,47 @@ def Record(name, object):
     )
 
 
+# Registration function for com_record subclasses.
+def register_record_class(cls):
+    """
+    Register a subclass of com_record to enable creation of the represented record objects.
+
+    A subclass of com_record requires the following class attributes to be instantiable:
+
+        TLBID : The GUID of the containing TypeLibrary as a string.
+        MJVER : The major version number of the TypeLibrary as an integer.
+        MNVER : The minor version number of the TypeLibrary as an integer.
+        LCID  : The LCID of the TypeLibrary as an integer.
+        GUID  : The GUID of the COM Record as a string.
+
+    with GUID strings in {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} notation.
+
+    To instantiate such a subclasses it has to be registered via this function.
+    """
+    if not issubclass(cls, pythoncom.com_record):
+        raise TypeError("Only subclasses of 'com_record' can be registered.")
+    try:
+        TLBID = cls.TLBID
+        MJVER = cls.MJVER
+        MNVER = cls.MNVER
+        LCID = cls.LCID
+        GUID = cls.GUID
+    except AttributeError as e:
+        raise AttributeError(f"Class {cls.__name__} cannot be instantiated.") from e
+    try:
+        _ = pythoncom.GetRecordFromGuids(TLBID, MJVER, MNVER, LCID, GUID)
+    except Exception as e:
+        raise TypeError(f"Class {cls.__name__} cannot be instantiated.") from e
+    # Since the class can be instantiated we know that it represents a valid COM Record
+    # in a properly registered TypeLibrary and that it has a 'GUID' class attribute.
+    if cls.GUID in pythoncom.RecordClasses:
+        raise ValueError(
+            f"Record class with same GUID {cls.GUID} "
+            f"is already registered with name '{pythoncom.RecordClasses[cls.GUID].__name__}'."
+        )
+    pythoncom.RecordClasses[cls.GUID] = cls
+
+
 ############################################
 # The base of all makepy generated classes
 ############################################