Should makepy generate subclasses for structs in the TypeLibrary?

[geppi]

When implementing pythoncom.com_record as a subclassable Python type in PR #2437, @mhammond wanted to assure that it doesn't introduce non deterministic behaviour. To address this issue, a subclass has to be explicitly registered with win32com.client.register_record_class before it can be used within the pywin32 machinery.

Although documentation was added that explains this mechanism, it doesn't seem to be very well recognised.
In addition, even when using makepy, it currently keeps the burden to manually define the subclasses and register them on the user.

I would like to discuss the idea to automatically generate the subclasses for structs defined in a TypeLibrary and register them by makepy. They would initially live in the namespace of the module generated by makepy.

I would argue that a user who runs makepy or uses EnsureDispatch can not only expect to work with static dispatch objects instead of generic COM objects but also to get TypeLibrary specific class instances instead of generic pythoncom.com_record objects.

Further points of discussion could be:

• Would we like to provide an option for makepy and alike to prevent or explicitly enable this automatic generation?
• Should we provide a mechanism to get the generated class objects into a more convenient namespace than the generated module, e.g. put them into the __all__ member of the module to enable a wild card import?

[mhammond]

That makes sense to me, but I'm not sure I have all the context - what do we currently generate and how does that change in your proposal? What was the motivation for allowing "user-written" subclasses in that other PR rather than doing this in the first place?

[geppi]

Well, all this was and still is a step by step learning process for me. Therefore the implementation wasn't done as straightforward as it probably could have been done by someone with a good general understanding of COM and the pywin32 code structure.

The situation at the moment is that nothing has changed as long as the user doesn't take action himself, i.e. all struct typedefs in a TypeLibrary are handled as incarnations of the base pythoncom.com_record class.

What the user has to do for making use of the pythoncom.com_record subclasses feature, is to provide a definition like the following for each subclass he wants to enable

class T_LINE(pythoncom.com_record):
	# This block is common for all structs from the same TypeLibrary.
	__slots__ = tuple()
	TLBID = '{E6F07342-C1F7-4E4E-B021-11BBD54B9F37}'
	MJVER = 1
	MNVER = 0
	LCID = 0
	# The GUID is specific for the particular struct typedef.
	GUID = '{B1461DD4-8C86-4627-B444-3D833C980111}'

and register this class with win32com.client.register_record_class(T_LINE).

With such a definition and registration, a COM record of this type can be created with a call to the constructor T_LINE() and also the factory functions win32com.client.Record() and pythoncom.GetRecordFromGuids() do return instances of this type. Records that are returned by a COM method which have the registered GUID, will also be instances of the T_LINE class.

What I'm proposing is to create definitions like the one above for all struct typedefs in the TypeLibrary and register them when running makepy or invoking functions that generate the TypeLib module.

There are a few things to consider:

1. Existing code that uses pywin32 could break if it checks for equality with pythoncom.com_record instead of using isinstance().
2. Once a pythoncom.com_record subclass is registered it can only be extended by a kind of "monkey patching".

The first point could be addressed by implementing an optional parameter in makepy and functions that generate the TypeLib module.

Regarding the second point:

While pythoncom.com_record is now subclassable, the subclasses themselves are not.
If a user e.g. wants to equip the T_LINE class with a length property, he has to do this in the class definition:

class T_LINE(pythoncom.com_record):
	# This block is common for all structs from the same TypeLibrary.
	__slots__ = tuple()
	TLBID = '{E6F07342-C1F7-4E4E-B021-11BBD54B9F37}'
	MJVER = 1
	MNVER = 0
	LCID = 0
	# The GUID is specific for the particular struct typedef.
	GUID = '{B1461DD4-8C86-4627-B444-3D833C980111}'

	@property
	def length(self):
		return ((self.endX - self.startX)**2 + (self.endY - self.startY)**2 + (self.endZ - self.startZ)**2)**(1/2)

If we already create the class definitions in makepy and register them, a user would have to add the length property to the existing class later.

This could be accomplished e.g. with a decorator:

@add_record_property(T_LINE)
def length(self):
	return ((self.endX - self.startX)**2 + (self.endY - self.startY)**2 + (self.endZ - self.startZ)**2)**(1/2)

and a decorator definition like this:

def add_record_property(cls):
	return lambda method: (setattr(cls,method.__name__,property(method)) or method)