ENH: add diag_indices, tril_indices, triu_indices

[bruAristimunha]

Resolves #686.

Summary

• Adds diag_indices, tril_indices, triu_indices — three index-generating functions that numpy, jax, and cupy all have but that are missing from the array-api standard and from this library.
• Signatures follow array-api conventions: parameter offset (matching xp.linalg.diagonal) instead of numpy's k; keyword-only arguments for everything except n; xp is required (these functions have no input array to infer from, following the default_dtype precedent).

Numpy migration

numpy.diag_indices(n, ndim=k)           -> xpx.diag_indices(n, ndim=k, xp=xp)
numpy.tril_indices(n, k=k, m=m)         -> xpx.tril_indices(n, offset=k, m=m, xp=xp)
numpy.triu_indices(n, k=k, m=m)         -> xpx.triu_indices(n, offset=k, m=m, xp=xp)

Delegation

• numpy / cupy / jax: forward directly (signatures match verbatim).
• dask: has tril_indices/triu_indices but no diag_indices — the last one falls through to the generic impl.
• torch: has tril_indices/triu_indices but with (row, col, *, offset) signature returning a 2×N tensor rather than a tuple; delegation translates. No torch.diag_indices exists.
• sparse, array-api-strictest: fall through to generic; marked xfail on those backends (no nonzero / data-dependent shapes).

Validation (n >= 0, ndim >= 1, m >= 0) happens in the delegation layer via a shared _check_nonneg helper, so all backends emit consistent ValueErrors before any backend-specific code runs.

Generic implementation

• diag_indices → (xp.arange(n),) * ndim.
• tril_indices/triu_indices → shared _tri_indices helper: xp.arange + broadcasting + xp.nonzero on the mask. Pure array-api, fully lazy on dask.

Also in this PR

Fixes a pre-existing bug in tests/conftest.py's NumPyReadOnly wrapper: type(o)(*gen) worked for namedtuples but failed for plain tuples of length ≥ 2. Exposed here because these are the first functions in the library that return a tuple of arrays.

Test plan

• pytest tests/test_funcs.py::TestDiagIndices tests/test_funcs.py::TestTriIndices — 155 passed across numpy, torch, jax, dask, array-api-strict (+ xfail on sparse/strictest/dask-use_to_read where noted).
• pytest tests/test_funcs.py full — all passing.
• lefthook run pre-commit --all-files — ruff, numpydoc, mypy, pyright, blacken-docs, validate-pyproject, dprint, typos all green.
• Dask laziness verified — lazy_xp_function(tril_indices)/lazy_xp_function(triu_indices) assert 0 .compute() calls, holds for both native and generic paths.

[bruAristimunha]

hey @lucascolley!

I was wondering, if you have some time, could you please review this PR? I would be happy to address and review any comments that you have.

I am open to address in any macro way to make the revision simpler (put more comments, get the reference and etc)

[lucascolley]

hey @bruAristimunha! I'm pretty busy right now but I'll try to take a look at this soon, thanks

[lucascolley]

somewhat of a side-comment: what is the general feeling on boolean upper parameters nowadays @ev-br ? I wonder whether we should consider exposing a single function with an upper parameter rather than two separate functions.

[lucascolley]

thanks @bruAristimunha, looks great! I haven't taken a detailed look yet, but a few comments for now.

1. please could you update https://github.com/data-apis/array-api-extra/blob/main/docs/api-reference.md ?
2. please could you also add device and xp tests, e.g.

   array-api-extra/tests/test_funcs.py

   Lines 764 to 771 in 2690f22

   	def test_device(self, xp: ModuleType, device: Device):
   	x = xp.asarray([1, 2, 3], device=device)
   	assert get_device(create_diagonal(x)) == device
   	def test_xp(self, xp: ModuleType):
   	x = xp.asarray([1, 2])
   	y = create_diagonal(x, xp=xp)
   	xp_assert_equal(y, xp.asarray([[1, 0], [0, 2]]))

3. please could you add a note to the Tri function docstrings that the generic implementation requires nonzero to be implemented.