add drop_existing kwarg to set_xindex

[ianhi]

• Closes Add new kwarg drop_existing to set_xindex #11007
• Tests added
• User visible changes (including notable bug fixes) are documented in whats-new.rst
• [NA] New functions/methods are listed in api.rst

[benbovy]

Thanks @ianhi, I think that this is a convenient addition!

I'd just rename drop_existing to simply drop. The latter is a bit less self-explanatory but more consistent with the rest of the Xarray API where drop is already a parameter of many methods like .reset_index, .reset_coords, .isel, .where, etc.

[max-sixty]

just to confirm — and I left a comment at #11007, so possibly folks saw this — we're sure this shouldn't replace by default? currently the closest function is set_index, which does exactly that, iiuc

[benbovy]

we're sure this shouldn't replace by default? currently the closest function is set_index, which does exactly that, iiuc

I don't have strong opinions on this, we could replace it by default indeed. It might break the workflow of some users who rely on explicit-only index replacement as a safety guard, however to my knowledge people are actually rather annoyed by that (including me :-)).

[ianhi]

re the default I was defaulting to being cautious given xarray's large userbase. But I think it's in general a large user base, perhaps not for this specific function. I agree that a default of drop=True is preferable. So the quesiton becomes are we comfortable with just doing that, or does that require a deprecation cycle?

[benbovy]

So the quesiton becomes are we comfortable with just doing that

Yes I think we are!

[max-sixty]

(this might be going too far, but we may not even need the drop kwarg...)