Repository navigation
DOC: Explain closing netCDF datasets before overwriting files - #11715
Open
senanurcetin wants to merge 3 commits into
Open
senanurcetin wants to merge 3 commits into
senanurcetin wants to merge 3 commits into
Conversation
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Related to #9361.
Problem
Datasets opened with
open_dataset()oropen_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 aPermissionError, particularly with HDF5-based netCDF4 files.Changes
This PR adds guidance to the I/O user guide explaining how to avoid this situation:
Dataset.load()before closing when the original values must remain available in memory.withstatement to ensure that datasets are closed when their context exits.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:
The main CI workflow reported two failing test jobs:
Python 3.14 flaky tests: Six PyDAP integration tests failed due to connection errors and HTTP 503 responses from the external
test.opendap.orgservice.Python 3.12 minimum versions: One Zarr backend test,
TestZarrDirectoryStore.test_chunk_encoding_with_dask[2], failed withRuntimeError: 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
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.