DEP: Deprecate rasterio backend (pydata#5808)

* DEP: Deprecate rasterio backend

* DOC: remove experimental

Co-authored-by: keewis <keewis@users.noreply.github.com>

* DOC: open rasterio in what's new

Co-authored-by: keewis <keewis@users.noreply.github.com>

* add a note to update deprecations on version change before releasing

* add the github handle [skip-ci]

Co-authored-by: keewis <keewis@users.noreply.github.com>
Co-authored-by: Keewis <keewis@posteo.de>

doc/user-guide/io.rst

@@ -742,6 +742,12 @@ GeoTIFFs and other gridded raster datasets can be opened using `rasterio`_, if
 rasterio is installed. Here is an example of how to use
 :py:func:`open_rasterio` to read one of rasterio's `test files`_:
 
+.. deprecated:: 0.19.1
+
+        Deprecated in favor of rioxarray.
+        For information about transitioning, see:
+        https://corteva.github.io/rioxarray/stable/getting_started/getting_started.html
+
 .. ipython::
     :verbatim:
 
@@ -769,12 +775,6 @@ coordinates defined in the file's projection provided by the ``crs`` attribute.
 See :ref:`/examples/visualization_gallery.ipynb#Parsing-rasterio-geocoordinates`
 for an example of how to convert these to longitudes and latitudes.
 
-.. warning::
-
-    This feature has been added in xarray v0.9.6 and should still be
-    considered experimental. Please report any bugs you may find
-    on xarray's github repository.
-
 
 Additionally, you can use `rioxarray`_ for reading in GeoTiff, netCDF or other
 GDAL readable raster data using `rasterio`_ as well as for exporting to a geoTIFF.

doc/whats-new.rst

@@ -19,6 +19,7 @@ What's New
 
 v0.19.1 (unreleased)
 ---------------------
+.. TODO(by keewis): update deprecations if we decide to skip 0.19.1
 
 New Features
 ~~~~~~~~~~~~
@@ -56,6 +57,8 @@ Breaking changes
 Deprecations
 ~~~~~~~~~~~~
 
+- Deprecate :py:func:`open_rasterio` (:issue:`4697`, :pull:`5808`).
+  By `Alan Snow <https://github.com/snowman2>`_.
 - Set the default argument for `roll_coords` to `False` for :py:meth:`DataArray.roll`
   and :py:meth:`Dataset.roll`. (:pull:`5653`)
   By `Tom Nicholas <https://github.com/TomNicholas>`_.

xarray/backends/rasterio_.py

@@ -170,7 +170,13 @@ def open_rasterio(
     lock=None,
     **kwargs,
 ):
-    """Open a file with rasterio (experimental).
+    """Open a file with rasterio.
+
+    .. deprecated:: 0.19.1
+
+        Deprecated in favor of rioxarray.
+        For information about transitioning, see:
+        https://corteva.github.io/rioxarray/stable/getting_started/getting_started.html
 
     This should work with any file that rasterio can open (most often:
     geoTIFF). The x and y coordinates are generated automatically from the
@@ -252,6 +258,13 @@ def open_rasterio(
     data : DataArray
         The newly created DataArray.
     """
+    warnings.warn(
+        "open_rasterio is Deprecated in favor of rioxarray. "
+        "For information about transitioning, see: "
+        "https://corteva.github.io/rioxarray/stable/getting_started/getting_started.html",
+        DeprecationWarning,
+        stacklevel=2,
+    )
     import rasterio
     from rasterio.vrt import WarpedVRT
 

xarray/tests/test_backends.py

@@ -4212,15 +4212,15 @@ class TestRasterio:
     def test_serialization(self):
         with create_tmp_geotiff(additional_attrs={}) as (tmp_file, expected):
             # Write it to a netcdf and read again (roundtrip)
-            with xr.open_rasterio(tmp_file) as rioda:
+            with pytest.warns(DeprecationWarning), xr.open_rasterio(tmp_file) as rioda:
                 with create_tmp_file(suffix=".nc") as tmp_nc_file:
                     rioda.to_netcdf(tmp_nc_file)
                     with xr.open_dataarray(tmp_nc_file) as ncds:
                         assert_identical(rioda, ncds)
 
     def test_utm(self):
         with create_tmp_geotiff() as (tmp_file, expected):
-            with xr.open_rasterio(tmp_file) as rioda:
+            with pytest.warns(DeprecationWarning), xr.open_rasterio(tmp_file) as rioda:
                 assert_allclose(rioda, expected)
                 assert rioda.attrs["scales"] == (1.0, 1.0, 1.0)
                 assert rioda.attrs["offsets"] == (0.0, 0.0, 0.0)
@@ -4236,7 +4236,9 @@ def test_utm(self):
                 )
 
             # Check no parse coords
-            with xr.open_rasterio(tmp_file, parse_coordinates=False) as rioda:
+            with pytest.warns(DeprecationWarning), xr.open_rasterio(
+                tmp_file, parse_coordinates=False
+            ) as rioda:
                 assert "x" not in rioda.coords
                 assert "y" not in rioda.coords
 
@@ -4248,7 +4250,7 @@ def test_non_rectilinear(self):
             transform=from_origin(0, 3, 1, 1).rotation(45), crs=None
         ) as (tmp_file, _):
             # Default is to not parse coords
-            with xr.open_rasterio(tmp_file) as rioda:
+            with pytest.warns(DeprecationWarning), xr.open_rasterio(tmp_file) as rioda:
                 assert "x" not in rioda.coords
                 assert "y" not in rioda.coords
                 assert "crs" not in rioda.attrs
@@ -4276,7 +4278,7 @@ def test_platecarree(self):
             crs="+proj=latlong",
             open_kwargs={"nodata": -9765},
         ) as (tmp_file, expected):
-            with xr.open_rasterio(tmp_file) as rioda:
+            with pytest.warns(DeprecationWarning), xr.open_rasterio(tmp_file) as rioda:
                 assert_allclose(rioda, expected)
                 assert rioda.attrs["scales"] == (1.0,)
                 assert rioda.attrs["offsets"] == (0.0,)
@@ -4324,7 +4326,7 @@ def test_notransform(self):
                     "x": [0.5, 1.5, 2.5, 3.5],
                 },
             )
-            with xr.open_rasterio(tmp_file) as rioda:
+            with pytest.warns(DeprecationWarning), xr.open_rasterio(tmp_file) as rioda:
                 assert_allclose(rioda, expected)
                 assert rioda.attrs["scales"] == (1.0, 1.0, 1.0)
                 assert rioda.attrs["offsets"] == (0.0, 0.0, 0.0)
@@ -4339,7 +4341,9 @@ def test_indexing(self):
         with create_tmp_geotiff(
             8, 10, 3, transform_args=[1, 2, 0.5, 2.0], crs="+proj=latlong"
         ) as (tmp_file, expected):
-            with xr.open_rasterio(tmp_file, cache=False) as actual:
+            with pytest.warns(DeprecationWarning), xr.open_rasterio(
+                tmp_file, cache=False
+            ) as actual:
 
                 # tests
                 # assert_allclose checks all data + coordinates
@@ -4455,7 +4459,7 @@ def test_caching(self):
             8, 10, 3, transform_args=[1, 2, 0.5, 2.0], crs="+proj=latlong"
         ) as (tmp_file, expected):
             # Cache is the default
-            with xr.open_rasterio(tmp_file) as actual:
+            with pytest.warns(DeprecationWarning), xr.open_rasterio(tmp_file) as actual:
 
                 # This should cache everything
                 assert_allclose(actual, expected)
@@ -4471,7 +4475,9 @@ def test_chunks(self):
             8, 10, 3, transform_args=[1, 2, 0.5, 2.0], crs="+proj=latlong"
         ) as (tmp_file, expected):
             # Chunk at open time
-            with xr.open_rasterio(tmp_file, chunks=(1, 2, 2)) as actual:
+            with pytest.warns(DeprecationWarning), xr.open_rasterio(
+                tmp_file, chunks=(1, 2, 2)
+            ) as actual:
 
                 import dask.array as da
 
@@ -4493,7 +4499,7 @@ def test_chunks(self):
     def test_pickle_rasterio(self):
         # regression test for https://github.com/pydata/xarray/issues/2121
         with create_tmp_geotiff() as (tmp_file, expected):
-            with xr.open_rasterio(tmp_file) as rioda:
+            with pytest.warns(DeprecationWarning), xr.open_rasterio(tmp_file) as rioda:
                 temp = pickle.dumps(rioda)
                 with pickle.loads(temp) as actual:
                     assert_equal(actual, rioda)
@@ -4545,7 +4551,7 @@ def test_ENVI_tags(self):
             }
             expected = DataArray(data, dims=("band", "y", "x"), coords=coords)
 
-            with xr.open_rasterio(tmp_file) as rioda:
+            with pytest.warns(DeprecationWarning), xr.open_rasterio(tmp_file) as rioda:
                 assert_allclose(rioda, expected)
                 assert isinstance(rioda.attrs["crs"], str)
                 assert isinstance(rioda.attrs["res"], tuple)
@@ -4560,7 +4566,7 @@ def test_ENVI_tags(self):
     def test_geotiff_tags(self):
         # Create a geotiff file with some tags
         with create_tmp_geotiff() as (tmp_file, _):
-            with xr.open_rasterio(tmp_file) as rioda:
+            with pytest.warns(DeprecationWarning), xr.open_rasterio(tmp_file) as rioda:
                 assert isinstance(rioda.attrs["AREA_OR_POINT"], str)
 
     @requires_dask
@@ -4575,7 +4581,9 @@ def test_no_mftime(self):
             8, 10, 3, transform_args=[1, 2, 0.5, 2.0], crs="+proj=latlong"
         ) as (tmp_file, expected):
             with mock.patch("os.path.getmtime", side_effect=OSError):
-                with xr.open_rasterio(tmp_file, chunks=(1, 2, 2)) as actual:
+                with pytest.warns(DeprecationWarning), xr.open_rasterio(
+                    tmp_file, chunks=(1, 2, 2)
+                ) as actual:
                     import dask.array as da
 
                     assert isinstance(actual.data, da.Array)
@@ -4586,10 +4594,12 @@ def test_http_url(self):
         # more examples urls here
         # http://download.osgeo.org/geotiff/samples/
         url = "http://download.osgeo.org/geotiff/samples/made_up/ntf_nord.tif"
-        with xr.open_rasterio(url) as actual:
+        with pytest.warns(DeprecationWarning), xr.open_rasterio(url) as actual:
             assert actual.shape == (1, 512, 512)
         # make sure chunking works
-        with xr.open_rasterio(url, chunks=(1, 256, 256)) as actual:
+        with pytest.warns(DeprecationWarning), xr.open_rasterio(
+            url, chunks=(1, 256, 256)
+        ) as actual:
             import dask.array as da
 
             assert isinstance(actual.data, da.Array)
@@ -4601,7 +4611,9 @@ def test_rasterio_environment(self):
             # Should fail with error since suffix not allowed
             with pytest.raises(Exception):
                 with rasterio.Env(GDAL_SKIP="GTiff"):
-                    with xr.open_rasterio(tmp_file) as actual:
+                    with pytest.warns(DeprecationWarning), xr.open_rasterio(
+                        tmp_file
+                    ) as actual:
                         assert_allclose(actual, expected)
 
     @pytest.mark.xfail(reason="rasterio 1.1.1 is broken. GH3573")
@@ -4618,7 +4630,7 @@ def test_rasterio_vrt(self):
                     # Value of single pixel in center of image
                     lon, lat = vrt.xy(vrt.width // 2, vrt.height // 2)
                     expected_val = next(vrt.sample([(lon, lat)]))
-                    with xr.open_rasterio(vrt) as da:
+                    with pytest.warns(DeprecationWarning), xr.open_rasterio(vrt) as da:
                         actual_shape = (da.sizes["x"], da.sizes["y"])
                         actual_crs = da.crs
                         actual_res = da.res
@@ -4672,7 +4684,7 @@ def test_rasterio_vrt_with_src_crs(self):
             with rasterio.open(tmp_file) as src:
                 assert src.crs is None
                 with rasterio.vrt.WarpedVRT(src, src_crs=src_crs) as vrt:
-                    with xr.open_rasterio(vrt) as da:
+                    with pytest.warns(DeprecationWarning), xr.open_rasterio(vrt) as da:
                         assert da.crs == src_crs
 
     @network
@@ -4692,7 +4704,7 @@ def test_rasterio_vrt_network(self):
                     # Value of single pixel in center of image
                     lon, lat = vrt.xy(vrt.width // 2, vrt.height // 2)
                     expected_val = next(vrt.sample([(lon, lat)]))
-                    with xr.open_rasterio(vrt) as da:
+                    with pytest.warns(DeprecationWarning), xr.open_rasterio(vrt) as da:
                         actual_shape = da.sizes["x"], da.sizes["y"]
                         actual_res = da.res
                         actual_val = da.sel(dict(x=lon, y=lat), method="nearest").data

xarray/tests/test_distributed.py

@@ -163,7 +163,7 @@ def test_dask_distributed_zarr_integration_test(loop, consolidated, compute) ->
 def test_dask_distributed_rasterio_integration_test(loop) -> None:
     with create_tmp_geotiff() as (tmp_file, expected):
         with cluster() as (s, [a, b]):
-            with Client(s["address"], loop=loop):
+            with pytest.warns(DeprecationWarning), Client(s["address"], loop=loop):
                 da_tiff = xr.open_rasterio(tmp_file, chunks={"band": 1})
                 assert isinstance(da_tiff.data, da.Array)
                 actual = da_tiff.compute()

xarray/tests/test_tutorial.py

@@ -32,11 +32,11 @@ def test_download_rasterio_from_github_load_without_cache(
         self, tmp_path, monkeypatch
     ):
         cache_dir = tmp_path / tutorial._default_cache_dir_name
-
-        arr_nocache = tutorial.open_rasterio(
-            "RGB.byte", cache=False, cache_dir=cache_dir
-        ).load()
-        arr_cache = tutorial.open_rasterio(
-            "RGB.byte", cache=True, cache_dir=cache_dir
-        ).load()
+        with pytest.warns(DeprecationWarning):
+            arr_nocache = tutorial.open_rasterio(
+                "RGB.byte", cache=False, cache_dir=cache_dir
+            ).load()
+            arr_cache = tutorial.open_rasterio(
+                "RGB.byte", cache=True, cache_dir=cache_dir
+            ).load()
         assert_identical(arr_cache, arr_nocache)