Rename required_ncols to the shorter ncols

seisman · seisman · commit 5eeb37bcb311 · 2025-03-10T16:08:06.000+08:00
diff --git a/pygmt/clib/session.py b/pygmt/clib/session.py
@@ -1774,7 +1774,7 @@ def virtualfile_in(
         z=None,
         extra_arrays=None,
         required_data=True,
-        required_ncols=2,
+        ncols=2,
     ):
         """
         Store any data inside a virtual file.
@@ -1800,7 +1800,7 @@ def virtualfile_in(
         required_data : bool
             Set to True when 'data' is required, or False when dealing with
             optional virtual files. [Default is True].
-        required_ncols
+        ncols
             Number of minimum required columns.
 
         Returns
@@ -1836,7 +1836,7 @@ def virtualfile_in(
             y=y,
             z=z,
             required_data=required_data,
-            required_ncols=required_ncols,
+            ncols=ncols,
             kind=kind,
         )
 
diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py
@@ -42,7 +42,7 @@
 
 
 def _validate_data_input(
-    data=None, x=None, y=None, z=None, required_data=True, required_ncols=2, kind=None
+    data=None, x=None, y=None, z=None, required_data=True, ncols=2, kind=None
 ) -> None:
     """
     Check if the combination of data/x/y/z is valid.
