Merge branch 'master' into docstring-formatter

Author: seisman

LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2017-2020 The PyGMT Developers
+Copyright (c) 2017-2021 The PyGMT Developers
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,

pygmt/base_plotting.py

@@ -9,6 +9,7 @@
 from pygmt.clib import Session
 from pygmt.exceptions import GMTError, GMTInvalidInput
 from pygmt.helpers import (
+    args_in_kwargs,
     build_arg_string,
     data_kind,
     dummy_context,
@@ -63,6 +64,7 @@ def _preprocess(self, **kwargs):  # pylint: disable=no-self-use
         C="lakes",
         B="frame",
         D="resolution",
+        E="dcw",
         I="rivers",
         L="map_scale",
         N="borders",
@@ -141,12 +143,36 @@ def coast(self, **kwargs):
         shorelines : str
             ``'[level/]pen'``
             Draw shorelines [Default is no shorelines]. Append pen attributes.
+        dcw : str or list
+            *code1,code2,…*\ [**+l**\|\ **L**\ ][**+g**\ *fill*\ ]
+            [**+p**\ *pen*\ ][**+z**]
+            Select painting or dumping country polygons from the
+            `Digital Chart of the World
+            <https://en.wikipedia.org/wiki/Digital_Chart_of_the_World>`__.
+            Append one or more comma-separated countries using the 2-character
+            `ISO 3166-1 alpha-2 convention
+            <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>`__.
+            To select a state of a country (if available), append
+            .\ *state*, (e.g, US.TX for Texas).  To specify a whole continent,
+            prepend **=** to any of the continent codes (e.g. =EU for Europe).
+            Append **+p**\ *pen* to draw polygon outlines
+            (default is no outline) and **+g**\ *fill* to fill them
+            (default is no fill). Append **+l**\|\ **+L** to *=continent* to
+            only list countries in that continent; repeat if more than one
+            continent is requested. Append **+z** to place the country code in
+            the segment headers via **-Z**\ *code* settings.To apply different
+            settings to different countries, pass a list of string arguments.
         {XY}
         {p}
         {t}
 
         """
         kwargs = self._preprocess(**kwargs)
+        if not args_in_kwargs(args=["C", "G", "S", "I", "N", "Q", "W"], kwargs=kwargs):
+            raise GMTInvalidInput(
+                """At least one of the following arguments must be specified:
+                lakes, land, water, rivers, borders, Q, or shorelines"""
+            )
         with Session() as lib:
             lib.call_module("coast", build_arg_string(kwargs))
 

pygmt/helpers/__init__.py

@@ -4,6 +4,7 @@
 from pygmt.helpers.decorators import fmt_docstring, kwargs_to_strings, use_alias
 from pygmt.helpers.tempfile import GMTTempFile, unique_name
 from pygmt.helpers.utils import (
+    args_in_kwargs,
     build_arg_string,
     data_kind,
     dummy_context,

pygmt/helpers/utils.py

@@ -220,3 +220,29 @@ def launch_external_viewer(fname):
         subprocess.run(["open", fname], check=False, **run_args)
     else:
         webbrowser.open_new_tab("file://{}".format(fname))
+
+
+def args_in_kwargs(args, kwargs):
+    """
+    Take a list and a dictionary, and determine if any entries in the list are
+    keys in the dictionary.
+
+    This function is used to determine if at least one of the required
+    arguments is passed to raise a GMTInvalidInput Error.
+
+    Parameters
+    ----------
+    args : list
+        List of required arguments, using the GMT short-form aliases.
+
+    kwargs : dict
+        The dictionary of kwargs is the format returned by the _preprocess
+        function of the BasePlotting class. The keys are the GMT
+        short-form aliases of the parameters.
+
+    Returns
+    --------
+    bool
+        If one of the required arguments is in ``kwargs``.
+    """
+    return any(arg in kwargs for arg in args)

pygmt/tests/test_coast.py

@@ -3,6 +3,7 @@
 """
 import pytest
 from pygmt import Figure
+from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers.testing import check_figures_equal
 
 
@@ -57,6 +58,7 @@ def test_coast_aliases():
         Y="a10c",
         p="135/25",
         t=13,
+        E="MA+gred",
         C="blue",
     )
     fig_test.coast(
@@ -75,6 +77,7 @@ def test_coast_aliases():
         yshift="a10c",  # Y
         perspective=[135, 25],  # p
         transparency=13,  # t
+        dcw="MA+gred",  # E
         lakes="blue",  # C
     )
     return fig_ref, fig_test
@@ -93,3 +96,98 @@ def test_coast_world_mercator():
         water="white",
     )
     return fig
