Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jorenham/scipy-stubs

Typing Stubs for SciPy
https://github.com/jorenham/scipy-stubs

basedmypy basedpyright data-science mypy pep484 pep561 pyright python python-stubs python-typing python3 scipy stubs type-stubs

Last synced: 4 days ago
JSON representation

Typing Stubs for SciPy

Host: GitHub
URL: https://github.com/jorenham/scipy-stubs
Owner: jorenham
License: bsd-3-clause
Created: 2024-08-22T01:00:45.000Z (5 months ago)
Default Branch: master
Last Pushed: 2025-01-14T21:47:34.000Z (5 days ago)
Last Synced: 2025-01-14T22:39:40.080Z (4 days ago)
Topics: basedmypy, basedpyright, data-science, mypy, pep484, pep561, pyright, python, python-stubs, python-typing, python3, scipy, stubs, type-stubs
Language: Python
Homepage: https://pypi.org/project/scipy-stubs/
Size: 3.12 MB
Stars: 29
Watchers: 1
Forks: 8
Open Issues: 16
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md

Awesome Lists containing this project

awesome-python-typing - scipy-stubs - Stubs for [SciPy](https://github.com/scipy/scipy). (Stub packages)
trackawesomelist - scipy-stubs (⭐2) - Stubs for [SciPy (⭐13k)](https://github.com/scipy/scipy). (Recently Updated / [Sep 15, 2024](/content/2024/09/15/README.md))

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/jorenham/scipy-stubs](https://github.com/jorenham/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

1. [`basedpyright`](https://github.com/DetachHead/basedpyright) (recommended)

1. [`basedmypy`](https://github.com/KotlinIsland/basedmypy)

1. [`pyright`](https://pyright.readthedocs.io/en/latest/index.html)

1. [`mypy`](https://mypy.readthedocs.io/en/stable/index.html) (not recommended, see

   [mypy_issues](https://github.com/erictraut/mypy_issues))

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/jorenham/scipy-stubs/blob/master/CONTRIBUTING.md))

- type-testing (see the `README.md` in [`scipy-stubs/tests`](https://github.com/jorenham/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

## AI generated Podcast

### Typing in SciPy

## See also

- [scipy/scipy#21614](https://github.com/scipy/scipy/issues/21614): On why `scipy-stubs` is a separate package, and not part of

  `scipy` (yet).

- [microsoft/python-type-stubs#321](https://github.com/microsoft/python-type-stubs/pull/321): The removal of Microsoft's

  `scipy-stubs` — that used to be bundled with Pylance — in favor of `scipy-stubs`.

- [`optype`](https://github.com/jorenham/optype): The fundamental typing package that made `scipy-stubs` possible.

- [`basedpyright`](https://github.com/detachhead/basedpyright): The recommended type-checker to use with `scipy-stubs`.

- [`basedmypy`](https://github.com/KotlinIsland/basedmypy): A [less-broken](https://github.com/erictraut/mypy_issues) `mypy` fork,

  with a bunch of cool extra features.