Fix stubs for buffer types

[aatle]

Python 3.12 introduced the python-visible buffer protocol with __buffer__ and __release_buffer__. It also defined collections.abc.Buffer.
This PR allows static type checkers to recognize some pygame types as buffers, helpful for Surface buffer operations with other libraries like numpy.

Stub changes:

• Add __buffer__() to Sound, BufferProxy, Mask, Color, PixelArray. Also add __release_buffer__() to first three.
• Replace internal image._BufferLike with typing_extensions.Buffer. Replace Sound.__init__() Any and numpy.ndarray overloads with one typing_extensions.Buffer overload.
• Minor change to type of BufferProxy.write() buffer argument

[ankith26]

This PR is failing stubtest, it is complaining that __buffer__ and __release_buffer__ are not actually present at runtime

[aatle]

Yes, I'll probably have to add a regex to mypy_allow_list.txt.
But I am confused why stubtest may sometimes give different results. (Possibly python version?) It failed for one environment with python 3.10.
And the pygame-ce main branch fails stubtest locally on my Windows computer due to AbstractGroup.__class_getitem__ not having positional-only arguments (python 3.13.0).

[ankith26]

It is probably dependent on the python version, I would suggest adding a python version check in the code instead of adding it to mypy allow list

[ankith26]

I'm not exactly clear what is the logic behind some places having __release_buffer__ and some places not having it. In my understanding from the docs, __release_buffer__ is only needed when some cleanup must be done.

Can you please clarify, and also maybe document it in the code/stubs with comments

[aatle]

I didn't know why some had __release_buffer__ either. The stubs directly reflect the PyBufferProcs of the code.
After some research, I can give some reasons why:

• Sound: if requested as multi-dimensional buffer, it has to allocate a new buffer, which it must release

• BufferProxy: always allocates a new view object, which must be deallocated

• Mask: allocates a buffer for use (which it caches until buffer is released)

• Color: gives its stored internal data for the view, requiring no allocation. May only be read-only buffer.

• PixelArray: gives itself for use in the view. It itself references a surface's pixels, which it cannot release.

I won't document this in the code nor in stubs with comments, it's not of this PR's concern to explain C code internal implementations.

[ankith26]

LGTM, thanks for the PR 🎉

[zoldalma999]

Looks good except for one nitpick. Feel free to resolve it (or not) and merge afterwards.