Figure.text: Support non-ASCII characters in the 'text' parameter (#2638

)

Co-authored-by: Yvonne Fröhlich <[email protected]>

pygmt/helpers/__init__.py

@@ -19,4 +19,5 @@
     data_kind,
     is_nonstr_iter,
     launch_external_viewer,
+    non_ascii_to_octal,
 )

pygmt/src/text.py

@@ -10,6 +10,7 @@
     fmt_docstring,
     is_nonstr_iter,
     kwargs_to_strings,
+    non_ascii_to_octal,
     use_alias,
 )
 
@@ -65,6 +66,12 @@ def text_(
     - ``x``/``y``, and ``text``
     - ``position`` and ``text``
 
+    The text strings passed via the ``text`` parameter can contain ASCII
+    characters and non-ASCII characters defined in the ISOLatin1+ encoding
+    (i.e., IEC_8859-1), and the Symbol and ZapfDingbats character sets.
+    See :gmt-docs:`cookbook/octal-codes.html` for the full list of supported
+    non-ASCII characters.
+
     Full option list at :gmt-docs:`text.html`
 
     {aliases}
@@ -223,7 +230,9 @@ def text_(
 
     # Append text at last column. Text must be passed in as str type.
     if kind == "vectors":
-        extra_arrays.append(np.atleast_1d(text).astype(str))
+        extra_arrays.append(
+            np.vectorize(non_ascii_to_octal)(np.atleast_1d(text).astype(str))
+        )
 
     with Session() as lib:
         file_context = lib.virtualfile_from_data(

pygmt/tests/baseline/test_text_nonascii.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: aca7c6732bc8410a6299582a2bf3b997
+  size: 17350
+  hash: md5
+  path: test_text_nonascii.png

pygmt/tests/test_text.py

@@ -371,3 +371,16 @@ def test_text_nonstr_text():
         text=[1, 2, 3.0, 4.0],
     )
     return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_text_nonascii():
+    """
+    Test passing text strings with non-ascii characters.
+    """
+    fig = Figure()
+    fig.basemap(region=[0, 10, 0, 10], projection="X10c", frame=True)
+    fig.text(position="TL", text="position-text:°α")
+    fig.text(x=1, y=1, text="xytext:°α")
+    fig.text(x=[5, 5], y=[3, 5], text=["xytext1:αζΔ❡", "xytext2:∑π∇✉"])
+    return fig