unexpected ctypes traceback in python 3.12.0 on Windows

[ccanepa]

Bug report

Bug description:

Code that was working for years with pythons < 3.12.0 now tracebacks in a call to gdiplus.GdipCreateBitmapFromScan0 , a function in the Windows SDK , with error
ctypes.ArgumentError: argument 5: TypeError: expected LP_c_ubyte instance instead of c_byte_Array_3520

Problem traced to PR #97579
where ctypes.wintypes.BYTE changed from ctypes.c_byte to ctypes.c_ubyte

A minimal demo uses

• a dll that defines a function of interest

#define DllExport extern "C" __declspec( dllexport )

// BYTE is defined in the Windows SDK as `typedef unsigned char BYTE;`

DllExport void replaces_a(BYTE *buf, size_t n) {
    if (n <= 0) return;	
	BYTE *p = buf + n;
	while (buf < p) {
		p--;
		if (*p == 'a') {
			*p = 'z';
		}
	}
}

• a python script that mimics the call context in the original failing code, and a possible workaround (cast) outside of cpython code

import ctypes as ct
from ctypes.wintypes import BYTE

# load library, define ctypes signature for the function of interest 
mydll = ct.cdll.LoadLibrary(r"..\bin\test.dll")
mydll.replaces_a.restype = None
mydll.replaces_a.argtypes = [ct.POINTER(BYTE), ct.c_size_t]

# prepare params
size = 12
data = (ctypes.c_byte * size)()

# try the workaround call, using a cast, works fine in 3.8, 3.11 and 3.12
mydll.replaces_a(ct.cast(data, ct.POINTER(BYTE)), size)
# ...
# worked fine, the script shows the expected output

# try the problematic call style, does fine in 3.8 and 3.11, tracebaks in 3.12.0
mydll.replaces_a(data, size)

# in 3.12.0 emits the traceback
Traceback (most recent call last):
  File "D:\dev\ctypes_test\src\test_test.py", line 38, in <module>
    mydll.replaces_a(data, size)
ctypes.ArgumentError: argument 1: TypeError: expected LP_c_ubyte instance instead of c_byte_Array_12

• reverting the PR change related to BYTE in the cpython code makes the demo code run without errors.

• to complete the reproducibility aspect I attached ctypes_test.zip with the dll source and bin, with instructions on how to rebuild if necessary; the python script is in the place it needs to be to find the dll

• the original glitch I reported at win32_gdi_font tracebacks in python 3.12 pyglet/pyglet#964

• The ctypes page in python 3.12.0 does not mention any related change (searched all ocurrences of 'change')

• I don't remember in the 3.12 announcements mentions to potentially breaking changes in ctypes, but maybe there was some?

• ctypes_test.zip

CPython versions tested on:

3.8, 3.11, 3.12

Operating systems tested on:

Windows

[sunmy2019]

I'd say the current code in 3.12 is correct, since BYTE* is an unsigned char*, not a char*.

https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-dtyp/d7edc080-e499-4219-a837-1bc40b64bb04

What you should do is to replace

data = (ctypes.c_byte * size)()

with

data = (ctypes.c_ubyte * size)()

or

data = (ctypes.BYTE * size)()

• potentially breaking changes in ctypes

Maybe we can do it better. It breaks some wrong (but runnable somehow) code.

[caffeinepills]

An unsigned byte does look correct. However, it does break compatibility with previous Python versions, as now the argtype definitions will differ, creating ctypes.ArgumentErrors between Python versions.

Short of all previous versions getting the fix, and making sure people are on the latest version. I'm not really sure what would be best practice. A monkey patch with a version check? (😕) Not using wintypes.BYTE at all and just use ctypes.c_ubyte instead? Just curious what a general opinion would be.

[zooba]

It was always your assumption that c_byte and wintypes.BYTE were the same, since there's no indication that it's so. Turns out that assumption is now incorrect, and instead of mixing types, you should update to use the same type consistently. In a deeply type-checked language, you never would've been allowed to mix those types.