@@ -65,29 +65,29 @@ def _validate_data_input(
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Must provide both x and y.
-    >>> _validate_data_input(x=[1, 2, 3], y=[4, 5, 6], required_ncols=3)
+    >>> _validate_data_input(x=[1, 2, 3], y=[4, 5, 6], ncols=3)
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Must provide x, y, and z.
     >>> import numpy as np
     >>> import pandas as pd
     >>> import xarray as xr
     >>> data = np.arange(8).reshape((4, 2))
-    >>> _validate_data_input(data=data, required_ncols=3, kind="matrix")
+    >>> _validate_data_input(data=data, ncols=3, kind="matrix")
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: data must provide x, y, and z columns.
     >>> _validate_data_input(
     ...     data=pd.DataFrame(data, columns=["x", "y"]),
-    ...     required_ncols=3,
+    ...     ncols=3,
     ...     kind="vectors",
     ... )
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: data must provide x, y, and z columns.
     >>> _validate_data_input(
     ...     data=xr.Dataset(pd.DataFrame(data, columns=["x", "y"])),
-    ...     required_ncols=3,
+    ...     ncols=3,
     ...     kind="vectors",
     ... )
     Traceback (most recent call last):
@@ -115,7 +115,7 @@ def _validate_data_input(
     GMTInvalidInput
         If the data input is not valid.
     """
-    required_z = required_ncols >= 3
+    required_z = ncols >= 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
diff --git a/pygmt/src/blockm.py b/pygmt/src/blockm.py
@@ -55,7 +55,7 @@ def _blockm(
     with Session() as lib:
         with (
             lib.virtualfile_in(
-                check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=3
+                check_kind="vector", data=data, x=x, y=y, z=z, ncols=3
             ) as vintbl,
             lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl,
         ):
diff --git a/pygmt/src/contour.py b/pygmt/src/contour.py
@@ -145,7 +145,7 @@ def contour(self, data=None, x=None, y=None, z=None, **kwargs):
 
     with Session() as lib:
         with lib.virtualfile_in(
-            check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=3
+            check_kind="vector", data=data, x=x, y=y, z=z, ncols=3
         ) as vintbl:
             lib.call_module(
                 module="contour", args=build_arg_list(kwargs, infile=vintbl)
diff --git a/pygmt/src/nearneighbor.py b/pygmt/src/nearneighbor.py
@@ -141,7 +141,7 @@ def nearneighbor(
     with Session() as lib:
         with (
             lib.virtualfile_in(
-                check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=3
+                check_kind="vector", data=data, x=x, y=y, z=z, ncols=3
             ) as vintbl,
             lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd,
         ):
diff --git a/pygmt/src/plot3d.py b/pygmt/src/plot3d.py
@@ -263,6 +263,6 @@ def plot3d(
             y=y,
             z=z,
             extra_arrays=extra_arrays,
-            required_ncols=3,
+            ncols=3,
         ) as vintbl:
             lib.call_module(module="plot3d", args=build_arg_list(kwargs, infile=vintbl))
diff --git a/pygmt/src/project.py b/pygmt/src/project.py
@@ -245,7 +245,7 @@ def project(
                 x=x,
                 y=y,
                 z=z,
-                required_ncols=2,
+                ncols=2,
                 required_data=False,
             ) as vintbl,
             lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl,
diff --git a/pygmt/src/surface.py b/pygmt/src/surface.py
@@ -155,7 +155,7 @@ def surface(
     with Session() as lib:
         with (
             lib.virtualfile_in(
-                check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=3
+                check_kind="vector", data=data, x=x, y=y, z=z, ncols=3
             ) as vintbl,
             lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd,
         ):
diff --git a/pygmt/src/triangulate.py b/pygmt/src/triangulate.py
@@ -138,7 +138,7 @@ def regular_grid(
         with Session() as lib:
             with (
                 lib.virtualfile_in(
-                    check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=2
+                    check_kind="vector", data=data, x=x, y=y, z=z, ncols=2
                 ) as vintbl,
                 lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd,
             ):
@@ -238,7 +238,7 @@ def delaunay_triples(
         with Session() as lib:
             with (
                 lib.virtualfile_in(
-                    check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=2
+                    check_kind="vector", data=data, x=x, y=y, z=z, ncols=2
                 ) as vintbl,
                 lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl,
             ):
diff --git a/pygmt/src/wiggle.py b/pygmt/src/wiggle.py
@@ -108,6 +108,6 @@ def wiggle(
 
     with Session() as lib:
         with lib.virtualfile_in(
-            check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=3
+            check_kind="vector", data=data, x=x, y=y, z=z, ncols=3
         ) as vintbl:
             lib.call_module(module="wiggle", args=build_arg_list(kwargs, infile=vintbl))
diff --git a/pygmt/src/xyz2grd.py b/pygmt/src/xyz2grd.py
@@ -149,7 +149,7 @@ def xyz2grd(
     with Session() as lib:
         with (
             lib.virtualfile_in(
-                check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=3
+                check_kind="vector", data=data, x=x, y=y, z=z, ncols=3
             ) as vintbl,
             lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd,
         ):
diff --git a/pygmt/tests/test_clib_virtualfile_in.py b/pygmt/tests/test_clib_virtualfile_in.py
@@ -41,9 +41,7 @@ def test_virtualfile_in_required_z_matrix(array_func, kind):
     )
     data = array_func(dataframe)
     with clib.Session() as lib:
-        with lib.virtualfile_in(
-            data=data, required_ncols=3, check_kind="vector"
-        ) as vfile:
+        with lib.virtualfile_in(data=data, ncols=3, check_kind="vector") as vfile:
             with GMTTempFile() as outfile:
                 lib.call_module("info", [vfile, f"->{outfile.name}"])
                 output = outfile.read(keep_tabs=True)
@@ -64,7 +62,7 @@ def test_virtualfile_in_required_z_matrix_missing():
     data = np.ones((5, 2))
     with clib.Session() as lib:
         with pytest.raises(GMTInvalidInput):
-            with lib.virtualfile_in(data=data, required_ncols=3, check_kind="vector"):
+            with lib.virtualfile_in(data=data, ncols=3, check_kind="vector"):
                 pass
 
 
@@ -90,9 +88,7 @@ def test_virtualfile_in_fail_non_valid_data(data):
             continue
         with clib.Session() as lib:
             with pytest.raises(GMTInvalidInput):
-                lib.virtualfile_in(
-                    x=variable[0], y=variable[1], z=variable[2], required_ncols=3
-                )
+                lib.virtualfile_in(x=variable[0], y=variable[1], z=variable[2], ncols=3)
 
     # Should also fail if given too much data
     with clib.Session() as lib:
