MNT: recommend write_crs & deprecate set_crs

docs/getting_started/crs_management.ipynb

@@ -527,7 +527,9 @@
     "This modifies the `xarray.Dataset` or `xarray.DataArray` and sets the CRS in a CF compliant manner.\n",
     "\n",
     "- [rio.write_crs()](../rioxarray.rst#rioxarray.rioxarray.XRasterBase.write_crs)\n",
-    "- [rio.crs](../rioxarray.rst#rioxarray.rioxarray.XRasterBase.crs)"
+    "- [rio.crs](../rioxarray.rst#rioxarray.rioxarray.XRasterBase.crs)\n",
+    "\n",
+    "**Note:** It is recommended to use `rio.write_crs()` if you want the CRS to persist on the Dataset/DataArray and to write the CRS CF compliant metadata. Calling only `rio.set_crs()` CRS storage method is lossy and will not modify the Dataset/DataArray metadata."
    ]
   },
   {
@@ -1098,7 +1100,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.4"
+   "version": "3.12.4"
   }
  },
  "nbformat": 4,

rioxarray/rioxarray.py

@@ -2,6 +2,7 @@
 This module is an extension for xarray to provide rasterio capabilities
 to xarray datasets/dataarrays.
 """
+
 # pylint: disable=too-many-lines
 import json
 import math
@@ -305,7 +306,7 @@ def crs(self) -> Optional[rasterio.crs.CRS]:
         # pyproj CRS if possible for performance
         for crs_attr in ("spatial_ref", "crs_wkt"):
             try:
-                self.set_crs(
+                self._set_crs(
                     self._obj.coords[self.grid_mapping].attrs[crs_attr],
                     inplace=True,
                 )
@@ -315,14 +316,14 @@ def crs(self) -> Optional[rasterio.crs.CRS]:
 
         # look in grid_mapping
         try:
-            self.set_crs(
+            self._set_crs(
                 pyproj.CRS.from_cf(self._obj.coords[self.grid_mapping].attrs),
                 inplace=True,
             )
         except (KeyError, pyproj.exceptions.CRSError):
             try:
                 # look in attrs for 'crs'
-                self.set_crs(self._obj.attrs["crs"], inplace=True)
+                self._set_crs(self._obj.attrs["crs"], inplace=True)
             except KeyError:
                 self._crs = False
                 return None
@@ -360,6 +361,10 @@ def set_crs(
         Set the CRS value for the Dataset/DataArray without modifying
         the dataset/data array.
 
+        .. deprecated:: 0.15.8
+            It is recommended to use `rio.write_crs()` instead. This
+        method will likely be removed in a future release.
+
         Parameters
         ----------
         input_crs: object
@@ -372,6 +377,34 @@ def set_crs(
         :obj:`xarray.Dataset` | :obj:`xarray.DataArray`:
             Dataset with crs attribute.
         """
+        warnings.warn(
+            "It is recommended to use 'rio.write_crs()' instead. 'rio.set_crs()' will likely"
+            "be removed in a future release.",
+            FutureWarning,
+            stacklevel=2,
+        )
+
+        return self._set_crs(input_crs, inplace=inplace)
+
+    def _set_crs(
+        self, input_crs: Any, inplace: bool = True
+    ) -> Union[xarray.Dataset, xarray.DataArray]:
+        """
+        Set the CRS value for the Dataset/DataArray without modifying
+        the dataset/data array.
+
+        Parameters
+        ----------
+        input_crs: object
+            Anything accepted by `rasterio.crs.CRS.from_user_input`.
+        inplace: bool, optional
+            If True, it will write to the existing dataset. Default is False.
+
+        Returns
+        -------
+        xarray.Dataset | xarray.DataArray
+            Dataset with crs attribute.
+        """
         crs = crs_from_user_input(input_crs)
         obj = self._get_obj(inplace=inplace)
         obj.rio._crs = crs
@@ -483,7 +516,7 @@ def write_crs(
         >>> raster = raster.rio.write_crs("epsg:4326")
         """
         if input_crs is not None:
-            data_obj = self.set_crs(input_crs, inplace=inplace)
+            data_obj = self._set_crs(input_crs, inplace=inplace)
         else:
             data_obj = self._get_obj(inplace=inplace)