issues

WIP PR for https://github.com/pydata/xarray/issues/3324. Since either_dict_or_kwargs is called 57 times, I don't want to modify every function call without a preliminary review. My main question is if using locals() at the top of each function is considered acceptable. Of course, if locals() is called after some local variables are created, this code could raise an error when no conflict exists. But explicitly passing in the function argument names in all 57 functions seems brittle. I'd appreciate any thoughts on the PR before I modify all the functions and write some tests.

This arose as part of https://github.com/pydata/xarray/pull/3352. Xarray has important-to-understand name-matching rules for whether or not a coordinate array is a dimension coordinate or a non-dimension coordinate. To my knowledge, this is not in the documentation anywhere.

This is what I had, but we decided to remove it since it was overly complicated for a list of key terms; maybe it'll be helpful going forward:

Name matching rules: Xarray follows simple but important-to-understand name matching rules for dimensions and coordinates. Let arr be an array with an existing dimension x and assigned new coordinates new_coords. If new_coords is a list-like for e.g. [1, 2, 3] then they must be assigned a name that matches an existing dimension. For example, if arr.assign_coords({'x': [1, 2, 3]}).

However, if new_coords is a one-dimensional DataArray, then the rules are slightly more complex. In this case, if both new_coords's name and only dimension match any dimension name in arr.dims, it is assigned as a dimension coordinate to arr. If new_coords's name matches a name in arr.dims but its own dimension name does not, it is assigned as a non-dimension coordinate with name new_coords.dims[0] to arr. Otherwise, an exception is raised.

Given that many Xarray methods accept dict or keyword arguments, this may effect other methods. That said, here is a minimal example with sel.

Minimal example

If I want to select based on a dimension named method, I cannot because Xarray thinks method is the method argument to sel:

```python

da1 = xr.DataArray(range(3), dims=['method'], coords={'method': range(3)}) da1 <xarray.DataArray (method: 3)> array([0, 1, 2]) Coordinates: * method (method) int64 0 1 2 da1.sel(method=0) ... TypeError: method must be a string ```

And if the method dimension has string labels, this fails silently:

```python

da2 = xr.DataArray(range(3), dims=['method'], coords={'method': list('abc')}) da2.sel(method='a') <xarray.DataArray (method: 3)> array([0, 1, 2]) Coordinates: * method (method) <U1 'a' 'b' 'c' ```

Expected Output

I think raising a ValueError and providing a clarifying error message is the right call, but maybe the maintainers have a different opinion. At the very least, it seems like Xarray could note that the DataArray instance has a dimension that matches one of the function arguments and ask the user to use dict-like arguments if required.

I imagine a general error handling function could be written to check this for any function and DataArray pair.