Add pygame.typing module

[damusss]

trafficstars

This PR would potentially implement https://github.com/pygame-community/pygame-ce/issues/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]

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.

[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.

[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 👍