Coding Guidelines

This document helps contributors match the expectations of code reviewers. It covers coding style and conventions.

Style

• Python code:

  • follows PEP 8

  • use Flake8. Run flake8 numba.

• C code doesn’t have a well-defined coding style (PEP 7 would be nice).

• Limit to 80 columns for maximum readability with all existing tools (such as code review UIs).

Typing annotations

• Numba uses Pyrefly to verify typing annotations in the CI. Run pyrefly check.

  • Only a subset of files are being checked (see pyrefly.toml).

  • Only in exceptional circumstances should type: ignore comments be used.

• Mypy’s stubtest tool is used to verify that Numba’s .pyi type stubs are consistent with the runtime implementation. Run python maint/stubtest.py (dependencies in maint/stubtest/requirements_stubtest.txt).

• Most of Numba code base does not use type hints. We welcome incremental PRs for gradually adding type hints.

• New features: use type hints even if the file isn’t in the pyrefly checklist.

• To add a file to the checklist: add it to project-includes in pyrefly.toml.

Python’s typing vs numba.core.typing

• typing name clash: Numba has its own typing module and types (e.g. Dict, Literal) that conflict with Python’s typing.

• Two options:

  • prefix Python typing imports with pt (e.g. from typing import Dict as ptDict).

  • or import typing as pt.

Runtime type checking

Most code is unannotated, so runtime type checking complements pyrefly.

• The test suite uses typeguard to validate type annotations at runtime.

• To enable: use runtests.py as the test runner with NUMBA_USE_TYPEGUARD=1:

  $ NUMBA_USE_TYPEGUARD=1 python runtests.py numba.tests
  

Discouraged APIs

The following APIs are being phased out. Wholesale removal is too disruptive, so the goal is to stop adding new uses and migrate existing ones over time.

Avoid @lower*

Avoid the low-level lower_builtin, lower_getattr, lower_setattr, lower_getattr_generic, lower_setattr_generic, lower_cast, and lower_constant decorators from numba/core/imputils.py. Prefer the high-level extension API instead: @overload, @overload_method, or @overload_attribute from numba.core.extending.

Avoid compile_internal

Avoid BaseContext.compile_internal from numba/core/base.py. Use resolve_value_type, get_call_type, and get_function instead:

disp_type = context.typing_context.resolve_value_type(func)
sig = disp_type.get_call_type(context.typing_context, arg_types, {})
call = context.get_function(disp_type, sig)
result = call(builder, args)

Avoid @njit

New code should use numba.jit instead of the legacy API numba.njit.