TYP: Type annotations, part 4 #313

crusaderky · 2025-04-18T13:48:26Z

Follow-up to #288
Get mypy mostly green everywhere except torch.

Copilot

Pull Request Overview

This pull request updates and standardizes type annotations throughout the array‑API‑compat codebase, ensuring that union types, keyword arguments, and collection type hints conform to the latest Python syntax and best practices.

Changes include replacing deprecated type imports, updating union syntax (using the “|” operator), and adding explicit types for **kwargs across multiple modules.
Several backend-specific modules (torch, numpy, dask, cupy, and common) now consistently annotate parameters and return types.

Reviewed Changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
array_api_compat/torch/fft.py	Updated import and kwargs annotation for FFT functions.
array_api_compat/torch/_aliases.py	Refined type annotations for promotion and result functions.
array_api_compat/numpy/*	Standardized type hints and error messages in linalg, _typing, _info.
array_api_compat/dask/array/*	Applied uniform type annotations and minor updates in error texts.
array_api_compat/cupy/*	Updated type annotations and internal alias handling.
array_api_compat/common/*	Adjusted typing in helper functions and internal modules.

Comments suppressed due to low confidence (1)

array_api_compat/dask/array/linalg.py:56

Typo in the error message: 'full_matrics' should be corrected to 'full_matrices'.

raise ValueError("full_matrics=True is not supported by dask.")

crusaderky · 2025-04-18T13:51:23Z

array_api_compat/common/_helpers.py


    # TODO: Account for other backends.
    return isinstance(x, sparse.SparseArray)


-def is_array_api_obj(x: object) -> TypeIs[_ArrayApiObj]:  # pyright: ignore[reportUnknownParameterType]
+def is_array_api_obj(x: object) -> TypeGuard[_ArrayApiObj]:


Given the current definition of _ArrayApiObj, TypeIs would cause downstream failures for all unknown array api compliant libraries.

Doesn't SupportsArrayNamespace cover all downstream array types?

crusaderky · 2025-04-18T13:55:54Z

array_api_compat/common/_typing.py

@@ -70,72 +69,11 @@ def shape(self, /) -> _T_co: ...
 DTypeKind: TypeAlias = _DTypeKind | tuple[_DTypeKind, ...]


-# `__array_namespace_info__.dtypes(kind="bool")`


holy overengineering Batman!

I was planning on making these generic on their dtype-types. Then, when combined with the array-api-namespace protocol, it becomes possible to statically type the individual dtypes of any array-api library. I don't see any other way to make that happen.

crusaderky · 2025-04-18T13:58:47Z

array_api_compat/numpy/__init__.py

-    from numpy import _CopyMode  # noqa: F401
-except ImportError:
-    pass
+from .linalg import matrix_transpose, vecdot  # type: ignore[no-redef] # noqa: F401


reverts regression from #288

what was the issue?

array_api_compat/numpy/_aliases.py

crusaderky · 2025-04-18T14:10:14Z

array_api_compat/cupy/_aliases.py

-    **kwargs,
+    dtype: DType | None = None,
+    device: Device | None = None,
+    copy: py_bool | None = _copy_default,


This is plain wrong and requires a dedicated follow-up

jorenham

Many (if not most) of the changes here revert work that I've done in #288. Why didn't you address those while it was still open? Then I could've explained my reasons for it, which would have saved us both a lot time.

Seeing large portions of my work being deleted with comments like "holy overengineering Batman!" is pretty frustrating, to say the least. Because this way you're literally wasting the time and effort I've put into it, without even knowing why I made those decisions.

jorenham · 2025-04-19T20:16:27Z

array_api_compat/common/_aliases.py

@@ -720,7 +722,7 @@ def iinfo(type_: DType | Array, /, xp: Namespace) -> Any:
    "finfo",
    "iinfo",
 ]
-_all_ignore = ["inspect", "array_namespace", "NamedTuple"]
+_all_ignore = ["is_cupy_namespace", "inspect", "array_namespace", "NamedTuple"]


Now that we have the __dir__ functions, are these _all_ignore's still needed?

jorenham · 2025-04-19T20:30:46Z

array_api_compat/common/_aliases.py

-    def _isscalar(a: object) -> TypeIs[int | float | None]:
-        return isinstance(a, (int, float, type(None)))
+    def _isscalar(a: object) -> TypeIs[float | None]:
+        return isinstance(a, int | float | NoneType)


With

Suggested change

return isinstance(a, int | float | NoneType)

return a is None or isinstance(a, int | float)

we avoid the types import _{while simultaneously accentuating the violent dissonance between the Python runtime and its type-system, given that the sole purpose of a type-system is to accurately describe the runtime behavior...}

jorenham · 2025-04-19T20:35:55Z

array_api_compat/common/_helpers.py

    )

 _API_VERSIONS_OLD: Final = frozenset({"2021.12", "2022.12", "2023.12"})
 _API_VERSIONS: Final = _API_VERSIONS_OLD | frozenset({"2024.12"})


-def _is_jax_zero_gradient_array(x: object) -> TypeGuard[_ZeroGradientArray]:
+def _is_jax_zero_gradient_array(x: object) -> TypeIs[_ZeroGradientArray]:


The TypeGuard was intentional. Because even if x is a _zeroGradientArray, and therefore a npt.NDArray[np.void], the function might still return False, in which case the TypeIs would narrow x to be not npt.NDArray[np.void], whereas a TypeGuard wouldn't.

So it's better to revert this change (and the one below here)

jorenham · 2025-04-19T20:37:16Z

array_api_compat/common/_helpers.py


    # TODO: Account for other backends.
    return isinstance(x, sparse.SparseArray)


-def is_array_api_obj(x: object) -> TypeIs[_ArrayApiObj]:  # pyright: ignore[reportUnknownParameterType]
+def is_array_api_obj(x: object) -> TypeGuard[_ArrayApiObj]:


Doesn't SupportsArrayNamespace cover all downstream array types?

jorenham · 2025-04-19T20:38:42Z

array_api_compat/common/_helpers.py

            namespaces.add(jnp)
        elif is_pydata_sparse_array(x):
            if use_compat is True:
                _check_api_version(api_version)
                raise ValueError("`sparse` does not have an array-api-compat wrapper")
            else:
-                import sparse  # pyright: ignore[reportMissingTypeStubs]
+                import sparse


there's no need for the else: clause

jorenham · 2025-04-19T21:12:15Z

array_api_compat/numpy/__init__.py

-    from numpy import _CopyMode  # noqa: F401
-except ImportError:
-    pass
+from .linalg import matrix_transpose, vecdot  # type: ignore[no-redef] # noqa: F401


what was the issue?

jorenham · 2025-04-19T21:16:13Z

array_api_compat/numpy/_info.py

@@ -139,7 +141,7 @@ def default_dtypes(
        self,
        *,
        device: Device | None = None,
-    ) -> dict[str, dtype[intp | float64 | complex128]]:
+    ) -> DefaultDTypes:


This is a lot less precise, so why did you change it?

jorenham · 2025-04-19T21:20:40Z

pyproject.toml

+
+[tool.pyright]
+include = ["src", "tests"]
+pythonVersion = "3.10"


this isn't needed

Suggested change

pythonVersion = "3.10"

it also makes type-checking in a CI matrix of different python version pretty much useless

jorenham · 2025-04-19T21:20:55Z

pyproject.toml

-  "E722"
+[tool.mypy]
+files = ["array_api_compat"]
+python_version = "3.10"


the comment below also applies here

Suggested change

python_version = "3.10"

jorenham · 2025-04-19T21:21:41Z

pyproject.toml

+
+[[tool.mypy.overrides]]
+module = ["cupy.*", "dask.*", "jax.*", "ndonnx.*", "sparse.*", "torch.*"]
+ignore_missing_imports = true


this is already true globally

Type annotations, part 4

362c48a

Copilot AI review requested due to automatic review settings April 18, 2025 13:48

crusaderky marked this pull request as draft April 18, 2025 13:48

Copilot AI reviewed Apr 18, 2025

View reviewed changes

crusaderky changed the title ~~Type annotations, part 4~~ TYP: Type annotations, part 4 Apr 18, 2025

crusaderky commented Apr 18, 2025

View reviewed changes

array_api_compat/numpy/_aliases.py Show resolved Hide resolved

Fix CopyMode

ad375dc

crusaderky commented Apr 18, 2025

View reviewed changes

revert

49f9ba7

crusaderky marked this pull request as ready for review April 18, 2025 15:09

lucascolley requested a review from jorenham April 19, 2025 14:09

jorenham requested changes Apr 19, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

TYP: Type annotations, part 4 #313

TYP: Type annotations, part 4 #313

crusaderky commented Apr 18, 2025 •

edited

Loading

Copilot AI left a comment

crusaderky Apr 18, 2025

jorenham Apr 19, 2025

crusaderky Apr 18, 2025

jorenham Apr 19, 2025

crusaderky Apr 18, 2025

jorenham Apr 19, 2025

crusaderky Apr 18, 2025

crusaderky Apr 18, 2025

jorenham left a comment

jorenham Apr 19, 2025

jorenham Apr 19, 2025

jorenham Apr 19, 2025

jorenham Apr 19, 2025

jorenham Apr 19, 2025

jorenham Apr 19, 2025

jorenham Apr 19, 2025

jorenham Apr 19, 2025

jorenham Apr 19, 2025

jorenham Apr 19, 2025

		@@ -70,72 +69,11 @@ def shape(self, /) -> _T_co: ...
		DTypeKind: TypeAlias = _DTypeKind \| tuple[_DTypeKind, ...]


		# `__array_namespace_info__.dtypes(kind="bool")`

	return isinstance(a, int \| float \| NoneType)
	return a is None or isinstance(a, int \| float)

TYP: Type annotations, part 4 #313

Are you sure you want to change the base?

TYP: Type annotations, part 4 #313

Conversation

crusaderky commented Apr 18, 2025 • edited Loading

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

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

Choose a reason for hiding this comment

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

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

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

crusaderky commented Apr 18, 2025 •

edited

Loading