Adds py.typed for typing support according to pep 561

[TrapsterDK]

Hi,

I've just started using the raylib package and ran into an issue where mypy does not check for typing. I looked further into it as the library already has type annotations in the __init__.pyi files. The issue occurs because the library is missing "py.typed" files to be up to date with pep 561 and the updated guidelines for typing.

This is therefore just a simple pull request that adds the "py.typed" file to both the raylib package and the pyray package.

[electronstudio]

The .pyi files only exist for the purpose of providing auto-completion in Pycharm (and generating the HTML documentation). The type information in them is fake. Therefore I'm doubtful it's a good idea to encourage people to use them for type checking. We already had someone complaining because apparently VScode does do type checking by default with them and it causes red underlines.

[electronstudio]

#129

[electronstudio]

It would be nice to have proper type checking, but it seems to be in conflict with the goal of providing nice completions/docs.

Questions to discuss:

If we did enable type checking with the current fake type hints, how bad would it be? Do the examples pass type checking? If not, how much work would it be to make fake hints that are good enough for checking?

Or, could we make actual correct type hints? Probably yes, but how much work would it be? Would they be less useful for completion/documentation than the fake hints? Is there a way to meet both goals?

[TrapsterDK]

I am willing to help / do all or most of the work required to add proper type hinting. I just need to know what is missing to generate the appropriate type hinting / how the type hints are fake at the moment. I assume this is automatically generated.

[electronstudio]

They are generated here:

raylib-python-cffi/make_docs.sh

Line 49 in 252fc29

echo "creating pyi files"

If you look at the .pyi files you'll see there are lot of 'Any' types, which are not accurate but I guess will pass (?).

The thing that makes them fake is the types like, e.g. Color in raylib pyi is set to be fake class called 'struct'.

raylib-python-cffi/raylib/__init__.pyi

Line 3788 in 252fc29

Color: struct

The real CFFI types don't actually have a Color class. It's a C type.

In pyray pyi the fakes are more elaborate, they also have fields so the IDE can autocomplete:

raylib-python-cffi/pyray/__init__.pyi

Line 3073 in 252fc29

class Color:

The real type is <class '_cffi_backend.__CDataOwn'> but that doeosn't have Python fields so if you set it to that you won't get autocompletion. And you won't know from a function signature whether it represents a Color or a Vector.

[TrapsterDK]

I have looked through the source code and understand what you mean by fake type hints. I don't think it would be useful to add the py.typed files at the moment as it would not be very helpful with the amount of Any type annotations.

For the typing to be useful it would require the entire interface to be typed. This would require adding typing to the C references and C structs. I do not believe it would help to add further typing to the struct objects in the raylib library as it would require wrapping each object as a class. I do however believe it could make sense to add typing to pyray as all structs are already wrapped.

I tried running the parser to see if the information for this is available and if the problem is feasible to solve. However, I keep running into Segmentation faults when the generation of the JSON files occur using "make_docs.sh".

The question is whether this feature is needed as I do not believe most people writing games type-check their code using mypy or alike.

[electronstudio]

Not sure why Raylib's raylib_parser doesn't work for you, you would have to report the issue to Raylib. The generated JSON files do indeed contain all the type info from the C headers - that's how we generate the pyi.

Yes wrapping all the C types in Python classes and providing type hints for the classes would be one solution.

But currently the structs in pyray are not wrapped. There are generator functions that are designed to look like class constructors, but what they return is a C type, not a Python class that wraps a C type. Yes it would be possible to autogenerate wrappers but it would increase complexity and reduce performance (need to wrap and unwrap on every function call) so I don't think it's a good idea.

[Softianix]

I have looked through the source code and understand what you mean by fake type hints. I don't think it would be useful to add the py.typed files at the moment as it would not be very helpful with the amount of Any type annotations.

For the typing to be useful it would require the entire interface to be typed. This would require adding typing to the C references and C structs. I do not believe it would help to add further typing to the struct objects in the raylib library as it would require wrapping each object as a class. I do however believe it could make sense to add typing to pyray as all structs are already wrapped.

I tried running the parser to see if the information for this is available and if the problem is feasible to solve. However, I keep running into Segmentation faults when the generation of the JSON files occur using "make_docs.sh".

The question is whether this feature is needed as I do not believe most people writing games type-check their code using mypy or alike.

Hello, great proposal 🔥

I think most Python projects nowadays use mypy and I'm also willing to help in work around type hints addition, if such decision will be made.

These "fake" type annotations for pyray (__init__.pyi) look ok for me, at first glance, as they are for Python interface.

Maybe, it would be ok to add py.typed marker for pyray and then the next big thing to do would be to add type hints for raylib CFFI, but most of the arguments are probably of ctypes and/or cffi types, so it wouldn't be as beneficial as adding type hints for pyray, so it may wait, I thing that we can skip / postpone it for now.

---

I disagree with:

it would not be very helpful with the amount of Any type annotations.

Now, if you configure mypy to ignore this library from type checking then it treats it as everything would be Any, but there are a lot of function signatures that have correct typing now, e.g.:

Of course, some of them have Any in their functions signatures, but in my opinion it is better to have something (add py.typed and use __init__.pyi with some arguments being Any) than nothing (ignore whole library - use Any for every argument)

[electronstudio]

I tried running mypy on the examples and got many type errors, so there is certainly work required before enabling py.typed.

Part of the problem is that CFFI is very forgiving about what types it will accept. It will auto convert Python lists and tuples to C structs, for instance. So attempting to pin it down with static typing requires finding all those cases and writing union types for everything it will accept.

If we could get all the examples to check with no errors then there is still the philosophical issue of whether its right to type check fake types, even if the fakes are self-consistent within the module.

One possibility might be to ship a separate raylib-stubs module and then people who want strict type checking can install that, which would hopefully avoid the complaints from regular users if it's not perfect.

[electronstudio]

This can probably be merged after merging #151