godotengine
SCons: Add unobtrusive type hints in SCons files
- Supersedes #86213
- Supersedes #92264
This PR adds scons_hints.py to the repo, which grants intellisense logic to all SCons files. Like #86213, this doesn't change any of the script files themselves outside of the include statement; however, the actual line is even more compact & setup to play nice with our new ruff formatter. Now all SCons files will have this header:
#!/usr/bin/env python
from misc.utility.scons_hints import *
No space after the shebang is deliberate, as this new line is effectively metadata. ~~The comments at the end are to disable a warning for a star import (not added to pyproject.toml, as this should be warned about for all other cases) & to not account for this line when performing isort~~ (EDIT: Removed comments; logic handled entirely by pyproject.toml). Opted to put the hint file in misc/utility to avoid cluttering the root, and the added verbosity helps the line feel more "no-touchy".
The only other changes were making isort automatically put the metadata import on top & adjusting the per-file-ignores for SCons files:
F821(Undefined name) was removed, as now all the names are properly defined.F403(Import star) was added, as this setup relies on the import star syntax.F405(Import star variable) was added, same as above.
Made a slight adjustment to no longer need the # noqa: F403 # isort: skip comment. Turns out that tool.ruff.lint.isort has options to define import order, so I made a dedicated metadata section which includes misc.scripts.scons_hints exclusively. Now tools don't have to worry about out-of-order sorts from automated IDE actions, as isort will ensure the metadata section is always on top. Additionally, F403 was added to the per-file ignores alongside F405, as it's the only instance of star importing in the entire repo & is isolated to SCons as-is.
With the belated due-date of 4.3 & largely indirect nature of this implementation, this felt like a safe milestone adjustment. Feel free to revert if this feels out-of-scope.
Looks good to me.
I'd just like to confirm that this stays fully optional, and not something we plan to enforce with more CI checks in the future. Third-party modules or platforms might have their own SCsub files which may or may not be updated to match the changes in this PR, and we don't want to break them.
It'd be 100% optional. I'll still make an effort to ensure every SCons file within the main repo uses it, but that should all be manageable manually.
The best point of comparison I can give is it's equivalent to the #!/usr/bin/env python shebang on the SCons files. While using a shebang in a non-executable context is technically invalid, it's to the end of giving the files proper syntax/hinting out of the gate; that is, it only affects IDE contexts. Likewise, we don't have any hard enforcement for adding #!/usr/bin/env python to the top of SCons files (though it's good practice & everyone does it anyway).