[jswhit]

Add extra_mode_flag kwarg to Dataset for user-defined formats (closes #1490)

netcdf-c (>= 4.10.0) supports user-defined formats (UDFs), which let
external dispatch layers read non-netCDF formats through the netCDF API.
The NetCDF Expansion Pack (NEP)
uses this to add readers for GRIB2, FITS, NASA CDF, PDS4, DICOM, PDB,
mmCIF and GeoTIFF.

netcdf-c normally picks the dispatch layer from the file's magic number,
so Dataset() already works for these formats with no changes. Some files
have no magic number, though (mmCIF, for example). For those, netcdf-c
needs a UDF mode flag passed to nc_open(), such as
nc_open(path, NC_NOWRITE|NC_UDF8, &ncid). Until now there was no way to
pass one from Python.

Almost all NEP supported formats contain the "magic number" and can be read by netcdf-c 4.10.0 without the extra flag. AFAICT, only DICOM files require it.

Changes

• New Dataset kwarg extra_mode_flag (default None). An integer
  that is ORed into the mode passed to nc_open():

  ds = netCDF4.Dataset("structure.cif", extra_mode_flag=netCDF4.NEP_UDF_MMCIF)

• New module constants NEP_UDF_*: the names match the macros in NEP's
  nep.h, and each maps a format to its NC_UDFn slot:
  NEP_UDF_GEOTIFF_BIGTIFF (UDF0), NEP_UDF_GEOTIFF_STANDARD (UDF1),
  NEP_UDF_GRIB2 (UDF2), NEP_UDF_FITS (UDF3), NEP_UDF_CDF (UDF4),
  NEP_UDF_PDS4 (UDF5), NEP_UDF_DICOM (UDF6), NEP_UDF_PDB (UDF7),
  NEP_UDF_MMCIF (UDF8), NEP_UDF_NEXTCDF4 (UDF9). They are hard-coded,
  like NC_DISKLESS/NC_PERSIST, so the module still compiles against
  older netcdf-c.
• Validation: the flag is only used for a plain read-only nc_open()
  (cmode == NC_NOWRITE). These cases raise an error:
  • mode other than 'r' (including 'rs'), or diskless, memory or
    parallel ‚Üí ValueError. NEP readers are read-only, and parallel or
    in-memory opens aren't expected to work with UDFs.
  • a value that isn't one of the NEP_UDF_* constants ‚Üí ValueError.
    This stops arbitrary mode bits (such as NC_WRITE) from being passed
    through.
  • netcdf-c < 4.10.0 ‚Üí NetCDF4MissingFeatureException.
• Docstring and type stubs (__init__.pyi, _netCDF4.pyi) updated.

The UDF itself still has to be registered with netcdf-c. For NEP that's
done through its .ncrc file, for example with NCRCENV_RC pointing at it.

Tests

The NEP-dependent tests are skipped unless the NEP readers are registered
with netcdf-c, so CI without NEP is unaffected.

• test/test_extra_mode_flag.py
  • Argument checks (runs on any netcdf-c >= 4.10.0).
  • Writes a small mmCIF file with its data_ magic number removed, checks
    that it fails to open by default, and checks that it opens and reads
    correctly with extra_mode_flag=NEP_UDF_MMCIF.
• test/test_nep_grib2.py with test/gfs_sample.grb2 (27 KB, the first 3
  messages of pygrib's sampledata/gfs.grb): reads HGT, TMP and RH and
  checks them against reference values from pygrib. It runs twice, once with
  the format detected from the magic number and once with
  extra_mode_flag=NEP_UDF_GRIB2. MANIFEST.in now includes test/*grb2.

Tested on macOS arm64 with netcdf-c 4.10.1, HDF5 2.2.0 and NEP v4.1.0 built
from source. The full test suite passes with and without NEP, and so do
stubtest and mypy test.

Notes

• NEP currently declares GRIB2 dimensions in the wrong order. For this
  2.5¬∞ grid it gives (y=144, x=73), but the data are stored as
  (lat=73, lon=144). The GRIB2 test reshapes before comparing, so it will
  keep passing once that's fixed in NEP.
• nep isn't on conda-forge yet
  (Add nep 3.0.0 conda-forge/staged-recipes#34309 is still open), and that package
  (v3.0.0) doesn't include the format readers, so testing currently needs
  a source build of NEP.

🤖 Generated with Claude Code

[jswhit]

This PR currently has no test coverage under Github Actions - the tests are skipped because NEP is not installed in any of the environments the tests run in. This can be remedied once the conda-forge package exists (conda-forge/staged-recipes#34309).