pygmt.info: Deprecate parameter "table" to "data" (remove in v0.7.0) (#1538)

Co-authored-by: Wei Ji <[email protected]>

Author: seisman

pygmt/src/info.py

@@ -6,13 +6,15 @@
 from pygmt.helpers import (
     GMTTempFile,
     build_arg_string,
+    deprecate_parameter,
     fmt_docstring,
     kwargs_to_strings,
     use_alias,
 )
 
 
 @fmt_docstring
+@deprecate_parameter("table", "data", "v0.5.0", remove_version="v0.7.0")
 @use_alias(
     C="per_column",
     I="spacing",
@@ -24,7 +26,7 @@
     r="registration",
 )
 @kwargs_to_strings(I="sequence", i="sequence_comma")
-def info(table, **kwargs):
+def info(data, **kwargs):
     r"""
     Get information about data tables.
 
@@ -47,7 +49,7 @@ def info(table, **kwargs):
 
     Parameters
     ----------
-    table : str or {table-like}
+    data : str or {table-like}
         Pass in either a file name to an ASCII data table, a 1D/2D
         {table-classes}.
     per_column : bool
@@ -80,7 +82,7 @@ def info(table, **kwargs):
         - str if none of the above parameters are used.
     """
     with Session() as lib:
-        file_context = lib.virtualfile_from_data(data=table)
+        file_context = lib.virtualfile_from_data(check_kind="vector", data=data)
         with GMTTempFile() as tmpfile:
             with file_context as fname:
                 arg_str = " ".join(

pygmt/tests/test_geopandas.py

@@ -44,7 +44,7 @@ def test_geopandas_info_geodataframe(gdf):
     Check that info can return the bounding box region from a
     geopandas.GeoDataFrame.
     """
-    output = info(table=gdf, per_column=True)
+    output = info(data=gdf, per_column=True)
     npt.assert_allclose(actual=output, desired=[0.0, 35.0, 0.0, 20.0])
 
 
@@ -62,7 +62,7 @@ def test_geopandas_info_shapely(gdf, geomtype, desired):
     object that has a __geo_interface__ property.
     """
     geom = gdf.loc[geomtype].geometry
-    output = info(table=geom, per_column=True)
+    output = info(data=geom, per_column=True)
     npt.assert_allclose(actual=output, desired=desired)
 
 

pygmt/tests/test_info.py

@@ -21,7 +21,7 @@ def test_info():
     """
     Make sure info works on file name inputs.
     """
-    output = info(table=POINTS_DATA)
+    output = info(data=POINTS_DATA)
     expected_output = (
         f"{POINTS_DATA}: N = 20 "
         "<11.5309/61.7074> "
@@ -31,6 +31,23 @@ def test_info():
     assert output == expected_output
 
 
+def test_info_deprecate_table_to_data():
+    """
+    Make sure that the old parameter "table" is supported and it reports a
+    warning.
+    """
+    with pytest.warns(expected_warning=FutureWarning) as record:
+        output = info(table=POINTS_DATA)  # pylint: disable=no-value-for-parameter
+        expected_output = (
+            f"{POINTS_DATA}: N = 20 "
+            "<11.5309/61.7074> "
+            "<-2.9289/7.8648> "
+            "<0.1412/0.9338>\n"
+        )
+        assert output == expected_output
+        assert len(record) == 1  # check that only one warning was raised
+
+
 @pytest.mark.parametrize(
     "table",
     [
@@ -55,7 +72,7 @@ def test_info_path(table):
     """
     Make sure info works on a pathlib.Path input.
     """
-    output = info(table=table)
+    output = info(data=table)
     expected_output = (
         f"{POINTS_DATA}: N = 20 "
         "<11.5309/61.7074> "
@@ -69,7 +86,7 @@ def test_info_2d_list():
     """
     Make sure info works on a 2d list.
     """
-    output = info(table=[[0, 8], [3, 5], [6, 2]])
+    output = info(data=[[0, 8], [3, 5], [6, 2]])
     expected_output = "<vector memory>: N = 3 <0/6> <2/8>\n"
     assert output == expected_output
 
@@ -88,7 +105,7 @@ def test_info_dataframe():
     Make sure info works on pandas.DataFrame inputs.
     """
     table = pd.read_csv(POINTS_DATA, sep=" ", header=None)
-    output = info(table=table)
+    output = info(data=table)
     expected_output = (
         "<vector memory>: N = 20 <11.5309/61.7074> <-2.9289/7.8648> <0.1412/0.9338>\n"
     )
@@ -100,7 +117,7 @@ def test_info_numpy_array_time_column():
     Make sure info works on a numpy.ndarray input with a datetime type.
     """
     table = pd.date_range(start="2020-01-01", periods=5).to_numpy()
-    output = info(table=table)
+    output = info(data=table)
     expected_output = (
         "<vector memory>: N = 5 <2020-01-01T00:00:00/2020-01-05T00:00:00>\n"
     )
@@ -117,7 +134,7 @@ def test_info_pandas_dataframe_time_column():
             "time": pd.date_range(start="2020-01-01", periods=5),
         }
     )
-    output = info(table=table)
+    output = info(data=table)
     expected_output = (
         "<vector memory>: N = 5 <10/15> <2020-01-01T00:00:00/2020-01-05T00:00:00>\n"
     )
@@ -135,7 +152,7 @@ def test_info_xarray_dataset_time_column():
             "time": ("index", pd.date_range(start="2020-01-01", periods=5)),
         },
     )
-    output = info(table=table)
+    output = info(data=table)
     expected_output = (
         "<vector memory>: N = 5 <10/15> <2020-01-01T00:00:00/2020-01-05T00:00:00>\n"
     )
@@ -147,7 +164,7 @@ def test_info_2d_array():
     Make sure info works on 2D numpy.ndarray inputs.
     """
     table = np.loadtxt(POINTS_DATA)
-    output = info(table=table)
+    output = info(data=table)
     expected_output = (
         "<matrix memory>: N = 20 <11.5309/61.7074> <-2.9289/7.8648> <0.1412/0.9338>\n"
     )
@@ -158,7 +175,7 @@ def test_info_1d_array():
     """
     Make sure info works on 1D numpy.ndarray inputs.
     """
-    output = info(table=np.arange(20))
+    output = info(data=np.arange(20))
     expected_output = "<vector memory>: N = 20 <0/19>\n"
     assert output == expected_output
 
@@ -167,7 +184,7 @@ def test_info_per_column():
     """
     Make sure the per_column option works.
     """
-    output = info(table=POINTS_DATA, per_column=True)
+    output = info(data=POINTS_DATA, per_column=True)
     npt.assert_allclose(
         actual=output, desired=[11.5309, 61.7074, -2.9289, 7.8648, 0.1412, 0.9338]
     )
@@ -178,7 +195,7 @@ def test_info_per_column_with_time_inputs():
     Make sure the per_column option works with time inputs.
     """
     table = pd.date_range(start="2020-01-01", periods=5).to_numpy()
-    output = info(table=table, per_column=True)
+    output = info(data=table, per_column=True)
     npt.assert_equal(
         actual=output, desired=["2020-01-01T00:00:00", "2020-01-05T00:00:00"]
     )
@@ -188,15 +205,15 @@ def test_info_spacing():
     """
     Make sure the spacing option works.
     """
-    output = info(table=POINTS_DATA, spacing=0.1)
+    output = info(data=POINTS_DATA, spacing=0.1)
     npt.assert_allclose(actual=output, desired=[11.5, 61.8, -3, 7.9])
 
 
 def test_info_spacing_bounding_box():
     """
     Make sure the spacing option for writing a bounding box works.
     """
-    output = info(table=POINTS_DATA, spacing="b")
+    output = info(data=POINTS_DATA, spacing="b")
     npt.assert_allclose(
         actual=output,
         desired=[
@@ -213,15 +230,15 @@ def test_info_per_column_spacing():
     """
     Make sure the per_column and spacing options work together.
     """
-    output = info(table=POINTS_DATA, per_column=True, spacing=0.1)
+    output = info(data=POINTS_DATA, per_column=True, spacing=0.1)
     npt.assert_allclose(actual=output, desired=[11.5, 61.8, -3, 7.9, 0.1412, 0.9338])
 
 
 def test_info_nearest_multiple():
     """
     Make sure the nearest_multiple option works.
     """
-    output = info(table=POINTS_DATA, nearest_multiple=0.1)
+    output = info(data=POINTS_DATA, nearest_multiple=0.1)
     npt.assert_allclose(actual=output, desired=[11.5, 61.8, 0.1])
 
 
@@ -231,4 +248,4 @@ def test_info_fails():
     DataFrame, or numpy ndarray.
     """
     with pytest.raises(GMTInvalidInput):
-        info(table=xr.DataArray(21))
+        info(data=xr.DataArray(21))