Add py.typed marker and gradual static typing

[Hermann-web]

Proposal

I'd like to contribute static type annotations to NeuroKit2, starting small and building up gradually. Before writing any code I wanted to check whether this is something maintainers would welcome, and if so, what approach fits best.

Proposed plan

1. PR 1 (infrastructure): add neurokit2/py.typed (PEP 561 marker, one empty file) so type checkers know the package intends to ship types, and wire up a checker in pyproject.toml + CI in permissive mode (no hard failures yet, just visibility).

2. PR 2 (proof of concept): annotate the stats/ submodule (~50 functions, no recent churn, mostly pure Python math). This gives a concrete example of what the annotations look like before committing to the full library.

3. Subsequent PRs: submodule by submodule, at whatever pace makes sense.

Checker choice

The two realistic options for a scientific Python library:

• mypy: most widespread in the NumPy/pandas/scipy ecosystem, battle-tested
• pyright: faster, stricter, what VS Code/Pylance uses under the hood; pandas recently switched to it

Given NeuroKit2 already uses the Astral stack (ruff, uv), pyright feels like a natural fit — but I'd go with whatever you prefer.

What I'm NOT proposing

• Rewriting any logic
• Touching complexity/ or other actively-developed submodules early on
• The initial CI step would be --ignore-missing-imports / basic mode so it doesn't block contributors

Happy to hear if there's a different approach you'd prefer, or if this isn't a priority right now.