static typing

[jorenham]

This adds inline annotations to the Python sources, and stubs for the Cython module. It's verified using mypy, basedpyright (a backwards-compatible fork of pyright that's less forgiving) both configured in strict mode, as well as pyrefly.

I tried to touch the "runtime code" for as much as was feasible, but in some cases I made some minor adjustments. These shouldn't affect the runtime behavior.

[gemini-code-assist]

Summary of Changes

Hello @jorenham, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces comprehensive static typing to the codebase, aiming to enhance code quality, reduce bugs, and improve developer experience. By adding inline type annotations throughout the Python source files and creating type stubs for Cython modules, the project now leverages mypy and basedpyright in strict mode to enforce type correctness. These changes are designed to be largely non-runtime impacting, focusing purely on static analysis benefits.

Highlights

• Static Type Checking Configuration: A new pyproject.toml file has been added to configure mypy and basedpyright for strict static type checking across the stl package, enabling various error codes for comprehensive analysis.
• Extensive Type Annotations: Inline type annotations have been added to Python source files (stl/base.py, stl/main.py, stl/stl.py, stl/utils.py) for functions, methods, class variables, and local variables, significantly improving code clarity and maintainability.
• Cython Type Stubs: A new type stub file (stl/_speedups.pyi) has been introduced to provide type hints for the Cython speedup module, allowing type checkers to analyze calls to these optimized functions.
• Refactored Properties in BaseMesh: The BaseMesh class in stl/base.py has been updated to replace older _get_or_update and _set helper functions with explicit @property and @<property_name>.setter decorators, enhancing readability and type safety for attributes like min_, max_, areas, centroids, and units.
• Dependency Updates: The tests/requirements.txt file has been updated to include mypy and basedpyright, ensuring that the static type checking tools are available for testing and development environments.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/type_check.yml

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces comprehensive static typing across the codebase, which is a fantastic improvement for maintainability and correctness. The use of TypeAlias, Final, ClassVar, protocols, and TYPE_CHECKING guards is excellent. The refactoring of properties in BaseMesh is also a great enhancement.

I've found one critical issue in stl/stl.py where a conditional was inverted, which would lead to a runtime error. I've left a specific comment with a suggested fix.

Overall, this is a high-quality contribution that significantly improves the codebase's quality. Once the identified issue is addressed, this should be ready to merge.

[jorenham]

should be ready for review now :)