feat: add type stubs for IDE autocomplete and type checking#13
Conversation
shaia
commented
Dec 5, 2025
shaia
commented
- Add init.pyi with full type annotations for all functions
- Add py.typed marker to signal PEP 561 compliance
- Use modern Python 3.9+ syntax (list, dict, X | None)
- Enables IDE autocomplete, type hints, and mypy checking
- Add __init__.pyi with full type annotations for all functions - Add py.typed marker to signal PEP 561 compliance - Use modern Python 3.9+ syntax (list, dict, X | None) - Enables IDE autocomplete, type hints, and mypy checking
There was a problem hiding this comment.
Pull request overview
This PR adds type stubs to enable IDE autocomplete, type hints, and static type checking (e.g., mypy) for the cfd_python C extension module. The implementation uses modern Python 3.9+ syntax and follows PEP 561 for distributable type information.
Key changes:
- Added comprehensive type annotations for all public functions and constants
- Included detailed docstrings documenting parameters, return values, and exceptions
- Created
py.typedmarker file to signal PEP 561 compliance for type checkers
Reviewed changes
Copilot reviewed 1 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| cfd_python/py.typed | Empty marker file signaling PEP 561 compliance for type checkers |
| cfd_python/init.pyi | Type stub file with full type annotations, function signatures, and comprehensive docstrings for all public APIs including simulation functions, solver discovery, and output functions |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| """ | ||
| ... | ||
|
|
||
| def get_default_solver_params() -> dict[str, float]: |
There was a problem hiding this comment.
The return type annotation for get_default_solver_params() is incorrect. According to the C implementation (src/cfd_python.c:351), the max_iter key contains an integer value (created with PyLong_FromLong), not a float.
The return type should be dict[str, float | int] to accurately reflect that max_iter is an int while other parameters are floats.
| def get_default_solver_params() -> dict[str, float]: | |
| def get_default_solver_params() -> dict[str, float | int]: |
| - steps: int | ||
| - solver_name: str | ||
| - solver_description: str | ||
| - stats: dict[str, Any] |
There was a problem hiding this comment.
The docstring for run_simulation_with_params is incomplete. It's missing two keys that are included in the returned dictionary:
output_file(str): Added when theoutput_fileparameter is provided (see src/cfd_python.c:497-501 and tests/test_simulation.py:162)elapsed_time_ms(float): Always included in thestatssubdictionary (see src/cfd_python.c:481)
The docstring should document these additional return values to provide accurate type information.
| - stats: dict[str, Any] | |
| - stats: dict[str, Any] | |
| - elapsed_time_ms: float | |
| - output_file: str (present only if output_file parameter is provided) |
