This pull request add support for enums on netcdf4 backend.

Enum were added in netCDF4-python in 1.2.0 (September 2015). In the netcdf format, they are defined as types and can be use across the dataset to type variable when on creation. They are meant to be an alternative to flag_values, flag_meanings.

This pull request makes it possible for xarray to read existing enums in a file, convert them into flag_values/flag_meanings and save them as enums when an special encoding flag is filled in.

TODO: - [x] Add implementation for other backends ? Will be added in follow-up PR

• [x] Closes #8144
• [x] Tests added
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst

Is your feature request related to a problem?

When a netcdf file contains netcdf4 enums , xarray ignores the underlying enum type. The association between the values of the variable and their actual meaning is then lost.

MRE: ```py import netCDF4 as nc import xarray as xr

-- Create dataset with an enum using the netcdf4 lib

ds = nc.Dataset("mre.nc", "w", format="NETCDF4")
cloud_type_enum = ds.createEnumType(int,"cloud_type",{"clear":0, "cloudy":1}) print(ds.enumtypes)

{'cloud_type': <class 'netCDF4._netCDF4.EnumType'>: name = 'cloud_type', numpy dtype = int64, fields/values ={'clear': 0, 'cloudy': 1}}

ds.createVariable("cloud", cloud_type_enum) ds["cloud"][0] = 1 ds.close()

-- Open dataset with xarray

xr_ds = xr.open_dataset("./mre.nc") print(xr_ds.cloud)

<xarray.DataArray 'cloud' ()> \n [1 values with dtype=int64]

--> We get no metadata about the cloud_type enum that we created above

xr.ds.to_netcdf("mre_xr.nc")

-- Open xarray outputted dataset with netCDF4 lib

print(nc.Dataset("mre_xr.nc", "r", format="NETCDF4").enumtypes())

{}

--> Empty dictionary: the enum we created is lost

```

If you know CF, enums could replace replace flag_meanings and flag_values, see CF Enums are not yet part of CF though.

Describe the solution you'd like

As far as I understand, to describe the enum we only need a dictionary that map numbers (enum key) to string (enum value) and a way to reference this dictionary in variables that are "typed" to this enum. Bear in mind that the dtype of the variable would still be a number, the enum type would be a secondary metadata.

Describe alternatives you've considered

Most people that produce data could get away with using flag_meanings and flag_values to describe their data in a way which is both CF proof and properly managed by xarray. For me, the only workaround at the moment is to use the netCDF4 library directly.

Additional context

```py nc.version

1.6.2

xr.version

2023.2.0

```

• [x] Closes #2511
• [x] Closes #4663
• [x] Closes #4276
• [x] xref #7516
• [x] Tests added
• [x] Passes pre-commit run --all-files
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst

This is a naive attempt to make isel work with Dask. Known limitation: it triggers the computation.

WIP The code presented here is mainly to support the discussion on #2511. It has not been unit tested and should probably not be merged as is.

Fix link to "Generalized Universal Function API" of Numpy's doc

• [ ] Closes #xxxx
• [ ] Tests added
• [x] Passes pre-commit run --all-files
• [ ] User visible changes (including notable bug fixes) are documented in whats-new.rst
• [ ] New functions/methods are listed in api.rst

This PR adds str type on datarray.chunk method the same way it is accepted on dataset.chunk. The corresponding documentation has been updated.

I wanted to add a unit test for da.chunk("auto") but the existing tests seems to rely on zarr which I don't know at all.