diff --git a/pygmt/clib/session.py b/pygmt/clib/session.py index 7680e81108e..eba799660f3 100644 --- a/pygmt/clib/session.py +++ b/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,6 +1751,10 @@ 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, @@ -1757,8 +1762,8 @@ def virtualfile_in( # noqa: PLR0912 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": diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py index 7223e45fe94..9e8858faec3 100644 --- a/pygmt/helpers/utils.py +++ b/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 diff --git a/pygmt/src/grdfill.py b/pygmt/src/grdfill.py index 46297ed418d..a45b21cebbd 100644 --- a/pygmt/src/grdfill.py +++ b/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, ): diff --git a/pygmt/src/grdimage.py b/pygmt/src/grdimage.py index ccdb7a1d09b..8e2e136ae55 100644 --- a/pygmt/src/grdimage.py +++ b/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 diff --git a/pygmt/src/grdtrack.py b/pygmt/src/grdtrack.py index 97fa441fa47..a7bb1c96c8b 100644 --- a/pygmt/src/grdtrack.py +++ b/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, ): diff --git a/pygmt/src/grdview.py b/pygmt/src/grdview.py index d2f754ccf57..23141e79ea9 100644 --- a/pygmt/src/grdview.py +++ b/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 diff --git a/pygmt/src/legend.py b/pygmt/src/legend.py index 9593cf1f2f2..16d58a08571 100644 --- a/pygmt/src/legend.py +++ b/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)) diff --git a/pygmt/src/project.py b/pygmt/src/project.py index 1356b84495f..d4986806b4a 100644 --- a/pygmt/src/project.py +++ b/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, ): diff --git a/pygmt/src/text.py b/pygmt/src/text.py index 7605776013e..eb232430439 100644 --- a/pygmt/src/text.py +++ b/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",