Home

Welcome to the h5netcdf wiki!

Contribution Guidelines

• New features and changes should be added via Pull Requests from forks for contributors as well as maintainers.
• Pull Requests should have at least one approval (once the maintainer count has increased).
• Self merges without approval are allowed for repository maintenance, hotfixes and if the code changes do not affect functionality.
• Directly pushing to the repository main branch should only be used as a last resort.
• Releases should be introduced via Pull Request and approved. Exception: Patch release after hotfix.

Release Workflow

1. Create release commit (can be done per PullRequest for more visibility)
   • versioning is done via setuptools_scm
   • update CHANGELOG.rst if necessary
   • add/update sections to README.rst (or documentation) if necessary
   • check all needed dependencies are listed in setup.py
2. Create release
   • draft new github release
   • tag version (eg v0.11.0) @ Target: main
   • set release title (eg. release 0.11.0)
   • add release description (eg. bugfix-release), tbd.

This will start the CI workflow once again. The workflow creates sdist and universal wheel and uploads it to PyPI.

References and reading material

Some valuable links on dimension scales:

• https://www.unidata.ucar.edu/blogs/developer/en/entry/dimensions_scales
• https://www.unidata.ucar.edu/blogs/developer/en/entry/dimension_scale2
• https://www.unidata.ucar.edu/blogs/developer/en/entry/dimension_scales_part_3
• https://www.unidata.ucar.edu/blogs/developer/en/entry/netcdf4_shared_dimensions
• https://www.unidata.ucar.edu/blogs/developer/en/entry/netcdf4_use_of_dimension_scales
• https://www.researchgate.net/publication/330347054_2A5_NETCDF-4_PERFORMANCE_IMPROVEMENTS_OPENING_COMPLEX_DATA_FILES

String NULLTERM vs NULLPAD:

• https://github.com/PyTables/PyTables/issues/264

netcdf4-python quirks:

• _Netcdf4Dimid gets attached to all data variables if a 2D coordinate variable is created and any variable is written/file is reopened for append, see https://github.com/Unidata/netcdf4-python/issues/1104
• unlimited variable dimensions are reported as current size of the dimension scale, even if the variable's underlying DATASPACE dimension is smaller (eg.0)

legacyapi vs new api feature comparison

feature	legacyapi	new api	type
1D boolean indexer	☑	☐	Variable/Dataset
resize on write	☑	☐	Dimension Variable/Dataset
resize dimension	only current dimension	dimension and all connected variables	Dimension Variable/Dataset
group name	name only	full path	Group
phony_dims	kwarg	kwarg	Dimension
decode_vlen_strings	☑	kwarg	Variable/Dataset
chunk sizes	h5netcdf	kwarg	Variable/Dataset
dimension .size returns	max size dimension and connected variables	size dimension	Dimension
valid netcdf	kwarg	kwarg	Attribute Variable/Dataset
h5py.Empty string attrs returns	b""	b""	Attribute
endian	☑	☐	Variable/Dataset
track order	☐	☐	File/Group Dataset