Add enumeration definitions in the friendly modules

[junkmd]

#345

I have modified the codegenerator so that the Python friendly enumerations are defined in the friendly module as derived classes of enum.IntFlag.

Specifically, for example, the Scripting.py changes as follows before and after this change.

import comtypes.gen._420B2830_E718_11CF_893D_00A0C9054228_0_1_0 as __wrapper_module__
from comtypes.gen._420B2830_E718_11CF_893D_00A0C9054228_0_1_0 import (
    FileAttribute, DriveTypeConst, TristateMixed, IFileSystem,
    SystemFolder, IFileCollection, StandardStreamTypes,
    _check_version, GUID, IFolderCollection, Dictionary, Directory,
    Remote, Library, StdOut, IOMode,
    __MIDL___MIDL_itf_scrrun_0001_0001_0003, WindowsFolder, VARIANT,
    Alias, helpstring, TristateUseDefault, IScriptEncoder, Archive,
    TextStream, IDrive, IFile, HRESULT, Hidden, StdErr, Folders,
    dispid, typelib_path, IFileSystem3, ReadOnly, ForWriting, StdIn,
    FileSystemObject, ForAppending, Encoder, CDRom, IDriveCollection,
    COMMETHOD, Volume, CompareMethod, BinaryCompare, IDictionary,
    BSTR, Normal, TristateTrue, TristateFalse, Fixed, UnknownType,
    Files, File, _lcid, Tristate, SpecialFolderConst, ForReading,
    ITextStream, __MIDL___MIDL_itf_scrrun_0001_0001_0001, Removable,
    RamDisk, VARIANT_BOOL, Drives, Folder, TemporaryFolder, CoClass,
    __MIDL___MIDL_itf_scrrun_0000_0000_0001, System,
    __MIDL___MIDL_itf_scrrun_0001_0001_0002, Compressed, TextCompare,
    DatabaseCompare, IFolder, IUnknown, Drive
)


__all__ = [
    'Encoder', 'FileAttribute', 'CDRom', 'IDriveCollection',
    'DriveTypeConst', 'TristateMixed', 'Volume', 'SystemFolder',
    'IFileSystem', 'IFileCollection', 'CompareMethod',
    'StandardStreamTypes', 'BinaryCompare', 'IDictionary', 'Normal',
    'TristateTrue', 'TristateFalse', 'Fixed', 'IFolderCollection',
    'Dictionary', 'Directory', 'Remote', 'Library', 'StdOut',
    'IOMode', '__MIDL___MIDL_itf_scrrun_0001_0001_0003',
    'UnknownType', 'WindowsFolder', 'Files', 'File', 'Tristate',
    'Alias', 'ForReading', 'SpecialFolderConst', 'ITextStream',
    'TristateUseDefault', 'IScriptEncoder',
    '__MIDL___MIDL_itf_scrrun_0001_0001_0001', 'Archive', 'Removable',
    'RamDisk', 'IDrive', 'TextStream', 'IFile', 'Drives', 'Folder',
    'Hidden', 'StdErr', 'Folders', 'TemporaryFolder', 'typelib_path',
    '__MIDL___MIDL_itf_scrrun_0000_0000_0001', 'ReadOnly', 'System',
    'IFileSystem3', 'ForWriting', 'Compressed',
    '__MIDL___MIDL_itf_scrrun_0001_0001_0002', 'StdIn', 'TextCompare',
    'DatabaseCompare', 'FileSystemObject', 'IFolder', 'Drive',
    'ForAppending'
]

↓

from enum import IntFlag

import comtypes.gen._420B2830_E718_11CF_893D_00A0C9054228_0_1_0 as __wrapper_module__
from comtypes.gen._420B2830_E718_11CF_893D_00A0C9054228_0_1_0 import (
    Hidden, Volume, Alias, TextCompare, SystemFolder,
    FileSystemObject, Fixed, typelib_path, IDrive, IFile, IDictionary,
    CoClass, _lcid, ForWriting, RamDisk, StdIn, COMMETHOD, Removable,
    CDRom, Files, TristateUseDefault, Archive, TristateMixed,
    _check_version, WindowsFolder, Remote, DatabaseCompare,
    TextStream, IUnknown, helpstring, HRESULT, IFolderCollection,
    Encoder, ITextStream, Dictionary, Compressed, VARIANT, BSTR,
    IFileCollection, IDriveCollection, Folder, VARIANT_BOOL, Drives,
    Folders, System, StdOut, UnknownType, File, ForAppending, StdErr,
    ReadOnly, BinaryCompare, IFolder, IScriptEncoder, IFileSystem,
    Drive, Normal, Directory, ForReading, TristateTrue, IFileSystem3,
    Library, dispid, TemporaryFolder, TristateFalse, GUID
)


