Merge branch 'main' into fix/arg_is_not_None

Author: weiji14

doc/contributing.md

@@ -405,9 +405,9 @@ When editing documentation, use the following standards to demonstrate the examp
 
 The API reference is manually assembled in `doc/api/index.rst`.
 The *autodoc* sphinx extension will automatically create pages for each
-function/class/module listed there.
+function/class/module/method listed there.
 
-You can reference functions, classes, methods, and modules from anywhere
+You can reference functions, classes, modules, and methods from anywhere
 (including docstrings) using:
 
 - <code>:func:\`package.module.function\`</code>
@@ -435,7 +435,7 @@ For GMT configuration parameters, an example is
 {gmt-term}`https://docs.generic-mapping-tools.org/latest/gmt.conf#term-COLOR_FOREGROUND <COLOR_FOREGROUND>`.
 
 Sphinx will create a link to the automatically generated page for that
-function/class/module.
+function/class/module/method.
 
 ## Contributing Code
 
@@ -500,7 +500,7 @@ Tests also help us be confident that we won't break your code in the future.
 
 When writing tests, don't test everything that the GMT function already tests, such as
 the every unique combination arguments. An exception to this would be the most popular
-modules, such as `plot` and `basemap`. The highest priority for tests should be the
+methods, such as `plot` and `basemap`. The highest priority for tests should be the
 Python-specific code, such as numpy, pandas, and xarray objects and the virtualfile
 mechanism.
 

doc/maintenance.md

@@ -254,7 +254,7 @@ publishing the actual release notes at https://www.pygmt.org/latest/changes.html
    typo fixes, CI configuration, test updates due to GMT releases, etc).
 5. Sort the items within each section (i.e., New Features, Enhancements, etc.)
    such that similar items are located near each other (e.g., new wrapped
-   modules, gallery examples, API docs changes) and entries within each group
+   modules and methods, gallery examples, API docs changes) and entries within each group
    are alphabetical.
 6. Move a few important items from the main sections to the highlights section.
 7. Edit the list of people who contributed to the release, linking to their

examples/gallery/lines/vector_heads_tails.py

@@ -2,7 +2,7 @@
 Vector heads and tails
 ----------------------
 
-Many modules in PyGMT allow plotting vectors with individual
+Many methods in PyGMT allow plotting vectors with individual
 heads and tails. For this purpose, several modifiers may be appended to
 the corresponding vector-producing parameters for specifying the placement
 of vector heads and tails, their shapes, and the justification of the vector.
@@ -21,7 +21,7 @@
 **+h**\ *shape* (e.g. ``+h0.5``).
 
 For further modifiers see the *Vector Attributes* subsection of the
-corresponding module.
+corresponding method.
 
 In the following we use the :meth:`pygmt.Figure.plot` method to plot vectors
 with individual heads and tails. We must specify the modifiers (together with

examples/get-started/README.txt

@@ -13,5 +13,5 @@ This tutorial assumes that PyGMT has been successfully
 
 This tutorial will progressively cover PyGMT plotting concepts, and later
 examples will use concepts explained in previous examples. It will not
-cover all PyGMT modules.
+cover all PyGMT methods.
 

examples/get-started/first_figure.py

@@ -4,8 +4,8 @@
 
 This tutorial page covers the basics of creating a figure using PyGMT - a
 Python wrapper for the Generic Mapping Tools (GMT). It will only use
-the ``coast`` module for plotting. Later examples will address other PyGMT
-modules.
+the ``coast`` method for plotting. Later examples will address other PyGMT
+methods.
 """
 
 ###############################################################################
@@ -21,7 +21,7 @@
 # Loading the library
 # -------------------
 #
-# The first step is to import ``pygmt``. All modules and figure generation is
+# The first step is to import ``pygmt``. All methods and figure generation is
 # accessible from the :mod:`pygmt` top level package.
 
 # sphinx_gallery_thumbnail_number = 4
@@ -38,14 +38,14 @@
 
 ###############################################################################
 # To add to a plot object (``fig`` in this example), the PyGMT module is used
-# as a method on the class. This example will use the module ``coast``, which
-# can be used to create a map without any other modules or external data. The
-# ``coast`` module plots the coastlines, borders, and bodies of water using a
-# database that is included in GMT.
+# as a method on the class. This example will use the ``coast`` method, which
+# can be used to create a map without any other methods, modules or external
+# data. The ``coast`` method plots the coastlines, borders, and bodies of water
+# using a database that is included in GMT.
 #
 # First, a region for the figure must be selected. This example will plot some
 # of the coast of Maine in the northeastern US. A Python list can be passed to
-# the ``region`` argument with the minimum and maximum X-values (longitude)
+# the ``region`` parameter with the minimum and maximum X-values (longitude)
 # and the minimum and maximum Y-values (latitude). For this example, the
 # minimum (bottom left) coordinates are (N43.75, W69) and the maximum (top
 # right) coordinates are (N44.75, W68). Negative values can be passed for

examples/projections/README.txt

@@ -2,7 +2,7 @@ Projections
 ===========
 
 PyGMT support many map projections. Use the ``projection`` parameter to specify which
-one you want to use in all plotting modules. The projection is specified by a one
+one you want to use in all plotting methods. The projection is specified by a one
 letter code along with (sometimes optional) reference longitude and latitude and the
 width of the map (for example, **A**\ *lon0/lat0*\ [*/horizon*\ ]\ */width*). The map
 height is determined based on the region and projection.

examples/tutorials/basics/frames.py

@@ -22,7 +22,7 @@
 
 ###############################################################################
 # To add the default GMT frame to the plot, use ``frame="f"`` in
-# :meth:`pygmt.Figure.basemap` or any other plotting module:
+# :meth:`pygmt.Figure.basemap` or any other plotting method:
 
 fig = pygmt.Figure()
 fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M25c")

pygmt/helpers/utils.py

@@ -119,12 +119,12 @@ def dummy_context(arg):
     yield arg
 
 
-def build_arg_string(kwargs):
+def build_arg_string(kwdict, infile=None, outfile=None):
     r"""
-    Transform keyword arguments into a GMT argument string.
+    Convert a dict and optional input/output files into a GMT argument string.
 
-    Make sure all arguments have been previously converted to a string
-    representation using the ``kwargs_to_strings`` decorator. The only
+    Make sure all values in ``kwdict`` have been previously converted to a
+    string representation using the ``kwargs_to_strings`` decorator. The only
     exceptions are True, False and None.
 
     Any lists or tuples left will be interpreted as multiple entries for the
@@ -138,14 +138,19 @@ def build_arg_string(kwargs):
 
     Parameters
     ----------
-    kwargs : dict
-        Parsed keyword arguments.
+    kwdict : dict
+        A dict containing parsed keyword arguments.
+    infile : str or pathlib.Path
+        The input file.
+    outfile : str or pathlib.Path
+        The output file.
 
     Returns
     -------
     args : str
         The space-delimited argument string with '-' inserted before each
-        keyword. The arguments are sorted alphabetically.
+        keyword. The arguments are sorted alphabetically, with optional input
+        file at the begining and optioanl output file at the end.
 
     Examples
     --------
@@ -191,29 +196,42 @@ def build_arg_string(kwargs):
     ...     )
     ... )
     -BWSne+tBlank\040Space -Baf -F+t"Empty\040\040Spaces" -l'Void\040Space'
