Add pygame.typing module

[damusss]

This PR would potentially implement #1682

As the title says, this PR adds the typing module to pygame. I've made some libraries myself and I often wanted to annotate properly things as colors and rects, but the types they accept are a wide range, especially the rect, so it would be really nice to put rect: pygame.typing.RectLike in an argument for example. I see no reason not to have this.

Details about the PR:

• only the contents of _common.pyi have been ported. This can be easily expanded in the future.
• _common.pyi has been removed
• src_py/typing.py has been added, being similar to _common.pyi
• gen_stubs.py has the functionality of copying typing.py to typing.pyi, to make type checkers happy
• __init__.py was modified to correctly import the typing module
• Since the API will be public, a consistent pattern has been chosen with @ankith26 , which is to add "Like" to the types, to annotate that it's not the actual object but rather a set of types that can replace it (if one needs the object to access the attributes, pygame.Rect is preferred over pygame.typing.RectLike, while if the object is going to be passed to a pygame function that accepts RectLike, there's no point in forcing a pygame.Rect. You get the idea.)

Tests and docs have been added. Docs are currently temporary, but might not be when you reader read this message.

[Starbuck5]

So before we add a whole new module for this, we should think about some things.

How do other libraries do this?

Does this need to be a module or can type variables be scattered where they are relevant? Like pygame.rect.RectLike?

How can we keep this stable? This exposes more stuff that we need to keep stable, are we okay with that?

[damusss]

So before we add a whole new module for this, we should think about some things.

How do other libraries do this?

Does this need to be a module or can type variables be scattered where they are relevant? Like pygame.rect.RectLike?

How can we keep this stable? This exposes more stuff that we need to keep stable, are we okay with that?

2. you could realistically only scatter rect, color and maybe rgba, maybe path and file to rwobject, but those are all implemented in C and they would require some injection.

3. what non stable things are we exposing?

[Matiiss]

As for how other libraries do it, here's numpy:
https://github.com/numpy/numpy/tree/main/numpy/typing
https://github.com/numpy/numpy/tree/main/numpy/_typing

Note that the _typing package is internally imported in stub (.pyi) files

[ankith26]

Overall, I really like where this PR is going! I am approving the code changes from my side. I left a few reviews for improving the test file.

As this is a significant change, I would like for this PR to have 3 approving reviews.

[ankith26]

Addressing some of Starbuck's points (in favour of this PR) from my POV

How do other libraries do this?
Does this need to be a module or can type variables be scattered where they are relevant? Like pygame.rect.RectLike?

As Matt already pointed out, numpy already has a dedicated submodule for typing stuff. In the future, if needed, we can make aliases in scattered places, but I'd like all the implementation to be in one file.

How can we keep this stable? This exposes more stuff that we need to keep stable, are we okay with that?

This PR already adds a test file, that should help with maintaining stability. OFC, the file could be expanded in future iterations.
If this makes approval more comfortable: we can always slap an "experimental" notice on the docs, and allow for more drastic changes here for a few releases.

[Matiiss]

LGTM, I sense this will be a great addition to pygame-ce

Maybe the type aliases could be hinted as TypeAliases, but if type checkers don't complain then it's probably that important.

I suppose sometime in the future we could restructure this a bit so that there's no need to literally copy-paste code from typing.py to typing.pyi, but I suppose it should be fine for now.

Thanks! 🚀

[bilhox]

Overall LGTM, I left some requested changes for the documentation part.
I feel like for people reading the docs, a list of structure for each type in pygame.type is a lot better for the user. Even though it's abstract and can technically handles an infinite number of type as long as it respects the structure, making a list of the most common types used feels essential for the user.

[bilhox]

pygame.gfxdraw does not handle string colors and mapped color, only sequences of 3 or 4 values are accepted (RGB and RGBA).

[damusss]

pygame.gfxdraw does not handle string colors and mapped color, only sequences of 3 or 4 values are accepted (RGB and RGBA).

so should i say supported by "almost" all pygame functions or do you want me to edit gfxdraw.pyi? the typehints were there already and they were wrong before this PR.

[Matiiss]

None of the sprite.pyi types seem to be exposed, is this intended? I find it would be greatly beneficial to expose those types as well. It would help with some testing I plan to do regarding those types and thus it would require access to concrete objects.

[damusss]

None of the sprite.pyi types seem to be exposed, is this intended? I find it would be greatly beneficial to expose those types as well. It would help with some testing I plan to do regarding those types and thus it would require access to concrete objects.

Do you mean types such as _SuportsSprite and _SupportsDirtySprite? It is kinda intended. This PR only implements the contents of common.pyi to keep the scope simple. extra typings can be added later with other PRs based on their need (at the start of the PR I added a lot more types but keeping it small is better). @ankith26 might have a say in the matter.

[Matiiss]

None of the sprite.pyi types seem to be exposed, is this intended? I find it would be greatly beneficial to expose those types as well. It would help with some testing I plan to do regarding those types and thus it would require access to concrete objects.

Do you mean types such as _SuportsSprite and _SupportsDirtySprite? It is kinda intended. This PR only implements the contents of common.pyi to keep the scope simple. extra typings can be added later with other PRs based on their need (at the start of the PR I added a lot more types but keeping it small is better). @ankith26 might have a say in the matter.

Fair enough, it can be handled in a later PR then 👍

[ankith26]

This PR still has my approval. This has been some nice work, thanks again for working on this! 😎

I think we can just merge it in for now (as it is a pretty safe change that wouldn't break any code) and see how it goes. If needed we can also mark this as experimental before the next release.