class __MIDL___MIDL_itf_scrrun_0001_0001_0003(IntFlag):
    StdIn = __wrapper_module__.StdIn
    StdOut = __wrapper_module__.StdOut
    StdErr = __wrapper_module__.StdErr


class CompareMethod(IntFlag):
    BinaryCompare = __wrapper_module__.BinaryCompare
    TextCompare = __wrapper_module__.TextCompare
    DatabaseCompare = __wrapper_module__.DatabaseCompare


class __MIDL___MIDL_itf_scrrun_0000_0000_0001(IntFlag):
    Normal = __wrapper_module__.Normal
    ReadOnly = __wrapper_module__.ReadOnly
    Hidden = __wrapper_module__.Hidden
    System = __wrapper_module__.System
    Volume = __wrapper_module__.Volume
    Directory = __wrapper_module__.Directory
    Archive = __wrapper_module__.Archive
    Alias = __wrapper_module__.Alias
    Compressed = __wrapper_module__.Compressed


class __MIDL___MIDL_itf_scrrun_0001_0001_0002(IntFlag):
    WindowsFolder = __wrapper_module__.WindowsFolder
    SystemFolder = __wrapper_module__.SystemFolder
    TemporaryFolder = __wrapper_module__.TemporaryFolder


class __MIDL___MIDL_itf_scrrun_0001_0001_0001(IntFlag):
    UnknownType = __wrapper_module__.UnknownType
    Removable = __wrapper_module__.Removable
    Fixed = __wrapper_module__.Fixed
    Remote = __wrapper_module__.Remote
    CDRom = __wrapper_module__.CDRom
    RamDisk = __wrapper_module__.RamDisk


class IOMode(IntFlag):
    ForReading = __wrapper_module__.ForReading
    ForWriting = __wrapper_module__.ForWriting
    ForAppending = __wrapper_module__.ForAppending


class Tristate(IntFlag):
    TristateTrue = __wrapper_module__.TristateTrue
    TristateFalse = __wrapper_module__.TristateFalse
    TristateUseDefault = __wrapper_module__.TristateUseDefault
    TristateMixed = __wrapper_module__.TristateMixed


StandardStreamTypes = __MIDL___MIDL_itf_scrrun_0001_0001_0003
FileAttribute = __MIDL___MIDL_itf_scrrun_0000_0000_0001
DriveTypeConst = __MIDL___MIDL_itf_scrrun_0001_0001_0001
SpecialFolderConst = __MIDL___MIDL_itf_scrrun_0001_0001_0002


__all__ = [
    'DriveTypeConst', 'FileAttribute', 'Hidden', 'Compressed',
    'SpecialFolderConst', '__MIDL___MIDL_itf_scrrun_0001_0001_0003',
    'StandardStreamTypes', 'Volume',
    '__MIDL___MIDL_itf_scrrun_0001_0001_0001', 'IFileCollection',
    'Alias', 'TextCompare', 'IDriveCollection', 'Folder',
    'SystemFolder', '__MIDL___MIDL_itf_scrrun_0000_0000_0001',
    'IOMode', 'FileSystemObject', 'Drives', 'Fixed', 'Folders',
    'typelib_path', 'IDrive', 'Tristate', 'System', 'StdOut', 'IFile',
    'UnknownType', 'File', 'IDictionary', 'ForAppending',
    'ForWriting', 'StdErr', 'CompareMethod', 'RamDisk', 'ReadOnly',
    'StdIn', '__MIDL___MIDL_itf_scrrun_0001_0001_0002',
    'BinaryCompare', 'Encoder', 'IFolder', 'IScriptEncoder',
    'Removable', 'IFileSystem', 'CDRom', 'Files',
    'TristateUseDefault', 'Drive', 'Archive', 'Normal',
    'TristateMixed', 'Directory', 'WindowsFolder', 'Remote',
    'DatabaseCompare', 'ForReading', 'TristateTrue', 'IFileSystem3',
    'Library', 'TextStream', 'TemporaryFolder', 'TristateFalse',
    'IFolderCollection', 'ITextStream', 'Dictionary'
]

