scipy-stubs

Precise type hints for all of SciPy.

Highlights

• Works out-of-the-box
  • all that's needed is to install scipy-stubs
  • does not require a mypy plugin or other configuration
  • available on PyPI and conda-forge
• Improves IDE suggestions and autocompletion
  • ... even if you don't use static typing in your code
  • no additional plugins required
• 0% runtime overhead
  • not even a single import is required
• 100% coverage of the public SciPy API
  • also covers most of the private API
• Precise type-hinting of dtypes and shape-types
  • works with all "array-likes" and "dtype-likes"
  • many of the functions that return an array are shape-typed
  • shape-typing is optional: all functions still accept arrays with unknown shape-type
• Type-checker agnostic
  • works with at least mypy, pyright/pylance and ruff
  • ... even in the strict mode
  • compatible with the Python Typing Spec
• SPEC 0 compliant
  • Supports Python ≥ 3.10
  • Supports NumPy ≥ 1.23.5

Installation

The source code is currently hosted on GitHub at github.com/jorenham/scipy-stubs.

Binary distributions are available at the Python Package Index (PyPI) and on conda-forge.

Using pip (PyPI)

To install from the PyPI, run:

pip install scipy-stubs

In case you haven't installed scipy yet, both can be installed with:

pip install scipy-stubs[scipy]

Using conda (conda-forge)

To install using Conda from the conda-forge channel, run:

conda install conda-forge::scipy-stubs

Supported static type-checkers

1. basedpyright (recommended)
2. basedmypy
3. pyright
4. mypy (not recommended, see erictraut/mypy_issues)

For validation and testing, scipy-stubs primarily uses basedmypy (a mypy fork) and basedpyright (a pyright fork). They are in generally stricter than mypy and pyright, so you can assume compatibility with mypy and pyright as well. But if you find that this isn't the case, then don't hesitate to open an issue or submit a pull request.

Versioning and requirements

The versioning scheme of scipy-stubs includes the compatible scipy version as {scipy_version}.{stubs_version}. Even though scipy-stubs doesn't enforce an upper bound on the scipy version, later scipy versions aren't guaranteed to be fully compatible.

The supported range of numpy versions are specified in SPEC 0, which scipy-stubs aims to follow as close as feasible.

Currently, scipy-stubs has one required dependency: optype. This is essential for scipy-stubs to work properly, as it relies heavily on it for annotating (shaped) array-likes, scalar-likes, shape-typing in general, and much more. At the moment, scipy-stubs requires the latest version optype.

The exact version requirements are specified in the pyproject.toml.

scipy coverage

The entire public API of scipy is fully annotated and verifiably valid. For the most part, this can also be said about scipy's private API and other internal machinery.

However, a small portion uses Untyped (an alias of Any) as "placeholder annotations". In those cases static type-checkers won't do any type-checking, and won't bother you with errors or warnings.

The following table shows the (subjective) proportion of scipy-stubs that is(n't) annotated with Untyped, ranging from 🌑 (100% Untyped) to 🌕 (0% Untyped).

Currently, only scipy.signal contains Untyped annotations; all other submodules have complete typing coverage.

Podcast (AI generated)

See also

• scipy/scipy#21614: On why scipy-stubs is a separate package, and not part of scipy (yet).
• microsoft/python-type-stubs#321: The removal of Microsoft's scipy-stubs — that used to be bundled with Pylance — in favor of scipy-stubs.
• optype: The fundamental typing package that made scipy-stubs possible.
• basedpyright: The recommended type-checker to use with scipy-stubs.
• basedmypy: A less-broken mypy fork, with a bunch of cool extra features.