[Type] ndarray typing 5: Pyright stubs for quadrants types and NDArray subscript syntax

[hughperkins]

Add .pyi stub files for primitive_types, ndarray_type, utils, annotations, and compound_types so that Pyright/mypy can type-check code using quadrants types. Update .gitignore to only ignore generated stubs in stubs/quadrants/_lib/. Add pyright test for primitive dtype annotations and NDArray subscript syntax.

Issue: #

Brief Summary

copilot:summary

Walkthrough

copilot:walkthrough

[hughperkins]

Opus 4.6 review:

PR Review: hp/typing-t4-5-pyright-stubs

Summary

This PR adds hand-written .pyi stub files for quadrants.types (annotations, compound_types, ndarray_type, primitive_types, utils) to enable Pyright/mypy type checking, narrows .gitignore to only ignore generated stubs in stubs/quadrants/_lib/, and extends pyright tests to cover NDArray subscript syntax and primitive dtype annotations.

---

Correctness

Stubs vs. runtime

• annotations.pyi: Matches runtime. Template init and __getitem__ signatures are correct. sparse_matrix_builder is correctly stubbed as an empty class.
• compound_types.pyi: CompoundType.check_matched(self, other: Any) -> bool — runtime implementations (e.g. in lang/matrix.py) raise on mismatch rather than returning False. Consider -> None or NoReturn for the failure path. from_kernel_struct_ret and to_string are fine.
• ndarray_type.pyi: Matches runtime. __init__ parameters and boundary: int attribute are correct. __class_getitem__ returns type[NdarrayType] in the stub; runtime returns cls(*args) (an instance). For annotation use this is acceptable; if desired, the return type could be NdarrayType to reflect the actual instance.
• primitive_types.pyi: PrimitiveMeta.__eq__ and __ne__ are declared as -> bool, but runtime can return NotImplemented for non-matching types. Consider -> bool | Literal[NotImplemented] for strictness, though impact is small.
• utils.pyi: Correct; function signatures match the runtime.

Missing from stubs

• NdarrayType: check_matched, to_dlpack, and layout are not stubbed. These are internal; omitting them is reasonable for user-facing annotations.
• quant module: No stub. quadrants.types re-exports quant; if quant is used in typed code, a stub may be needed later.

---

Stub signature consistency

Module	Status
annotations	✓ Consistent
compound_types	✓ Minor: check_matched return type
ndarray_type	✓ Consistent
primitive_types	✓ Minor: __eq__/__ne__ can return NotImplemented
utils	✓ Consistent

---

.gitignore change

Change: stubs/ → stubs/quadrants/_lib/

Assessment: Correct. Hand-written stubs live in stubs/quadrants/types/ and are now tracked. Generated stubs (e.g. quadrants_python.pyi from pybind11-stubgen) live in stubs/quadrants/_lib/core/ and remain ignored. CI builds the package, generates the stub, and copies it into stubs/quadrants/_lib/core/ before running Pyright.

---

Test files

test_ndarray_type.py

• Covers legacy ndarray() call syntax with # type: ignore[reportInvalidTypeForm].
• Covers new subscript syntax (NDArray[dtype, ndim]) without ignores.
• Tests both @qd.kernel and @qd.kernel().
• Tests @qd.data_oriented classes with kernel methods.
• Runtime test calls k3 and some_class.k3.

test_primitive_types.py

• Covers primitive dtypes (f32, i32, etc.) as annotations.
• Covers NDArray[dtype, ndim], NDArray[dtype], and bare NDArray.
• Covers from __future__ import annotations.
• Covers qd.types.NDArray and qd.types.f32.
• Covers return types, Optional, variable annotations, class attributes, and via_types.

Pyright reports 0 errors on both test files.

---

Suggestions for improvement

1. CompoundType.check_matched: Change return type from -> bool to -> None (or document that it raises on mismatch).
2. PrimitiveMeta.eq/ne: Optionally use -> bool | Literal[NotImplemented] for strict typing.
3. NdarrayType.class_getitem: Optionally change return type from type[NdarrayType] to NdarrayType to match the instance returned at runtime.
4. quant stub: Add a quant.pyi stub if quant is used in typed user code.

---

Conclusion

No blocking issues. The stubs align with the runtime, the .gitignore change is correct, and the tests cover the main type-checking scenarios. The suggestions above are minor refinements.