Agent python interface file (.pyi)

[Robadob]

Discussed in https://github.com/FLAMEGPU/FLAMEGPU2/discussions/1163

Python IDEs are not currently able to detect the agent-python API, as it does not exist as a Python package.

This could be resolved with a python interface file (.pyi) that contains method stubs.

SWIG does not currently support generation of these files.

[ptheywood]

Notes/thoughts dumped from internal slack discussion:

the python ide integration will be looking at the pyflamegpu module and correctly thinking it doesn't have a method named getID.

I.e. having pyflamegpu there without a locally scoped version that represents the device api object but on the host will never work. could maybe do something with .pyi files

pyflmaegpu.MessageSpatial2D has no methods defined (it's device api only)

>>> dir(pyflamegpu.MessageSpatial2D)
['__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__swig_destroy__', '__weakref__', 'thisown']

fix would be to create some empty classes which map the whole Device API i.e. pyi files

looks like a few people have asked for swig to generated pyi files in the past and its not been done / there was a bit of work on it. But even then we don't actually want to wrap our device code in swig, codegen doesn't actually use it.

and that wouldn't help with the methods on the pyflamegpu object either which is a module at that scope not an object

mypy has a tool for generating stubs, but won't work for things not wrapped in swig so doesn't actually help. Unless we get swig to wrap the device stuff in a separate target, generate stubs from that, and then add those to the pyflamegpu module, but doubt swig will wrap device api stuff successfully.

https://mypy.readthedocs.io/en/stable/stubgen.html