README.md

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

It's also possible to install both scipy and scipy-stubs together through the bundled scipy-typed package:

conda install conda-forge::scipy-typed

Packages overview

		Python packages
		scipy-stubs	scipy + scipy-stubs
PyPI	pip install {}	scipy-stubs	scipy-stubs[scipy]
conda-forge	conda install conda-forge::{}	scipy-stubs	scipy-typed

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.

There are no additional restrictions enforced by scipy-stubs on the numpy requirements. For scipy[-stubs] 1.14.* and 1.15.* that is numpy >= 1.23.5.

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.

Supported static type-checkers

1. basedpyright (recommended)
2. basedmypy
3. pyright
4. mypy (not recommended, see 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.

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.

Untyped

A small portion of the stubs uses the Untyped type (an alias of Any) as a "placeholder" or "to-do" annotation. In those cases static type-checkers won't do any type-checking, and won't bother you with errors or warnings, so you probably won't even notice it. The current goal of scipy-stubs is to replace all Untyped annotations with more meaningful ones.

At the moment, out of the 21 scipy.* subpackages, the only one that still has (some) Untyped annotations, is scipy.signal. See scipy-stubs#99 for an overview.

Contributing

There are many ways that you can help improve scipy-stubs, for example

• reporting issues, bugs, or other unexpected outcomes
• improving the .pyi stubs (see CONTRIBUTING.md)
• type-testing (see the README.md in scipy-stubs/tests for the specifics)
• write new documentation (usage examples, guides, tips & tricks, FAQ, etc.), or e.g. improve this README.md
• help spread the word on scipy-stubs, so that more can benefit from using it

AI generated Podcast

Typing in SciPy

SciPy.Type.Hints.mp4

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.