+
+
+def test_coast_required_args():
+    "Test if fig.coast fails when not given required arguments"
+    fig = Figure()
+    with pytest.raises(GMTInvalidInput):
+        fig.coast(region="EG")
+
+
+@check_figures_equal()
+def test_coast_dcw_single():
+    "Test passing a single country code to dcw"
+    fig_ref, fig_test = Figure(), Figure()
+    # Use single-character arguments for the reference image
+    fig_ref.coast(R="-10/15/25/44", J="M15c", B="a", G="brown", E="ES+gbisque+pblue")
+    fig_test.coast(
+        region=[-10, 15, 25, 44],
+        frame="a",
+        projection="M15c",
+        land="brown",
+        dcw="ES+gbisque+pblue",
+    )
+    return fig_ref, fig_test
+
+
+@check_figures_equal()
+def test_coast_dcw_multiple():
+    "Test passing multiple country code to dcw"
+    fig_ref, fig_test = Figure(), Figure()
+    # Use single-character arguments for the reference image
+    fig_ref.coast(R="-10/15/25/44", J="M15c", B="a", G="brown", E="ES,IT+gbisque+pblue")
+    fig_test.coast(
+        region=[-10, 15, 25, 44],
+        frame="a",
+        projection="M15c",
+        land="brown",
+        dcw="ES,IT+gbisque+pblue",
+    )
+    return fig_ref, fig_test
+
+
+@check_figures_equal()
+def test_coast_dcw_list():
+    "Test passing a list of country codes and fill options to dcw"
+    fig_ref, fig_test = Figure(), Figure()
+    # Use single-character arguments for the reference image
+    fig_ref.coast(
+        R="-10/15/25/44",
+        J="M15c",
+        B="a",
+        G="brown",
+        E=["ES+gbisque+pgreen", "IT+gcyan+pblue"],
+    )
+    fig_test.coast(
+        region=[-10, 15, 25, 44],
+        frame="a",
+        projection="M15c",
+        land="brown",
+        dcw=["ES+gbisque+pgreen", "IT+gcyan+pblue"],
+    )
+    return fig_ref, fig_test
+
+
+@check_figures_equal()
+def test_coast_dcw_continent():
+    "Test passing a continent code to dcw"
+    fig_ref, fig_test = Figure(), Figure()
+    # Use single-character arguments for the reference image
+    fig_ref.coast(R="-10/15/25/44", J="M15c", B="a", G="brown", E="=AF+gbisque+pblue")
+    fig_test.coast(
+        region=[-10, 15, 25, 44],
+        frame="a",
+        projection="M15c",
+        land="brown",
+        dcw="=AF+gbisque+pblue",
+    )
+    return fig_ref, fig_test
+
+
+@check_figures_equal()
+def test_coast_dcw_state():
+    "Test passing a US state code to dcw"
+    fig_ref, fig_test = Figure(), Figure()
+    # Use single-character arguments for the reference image
+    fig_ref.coast(
+        R="-75/-69/40/44", J="M15c", B="a", G="brown", E="US.MA+gbisque+pblue"
+    )
+    fig_test.coast(
+        region=[-75, -69, 40, 44],
+        frame="a",
+        projection="M15c",
+        land="brown",
+        dcw="US.MA+gbisque+pblue",
+    )
+    return fig_ref, fig_test

pygmt/tests/test_helpers.py

@@ -6,7 +6,13 @@
 import numpy as np
 import pytest
 from pygmt.exceptions import GMTInvalidInput
-from pygmt.helpers import GMTTempFile, data_kind, kwargs_to_strings, unique_name
+from pygmt.helpers import (
+    GMTTempFile,
+    args_in_kwargs,
+    data_kind,
+    kwargs_to_strings,
+    unique_name,
+)
 
 
 @pytest.mark.parametrize(
@@ -90,3 +96,17 @@ def test_gmttempfile_read():
             ftmp.write("in.dat: N = 2\t<1/3>\t<2/4>\n")
         assert tmpfile.read() == "in.dat: N = 2 <1/3> <2/4>\n"
         assert tmpfile.read(keep_tabs=True) == "in.dat: N = 2\t<1/3>\t<2/4>\n"
+
+
+def test_args_in_kwargs():
+    "Test that args_in_kwargs function returns correct Boolean responses."
+    kwargs = {"A": 1, "B": 2, "C": 3}
+    # Passing list of arguments with passing values in the beginning
+    passing_args_1 = ["B", "C", "D"]
+    assert args_in_kwargs(args=passing_args_1, kwargs=kwargs)
+    # Passing list of arguments that starts with failing arguments
+    passing_args_2 = ["D", "X", "C"]
+    assert args_in_kwargs(args=passing_args_2, kwargs=kwargs)
+    # Failing list of arguments
+    failing_args = ["D", "E", "F"]
+    assert not args_in_kwargs(args=failing_args, kwargs=kwargs)