Enhance text with extra functionality and aliases

pygmt/base_plotting.py

@@ -813,7 +813,7 @@ def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwarg
             lib.call_module("legend", arg_str)
 
     @fmt_docstring
-    @use_alias(R="region", J="projection", B="frame")
+    @use_alias(R="region", J="projection", B="frame", W="pen")
     @kwargs_to_strings(
         R="sequence",
         textfiles="sequence_space",
@@ -855,25 +855,31 @@ def text(
             the text
         text : str or 1d array
             The text string, or an array of strings to plot on the figure
-        angle: int, float or bool
+        angle: int, float, str or bool
             Set the angle measured in degrees counter-clockwise from
             horizontal. E.g. 30 sets the text at 30 degrees. If no angle is
-            given then the input textfile(s) must have this as a column.
+            explicitly given (i.e. angle=True) then the input textfile(s) must
+            have this as a column.
         font : str or bool
             Set the font specification with format "size,font,color" where size
             is text size in points, font is the font to use, and color sets the
             font color. E.g. "12p,Helvetica-Bold,red" selects a 12p red
-            Helvetica-Bold font. If no font info is given then the input
-            textfile(s) must have this information in one of its columns.
-        justify: str or bool
+            Helvetica-Bold font. If no font info is explicitly given (i.e.
+            font=True), then the input textfile(s) must have this information
+            in one of its columns.
+        justify : str or bool
             Set the alignment which refers to the part of the text string that
             will be mapped onto the (x,y) point. Choose a 2 character
             combination of L, C, R (for left, center, or right) and T, M, B for
             top, middle, or bottom. E.g., BL for lower left. If no
-            justification is given then the input textfile(s) must have this as
-            a column.
+            justification is explicitly given (i.e. justify=True), then the
+            input textfile(s) must have this as a column.
         {J}
         {R}
+        pen : str
+            Sets the pen used to draw a rectangle around the text string
+            (see *clearance*) [Default is width = default, color = black,
+            style = solid].
         """
         kwargs = self._preprocess(**kwargs)
 
@@ -888,7 +894,7 @@ def text(
         if angle is not None or font is not None or justify is not None:
             if "F" not in kwargs.keys():
                 kwargs.update({"F": ""})
-            if angle is not None and isinstance(angle, (int, float)):
+            if angle is not None and isinstance(angle, (int, float, str)):
                 kwargs["F"] += f"+a{str(angle)}"
             if font is not None and isinstance(font, str):
                 kwargs["F"] += f"+f{font}"

pygmt/tests/test_text.py

@@ -8,6 +8,7 @@
 
 from .. import Figure
 from ..exceptions import GMTInvalidInput
+from ..helpers import GMTTempFile
 
 TEST_DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
 POINTS_DATA = os.path.join(TEST_DATA_DIR, "points.txt")
@@ -130,6 +131,23 @@ def test_text_font_bold(region, projection):
     return fig
 
 
+@pytest.mark.mpl_image_compare
+def test_text_pen(region, projection):
+    """
+    Print text with thick green dashed pen
+    """
+    fig = Figure()
+    fig.text(
+        region=region,
+        projection=projection,
+        x=1.2,
+        y=1.2,
+        text="green pen around text",
+        pen="thick,green,dashed",
+    )
+    return fig
+
+
 @pytest.mark.mpl_image_compare
 def test_text_justify_bottom_right_and_top_left(region, projection):
     """
@@ -172,3 +190,25 @@ def test_text_justify_parsed_from_textfile():
         D="j0.45/0+vred",  # draw red-line from xy point to text label (city name)
     )
     return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_text_angle_font_justify_from_textfile(region, projection):
+    """
+    Print text with x, y, angle, font, justify, and text arguments parsed from
+    the textfile.
+    """
+    fig = Figure()
+    with GMTTempFile(suffix=".txt") as tempfile:
+        with open(tempfile.name, "w") as tmpfile:
+            tmpfile.write("114 0.5 30 22p,Helvetica-Bold,black LM BORNEO")
+        fig.text(
+            region=[113, 117.5, -0.5, 3],
+            projection="M5c",
+            frame="a",
+            textfiles=tempfile.name,
+            angle=True,
+            font=True,
+            justify=True,
+        )
+    return fig