pyright --verifytypes with npt.NDArray reveals Type of parameter "dtype" is partially unknown Parameter type is "DTypeLike"

[MarcoGorelli]

Describe the bug

If I have a codebase which uses npt.NDArray, then pyright --verifytypes reported low coverage because numpy types are partially unknown

Is there some other setting I should be running --verifytypes on NumPy with?

Code or Screenshots

Here's a complete minimal repro:

I have a directory with this structure:

.
├── foo
│   ├── __init__.py
│   └── py.typed
└── pyproject.toml

File contents:

foo/__init__.py

from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    import numpy.typing as npt
    import numpy as np

def func(a: npt.NDArray[np.float64]) -> None:
    return None

pyproject.toml;

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "foo"
version = "0.1.0"
requires-python = ">=3.9"

Then, I do:

uv venv
. .venv/bin/activate
uv pip install -U numpy pyright

Finally:

pyright --verifytypes foo

reveals:

``` Module name: "foo" Package directory: "/home/marcogorelli/tmp-repo/foo" Module directory: "/home/marcogorelli/tmp-repo/foo" Path of py.typed file: "/home/marcogorelli/tmp-repo/foo/py.typed"

Public modules: 1
foo

Symbols used in public interface:
foo.func
/home/marcogorelli/tmp-repo/foo/init.py:9:5 - error: Type of parameter "a" is partially unknown
  Parameter type is "NDArray[float64]"
numpy.ndarray.new
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/numpy/init.pyi:2060:9 - error: Type of parameter "dtype" is partially unknown
  Parameter type is "DTypeLike"
numpy.dtype.new
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/numpy/init.pyi:1531:9 - error: Type of parameter "dtype" is partially unknown
  Parameter type is "type[slice[Any, Any, Any]] | type[Decimal] | type[Fraction] | type[UUID] | type[date] | type[time] | type[timedelta] | type[tzinfo] | type[tuple[Any, ...]] | type[list[Any]] | type[set[Any]] | type[frozenset[Any]] | type[dict[Any, Any]] | type[object_]"
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/numpy/init.pyi:1531:9 - error: Type of parameter "dtype" is partially unknown
  Parameter type is "type[complex] | type[bytes] | type[str] | type[memoryview[int]] | type[slice[Any, Any, Any]] | type[Decimal] | type[Fraction] | type[UUID] | type[date] | type[time] | type[timedelta] | type[tzinfo] | type[tuple[Any, ...]] | type[list[Any]] | type[set[Any]] | type[frozenset[Any]] | type[dict[Any, Any]]"
decimal.Decimal.ge
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/decimal.pyi:82:9 - error: Type of parameter "value" is partially unknown
  Parameter type is "_ComparableNum"
numbers.Rational
error: Type of base class "numbers.Real" is partially unknown
numbers.Real
error: Type of base class "numbers.Complex" is partially unknown
numbers.Real.divmod
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/numbers.pyi:124:9 - error: Type annotation for parameter "other" is missing
numbers.Real.rdivmod
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/numbers.pyi:125:9 - error: Type annotation for parameter "other" is missing
numbers.Real.floordiv
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/numbers.pyi:127:9 - error: Type annotation for parameter "other" is missing
numbers.Real.rfloordiv
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/numbers.pyi:129:9 - error: Type annotation for parameter "other" is missing
numbers.Real.mod
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/numbers.pyi:131:9 - error: Type annotation for parameter "other" is missing
numbers.Real.rmod
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/numbers.pyi:133:9 - error: Type annotation for parameter "other" is missing
numbers.Real.lt
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/numbers.pyi:135:9 - error: Type annotation for parameter "other" is missing
numbers.Real.le
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/numbers.pyi:137:9 - error: Type annotation for parameter "other" is missing
numbers.Complex.add
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/numbers.pyi:78:9 - error: Type annotation for parameter "other" is missing
numbers.Complex.radd
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/numbers.pyi:80:9 - error: Type annotation for parameter "other" is missing
numbers.Complex.sub
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/numbers.pyi:85:9 - error: Type annotation for parameter "other" is missing
numbers.Complex.rsub
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/numbers.pyi:86:9 - error: Type annotation for parameter "other" is missing
numbers.Complex.mul
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/numbers.pyi:88:9 - error: Type annotation for parameter "other" is missing
numbers.Complex.rmul
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/numbers.pyi:90:9 - error: Type annotation for parameter "other" is missing
numbers.Complex.truediv
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/numbers.pyi:92:9 - error: Type annotation for parameter "other" is missing
numbers.Complex.rtruediv
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/numbers.pyi:94:9 - error: Type annotation for parameter "other" is missing
numbers.Complex.pow
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/numbers.pyi:96:9 - error: Type annotation for parameter "exponent" is missing
numbers.Complex.rpow
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/numbers.pyi:98:9 - error: Type annotation for parameter "base" is missing
decimal.Decimal.gt
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/decimal.pyi:83:9 - error: Type of parameter "value" is partially unknown
  Parameter type is "_ComparableNum"
decimal.Decimal.le
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/decimal.pyi:84:9 - error: Type of parameter "value" is partially unknown
  Parameter type is "_ComparableNum"
decimal.Decimal.lt
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/decimal.pyi:85:9 - error: Type of parameter "value" is partially unknown
  Parameter type is "_ComparableNum"
fractions.Fraction
error: Type of base class "numbers.Rational" is partially unknown
fractions.Fraction.new
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/fractions.pyi:30:9 - error: Type of parameter "numerator" is partially unknown
  Parameter type is "int | Rational"
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/fractions.pyi:30:9 - error: Type of parameter "denominator" is partially unknown
  Parameter type is "int | Rational | None"
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/fractions.pyi:30:9 - error: Type of parameter "numerator" is partially unknown
  Parameter type is "float | Decimal | str"
fractions.Fraction.from_decimal
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/fractions.pyi:39:9 - error: Type of parameter "dec" is partially unknown
  Parameter type is "Decimal"
fractions.Fraction.lt
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/fractions.pyi:143:9 - error: Type of parameter "b" is partially unknown
  Parameter type is "_ComparableNum"
fractions.Fraction.gt
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/fractions.pyi:144:9 - error: Type of parameter "b" is partially unknown
  Parameter type is "_ComparableNum"
fractions.Fraction.le
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/fractions.pyi:145:9 - error: Type of parameter "b" is partially unknown
  Parameter type is "_ComparableNum"
fractions.Fraction.ge
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/pyright/dist/dist/typeshed-fallback/stdlib/fractions.pyi:146:9 - error: Type of parameter "b" is partially unknown
  Parameter type is "_ComparableNum"
numpy.ndarray.setfield
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/numpy/init.pyi:2368:9 - error: Type of parameter "dtype" is partially unknown
  Parameter type is "DTypeLike"
numpy.ndarray.trace
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/numpy/init.pyi:2394:9 - error: Type of parameter "dtype" is partially unknown
  Parameter type is "DTypeLike"
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/numpy/init.pyi:2394:9 - error: Type of parameter "dtype" is partially unknown
  Parameter type is "DTypeLike"
numpy.ndarray.astype
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/numpy/init.pyi:2529:9 - error: Type of parameter "dtype" is partially unknown
  Parameter type is "_DTypeLike[_SCT@astype]"
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/numpy/init.pyi:2529:9 - error: Type of parameter "dtype" is partially unknown
  Parameter type is "DTypeLike"
numpy.ndarray.view
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/numpy/init.pyi:2547:9 - error: Type of parameter "dtype" is partially unknown
  Parameter type is "_DTypeLike[_SCT@view]"
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/numpy/init.pyi:2547:9 - error: Type of parameter "dtype" is partially unknown
  Parameter type is "DTypeLike"
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/numpy/init.pyi:2547:9 - error: Type of parameter "dtype" is partially unknown
  Parameter type is "DTypeLike"
numpy.ndarray.getfield
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/numpy/init.pyi:2560:9 - error: Type of parameter "dtype" is partially unknown
  Parameter type is "_DTypeLike[_SCT@getfield]"
/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/numpy/init.pyi:2560:9 - error: Type of parameter "dtype" is partially unknown
  Parameter type is "DTypeLike"

Symbols exported by "foo": 1
With known type: 0
With ambiguous type: 0
With unknown type: 1

Other symbols referenced but not exported by "foo": 1249
With known type: 1207
With ambiguous type: 0
With unknown type: 42

Symbols without documentation:
Functions without docstring: 258
Functions without default param: 47
Classes without docstring: 134

Type completeness score: 0%

Completed in 1.086sec

</details>
which ends with

/home/marcogorelli/tmp-repo/.venv/lib/python3.12/site-packages/numpy/init.pyi:2560:9 - error: Type of parameter "dtype" is partially unknown
  Parameter type is "DTypeLike"

**VS Code extension or command-line**
Are you running pyright as a VS Code extension, a language server in another editor, integrated into Pylance, or the command-line tool? Which version?

pyright 1.1.394, command line

[erictraut]

The issue here is that numpy is importing the type decimal.Decimal from the typeshed stubs, but this type is defined in an incomplete manner. In particular, its definition uses the numbers.Rational type, which derives from numbers.Real which has multiple methods that are missing parameter annotations. Therefore, these types introduce an Unknown. See here.

I think the ideal solution here is to improve the typeshed type annotations in the numbers typeshed stub. At a minimum, these parameters should be annotated with the Incomplete symbol, which is an alias to Any used elsewhere in the typeshed stubs. If you're interested in helping to improve the typeshed stubs, the maintainers would probably accept a contribution in this area.

In the meantime, you can use pyright's --verifytypes option in conjunction with --ignoreexternal. This tells pyright to ignore Unknown or partially-unknown types that are imported from another external library.

[MarcoGorelli]

nice, thank you so much!