improve `CONTRIBUTING.md`

[jorenham]

• Code style: https://typing.readthedocs.io/en/latest/guides/writing_stubs.html#style-guide
• Stub-writing tips & tricks:
  • scipy._typing
  • numpy.typing vs optype.numpy
  • how to @overload on specific positional-or-keyword parameters
    (see e.g. signal.windows: Add type stubs for _windows.pyi. #153 (comment))

[vincent-teh]

Hi there. I was writing Scipy code for my uni project last week, only to realize that the current official Scipy does not have a proper static typing system, leading to my VSCode IntelliJ being unable to work with return value properly. While scrolling through Scipy's issue page, I stumbled across your project and I would like to contribute. However, due to my inexperience, I would like to first ask regarding the type-testing file:

How to contribute, e.g.
reporting bugs
writing type-tests

How could I run the existing file, since the testing file itself is also a stub file, pyi, and there aren't many resources regarding it. Pardon if the question is quite basic :).

[jorenham]

Pardon if the question is quite basic :).

That's no problem at all; typing in Python is very confusing, and the documentation isn't really beginner friendly.

---

How could I run the existing file, since the testing file itself is also a stub file, pyi, and there aren't many resources regarding it.

These .pyi "stub" files are only read by static type-checkers. So at runtime, these are simply ignored. This means that .pyi stubs aren't something that can "run" like .py scripts.

However, the typical workflow for stubs, isn't all that different from "regular" runtime project. The main difference is that instead of running the unit-tests with e.g. pytest, you run stubtest (part of mypy) instead. That will verify that your {some_module}.pyi annotations are compatible with the {some_module}.py implementation.

We also use other tools in scipy-stubs, such as ruff, basedpyright and mypy, to make sure that the typing is correct.
See https://github.com/scipy/scipy-stubs/blob/master/CONTRIBUTING.md#your-first-code-contribution on how you can use tox to run all of these locally.

When you submit a PR, all these tools will automatically check you code (with github actions), which can be seen as something like a safety net. But since that takes a while to run, it's easier to run e.g. poe tox locally.

The "type-test" I mentioned are quite limited at the moment (https://github.com/scipy/scipy-stubs/tree/master/tests/typetests), so adding more of them would be very helpful! Their purpose is to sketch a semi-realistic usage scenario, and verify with assert_type that the inferred types are what we want it to be.
Like I mentioned before, these tests aren't "run" with e,g, pytest. And unlike the actual stubs in scipy-stubs/, stubtest also isn't ran on them. Instead, they are (only) checked with the static type-checkers (basedpyright and basedmypy).
So of you prefer, you could also write them as .py scripts; just keep in mind that they won't actually be executed.