Repository: pydata/xarray

Issue:
Should `.reset_encoding` be `.drop_encoding`?
### What is your issue?

Not the greatest issue facing the universe — but for the cause of consistency — should `.reset_encoding` be `.drop_encoding`, since it drops all encoding attributes?

For comparison:
- `.reset_coords` — "Given names of coordinates, reset them to become variables."
- '.drop_vars` — "Drop variables from this dataset."

Also ref #8258

Discussion:
max-sixty: The failures are unrelated, instead re #8296, so planning to merge this unless there are any comments...

Patch:
diff --git a/doc/api-hidden.rst b/doc/api-hidden.rst
index d97c4010..552d11a0 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 0cf07f91..96b48648 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 2ffc25b2..ffded682 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 8f576f48..40c50e15 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 <https://github.com/max-sixty>`_.
 
 Bug fixes
 ~~~~~~~~~
diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py
index cc5d4a87..391b4ed9 100644
--- a/xarray/core/dataarray.py
+++ b/xarray/core/dataarray.py
@@ -914,9 +914,15 @@ class DataArray(
         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 a1faa538..ebd6fb6f 100644
--- a/xarray/core/dataset.py
+++ b/xarray/core/dataset.py
@@ -756,9 +756,15 @@ class Dataset(
         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 3baecfe5..fa5523b1 100644
--- a/xarray/core/variable.py
+++ b/xarray/core/variable.py
@@ -883,6 +883,12 @@ class Variable(NamedArray, AbstractArray, VariableArithmetic):
             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={})
 


Test patch:
diff --git a/xarray/tests/test_dataarray.py b/xarray/tests/test_dataarray.py
index d497cd5a..5eb5394d 100644
--- a/xarray/tests/test_dataarray.py
+++ b/xarray/tests/test_dataarray.py
@@ -287,7 +287,7 @@ class TestDataArray:
         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 @@ class TestDataArray:
         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 12347c8d..687aae8f 100644
--- a/xarray/tests/test_dataset.py
+++ b/xarray/tests/test_dataset.py
@@ -2959,7 +2959,7 @@ class TestDataset:
         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 @@ class TestDataset:
         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 1ffd51f4..73238b6a 100644
--- a/xarray/tests/test_variable.py
+++ b/xarray/tests/test_variable.py
@@ -473,12 +473,12 @@ class VariableSubclassobjects(ABC):
             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 @@ class VariableSubclassobjects(ABC):
         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 == {}