Skip to content

Include array shape in generated annotations - #132

Merged
lagru merged 5 commits into
scientific-python:mainfrom
lagru:shape-dtype-expansion
Nov 6, 2026
Merged

lagru merged 5 commits into
scientific-python:mainfrom
lagru:shape-dtype-expansion

Conversation

@lagru

@lagru lagru commented Nov 6, 2026 •

Copy link
Copy Markdown
Member

This bundles a few things that I should have probably committed separately while iterating on them:

  1. Closes Include shape of NumPy array #76. Shape information in doctypes is now translated into annotations. This even goes for shapes with optional dimensions – which use expansion like in the plugin example to create a union of arrays – one for each supported dimensionality. Shapes with "..." are treated as unbounded dimensionality and translated to tuple[Any, ...] like NumPy v2.5 suggests. Empty shapes are supported too.

  2. Dtype unions are now also expanded into a union of arrays each with one of the dtypes. This is because I'm not sure if np.dtype actually supports unions. I can't find examples of that in NumPy's repo. For now, expansion should be on the safe side.

  3. Closes ArrayLike limitations #125. Shape and dtype are now stripped from ArrayLikes which don't support them as their are a union that can't be subscribed. This means, ArrayLikes are a really generic broad type.

  4. Cleans up some issues with the grammar: the literal and subscriptions rules have some necessary overlap. The subscription rule should now win unless the expression contains an actual literal type.

Also some refactoring, and especially new stuff like expand_expression, Expr.{find_all|try_find_one|find_one} enable all this.

Release note

For maintainers and optionally contributors, please refer to changelist's README on how to document this PR for the release notes.

Experimental: Include shape information when translating doctypes
to annotations with `numpy.typing.NDArray`. This includes support
for shapes with optional dimensions which use expansion like in
the plugin example to create a union of arrays – one for each
supported rank. Shapes with "..." are treated as an unspecified
number of dimensions and are to `tuple[Any, ...]`. Empty shapes
are supported too.
{label="enhancement"}
Expand arrays whose dtype is a union of dtypes into a union of
arrays, one for each given dtype. This might be necessary if
`numpy.typing.dtype` does not support unions as arguments.
{label="fix"}
Strip shape and dtype from *ArrayLikes* when converting them
to an annotation since `numpy.typing.ArrayLike` doesn't support
adding that information.
{label="fix"}

lagru added 5 commits November 6, 2026 22:31
This bundles a few things that I should have probably committed
separately while iterating on them:

1. Shape information in doctypes is now translated into annotations.
This even goes for shapes with optional dimensions – which use expansion
like in the plugin example to create a union of arrays – one for each
supported dimensionality. Shapes with "..." are treated as unbounded
dimensionality and translated to `tuple[Any, ...]` like NumPy v2.5
suggests [1]. Empty shapes are supported too.

2. Dtype unions are now also expanded into a union of arrays each with
one of the dtypes. This is because I'm not sure if `np.dtype` actually
supports unions. I can't find examples of that in NumPy's repo. For now,
expansion should be on the safe side.

3. Shape and dtype are now stripped from *ArrayLikes* which don't
support them as their are a union that can't be subscribed [1]. This
means, *ArrayLikes* are a really generic broad type. Will address scientific-python#125.

Some refactoring, and especially new stuff like `expand_expression`,
`Expr.{find_all|try_find_one|find_one}` enable all this.

[1] https://numpy.org/doc/stable/reference/typing.html#api
@lagru lagru added bug Something isn't working enhancement New feature or functionality fix Addresses regressions & bugs and removed bug Something isn't working labels Nov 6, 2026
@lagru lagru added this to the v0.7 milestone Nov 6, 2026
@lagru
lagru marked this pull request as ready for review November 6, 2026 21:58
@lagru
lagru merged commit 90e7d6e into scientific-python:main Nov 6, 2026
9 checks passed
@lagru
lagru deleted the shape-dtype-expansion branch November 6, 2026 22:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or functionality fix Addresses regressions & bugs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ArrayLike limitations Include shape of NumPy array

1 participant