TYP: type annotations #135

crusaderky · 2025-03-21T15:35:56Z

Implement thorough static type annotations
Align type annotations conventions to array-api-compat (TYP: Type annotations overhaul, part 1 array-api-compat#257)
Add py.typed
Manually run mypy and fix most typing issues
Manually run isort (one-off)
Fix bug where iinfo and finfo would return a numpy dtype instead of a DType

Out of scope

Fix all mypy errors (some highlight material issues that deserve their own PRs)
Add mypy to CI
Make pyright happy
tests module

ev-br · 2025-03-21T15:43:36Z

Can ignore python 3.9, cf #129

crusaderky · 2025-03-21T15:59:38Z

array_api_strict/_creation_functions.py

+# Note: indexing was 'str' in <=2024.12
+def meshgrid(*arrays: Array, indexing: str = "xy") -> list[Array]:


data-apis/array-api#915

not sure if this is inconsequential enough that I should just go on and define it as Literal here?

array_api_strict/_data_type_functions.py

crusaderky · 2025-03-21T16:56:12Z

Can ignore python 3.9, cf #129

Unless you plan to merge #129 now, I can't ignore 3.9 as it would make all CI to fail.

crusaderky · 2025-03-21T17:00:38Z

CC @jorenham @NeilGirdhar

ev-br

Thanks for the PR Guido!

I went through up to _linalg.py before running out of steam for the week. In general it looks great, my main gripe is about annotations for python scalars:

several look like global search-and-replace : floordiv, __gt__ just do not accept complex
I'm -1 for changing bool | int | float into just float.

array_api_strict/_array_object.py

ev-br · 2025-03-21T16:27:16Z

array_api_strict/_array_object.py

@@ -184,7 +193,9 @@ def __array__(self, dtype: None | np.dtype[Any] = None, copy: None | bool = None
    # spec in places where it either deviates from or is more strict than
    # NumPy behavior

-    def _check_allowed_dtypes(self, other: bool | int | float | Array, dtype_category: str, op: str) -> Array:
+    def _check_allowed_dtypes(
+        self, other: Array | complex, dtype_category: str, op: str


ints, bools and floats are allowed. I get that a float is-a complex but nonetheless. As long as this is for a human reader more than for a linter, let's be more descriptive. Here and elsewhere.

As long as this is for a human reader more than for a linter

I think @jorenham is right that this has a lot of drawbacks. Once you get used to annotations, you know that complex subsumes all of those options. If you want to make things clear for novices, why not use a docstring?

Here's the point though, none of this is for a human reader that isn't pushing a PR to this repo, save for the public functions in _flags.py!

https://data-apis.org/array-api-strict/api.html

Sorry, no. If the tooling is not ready, we don't use it until it is. Please roll it back, here and in the -strict PR.

What do you mean by the "the tooling is not ready"? Python typing will probably never alter the definition of these basic types, right?

What do you mean by the "the tooling is not ready"? Python typing will probably never alter the definition of these basic types, right?

That's right.

array_api_strict/_creation_functions.py

array_api_strict/_dtypes.py

array_api_strict/_linalg.py

jorenham

Good stuff! I left a couple of suggestions; do with it what you want 👌🏻

array_api_strict/_array_object.py

jorenham · 2025-03-21T19:26:47Z

array_api_strict/_array_object.py

@@ -184,7 +193,9 @@ def __array__(self, dtype: None | np.dtype[Any] = None, copy: None | bool = None
    # spec in places where it either deviates from or is more strict than
    # NumPy behavior

-    def _check_allowed_dtypes(self, other: bool | int | float | Array, dtype_category: str, op: str) -> Array:
+    def _check_allowed_dtypes(
+        self, other: Array | complex, dtype_category: str, op: str


What do you mean by the "the tooling is not ready"? Python typing will probably never alter the definition of these basic types, right?

That's right.

array_api_strict/_array_object.py

array_api_strict/_sorting_functions.py

array_api_strict/_typing.py

array_api_strict/_utility_functions.py

array_api_strict/tests/test_validation.py

pyproject.toml

jorenham · 2025-03-21T20:45:07Z

I took the liberty of creating a label for static typing stuff _{and painted it black _{because that's how I prefer my coffee (and my metal)}}

Co-authored-by: Joren Hammudoglu <[email protected]>

ev-br

Let me record my -1 on bool | int |float until data-apis/array-api-compat#257 (comment) is done.

crusaderky · 2025-03-26T16:21:10Z

Let me record my -1 on bool | int |float until data-apis/array-api-compat#257 (comment) is done.

ev-br · 2025-03-26T16:40:00Z

To repeat, my only strong feelings are on

consistency of annotations and signatures with the Array API docs and stubs, and
int | bool | float,
in this order.

With these two items being there, I'm declaring my expertise on typing to run out, the typing itself being considered mostly harmless; I'm thus dismissing my request for changes and bow out. As long as my boundary conditions are not exceeded, I'm happy with whatever y'all converge on.

Request addressed.

crusaderky · 2025-03-26T16:46:01Z

This is ready for final review.

crusaderky · 2025-03-27T17:36:38Z

I believe there should not be any oustanding comments?

lucascolley · 2025-03-29T22:15:34Z

Trying to push things forward hat on:

It sounds like both @crusaderky and I would be happy to keep int | bool | float in for now given @ev-br's concern, with a view to eventually removing them once we have array-api-typing up and running and readable/documented aliases, which make sense appearing both in the 'real' annotations and on the spec pages.

Would merging @crusaderky's 2 PRs disrupt your work at data-apis/array-api-compat#288 @jorenham ?

consistency of annotations and signatures with the Array API docs and stubs, and

int | bool | float,
in this order.

I haven't read the entirety of all of these threads, but are there any outstanding concerns about consistency apart from the int | bool | float situation?

Opinion hat on:

For me, there is no significant consistency concern about int | bool | float, for reasons already stressed in this thread: these annotations are tool/developer facing, not user facing. I think it is fairly obvious to developers adopting the spec that the spec pages are the source of truth. Following SciPy's lead, we should distinguish between documented types (for docs readability) and the actual type annotations, keeping in mind that we can hope for these to converge somewhat with array-api-typing. In this sense some 'inconsistency' is actually desirable.

If the concern is that inconsistency between the spec saying int | float and an annotation in (say) array-api-strict saying float will confuse array-api-strict developers, I think this is best remedied in the relevant contributor guides, rather than holding up the typing experts from making the much-desired improvements.

crusaderky added 2 commits March 21, 2025 15:32

TYP: type annotations

73e998e

Python 3.9 fixes

d6ef302

crusaderky commented Mar 21, 2025

View reviewed changes

array_api_strict/_data_type_functions.py Show resolved Hide resolved

crusaderky commented Mar 21, 2025

View reviewed changes

array_api_strict/_data_type_functions.py Show resolved Hide resolved

self-review

44ebd51

crusaderky force-pushed the typing branch from d15fed8 to 44ebd51 Compare March 21, 2025 16:55

jorenham self-requested a review March 21, 2025 17:04

ev-br reviewed Mar 21, 2025

View reviewed changes

code review

b40974c

jorenham reviewed Mar 21, 2025

View reviewed changes

jorenham added the Static Typing label Mar 21, 2025

crusaderky and others added 4 commits March 21, 2025 21:11

Update array_api_strict/_array_object.py

e2c6d40

Co-authored-by: Joren Hammudoglu <[email protected]>

Apply suggestions from code review

6cd171b

Co-authored-by: Joren Hammudoglu <[email protected]>

fix

ddf6260

code review

6ad0d17

ev-br previously requested changes Mar 26, 2025

View reviewed changes

crusaderky added 3 commits March 26, 2025 16:20

fixes

4ea617b

normalize order

faca616

verbose Python scalar types

7effb68

crusaderky force-pushed the typing branch from 052dc93 to 7effb68 Compare March 26, 2025 16:20

crusaderky marked this pull request as ready for review March 26, 2025 16:47

crusaderky mentioned this pull request Mar 27, 2025

TYP: Type annotations overhaul, part 2 data-apis/array-api-compat#291

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

TYP: type annotations #135

TYP: type annotations #135

crusaderky commented Mar 21, 2025 •

edited

Loading

ev-br commented Mar 21, 2025

crusaderky Mar 21, 2025

crusaderky Mar 21, 2025

crusaderky commented Mar 21, 2025

crusaderky commented Mar 21, 2025

ev-br left a comment

ev-br Mar 21, 2025

NeilGirdhar Mar 21, 2025

crusaderky Mar 21, 2025

ev-br Mar 21, 2025

NeilGirdhar Mar 21, 2025 •

edited

Loading

jorenham Mar 21, 2025

jorenham left a comment

jorenham Mar 21, 2025

jorenham commented Mar 21, 2025

ev-br left a comment

crusaderky commented Mar 26, 2025

ev-br commented Mar 26, 2025 •

edited

Loading

crusaderky commented Mar 26, 2025

crusaderky commented Mar 27, 2025

lucascolley commented Mar 29, 2025 •

edited

Loading

		# Note: indexing was 'str' in <=2024.12
		def meshgrid(*arrays: Array, indexing: str = "xy") -> list[Array]:

TYP: type annotations #135

Are you sure you want to change the base?

TYP: type annotations #135

Conversation

crusaderky commented Mar 21, 2025 • edited Loading

Out of scope

ev-br commented Mar 21, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

crusaderky commented Mar 21, 2025

crusaderky commented Mar 21, 2025

ev-br left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

NeilGirdhar Mar 21, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jorenham left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jorenham commented Mar 21, 2025

ev-br left a comment

Choose a reason for hiding this comment

crusaderky commented Mar 26, 2025

ev-br commented Mar 26, 2025 • edited Loading

crusaderky commented Mar 26, 2025

crusaderky commented Mar 27, 2025

lucascolley commented Mar 29, 2025 • edited Loading

Trying to push things forward hat on:

Opinion hat on:

crusaderky commented Mar 21, 2025 •

edited

Loading

NeilGirdhar Mar 21, 2025 •

edited

Loading

ev-br commented Mar 26, 2025 •

edited

Loading

lucascolley commented Mar 29, 2025 •

edited

Loading