(edited: code snippet was changed after merging #493)

Previous description:

from comtypes.gen._420B2830_E718_11CF_893D_00A0C9054228_0_1_0 import (
    TextCompare, IFileSystem3, Fixed, StdIn,
    __MIDL___MIDL_itf_scrrun_0001_0001_0001, StdOut, IUnknown, CDRom,
    Files, _check_version, helpstring, System, Normal, StdErr,
    HRESULT, ForAppending, CompareMethod, typelib_path, ReadOnly,
    Alias, IOMode, VARIANT_BOOL, Removable, Library,
    TristateUseDefault, Drive, IDriveCollection, ForWriting, Encoder,
    IScriptEncoder, Directory, IFileCollection, _lcid, RamDisk,
    Dictionary, GUID, COMMETHOD, StandardStreamTypes, TristateTrue,
    SpecialFolderConst, IFile, Hidden, SystemFolder, IFileSystem,
    Archive, TextStream, IFolderCollection, FileAttribute,
    __MIDL___MIDL_itf_scrrun_0001_0001_0002, IDrive, FileSystemObject,
    BSTR, CoClass, BinaryCompare, TristateMixed, Remote, Tristate,
    Compressed, UnknownType, Drives, TemporaryFolder, VARIANT,
    DatabaseCompare, __MIDL___MIDL_itf_scrrun_0000_0000_0001,
    WindowsFolder, File, dispid, TristateFalse, IDictionary,
    ForReading, ITextStream, Folders,
    __MIDL___MIDL_itf_scrrun_0001_0001_0003, IFolder, Folder,
    DriveTypeConst, Volume
)


__all__ = [
    'TextCompare', 'StandardStreamTypes', 'IFileSystem3', 'Fixed',
    'StdIn', '__MIDL___MIDL_itf_scrrun_0001_0001_0001', 'StdOut',
    'CDRom', 'Files', 'TristateTrue', 'SpecialFolderConst', 'IFile',
    'Hidden', 'System', 'DriveTypeConst', 'Normal', 'SystemFolder',
    'Folder', 'IFileSystem', 'StdErr', 'Archive', 'ForAppending',
    'TextStream', 'IFolderCollection', 'CompareMethod',
    'FileAttribute', '__MIDL___MIDL_itf_scrrun_0001_0001_0002',
    'IDrive', 'FileSystemObject', 'typelib_path', 'ReadOnly',
    'BinaryCompare', 'TristateMixed', 'Remote', 'Tristate',
    'Compressed', 'UnknownType', 'Alias', 'Drives', 'Dictionary',
    'DatabaseCompare', '__MIDL___MIDL_itf_scrrun_0000_0000_0001',
    'IOMode', 'WindowsFolder', 'File', 'Library', 'TristateFalse',
    'IDictionary', 'ForReading', 'TristateUseDefault', 'ITextStream',
    'Drive', 'IDriveCollection', 'Folders', 'ForWriting', 'Encoder',
    '__MIDL___MIDL_itf_scrrun_0001_0001_0003', 'IScriptEncoder',
    'Directory', 'IFolder', 'IFileCollection', 'RamDisk',
    'TemporaryFolder', 'Removable', 'Volume'
]

↓

from enum import IntFlag

from comtypes.gen import _420B2830_E718_11CF_893D_00A0C9054228_0_1_0
from comtypes.gen._420B2830_E718_11CF_893D_00A0C9054228_0_1_0 import (
    ForAppending, GUID, TristateMixed, Removable, Alias, Folders,
    IDriveCollection, CoClass, Remote, IFileSystem, DatabaseCompare,
    Compressed, ForWriting, Directory, UnknownType, VARIANT,
    typelib_path, ReadOnly, IFileCollection, StdIn, IFolder,
    helpstring, StdErr, Volume, SystemFolder, TemporaryFolder, _lcid,
    Fixed, Drive, IFileSystem3, System, BSTR, BinaryCompare, Folder,
    ITextStream, Hidden, Normal, COMMETHOD, CDRom, File, HRESULT,
    TristateFalse, IDrive, TristateUseDefault, Drives, RamDisk,
    IFolderCollection, Archive, IUnknown, TextCompare, Encoder,
    TristateTrue, dispid, IFile, Files, ForReading, IDictionary,
    TextStream, WindowsFolder, _check_version, StdOut, Dictionary,
    Library, VARIANT_BOOL, FileSystemObject, IScriptEncoder
)


class __MIDL___MIDL_itf_scrrun_0001_0001_0002(IntFlag):
    WindowsFolder = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.WindowsFolder
    SystemFolder = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.SystemFolder
    TemporaryFolder = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.TemporaryFolder


class IOMode(IntFlag):
    ForReading = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.ForReading
    ForWriting = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.ForWriting
    ForAppending = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.ForAppending


class Tristate(IntFlag):
    TristateTrue = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.TristateTrue
    TristateFalse = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.TristateFalse
    TristateUseDefault = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.TristateUseDefault
    TristateMixed = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.TristateMixed


class __MIDL___MIDL_itf_scrrun_0001_0001_0003(IntFlag):
    StdIn = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.StdIn
    StdOut = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.StdOut
    StdErr = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.StdErr


class __MIDL___MIDL_itf_scrrun_0000_0000_0001(IntFlag):
    Normal = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.Normal
    ReadOnly = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.ReadOnly
    Hidden = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.Hidden
    System = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.System
    Volume = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.Volume
    Directory = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.Directory
    Archive = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.Archive
    Alias = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.Alias
    Compressed = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.Compressed


class CompareMethod(IntFlag):
    BinaryCompare = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.BinaryCompare
    TextCompare = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.TextCompare
    DatabaseCompare = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.DatabaseCompare


class __MIDL___MIDL_itf_scrrun_0001_0001_0001(IntFlag):
    UnknownType = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.UnknownType
    Removable = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.Removable
    Fixed = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.Fixed
    Remote = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.Remote
    CDRom = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.CDRom
    RamDisk = _420B2830_E718_11CF_893D_00A0C9054228_0_1_0.RamDisk


SpecialFolderConst = __MIDL___MIDL_itf_scrrun_0001_0001_0002
StandardStreamTypes = __MIDL___MIDL_itf_scrrun_0001_0001_0003
FileAttribute = __MIDL___MIDL_itf_scrrun_0000_0000_0001
DriveTypeConst = __MIDL___MIDL_itf_scrrun_0001_0001_0001


__all__ = [
    'ForAppending', 'Hidden', 'Normal',
    '__MIDL___MIDL_itf_scrrun_0001_0001_0003', 'CDRom', 'File',
    'TristateMixed', '__MIDL___MIDL_itf_scrrun_0000_0000_0001',
    'Removable', 'Alias', 'Tristate', 'TristateFalse', 'Folders',
    'IDrive', 'IDriveCollection', 'CompareMethod', 'Remote',
    'IFileSystem', 'TristateUseDefault', 'FileAttribute',
    'DatabaseCompare', 'Compressed',
    '__MIDL___MIDL_itf_scrrun_0001_0001_0001', 'Drives', 'ForWriting',
    'RamDisk', 'IOMode', 'IFolderCollection', 'Directory', 'Archive',
    'UnknownType', 'StandardStreamTypes', 'typelib_path', 'ReadOnly',
    'TextCompare', 'Encoder', 'TristateTrue', 'IFileCollection',
    'StdIn', 'IFolder', 'StdErr', 'Volume', 'IFile', 'SystemFolder',
    'SpecialFolderConst', 'TemporaryFolder', 'Files', 'ForReading',
    'Fixed', 'IDictionary', 'TextStream', 'Drive', 'IFileSystem3',
    'WindowsFolder', 'StdOut', 'System',
    '__MIDL___MIDL_itf_scrrun_0001_0001_0002', 'Dictionary',
    'BinaryCompare', 'DriveTypeConst', 'Folder', 'Library',
    'ITextStream', 'FileSystemObject', 'IScriptEncoder'
]

So far I have been trying to define enums in the wrapper modules.
However, the executable wrapper module code is generated relying on the enumeration type names are assigned as aliases of c_int.

Defining enumeration types in the friendly module does not affect the wrapper module implementation. And it is a low-cost implementation way.

This is backward-compatibility-breaking that changes symbols in the friendly modules previously imported as aliases of c_int.

There may be projects that still want to use these symbols (like TgtEnum) as aliases for c_int after this change.
But, in that case, changing the codebase as followings are able to correspond without much effort.

• from from comtypes.gen.friendly import TgtEnum
  • to from comtypes.gen import friendly; TgtEnum = friendly.__wrapper_module__.TgtEnum
  • to TgtEnum = c_int

(edited: explanation of alternatives was changed after merging #493)

Previous description:

There may be projects that still want to use these symbols as aliases for c_int after this change.
But, in that case, changing the code from from comtypes.gen.friendly import TgtEnum to TgtEnum = c_int is able to correspond without much effort.

[junkmd]

CIs are passed.

memo

https://ci.appveyor.com/project/cfarrow/comtypes/builds/46028903
https://github.com/enthought/comtypes/actions/runs/3997246728/jobs/6858324176
https://ci.appveyor.com/project/pywinauto/pywinauto/builds/46028939

[junkmd]

@vasily-v-ryabov

This is backward-compatibility-breaking changes.
So I would like to make agreement.
Please review this.

[vasily-v-ryabov]

In my opinion this is OK. But it should be carefully described in the change log and README.

[junkmd]

described in the change log and README.

I think the summary of this change would be worded as such.

The enumeration types are now generated in user-friendly-named modules.
Those names were assigned as `c_int` aliases in previous versions.

[jaraco]

In my opinion, backward-incompatible changes are okay if they're well-communicated and have value. I don't have enough insight to assess these tradeoffs. I did notice that this change is identified for a 1.3 milestone, which doesn't sound like a backward-incompatible change. Use your judgment. I would recommend not coupling this work with the drop_py2 work.

[junkmd]

Ok, I see where the other maintainers are concerned about the situation.

I agree not to merge this PR currently yet.

I would like to leave it open to let the community know that there are plans to add this feature.
I suggest merging this in 2 weeks to a month after the drop_py2 version is released.

[junkmd]

And I am considering adding a label to put on such PRs.

[junkmd]

close and re-open to re-run CI

[junkmd]

The codebase conflicts that occurred during the merging of #493 have been resolved.
As wrapper modules have been imported with abstracted names into friendly modules, the method of defining enumeration members has changed.
In accordance with these changes, the kanban has been updated.

And CIs are passed.

memo

https://github.com/enthought/comtypes/actions/runs/5532216702/jobs/10093976801?pr=475
https://ci.appveyor.com/project/cfarrow/comtypes/builds/47529802
https://ci.appveyor.com/project/pywinauto/pywinauto/builds/47529963

[vasily-v-ryabov]

Is it still breaking backward compatibility? Can we consider supporting both new approach and deprecated legacy names?

[jaraco]

This approach looks sound and valuable.

I don't have any substantive suggestions.

If I were rolling out this change, here's what I'd recommend:

• Release it as a 1.x change noting the breaking behavior.
• Provide advice to users on how to identify if the breaking behavior affects them and how to migrate.
• Be prepared to back out the change if it causes unexpected breakage that's not readily mitigated by the users.
• If backing out the change, explore a transitional approach that gives users advanced warning and a better path to migration.

[junkmd]

Of course, we should tell that TgtEnum is (will be) no longer an alias for ctypes.c_int to users in the release note and documents.

For example (but I have not seen anything like this), projects with the following codebase will not work with this change.

from comtypes.gen.friendly import TgtEnum
a = TgtEnum.from_param(...)

However, I believe that we have found a way to support both new approach and deprecated legacy names.

For example, after releasing a version with this PR, users can still use the old definitions by changing import and the definitions of module-level symbols as follows;

- from comtypes.gen.friendly import TgtEnum
+ import ctypes
+ TgtEnum = ctypes.c_int
a = TgtEnum.from_param(...)

- from comtypes.gen.friendly import TgtEnum
+ from comtypes.gen import friendly
+ TgtEnum = friendly.__wrapper_module__.TgtEnum
a = TgtEnum.from_param(...)

- from comtypes.gen import friendly
+ from comtypes.gen.friendly import __wrapper_module__ as friendly
a = friendly.TgtEnum.from_param(...)

By including these examples in the release note, there will be less confusion for users.