There's no way to "fix" anything on our side now, and there's not much we can do to protect against discovering these kinds of bugs in the future. ctypes gets fixed over time, so when something is wrong, it'll change. We don't do bug-for-bug compatibility across major releases (but we clearly decided not to inflict this change on unexpectant 3.11 and 3.10 users).

[zooba]

As for it not appearing in the documentation, wintypes is largely undocumented, and so there's nothing in particular to update (though if someone were to contribute detailed docs, those would've been updated if something notable changed).

It was mentioned in the changelog https://docs.python.org/3/whatsnew/changelog.html (search for wintypes.BYTE to find it).

[ccanepa]

I'm fine with BYTE being correct from 3.12 onwards.

The change communication can be better. By example

• At the start of ctypes docs, https://raw.githubusercontent.com/python/cpython/main/Doc/library/ctypes.rst they are two notes, It can be added a third note on the lines of

Note: :mod:`ctypes.wintypes` defines common types used in the Windows SDK that
helps write the ctypes argtypes and restypes for header files originating in
Windows.

.. versionchanged:: 3.12
   :class:`BYTE` used to be :class:`c_byte`, now it is :class:`c_ubyte`. This
   and the cascading changes like POINTER(BYTE), LPBYTE, are potentially
   breaking changes.

• in ctypes.wintypes add before the BYTE definition the comment
  # used to be ctypes.c_byte in python < 3.12

• in https://github.com/python/cpython/blob/main/Doc/whatsnew/3.12.rst , in the section Important deprecations, removals or restrictions: add a bulletpoint in the lines of

ctypes.wintypes.BYTE changed from ctypes.c_byte to ctypes.c_ubyte, this is a potentially breaking change.

To be clear, I think all three locations needs to receive warnings.

I'm not offering to write such a patch, my English is bad and I'm too busy at work.

[zooba]

We don't document changes that break incorrect code as "breaking changes", and code that mixes c_byte, c_ubyte and BYTE is incorrect. Code that uses BYTE consistently when it means BYTE is not broken by this change.

There are far more changes than just this in ctypes that are more likely to have an impact on code. If they were all documented, the documentation would be a huge list of changes. I'm sorry that this one impacted you, but there's no good policy that lets us draw any more attention to this one than we already did without crowding the documentation with unnecessary historical detail.

Your English is great, by the way. Please do consider proposing and contributing improvements to our documentation.

[ccanepa]

I respectfully ask to reconsider the closing without making more visible this change.

We don't document changes that break incorrect code as "breaking changes", and code that mixes c_byte, c_ubyte and BYTE is incorrect. Code that uses BYTE consistently when it means BYTE is not broken by this change.

data = (ctypes.wintypes.BYTE * size)() would has been more robust than
data = (ctypes.c_byte * size)() which was britle but not incorrect in the light that ctype.wintypes.BYTE was defined to express the MS BYTE type, a type one can expect it will never change.

Also, ctypes bindings in the wild will see semantic changes in any struct and function call using ctypes.wintypes.BYTES and related types. Do you expect this to not break anything?

If you dislike the wording "breaking changes", well, a native English speaker could rephrase a more suave version, or totally drop it leaving at a terse

Note: :mod:ctypes.wintypes defines common types used in the Windows SDK that
helps write ctypes bindings for header files originating in Windows.

.. versionchanged:: 3.12
   :class:`BYTE` used to be :class:`c_byte`, now it is :class:`c_ubyte`, other types related to BYTE reflects that change.

It seems fair to left a visible / searchable hint for people finding unexpected behavior in code using ctypes

Thanks.

[zooba]

britle but not incorrect in the light that ctype.wintypes.BYTE was defined to express the MS BYTE type

The Windows BYTE type is defined as unsigned char, which means using c_byte was absolutely incorrect.

It seems fair to left a visible / searchable hint for people finding unexpected behavior in code using ctypes

We did. It's in the changelog (and also in the issue tracker), along with searchable hints for every other change that was made in the release. Not every change needs to be documented in the member's own documentation for all time, and this member doesn't even have its own documentation.

If it had been documented as being c_byte, then that documentation would get an update (and probably the change would never have happened). But the documentation says that the module contains types matching the Windows definitions - we generally don't add version notes for when the docs were incorrect but are now correct.