Skip to content

DOC: Explain closing netCDF datasets before overwriting files - #11715

Open
senanurcetin wants to merge 3 commits into
pydata:mainfrom
senanurcetin:docs/netcdf-close-before-overwrite
Open

senanurcetin wants to merge 3 commits into
pydata:mainfrom
senanurcetin:docs/netcdf-close-before-overwrite

Conversation

@senanurcetin

@senanurcetin senanurcetin commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Description

Related to #9361.

Problem

Datasets opened with open_dataset() or open_mfdataset() can retain open file handles because netCDF data is loaded lazily.

Overwriting one of those source files with Dataset.to_netcdf() while it is still open may raise a PermissionError, particularly with HDF5-based netCDF4 files.

Changes

This PR adds guidance to the I/O user guide explaining how to avoid this situation:

  • Close datasets before overwriting their source files.
  • Use Dataset.load() before closing when the original values must remain available in memory.
  • Use a with statement to ensure that datasets are closed when their context exits.
  • Clarify that the same file-handling considerations apply to open_mfdataset().

Scope

The change is limited to doc/user-guide/io.md.

No runtime behavior, public APIs, or netCDF backend implementations are modified.

This documentation addition explains a safe workflow for avoiding the reported error; it does not implement an automatic file-closing mechanism.

Testing

This PR contains documentation changes only and does not modify runtime code or add automated regression tests.

The following checks passed:

  • Pre-commit checks
  • Documentation preview
  • CI Additional
  • Slow Hypothesis CI

The main CI workflow reported two failing test jobs:

  1. Python 3.14 flaky tests: Six PyDAP integration tests failed due to connection errors and HTTP 503 responses from the external test.opendap.org service.

  2. Python 3.12 minimum versions: One Zarr backend test, TestZarrDirectoryStore.test_chunk_encoding_with_dask[2], failed with RuntimeError: error during blosc decompression: 0. The job recorded 22,060 passing tests and one failure.

Neither failure involves the documentation file modified by this PR. However, the Blosc failure is separate from the external OPeNDAP outage and should not be described as a network-related failure.

The complete upstream test suite has not passed, and the documented workflow has not been independently exercised in this review.

Checklist

  • Documentation guidance added.
  • Personally review the documentation for technical accuracy.
  • Verify the documented workflow in the relevant environment.
  • Complete the repository's AI contribution checklist.

No new functions or methods require API documentation.

AI Disclosure

OpenAI ChatGPT assisted with preparing the documentation contribution and reviewing its technical scope.

The contributor remains responsible for understanding, independently reviewing, and validating the submitted content.

@senanurcetin senanurcetin changed the title DOC explain closing netCDF datasets before overwriting files (GH-9361) BUG: Suppress expected all-NaN warnings in quantile fallback- #11714 Oct 13, 2026
@senanurcetin senanurcetin changed the title BUG: Suppress expected all-NaN warnings in quantile fallback- #11714 DOC: Explain closing netCDF datasets before overwriting files Oct 13, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant