CONTRIBUTING.md

NumType's Contributing guidelines

Welcome to the NumPy community! We're excited to have you here. Whether you're new to open source or experienced, your contributions help us grow.

Pull requests (PRs) are always welcome, but making a PR is just the start. Please respond to comments and requests for changes to help move the process forward. Please follow our Code of Conduct, which applies to all interactions, including issues and PRs.

For more, please read https://www.numpy.org/devdocs/dev/index.html

Thank you for contributing, and happy coding!

---

Setting up the environment

Ensure you have uv installed. Now you can install the project with the dev dependencies:

uv sync

You can also install it with a specific Python version, e.g. 3.10, as

uv sync --python 3.10

Linting and formatting with ruff

NumType uses ruff for linting and formatting, and is automatically installed as a local development dependency. This way, you can lint all .py and .pyi files with:

$ uv run ruff check
All checks passed!

Or, to format your code, run

$ uv run ruff format
351 files left unchanged

Be sure to do this before you open a pull request — the CI will complain if you don't.

For more details, see https://docs.astral.sh/ruff/.

Type-checking and Testing

To validate that the annotations are correct and run tests, we use several tools: basedpyright, mypy, and pytest. All are included as development dependency-group, so that uv sync will install them by default.

basedpyright

You can run basedpyright on the entire project using:

$ uv run basedpyright
0 errors, 0 warnings, 0 notes

Since this can take somewhere between 20 to 50 seconds to run, you may want to limit this to a subdirectory or a specific file that you're working on.

See https://docs.basedpyright.com/ for IDE integration and other info.

mypy

Mypy is used for type-checking the codebase and the type-tests. It takes more effort to run it on the codebase than basedpyright. This is primarily a consequence of mypy's inconsequent prioritization of the stubs bundled with NumPy over the numpy-stubs within a local development environment. To get around this, you can delete all *.pyi from your local numpy installation directory by running uv tool/unstub.py.

General Type Checking

To run mypy generally (excluding the main numpy dependency group):

uv run --no-editable --no-group=numpy mypy .

Cache Issues

In rare cases, the cache (.mypy_cache in the numtype root) can get corrupted, leading to incorrect results. If CI output differs from your local output, delete this directory.

The documentation can be found at https://mypy.readthedocs.io/, and issues can be reported at https://github.com/python/mypy.

pytest

Pytest runs runtime tests located in src/*/@test. It works out-of-the-box:

uv run pytest [OPTIONS]

For available options, see the pytest documentation.

Lefthook

Lefthook is a modern Git hooks manager, which automatically lints and formats your code before you committing it. It will also keep your uv environment up-to-date with the lockfile when you git pull.

To install it as a uv tool, run

uv tool install lefthook --upgrade

To set it up, navigate to the root of the numtype repo, and run

lefthook install

or

uvx lefthook install

Now let's see it all works:

$ lefthook validate
All good

See https://lefthook.dev/ for more information.

Tox

You can run the linters, type-checkers, runtime tests, and stubtest, all at once through a single tox command.

It's easiest to install it as a uv tool:

uv tool install tox --with tox-uv --upgrade

To run it, navigate to the root of the cloned numtype directory, and run

tox p

or alternatively,

uvx tox p

If all is good, then you should see something like this appear:

ruff: OK ✔ in 0.05 seconds
pytest: OK ✔ in 0.34 seconds
3.11: OK ✔ in 20.44 seconds
3.10: OK ✔ in 21.53 seconds
3.12: OK ✔ in 22.32 seconds
3.13: OK ✔ in 26.41 seconds
basedpyright: OK ✔ in 27.33 seconds
  ruff: OK (0.05=setup[0.03]+cmd[0.01,0.01] seconds)
  pytest: OK (0.34=setup[0.02]+cmd[0.32] seconds)
  basedpyright: OK (27.33=setup[0.02]+cmd[27.31] seconds)
  mypy: OK (36.39=setup[0.02]+cmd[36.37] seconds)
  3.10: OK (21.53=setup[0.43]+cmd[21.10] seconds)
  3.11: OK (20.44=setup[0.42]+cmd[20.01] seconds)
  3.12: OK (22.32=setup[0.44]+cmd[21.88] seconds)
  3.13: OK (26.41=setup[0.48]+cmd[25.93] seconds)
  congratulations :) (36.44 seconds)

Tox installs everything in isolated environments, so you don't have to worry about your local or global pip or uv environments.

See https://tox.wiki/en/stable/ for more information.

Documentation

The documentation lives in docs/, the README.md, and CONTRIBUTING.md. Please read it carefully before proposing any changes. Ensure that the markdown is formatted correctly with markdownlint.

Previewing Documentation Site

NumType uses MkDocs for documentation static site generation. To preview the documentation site locally:

uv run mkdocs serve

This will start a local server at http://127.0.0.1:8000/numtype/ where you can preview your changes. The server automatically refreshes when you make changes to the documentation files.

Development Tools

NumType provides several development tools to help with development.

For detailed usage of each tool, please refer to the README.md in the tool directory or the docstrings within each tool.

Commit message style

For the most part, commit messages in NumType should follow NumPy's guidelines for writing commit messages. The main difference is that we don't use the prefix acronyms (e.g. TYP). Instead, we use Gitmoji as a modern alternative. Using it gitmoji is not a hard requirement, just a colorful recommendation. For VSCode users it's most convenient to use the gitmoji-vscode extension.

Code style

For .py files, NumType follows the black style, and the .pyi stubs follow the official style guide for stubs. Both .py and .pyi are linted and formatted using ruff, which is one of the development dependencies.