Session.virtualfile_in: Deprecate parameter 'required_data' to 'required' (will be removed in v0.20.0) (#3931)

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

Author: seisman

pygmt/clib/session.py

@@ -28,6 +28,7 @@
 from pygmt.helpers import (
     _validate_data_input,
     data_kind,
+    deprecate_parameter,
     tempfile_from_geojson,
     tempfile_from_image,
 )
@@ -1750,15 +1751,19 @@ def virtualfile_from_stringio(
 
     # TODO(PyGMT>=0.20.0): Remove the deprecated parameter 'required_z'.
     # TODO(PyGMT>=0.20.0): Remove the deprecated parameter 'extra_arrays'.
+    # TODO(PyGMT>=0.20.0): Remove the deprecated parameter 'required_data'.
+    @deprecate_parameter(
+        "required_data", "required", "v0.16.0", remove_version="v0.20.0"
+    )
     def virtualfile_in(  # noqa: PLR0912
         self,
         check_kind=None,
         data=None,
         x=None,
         y=None,
         z=None,
+        required=True,
         mincols=2,
-        required_data=True,
         required_z=False,
         extra_arrays=None,
     ):
@@ -1780,12 +1785,16 @@ def virtualfile_in(  # noqa: PLR0912
             data input.
         x/y/z : 1-D arrays or None
             x, y, and z columns as numpy arrays.
+        required : bool
+            Set to True when 'data' or ('x' and 'y') is required. Set to False when
+            dealing with optional virtual files. Default is True.
+
+            .. versionchanged:: v0.16.0
+               The parameter 'required_data' is renamed to 'required'. The parameter
+               'required_data' is deprecated in v0.16.0 and will be removed in v0.20.0.
         mincols
             Number of minimum required columns. Default is 2 (i.e. require x and y
             columns).
-        required_data : bool
-            Set to True when 'data' is required, or False when dealing with
-            optional virtual files. [Default is True].
         required_z : bool
             State whether the 'z' column is required.
 
@@ -1838,19 +1847,19 @@ def virtualfile_in(  # noqa: PLR0912
             )
             mincols = 3
 
-        kind = data_kind(data, required=required_data)
+        kind = data_kind(data, required=required)
         _validate_data_input(
             data=data,
             x=x,
             y=y,
             z=z,
+            required=required,
             mincols=mincols,
-            required_data=required_data,
             kind=kind,
         )
 
         if check_kind:
-            valid_kinds = ("file", "arg") if required_data is False else ("file",)
+            valid_kinds = ("file", "arg") if required is False else ("file",)
             if check_kind == "raster":
                 valid_kinds += ("grid", "image")
             elif check_kind == "vector":

pygmt/helpers/utils.py

@@ -43,7 +43,7 @@
 
 
 def _validate_data_input(  # noqa: PLR0912
-    data=None, x=None, y=None, z=None, mincols=2, required_data=True, kind=None
+    data=None, x=None, y=None, z=None, required=True, mincols=2, kind=None
 ) -> None:
     """
     Check if the combination of data/x/y/z is valid.
@@ -53,7 +53,7 @@ def _validate_data_input(  # noqa: PLR0912
     >>> _validate_data_input(data="infile")
     >>> _validate_data_input(x=[1, 2, 3], y=[4, 5, 6])
     >>> _validate_data_input(x=[1, 2, 3], y=[4, 5, 6], z=[7, 8, 9])
-    >>> _validate_data_input(data=None, required_data=False)
+    >>> _validate_data_input(data=None, required=False)
     >>> _validate_data_input()
     Traceback (most recent call last):
         ...
@@ -119,7 +119,7 @@ def _validate_data_input(  # noqa: PLR0912
     required_z = mincols >= 3
     if data is None:  # data is None
         if x is None and y is None:  # both x and y are None
-            if required_data:  # data is not optional
+            if required:  # data is not optional
                 msg = "No input data provided."
                 raise GMTInvalidInput(msg)
         elif x is None or y is None:  # either x or y is None

pygmt/src/grdfill.py

@@ -225,7 +225,7 @@ def grdfill(
             # Fill mode.
             with (
                 lib.virtualfile_in(
-                    check_kind="raster", data=gridfill, required_data=False
+                    check_kind="raster", data=gridfill, required=False
                 ) as vbggrd,
                 lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd,
             ):

pygmt/src/grdimage.py

@@ -170,7 +170,7 @@ def grdimage(self, grid: PathLike | xr.DataArray, **kwargs):
         with (
             lib.virtualfile_in(check_kind="raster", data=grid) as vingrd,
             lib.virtualfile_in(
-                check_kind="raster", data=kwargs.get("I"), required_data=False
+                check_kind="raster", data=kwargs.get("I"), required=False
             ) as vshadegrid,
         ):
             kwargs["I"] = vshadegrid

pygmt/src/grdtrack.py

@@ -313,7 +313,7 @@ def grdtrack(
         with (
             lib.virtualfile_in(check_kind="raster", data=grid) as vingrd,
             lib.virtualfile_in(
-                check_kind="vector", data=points, required_data=False
+                check_kind="vector", data=points, required=False
             ) as vintbl,
             lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl,
         ):

pygmt/src/grdview.py

@@ -145,7 +145,7 @@ def grdview(self, grid: PathLike | xr.DataArray, **kwargs):
         with (
             lib.virtualfile_in(check_kind="raster", data=grid) as vingrd,
             lib.virtualfile_in(
-                check_kind="raster", data=kwargs.get("G"), required_data=False
+                check_kind="raster", data=kwargs.get("G"), required=False
             ) as vdrapegrid,
         ):
             kwargs["G"] = vdrapegrid

pygmt/src/legend.py

@@ -98,5 +98,5 @@ def legend(
         raise GMTInvalidInput(msg)
 
     with Session() as lib:
-        with lib.virtualfile_in(data=spec, required_data=False) as vintbl:
+        with lib.virtualfile_in(data=spec, required=False) as vintbl:
             lib.call_module(module="legend", args=build_arg_list(kwargs, infile=vintbl))

pygmt/src/project.py

@@ -247,7 +247,7 @@ def project(
                 y=y,
                 z=z,
                 mincols=2,
-                required_data=False,
+                required=False,
             ) as vintbl,
             lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl,
         ):

pygmt/src/text.py

@@ -190,8 +190,8 @@ def text_(  # noqa: PLR0912
         msg = "Provide either 'textfiles', 'x'/'y'/'text', or 'position'/'text'."
         raise GMTInvalidInput(msg)
 
-    required_data = position is None
-    kind = data_kind(textfiles, required=required_data)
+    data_is_required = position is None
+    kind = data_kind(textfiles, required=data_is_required)
 
     if position is not None and (text is None or is_nonstr_iter(text)):
         msg = "'text' can't be None or array when 'position' is given."
@@ -261,9 +261,7 @@ def text_(  # noqa: PLR0912
 
     with Session() as lib:
         with lib.virtualfile_in(
-            check_kind="vector",
-            data=textfiles or data,
-            required_data=required_data,
+            check_kind="vector", data=textfiles or data, required=data_is_required
         ) as vintbl:
             lib.call_module(
                 module="text",