diff --git a/doc/api-hidden.rst b/doc/api-hidden.rst index d97c4010528..552d11a06dc 100644 --- a/doc/api-hidden.rst +++ b/doc/api-hidden.rst @@ -265,7 +265,7 @@ Variable.dims Variable.dtype Variable.encoding - Variable.reset_encoding + Variable.drop_encoding Variable.imag Variable.nbytes Variable.ndim diff --git a/doc/api.rst b/doc/api.rst index 0cf07f91df8..96b4864804f 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -110,9 +110,9 @@ Dataset contents Dataset.drop_indexes Dataset.drop_duplicates Dataset.drop_dims + Dataset.drop_encoding Dataset.set_coords Dataset.reset_coords - Dataset.reset_encoding Dataset.convert_calendar Dataset.interp_calendar Dataset.get_index @@ -303,8 +303,8 @@ DataArray contents DataArray.drop_vars DataArray.drop_indexes DataArray.drop_duplicates + DataArray.drop_encoding DataArray.reset_coords - DataArray.reset_encoding DataArray.copy DataArray.convert_calendar DataArray.interp_calendar diff --git a/doc/user-guide/io.rst b/doc/user-guide/io.rst index 2ffc25b2009..ffded682035 100644 --- a/doc/user-guide/io.rst +++ b/doc/user-guide/io.rst @@ -260,12 +260,12 @@ Note that all operations that manipulate variables other than indexing will remove encoding information. In some cases it is useful to intentionally reset a dataset's original encoding values. -This can be done with either the :py:meth:`Dataset.reset_encoding` or -:py:meth:`DataArray.reset_encoding` methods. +This can be done with either the :py:meth:`Dataset.drop_encoding` or +:py:meth:`DataArray.drop_encoding` methods. .. ipython:: python - ds_no_encoding = ds_disk.reset_encoding() + ds_no_encoding = ds_disk.drop_encoding() ds_no_encoding.encoding .. _combining multiple files: diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 8f576f486dc..40c50e158ad 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -45,7 +45,12 @@ Breaking changes Deprecations ~~~~~~~~~~~~ - +- Rename :py:meth:`Dataset.reset_encoding` & :py:meth:`DataArray.reset_encoding` + to :py:meth:`Dataset.drop_encoding` & :py:meth:`DataArray.drop_encoding` for + consistency with other ``drop`` & ``reset`` methods — ``drop`` generally + removes something, while ``reset`` generally resets to some default or + standard value. (:pull:`8287`, :issue:`8259`) + By `Maximilian Roos `_. Bug fixes ~~~~~~~~~ diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index cc5d4a8744c..391b4ed9412 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -914,9 +914,15 @@ def encoding(self, value: Mapping[Any, Any]) -> None: self.variable.encoding = dict(value) def reset_encoding(self) -> Self: + warnings.warn( + "reset_encoding is deprecated since 2023.11, use `drop_encoding` instead" + ) + return self.drop_encoding() + + def drop_encoding(self) -> Self: """Return a new DataArray without encoding on the array or any attached coords.""" - ds = self._to_temp_dataset().reset_encoding() + ds = self._to_temp_dataset().drop_encoding() return self._from_temp_dataset(ds) @property diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py index a1faa538564..ebd6fb6f51f 100644 --- a/xarray/core/dataset.py +++ b/xarray/core/dataset.py @@ -756,9 +756,15 @@ def encoding(self, value: Mapping[Any, Any]) -> None: self._encoding = dict(value) def reset_encoding(self) -> Self: + warnings.warn( + "reset_encoding is deprecated since 2023.11, use `drop_encoding` instead" + ) + return self.drop_encoding() + + def drop_encoding(self) -> Self: """Return a new Dataset without encoding on the dataset or any of its variables/coords.""" - variables = {k: v.reset_encoding() for k, v in self.variables.items()} + variables = {k: v.drop_encoding() for k, v in self.variables.items()} return self._replace(variables=variables, encoding={}) @property diff --git a/xarray/core/variable.py b/xarray/core/variable.py index 3baecfe5f6d..fa5523b1340 100644 --- a/xarray/core/variable.py +++ b/xarray/core/variable.py @@ -883,6 +883,12 @@ def encoding(self, value): raise ValueError("encoding must be castable to a dictionary") def reset_encoding(self) -> Self: + warnings.warn( + "reset_encoding is deprecated since 2023.11, use `drop_encoding` instead" + ) + return self.drop_encoding() + + def drop_encoding(self) -> Self: """Return a new Variable without encoding.""" return self._replace(encoding={}) diff --git a/xarray/tests/test_dataarray.py b/xarray/tests/test_dataarray.py index d497cd5a54d..5eb5394d58e 100644 --- a/xarray/tests/test_dataarray.py +++ b/xarray/tests/test_dataarray.py @@ -287,7 +287,7 @@ def test_encoding(self) -> None: self.dv.encoding = expected2 assert expected2 is not self.dv.encoding - def test_reset_encoding(self) -> None: + def test_drop_encoding(self) -> None: array = self.mda encoding = {"scale_factor": 10} array.encoding = encoding @@ -296,7 +296,7 @@ def test_reset_encoding(self) -> None: assert array.encoding == encoding assert array["x"].encoding == encoding - actual = array.reset_encoding() + actual = array.drop_encoding() # did not modify in place assert array.encoding == encoding diff --git a/xarray/tests/test_dataset.py b/xarray/tests/test_dataset.py index 12347c8d62e..687aae8f1dc 100644 --- a/xarray/tests/test_dataset.py +++ b/xarray/tests/test_dataset.py @@ -2959,7 +2959,7 @@ def test_copy_with_data_errors(self) -> None: with pytest.raises(ValueError, match=r"contain all variables in original"): orig.copy(data={"var1": new_var1}) - def test_reset_encoding(self) -> None: + def test_drop_encoding(self) -> None: orig = create_test_data() vencoding = {"scale_factor": 10} orig.encoding = {"foo": "bar"} @@ -2967,7 +2967,7 @@ def test_reset_encoding(self) -> None: for k, v in orig.variables.items(): orig[k].encoding = vencoding - actual = orig.reset_encoding() + actual = orig.drop_encoding() assert actual.encoding == {} for k, v in actual.variables.items(): assert v.encoding == {} diff --git a/xarray/tests/test_variable.py b/xarray/tests/test_variable.py index 1ffd51f4a04..73238b6ae3a 100644 --- a/xarray/tests/test_variable.py +++ b/xarray/tests/test_variable.py @@ -473,12 +473,12 @@ def test_encoding_preserved(self): assert_identical(expected.to_base_variable(), actual.to_base_variable()) assert expected.encoding == actual.encoding - def test_reset_encoding(self) -> None: + def test_drop_encoding(self) -> None: encoding1 = {"scale_factor": 1} # encoding set via cls constructor v1 = self.cls(["a"], [0, 1, 2], encoding=encoding1) assert v1.encoding == encoding1 - v2 = v1.reset_encoding() + v2 = v1.drop_encoding() assert v1.encoding == encoding1 assert v2.encoding == {} @@ -486,7 +486,7 @@ def test_reset_encoding(self) -> None: encoding3 = {"scale_factor": 10} v3 = self.cls(["a"], [0, 1, 2], encoding=encoding3) assert v3.encoding == encoding3 - v4 = v3.reset_encoding() + v4 = v3.drop_encoding() assert v3.encoding == encoding3 assert v4.encoding == {}