Fix the `tlbparser` ctypes mapping for `VT_I1`.

Start with the VT_I1 entry in the type mapping inside tools.tlbparser, then check how comtypes codegenerator emits that type for method arguments, return values and struct/union fields. Read #962 and the NumPy SAFEARRAY path to see what is already proposed. The issue asks for a decision on backward compatibility as well as the mapping change, so "done" needs maintainer agreement on the plan, not only a code edit.

Summary

tools.tlbparser maps the COM type VT_I1 to ctypes.c_char.
This mapping has been used since the early days of the project.

However, VT_I1 means a signed 8-bit integer (see MSLearn). ctypes.c_char represents one byte of character data.
So, the current mapping does not match the meaning of the COM type.

#962 by @haoxuanjng-lang proposes mapping VT_I1 to ctypes.c_byte.
This change may help handle numeric data correctly and fix problems with NumPy support.

However, this mapping has been used for a long time.
Changing it may affect existing Python code.
We need to check both the need for this fix and its impact on users.

Proposed Changes

The generated types for VT_I1 will change:

• For VT_I1, c_char will become c_byte.
• For pointers to VT_I1, STRING will become POINTER(c_byte).
  • Other types that generate STRING, such as VT_LPSTR, are not affected.

This change may also affect arrays and other types that contain VT_I1, such as pointers, SAFEARRAYs, and C arrays.

[!IMPORTANT]

How this package marshals automation.VARIANT values is outside the scope of this issue. This issue is limited to the type library parser and code generator.

Problems

1. NumPy support

VT_I1 is a signed 8-bit integer. Its matching NumPy data type is numpy.int8.

However, when VT_I1 is mapped to ctypes.c_char, SAFEARRAY elements may be treated as character data. This causes problems when creating or converting NumPy arrays.
Negative values or array shapes also not work as expected.

Mapping VT_I1 to the correct signed integer type may fix these problems.

2. The relation between COM types and ctypes types

COM type information defines data types, such as method arguments and return values. comtypes reads this information with tlbparser and creates Python modules with codegenerator.

In these modules, ctypes types are used for COM method arguments and return values, as well as structure and union fields. These types must match the meaning of the data defined by COM type information.

VT_I1 means a signed 8-bit integer, so ctypes.c_byte matches its meaning. ctypes.c_char also uses one byte, but it is for character data. The two types do not have the same meaning.

Therefore, the mapping in tlbparser affects the types of method arguments and return values, as well as structure and union fields in generated modules.
We need the correct mapping so that these types match the COM type information.

3. Long-standing behavior and backward compatibility

The mapping from VT_I1 to ctypes.c_char has been used since the early days of the project.
Existing Python code may depend on this behavior.

For example, users may pass bytes to generated methods or expect return values to be bytes.
Some code may also depend on structure or union fields using c_char.

#962 improves the handling of numeric values. However, it also affects some existing calls.

Long-standing behavior is not always intended behavior. However, fixing a bug and ignoring its impact on existing users are two different things.

If the impact of the change is very small, or users can easily fix their calling code, this is a strong reason to make the change. However, if important libraries or common use cases are affected, and users cannot easily fix the problem, this may block the change.

We need to understand not only why the fix is needed, but also which code is affected, how users can fix the problem, and how much work is required.
Based on this information, we can decide how to change the mapping and how to handle backward compatibility.

Completion criteria

• VT_I1 is mapped to the correct ctypes type for a signed 8-bit integer.
• Generated method arguments and return values, as well as structure and union fields, match the COM type information.
• NumPy SAFEARRAY support gives the expected values, signs, dtype, and shape.
• The impact on existing code and the work needed to fix it are clear.
• Important affected libraries and use cases have been checked, and a plan for backward compatibility has been decided.
• The required tests and documentation are ready.