Add overloads for DataArray.argmin and DataArray.argmax on dim parameter

[SurfyPenguin]

What this does

Adds @overload decorators to DataArray.argmin and DataArray.argmax so type checkers can narrow the return type based on the dim argument.

• dim: str -> Self
• dim: Collection[Hashable] | EllipsisType | None = None -> dict[Hashable, Self]

Additional info

While testing, I noticed this FutureWarning:

FutureWarning: Behaviour of argmin/argmax with neither dim nor axis argument will change to return a dict of indices of each dimension. To get a single, flat index, please use np.argmin(da.data) or np.argmax(da.data) instead of da.argmin() or da.argmax().

The overload reflects the intended behavior i.e. dim=None is typed to return dict[Hashable, Self] rather than Self.

• Closes Overload DataArray's argmin and argmax methods on dim parameter #10893
• Tests added
• User visible changes (including notable bug fixes) are documented in whats-new.rst
• New functions/methods are listed in api.rst

[welcome]

Thank you for opening this pull request! It may take us a few days to respond here, so thank you for being patient.
If you have questions, some answers may be found in our contributing guidelines.

[SurfyPenguin]

Closing this PR for now.
After syncing with main and re-running mypy. I realized my overload pattern for DataArray.argmin and DataArray.argmax reproduces the exact overlap issue tracked in #10893 .

[headtr1ck]

This approach is actually correct. The ignore is important and it will work exactly as intended.

[SurfyPenguin]

@headtr1ck , thanks for the clarification. I was not sure if type: ignore[overload-overlap] was the right thing to do here. Good to know its intentional. I'm re-opening the PR.

[headtr1ck]

Yes it's correct. Mypy correctly complains because technically it is overlapping because str is an IT table of hashable. But if you ignore this, it will correctly infer that str will return Self while e.g. a list returns something else (it will start looking through the overloads by their order and pick the first match).

[themavik]

nit: type: ignore[overload-overlap] covers str vs Collection[Hashable]; mypy/pyright upgrades sometimes tighten overlap diagnostics—may need a narrower split later.

[welcome]

Congratulations on completing your first pull request! Welcome to Xarray! We are proud of you, and hope to see you again!