fix: handle non-iterable hashables as dim names

[ianhi]

Fixes: #10634

• Core dimension parsing fixes in namedarray/core.py
• Type definition updates in _typing.py
• Index handling fixes in core/indexes.py
• DataArray dimension parsing in core/dataarray.py
• Variable docstring updates in core/variable.py

This exposed that ('a', 'b') is ambiguous as it is both hashable and a sequence of hashable, so I added an error message in a case where it is ambiguous.

There's some error duplication logic, but that is matching the existing duplication of logic.

• Closes Cannot build xarrays with hashable UUIDs as dims #10634
• Tests added
• [NA?] User visible changes (including notable bug fixes) are documented in whats-new.rst
• [NA] New functions/methods are listed in api.rst

[Illviljan]

There's been a lot of struggles with this in the past, see #8210 #6142 #8199 for more reading.

The idea with the previous typing is that xarray promises to normalize str and the outer Iterable to tuple[Hashable, ...], anything more exotic should follow tuple[Hashable, ...] for example (1, None, "z", ("a", "b")).
xarray internals is not perfect either, a lot of parts in xarray still expects dims: tuple[str, ...]

NamedArray handles this fine I think on Main, so I think this PR should try to solve this at the DataArray/Variable level:

import numpy as np
import xarray as xr

some_id = uuid.uuid4()
some_id_2 = uuid.uuid4()

dims = (some_id, some_id_2)
xr.NamedArray(dims, np.asarray([[0.0, 1.0]]))
# <xarray.NamedArray (14a722b6-c795-4557-9255-e3a35b76f383: 1,
#                     d9ebaff1-47b9-4266-8f3f-cb4f2e66719e: 2)> Size: 16B
# array([[0., 1.]])

It probably would've been much easier if dims: list[Hashable], no ambiguity then but other issues as well.

[Illviljan]

Tweaking types usually opens a can of worms.

xarray/namedarray/utils.py: note: In function "infix_dims":
xarray/namedarray/utils.py:165: error: Item "Hashable" of "Hashable | Iterable[Hashable]" has no attribute "__iter__" (not iterable)  [union-attr]

drop_missing_dims, which is used in infix_dims probably needs to be rewritten to return _Dims. The raise case looks risky.

xarray/tests/test_namedarray.py: note: In member "test_permute_dims" of class "TestNamedArray":
xarray/tests/test_namedarray.py:545: error: Expected iterable as variadic argument  [misc]

test_permute_dims uses _DimsLike, try Iterable[_Dim] instead.
Not a big fan of the Iterable[_Dim] style, Would've been nice if these non-public functions simplified and used tuple[Hashable, ...] instead and the normalization was done somewhere else.

 xarray/tests/test_hashable.py: note: In function "test_hashable_dims":
xarray/tests/test_hashable.py:60: error: Argument "dims" to "DataArray" has incompatible type "list[int | tuple[Any, ...] | DEnum | CustomHashable | UUID] | int | tuple[Any, ...] | DEnum | CustomHashable | UUID"; expected "str | Iterable[Hashable] | None"  [arg-type]
xarray/tests/test_hashable.py:66: error: Argument "dims" to "DataArray" has incompatible type "list[int | tuple[Any, ...] | DEnum | CustomHashable | UUID] | int | tuple[Any, ...] | DEnum | CustomHashable | UUID"; expected "str | Iterable[Hashable] | None"  [arg-type]

DataArray is just missing _DimsLike.

[Illviljan]

Suggested change

	name, wrap it in a list: [('a', 'b')].
	name, wrap it in a another tuple: (('a', 'b'),) or list: [('a', 'b')].

Should recommend what xarray tries to use internally first, tuple[Hashable, ...].

[Illviljan]

Suggested change

	name, wrap it in a list: [('a', 'b')].
	name, wrap it in a tuple: (('a', 'b'),) or list: [('a', 'b')].

[Illviljan]

_parse_dimensions is triggered every time NamedArray is initialized. Adding more if-cases will slow down for the people (and NamedArray internally) using the correct type dims: tuple[Hashable, ...].

Would be nice to invert the check to promote correct typing.