https://github.com/scipy/scipy-stubs
Typing Stubs for SciPy
https://github.com/scipy/scipy-stubs
python scipy stubs-only
Last synced: 17 days ago
JSON representation
Typing Stubs for SciPy
- Host: GitHub
- URL: https://github.com/scipy/scipy-stubs
- Owner: scipy
- License: bsd-3-clause
- Created: 2024-08-22T01:00:45.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2025-04-07T21:12:39.000Z (22 days ago)
- Last Synced: 2025-04-12T23:13:40.983Z (17 days ago)
- Topics: python, scipy, stubs-only
- Language: Python
- Homepage: https://scipy.org
- Size: 3.35 MB
- Stars: 43
- Watchers: 17
- Forks: 12
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
scipy-stubs
Precise type hints for all of SciPy.
______________________________________________________________________
## Highlights
- Works out-of-the-box
- all that's needed is to [install `scipy-stubs`](#installation)
- does not require a `mypy` plugin or other configuration
- available on [PyPI](https://pypi.org/project/scipy-stubs/) and [conda-forge](https://anaconda.org/conda-forge/scipy-stubs)
- 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](https://docs.scipy.org/doc/scipy/reference/index.html)
- also covers most of the private API
- Precise type-hinting of dtypes and [shape-types](https://github.com/numpy/numpy/issues/16544)
- 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`](https://github.com/KotlinIsland/basedmypy),
[`pyright`](https://github.com/DetachHead/basedpyright)/pylance and [`ruff`](https://github.com/astral-sh/ruff)
- ... even in the strict mode
- compatible with the [Python Typing Spec](https://typing.readthedocs.io/en/latest/spec/index.html)
- [SPEC 0](https://scientific-python.org/specs/spec-0000/) compliant
- Supports Python ≥ 3.10
- Supports NumPy ≥ 1.23.5
## Installation
The source code is currently hosted on GitHub at [github.com/scipy/scipy-stubs](https://github.com/scipy/scipy-stubs/).
Binary distributions are available at the [Python Package Index (PyPI)](https://pypi.org/project/scipy-stubs/) and on
[conda-forge](https://anaconda.org/conda-forge/scipy-stubs).
### Using pip (PyPI)
To install from the [PyPI](https://pypi.org/project/scipy-stubs/), run:
```bash
pip install scipy-stubs
```
In case you haven't installed `scipy` yet, both can be installed with:
```bash
pip install scipy-stubs[scipy]
```
### Using conda (conda-forge)
To install using Conda from the [conda-forge channel](https://anaconda.org/conda-forge/scipy-stubs), run:
```bash
conda install conda-forge::scipy-stubs
```
It's also possible to install both `scipy` and `scipy-stubs` together through the bundled
[`scipy-typed`](https://anaconda.org/conda-forge/scipy-typed) package:
```bash
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`](https://github.com/jorenham/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`](pyproject.toml).
## Supported static type-checkers
- [`basedpyright`](https://github.com/DetachHead/basedpyright)
- [`pyright`](https://pyright.readthedocs.io/en/latest/index.html)
- [`basedmypy`](https://github.com/KotlinIsland/basedmypy)
- [`mypy`](https://mypy.readthedocs.io/en/stable/index.html)
For validation and testing, `scipy-stubs` primarily uses [`basedmypy`](https://github.com/KotlinIsland/basedmypy) (a `mypy` fork)
and [`basedpyright`](https://github.com/DetachHead/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.
Note that this does not mean that all annotations are optimal, and some might even be incorrect. If you encounter this, it would
help a lot if you could open an issue or a PR for it.
## 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](https://github.com/scipy/scipy-stubs/blob/master/CONTRIBUTING.md))
- type-testing (see the `README.md` in [`scipy-stubs/tests`](https://github.com/scipy/scipy-stubs/tree/master/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