def save_dataset(
file_name: str,
dataset: xr.Dataset | xr.DataArray,
format_name: str = None,
*,
allow_overwrite: bool = False,
**kwargs: Any,
) -> None:
"""Save data from :xarraydoc:`Dataset` or :xarraydoc:`DataArray` to a file.
Parameters
----------
file_name : str
File to write the data to.
format_name : str
Format the file should be in, if not provided it will be inferred from the file extension.
dataset: xr.Dataset|xr.DataArray
Data to be written to file.
allow_overwrite : bool
Whether or not to allow overwriting existing files, by default False
**kwargs: Any
Additional keyword arguments passes to the ``write_dataset`` implementation
of the data io plugin. If you aren't sure about those use ``get_datawriter``
to get the implementation with the proper help and autocomplete.
"""
protect_from_overwrite(file_name, allow_overwrite=allow_overwrite)
io = get_data_io(format_name or inferr_file_format(file_name, needs_to_exist=False))
io.save_dataset( # type: ignore[call-arg]
file_name=file_name,
dataset=dataset,
**kwargs,
)
def test_protect_from_overwrite_file_exists(tmp_path: Path):
"""Error by default if file exists."""
path = tmp_path / "dummy.txt"
path.touch()
with pytest.raises(FileExistsError, match="The file .+? already exists"):
protect_from_overwrite(path)
def save_result(
result_path: str,
result: Result,
format_name: str = None,
*,
allow_overwrite: bool = False,
**kwargs: Any,
) -> None:
"""Write a :class:`Result` instance to a spec file.
Parameters
----------
result_path : str
Path to write the result data to.
result : Result
:class:`Result` instance to write.
format_name : str
Format the result should be saved in, if not provided and it is a file
it will be inferred from the file extension.
allow_overwrite : bool
Whether or not to allow overwriting existing files, by default False
**kwargs: Any
Additional keyword arguments passes to the ``save_result`` implementation
of the project io plugin.
"""
protect_from_overwrite(result_path, allow_overwrite=allow_overwrite)
io = get_project_io(format_name or inferr_file_format(
result_path, needs_to_exist=False, allow_folder=True))
io.save_result( # type: ignore[call-arg]
result_path=result_path,
result=result,
**kwargs,
)
def save_scheme(
file_name: str,
scheme: Scheme,
format_name: str = None,
*,
allow_overwrite: bool = False,
**kwargs: Any,
) -> None:
"""Save a :class:`Scheme` instance to a spec file.
Parameters
----------
file_name : str
File to write the scheme specs to.
scheme : Scheme
:class:`Scheme` instance to save to specs file.
format_name : str
Format the file should be in, if not provided it will be inferred from the file extension.
allow_overwrite : bool
Whether or not to allow overwriting existing files, by default False
**kwargs: Any
Additional keyword arguments passes to the ``save_scheme`` implementation
of the project io plugin.
"""
protect_from_overwrite(file_name, allow_overwrite=allow_overwrite)
io = get_project_io(format_name
or inferr_file_format(file_name, needs_to_exist=False))
io.save_scheme(file_name=file_name, scheme=scheme,
**kwargs) # type: ignore[call-arg]
def test_protect_from_overwrite_not_empty_dir(tmpdir: LocalPath):
"""Error by default if path is an not empty dir."""
path = tmpdir / "dummy"
path.mkdir()
(path / "dummy.txt").write_text("test", encoding="utf8")
with pytest.raises(FileExistsError,
match="The folder .+? already exists and is not empty"):
protect_from_overwrite(path)
def save_result(
result: Result,
result_path: StrOrPath,
format_name: str = None,
*,
allow_overwrite: bool = False,
update_source_path: bool = True,
saving_options: SavingOptions = SAVING_OPTIONS_DEFAULT,
**kwargs: Any,
) -> list[str]:
"""Write a :class:`Result` instance to a spec file.
Parameters
----------
result : Result
:class:`Result` instance to write.
result_path : StrOrPath
Path to write the result data to.
format_name : str
Format the result should be saved in, if not provided and it is a file
it will be inferred from the file extension.
allow_overwrite : bool
Whether or not to allow overwriting existing files, by default False
update_source_path: bool
Whether or not to update the ``source_path`` attribute to ``result_path`` when saving.
by default True
saving_options : SavingOptions
Options for the saved result.
**kwargs : Any
Additional keyword arguments passes to the ``save_result`` implementation
of the project io plugin.
Returns
-------
list[str] | None
List of file paths which were saved.
"""
protect_from_overwrite(result_path, allow_overwrite=allow_overwrite)
io = get_project_io(
format_name or inferr_file_format(result_path, needs_to_exist=False, allow_folder=True)
)
paths = io.save_result( # type: ignore[call-arg]
result_path=Path(result_path).as_posix(),
result=result,
saving_options=saving_options,
**kwargs,
)
if update_source_path is True:
result.source_path = Path(result_path).as_posix()
return paths
def save_dataset(
dataset: xr.Dataset | xr.DataArray,
file_name: StrOrPath,
format_name: str = None,
*,
data_filters: list[str] | None = None,
allow_overwrite: bool = False,
update_source_path: bool = True,
**kwargs: Any,
) -> None:
"""Save data from :xarraydoc:`Dataset` or :xarraydoc:`DataArray` to a file.
Parameters
----------
dataset : xr.Dataset | xr.DataArray
Data to be written to file.
file_name : StrOrPath
File to write the data to.
format_name : str
Format the file should be in, if not provided it will be inferred from the file extension.
data_filters : list[str] | None
Optional list of items in the dataset to be saved.
allow_overwrite : bool
Whether or not to allow overwriting existing files, by default False
update_source_path: bool
Whether or not to update the ``source_path`` attribute to ``file_name`` when saving.
by default True
**kwargs : Any
Additional keyword arguments passes to the ``write_dataset`` implementation
of the data io plugin. If you aren't sure about those use ``get_datawriter``
to get the implementation with the proper help and autocomplete.
"""
protect_from_overwrite(file_name, allow_overwrite=allow_overwrite)
io = get_data_io(format_name
or inferr_file_format(file_name, needs_to_exist=False))
if "loader" in dataset.attrs:
del dataset.attrs["loader"]
if "source_path" in dataset.attrs:
orig_source_path: str = dataset.attrs["source_path"]
del dataset.attrs["source_path"]
io.save_dataset( # type: ignore[call-arg]
file_name=Path(file_name).as_posix(),
dataset=dataset,
**kwargs,
)
dataset.attrs["loader"] = load_dataset
if update_source_path is True or "orig_source_path" not in locals():
dataset.attrs["source_path"] = Path(file_name).as_posix()
else:
dataset.attrs["source_path"] = Path(orig_source_path).as_posix()
def save_scheme(
scheme: Scheme,
file_name: StrOrPath,
format_name: str = None,
*,
allow_overwrite: bool = False,
update_source_path: bool = True,
**kwargs: Any,
) -> None:
"""Save a :class:`Scheme` instance to a spec file.
Parameters
----------
scheme : Scheme
:class:`Scheme` instance to save to specs file.
file_name : StrOrPath
File to write the scheme specs to.
format_name : str
Format the file should be in, if not provided it will be inferred from the file extension.
allow_overwrite : bool
Whether or not to allow overwriting existing files, by default False
update_source_path: bool
Whether or not to update the ``source_path`` attribute to ``file_name`` when saving.
by default True
**kwargs : Any
Additional keyword arguments passes to the ``save_scheme`` implementation
of the project io plugin.
"""
protect_from_overwrite(file_name, allow_overwrite=allow_overwrite)
io = get_project_io(format_name or inferr_file_format(file_name, needs_to_exist=False))
io.save_scheme( # type: ignore[call-arg]
file_name=Path(file_name).as_posix(),
scheme=scheme,
**kwargs,
)
if update_source_path is True:
scheme.source_path = Path(file_name).as_posix()
def test_protect_from_overwrite_empty_dir(tmpdir: LocalPath):
"""Nothing happens when the folder is empty"""
path = tmpdir / "dummy"
path.mkdir()
protect_from_overwrite(path)
def test_protect_from_overwrite_allow_overwrite(tmp_path: Path):
"""Nothing happens when allow_overwrite=True"""
path = tmp_path / "dummy.txt"
path.touch()
protect_from_overwrite(path, allow_overwrite=True)