Explainer on what is supported

Open
#808 8 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
python
Domain
documentation

Research direction

No files or tests are named in the issue. Start by reviewing the existing NumPy typing documentation and the two mypy examples, then determine which behaviors and limitations should be documented. Done means a clear explanation or feature list covering supported typing behavior and the rank-reduction case.

Written by the indexing model from the issue text.

Description

topic: documentation
Issue with current documentation:

Not necessarily related to numtype but NumPy typing in general. I'm a bit confused as to what is expected to work in user code and what isn't. Is there some documentation which explains this? Perhaps a page or simple list of features would help elucidate this for users.

As a concrete example - I'd like a type checker to be able to pick up this example related to reducing rank of the array. This should fail, but currently passes with mypy v1.19.1 NumPy v2.4.0 Python 3.14. Is this sort of thing even possible without language changes or runtime typing? Is support for this on the horizon?

from typing import NewType
from numpy import ndarray
import numpy as np

A = NewType("A", int)
B = NewType("B", int)
C = NewType("C", int)
type U8 = np.dtype[np.uint8]

# Should fail - currently pass. Actual returned type is `ndarray[tuple[B], U8]`
def f1(a: ndarray[tuple[A, B, C], U8]) -> ndarray[tuple[A, B], U8]:
    return a[:, 2, :]

rng = np.random.default_rng(0)
a: ndarray[tuple[A, B, C], U8] = rng.integers(0, 100, size=(10, 20, 30), dtype=np.uint8)
print(f1(a).shape)

By contrast this correctly fails with mypy

# Should fail - correctly fails
# error: Incompatible return value type (got "ndarray[tuple[A, B, C], dtype[unsignedinteger[_8Bit]]]", expected "ndarray[tuple[A, C, B], dtype[unsignedinteger[_8Bit]]]")  [return-value]
def f2(a: ndarray[tuple[A, B, C], U8]) -> ndarray[tuple[A, C, B], U8]:
    return a + 2

a: ndarray[tuple[A, B, C], U8] = rng.integers(0, 100, size=(10, 20, 30), dtype=np.uint8)
print(f2(a).shape)
Idea or request for content:

No response

Dominant language
Python
Stars
79
Forks
8
No merged PRs in 30d

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from numpy/numtype

All issues in numpy/numtype

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.