+    >>> print(
+    ...     build_arg_string(
+    ...         dict(A="0", B=True, C="rainbow"),
+    ...         infile="input.txt",
+    ...         outfile="output.txt",
+    ...     )
+    ... )
+    input.txt -A0 -B -Crainbow ->output.txt
     """
     gmt_args = []
 
-    for key in kwargs:
+    for key in kwdict:
         if len(key) > 2:  # raise an exception for unrecognized options
             raise GMTInvalidInput(f"Unrecognized parameter '{key}'.")
-        if kwargs[key] is None or kwargs[key] is False:
+        if kwdict[key] is None or kwdict[key] is False:
             pass  # Exclude arguments that are None and False
-        elif is_nonstr_iter(kwargs[key]):
-            for value in kwargs[key]:
+        elif is_nonstr_iter(kwdict[key]):
+            for value in kwdict[key]:
                 _value = str(value).replace(" ", r"\040")
                 gmt_args.append(rf"-{key}{_value}")
-        elif kwargs[key] is True:
+        elif kwdict[key] is True:
             gmt_args.append(f"-{key}")
         else:
             if key != "J":  # non-projection parameters
-                _value = str(kwargs[key]).replace(" ", r"\040")
+                _value = str(kwdict[key]).replace(" ", r"\040")
             else:
                 # special handling if key == "J" (projection)
                 # remove any spaces in PROJ4 string
-                _value = str(kwargs[key]).replace(" ", "")
+                _value = str(kwdict[key]).replace(" ", "")
             gmt_args.append(rf"-{key}{_value}")
-    return " ".join(sorted(gmt_args))
+    gmt_args = sorted(gmt_args)
+    if infile:
+        gmt_args = [str(infile)] + gmt_args
+    if outfile:
+        gmt_args.append("->" + str(outfile))
+    return " ".join(gmt_args)
 
 
 def is_nonstr_iter(value):
@@ -306,5 +324,23 @@ def args_in_kwargs(args, kwargs):
     --------
     bool
         If one of the required arguments is in ``kwargs``.
+
+    Examples
+    --------
+
+    >>> args_in_kwargs(args=["A", "B"], kwargs={"C": "xyz"})
+    False
+    >>> args_in_kwargs(args=["A", "B"], kwargs={"B": "af"})
+    True
+    >>> args_in_kwargs(args=["A", "B"], kwargs={"B": None})
+    False
+    >>> args_in_kwargs(args=["A", "B"], kwargs={"B": True})
+    True
+    >>> args_in_kwargs(args=["A", "B"], kwargs={"B": False})
+    False
+    >>> args_in_kwargs(args=["A", "B"], kwargs={"B": 0})
+    True
     """
-    return any(arg in kwargs for arg in args)
+    return any(
+        kwargs.get(arg) is not None and kwargs.get(arg) is not False for arg in args
+    )

pygmt/src/__init__.py

@@ -1,5 +1,5 @@
 """
-Source code for PyGMT modules.
+Source code for PyGMT methods.
 """
 # pylint: disable=import-outside-toplevel
 

pygmt/src/blockm.py

@@ -51,8 +51,10 @@ def _blockm(block_method, data, x, y, z, outfile, **kwargs):
             with table_context as infile:
                 if outfile is None:
                     outfile = tmpfile.name
-                arg_str = " ".join([infile, build_arg_string(kwargs), "->" + outfile])
-                lib.call_module(module=block_method, args=arg_str)
+                lib.call_module(
+                    module=block_method,
+                    args=build_arg_string(kwargs, infile=infile, outfile=outfile),
+                )
 
         # Read temporary csv output to a pandas table
         if outfile == tmpfile.name:  # if user did not set outfile, return pd.DataFrame