Rename reset_encoding to drop_encoding (#8287)

* Rename `reset_encoding` to `drop_encoding`

Closes #8259

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update dataarray.py

Co-authored-by: Illviljan <[email protected]>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update xarray/core/dataarray.py

Co-authored-by: Michael Niklas  <[email protected]>

* Update xarray/core/variable.py

Co-authored-by: Michael Niklas  <[email protected]>

* Update xarray/core/dataset.py

Co-authored-by: Michael Niklas  <[email protected]>

* api

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Illviljan <[email protected]>
Co-authored-by: Michael Niklas <[email protected]>

Author: 4 people

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

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

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:

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 <https://github.com/max-sixty>`_.
 
 Bug fixes
 ~~~~~~~~~

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

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

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={})
 

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

xarray/tests/test_dataset.py

@@ -2959,15 +2959,15 @@ 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"}
 
         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 == {}

xarray/tests/test_variable.py

@@ -473,20 +473,20 @@ 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 == {}
 
         # encoding set via setter
         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 == {}