Missing stub files confuse static type checkers
- Dominant language
- C++
- Stars
- 161
- Forks
- 59
- Avg merge
- 2d 22h
- Merged PRs (30d)
- 7
Description
Currently, the `openpmd-api` module confuses static type checkers like [`pyright`](https://github.com/microsoft/pyright):

Inspecting the `openpmd-api` module via `inspect` and `dir` using the following:
```
sasyed@MAC-140753 ~/D/p/t/heponhpc> cat tmp.py
import openpmd_api as io
import inspect
print("is openpmd-api a module? ", inspect.ismodule(io))
print("what methods are available via openpmd-api? \n", dir(io))
```
I see
```
sasyed@MAC-140753 ~/D/p/t/heponhpc> python tmp.py
is openpmd-api a module? True
what methods are available via openpmd-api?
['Access', 'Access_Type', 'Allocation', 'Attributable', 'Attribute_Keys', 'Base_Record_Base_Record_Component',
'Base_Record_Component', 'Base_Record_Component_Container', 'Base_Record_Mesh_Record_Component',
'Base_Record_Patch_Record_Component', 'Base_Record_Record_Component', 'ChunkInfo', 'DaskArray',
'DaskDataFrame', 'DataFrame', 'Dataset', 'Datatype', 'Dynamic_Memory_View', 'Geometry', 'IndexedIteration',
'Iteration', 'Iteration_Container', 'Iteration_Encoding', 'Mesh', 'Mesh_Container', 'Mesh_Record_Component',
'Mesh_Record_Component_Container', 'ParticleSpecies', 'Particle_Container', 'Particle_Patches',
'Particle_Patches_Container', 'Patch_Record', 'Patch_Record_Component',
'Patch_Record_Component_Container', 'Patch_Record_Container', 'ReadIterations', 'Record',
'Record_Component', 'Record_Component_Container', 'Record_Container', 'Series', 'Unit_Dimension',
'WriteIterations', 'WrittenChunkInfo', '__builtins__', '__cached__', '__doc__', '__file__', '__license__',
'__loader__', '__name__', '__package__', '__path__', '__spec__', '__version__', 'cxx',
'determine_datatype', 'file_extensions', 'list_series', 'openpmd_api_cxx', '
particles_to_daskdataframe', 'particles_to_dataframe', 'record_component_to_daskarray',
'variants']
sasyed@MAC-140753 ~/D/p/t/heponhpc>
```
However, if I use the LSP command to go to the definition of the `openpmd-api` module, I am directed to this [`__init__.py`](https://github.com/openPMD/openPMD-api/blob/dev/src/binding/python/openpmd_api/__init__.py) in the install directory which is missing the definition for `Series`.
## Proposed fix
Per https://github.com/pybind/pybind11/issues/2350, this can be fixed by using [`pybind11-stubgen`](https://github.com/sizmailov/pybind11-stubgen)/[`mypy-stubgen`](https://mypy.readthedocs.io/en/stable/stubgen.html#automatic-stub-generation-stubgen)/etc to generate the stubs.
## Documents of interest
- https://github.com/microsoft/pyright/blob/main/docs/type-stubs.md
- https://peps.python.org/pep-0561/
Contributor guide
Assessment
This issue has not been assessed yet.