Figure.coast: Make the 'resolution' parameter more Pythonic

Author: seisman

pygmt/src/coast.py

@@ -2,6 +2,9 @@
 coast - Plot land and water.
 """
 
+from typing import Literal
+
+from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import (
@@ -20,7 +23,6 @@
     A="area_thresh",
     B="frame",
     C="lakes",
-    D="resolution",
     E="dcw",
     F="box",
     G="land",
@@ -37,7 +39,13 @@
     t="transparency",
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
-def coast(self, **kwargs):
+def coast(
+    self,
+    resolution: Literal[  # noqa: ARG001
+        "auto", "full", "high", "intermediate", "low", "crude"
+    ] = "auto",
+    **kwargs,
+):
     r"""
     Plot continents, shorelines, rivers, and borders on maps.
 
@@ -75,11 +83,19 @@ def coast(self, **kwargs):
         parameter. Optionally, specify separate fills by appending
         **+l** for lakes or **+r** for river-lakes, and passing multiple
         strings in a list.
-    resolution : str
-        **f**\|\ **h**\|\ **i**\|\ **l**\|\ **c**.
-        Select the resolution of the data set to: (**f**\ )ull,
-        (**h**\ )igh, (**i**\ )ntermediate, (**l**\ )ow,
-        and (**c**\ )rude.
+    resolution
+        Select the resolution of the GSHHG coastline data set to use. The available
+        resolutions from highest to lowest are:
+
+        - ``"full"`` - Full resolution (may be very slow for large regions).
+        - ``"high"`` - High resolution (may be slow for large regions).
+        - ``"intermediate"`` - Intermediate resolution.
+        - ``"low"`` - Low resolution.
+        - ``"crude"`` - Crude resolution, for tasks that need crude continent outlines
+          only.
+
+        The default is ``"auto"`` to automatically select the best resolution given the
+        chosen map scale.
     land : str
         Select filling or clipping of "dry" areas.
     rivers : int, str, or list
@@ -220,11 +236,15 @@ def coast(self, **kwargs):
     >>> # Show the plot
     >>> fig.show()
     """
+    alias = AliasSystem(
+        D=Alias("resolution", mapping=True),
+    )
     kwargs = self._preprocess(**kwargs)
     if not args_in_kwargs(args=["C", "G", "S", "I", "N", "E", "Q", "W"], kwargs=kwargs):
         raise GMTInvalidInput(
             """At least one of the following parameters must be specified:
             lakes, land, water, rivers, borders, dcw, Q, or shorelines"""
         )
+
     with Session() as lib:
-        lib.call_module(module="coast", args=build_arg_list(kwargs))
+        lib.call_module(module="coast", args=build_arg_list(alias.kwdict))

pygmt/tests/test_coast.py

@@ -29,7 +29,7 @@ def test_coast_world_mercator():
         projection="M15c",
         frame="af",
         land="#aaaaaa",
-        resolution="c",
+        resolution="crude",
         water="white",
     )
     return fig