pygmt.surface: Deprecate parameter "outfile" to "outgrid" (remove in v0.7.0) (GenericMappingTools#1458)

* Rename outfile to outgrid in surface

* Switch outfile to outgrid in test file

* Update pygmt/tests/test_surface.py

Co-authored-by: Meghan Jones <meghanj@alum.mit.edu>
Co-authored-by: actions-bot <58130806+actions-bot@users.noreply.github.com>

Author: 3 people

pygmt/src/surface.py

@@ -9,6 +9,7 @@
     GMTTempFile,
     build_arg_string,
     data_kind,
+    deprecate_parameter,
     dummy_context,
     fmt_docstring,
     kwargs_to_strings,
@@ -17,10 +18,11 @@
 
 
 @fmt_docstring
+@deprecate_parameter("outfile", "outgrid", "v0.5.0", remove_version="v0.7.0")
 @use_alias(
     I="spacing",
     R="region",
-    G="outfile",
+    G="outgrid",
     V="verbose",
     a="aspatial",
     f="coltypes",
@@ -60,7 +62,7 @@ def surface(x=None, y=None, z=None, data=None, **kwargs):
         *xmin/xmax/ymin/ymax*\[**+r**][**+u**\ *unit*].
         Specify the region of interest.
 
-    outfile : str
+    outgrid : str
         Optional. The file name for the output netcdf file with extension .nc
         to store the grid in.
 
@@ -72,11 +74,11 @@ def surface(x=None, y=None, z=None, data=None, **kwargs):
     Returns
     -------
     ret: xarray.DataArray or None
-        Return type depends on whether the ``outfile`` parameter is set:
+        Return type depends on whether the ``outgrid`` parameter is set:
 
-        - :class:`xarray.DataArray`: if ``outfile`` is not set
-        - None if ``outfile`` is set (grid output will be stored in file set by
-          ``outfile``)
+        - :class:`xarray.DataArray`: if ``outgrid`` is not set
+        - None if ``outgrid`` is set (grid output will be stored in file set by
+          ``outgrid``)
     """
     kind = data_kind(data, x, y, z)
     if kind == "vectors" and z is None:
@@ -93,17 +95,17 @@ def surface(x=None, y=None, z=None, data=None, **kwargs):
             else:
                 raise GMTInvalidInput("Unrecognized data type: {}".format(type(data)))
             with file_context as infile:
-                if "G" not in kwargs.keys():  # if outfile is unset, output to tmpfile
+                if "G" not in kwargs.keys():  # if outgrid is unset, output to tmpfile
                     kwargs.update({"G": tmpfile.name})
-                outfile = kwargs["G"]
+                outgrid = kwargs["G"]
                 arg_str = " ".join([infile, build_arg_string(kwargs)])
                 lib.call_module(module="surface", args=arg_str)
 
-        if outfile == tmpfile.name:  # if user did not set outfile, return DataArray
-            with xr.open_dataarray(outfile) as dataarray:
+        if outgrid == tmpfile.name:  # if user did not set outgrid, return DataArray
+            with xr.open_dataarray(outgrid) as dataarray:
                 result = dataarray.load()
                 _ = result.gmt  # load GMTDataArray accessor information
-        elif outfile != tmpfile.name:  # if user sets an outfile, return None
+        elif outgrid != tmpfile.name:  # if user sets an outgrid, return None
             result = None
 
     return result

pygmt/tests/test_surface.py

@@ -82,34 +82,55 @@ def test_surface_wrong_kind_of_input(ship_data):
         surface(data=data, spacing="5m", region=[245, 255, 20, 30])
 
 
-def test_surface_with_outfile_param(ship_data):
+def test_surface_with_outgrid_param(ship_data):
     """
     Run surface with the -Goutputfile.nc parameter.
     """
     data = ship_data.values  # convert pandas.DataFrame to numpy.ndarray
     try:
         output = surface(
-            data=data, spacing="5m", region=[245, 255, 20, 30], outfile=TEMP_GRID
+            data=data, spacing="5m", region=[245, 255, 20, 30], outgrid=TEMP_GRID
         )
-        assert output is None  # check that output is None since outfile is set
-        assert os.path.exists(path=TEMP_GRID)  # check that outfile exists at path
+        assert output is None  # check that output is None since outgrid is set
+        assert os.path.exists(path=TEMP_GRID)  # check that outgrid exists at path
         with xr.open_dataarray(TEMP_GRID) as grid:
             assert isinstance(grid, xr.DataArray)  # ensure netcdf grid loads ok
     finally:
         os.remove(path=TEMP_GRID)
     return output
 
 
+def test_surface_deprecate_outfile_to_outgrid(ship_data):
+    """
+    Make sure that the old parameter "outfile" is supported and it reports a
+    warning.
+    """
+    with pytest.warns(expected_warning=FutureWarning) as record:
+        data = ship_data.values  # convert pandas.DataFrame to numpy.ndarray
+        try:
+            output = surface(
+                data=data, spacing="5m", region=[245, 255, 20, 30], outfile=TEMP_GRID
+            )
+            assert output is None  # check that output is None since outfile is set
+            assert os.path.exists(path=TEMP_GRID)  # check that file exists at path
+
+            with xr.open_dataarray(TEMP_GRID) as grid:
+                assert isinstance(grid, xr.DataArray)  # ensure netcdf grid loads ok
+        finally:
+            os.remove(path=TEMP_GRID)
+        assert len(record) == 1  # check that only one warning was raised
+
+
 def test_surface_short_aliases(ship_data):
     """
     Run surface using short aliases -I for spacing, -R for region, -G for
-    outfile.
+    outgrid.
     """
     data = ship_data.values  # convert pandas.DataFrame to numpy.ndarray
     try:
         output = surface(data=data, I="5m", R=[245, 255, 20, 30], G=TEMP_GRID)
-        assert output is None  # check that output is None since outfile is set
-        assert os.path.exists(path=TEMP_GRID)  # check that outfile exists at path
+        assert output is None  # check that output is None since outgrid is set
+        assert os.path.exists(path=TEMP_GRID)  # check that outgrid exists at path
         with xr.open_dataarray(TEMP_GRID) as grid:
             assert isinstance(grid, xr.DataArray)  # ensure netcdf grid loads ok
     finally: