Figure.plot/Figure.plot3d/Figure.text: Migrate the transparency parameter to the new alias system (#4068)

Author: seisman

pygmt/src/plot.py

@@ -2,6 +2,7 @@
 plot - Plot lines, polygons, and symbols in 2-D.
 """
 
+from collections.abc import Sequence
 from typing import Literal
 
 from pygmt._typing import PathLike, TableLike
@@ -44,7 +45,6 @@
     i="incols",
     l="label",
     p="perspective",
-    t="transparency",
     w="wrap",
 )
 @kwargs_to_strings(R="sequence", i="sequence_comma", p="sequence")
@@ -61,6 +61,7 @@ def plot(  # noqa: PLR0912, PLR0913
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | tuple[int, int] | bool = False,
+    transparency: float | Sequence[float] | bool | None = None,
     **kwargs,
 ):
     r"""
@@ -91,6 +92,7 @@ def plot(  # noqa: PLR0912, PLR0913
        - J = projection
        - V = verbose
        - c = panel
+       - t = transparency
 
     Parameters
     ----------
@@ -228,9 +230,8 @@ def plot(  # noqa: PLR0912, PLR0913
     {label}
     {perspective}
     {transparency}
-        ``transparency`` can also be a 1-D array to set varying
-        transparency for symbols, but this option is only valid if using
-        ``x``/``y``.
+        ``transparency`` can also be a 1-D array to set varying transparency for
+        symbols, but this option is only valid if using ``x``/``y``.
     {wrap}
     """
     # TODO(GMT>6.5.0): Remove the note for the upstream bug of the "straight_line"
@@ -254,11 +255,14 @@ def plot(  # noqa: PLR0912, PLR0913
         # Size
         if is_nonstr_iter(size):
             data["size"] = size
-        # Intensity and transparency
-        for flag, name in [("I", "intensity"), ("t", "transparency")]:
-            if is_nonstr_iter(kwargs.get(flag)):
-                data[name] = kwargs[flag]
-                kwargs[flag] = ""
+        # Intensity
+        if is_nonstr_iter(kwargs.get("I")):
+            data["intensity"] = kwargs["I"]
+            kwargs["I"] = ""
+        # Transparency
+        if is_nonstr_iter(transparency):
+            data["transparency"] = transparency
+            transparency = True
         # Symbol must be at the last column
         if is_nonstr_iter(symbol):
             if "S" not in kwargs:
@@ -273,7 +277,7 @@ def plot(  # noqa: PLR0912, PLR0913
             ("fill", kwargs.get("G")),
             ("size", size),
             ("intensity", kwargs.get("I")),
-            ("transparency", kwargs.get("t")),
+            ("transparency", transparency),
             ("symbol", symbol),
         ]:
             if is_nonstr_iter(value):
@@ -292,6 +296,7 @@ def plot(  # noqa: PLR0912, PLR0913
         J=projection,
         V=verbose,
         c=panel,
+        t=transparency,
     )
     aliasdict.merge(kwargs)
 

pygmt/src/plot3d.py

@@ -2,6 +2,7 @@
 plot3d - Plot lines, polygons, and symbols in 3-D.
 """
 
+from collections.abc import Sequence
 from typing import Literal
 
 from pygmt._typing import PathLike, TableLike
@@ -45,7 +46,6 @@
     i="incols",
     l="label",
     p="perspective",
-    t="transparency",
     w="wrap",
 )
 @kwargs_to_strings(R="sequence", i="sequence_comma", p="sequence")
@@ -63,6 +63,7 @@ def plot3d(  # noqa: PLR0912, PLR0913
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | tuple[int, int] | bool = False,
+    transparency: float | Sequence[float] | bool | None = None,
     **kwargs,
 ):
     r"""
@@ -93,6 +94,7 @@ def plot3d(  # noqa: PLR0912, PLR0913
        - J = projection
        - V = verbose
        - c = panel
+       - t = transparency
 
     Parameters
     ----------
@@ -206,9 +208,8 @@ def plot3d(  # noqa: PLR0912, PLR0913
     {label}
     {perspective}
     {transparency}
-        ``transparency`` can also be a 1-D array to set varying
-        transparency for symbols, but this option is only valid if using
-        ``x``/``y``/``z``.
+        ``transparency`` can also be a 1-D array to set varying transparency for
+        symbols, but this option is only valid if using ``x``/``y``/``z``.
     {wrap}
     """
     # TODO(GMT>6.5.0): Remove the note for the upstream bug of the "straight_line"
@@ -232,11 +233,14 @@ def plot3d(  # noqa: PLR0912, PLR0913
         # Size
         if is_nonstr_iter(size):
             data["size"] = size
-        # Intensity and transparency
-        for flag, name in [("I", "intensity"), ("t", "transparency")]:
-            if is_nonstr_iter(kwargs.get(flag)):
-                data[name] = kwargs[flag]
-                kwargs[flag] = ""
+        # Intensity
+        if is_nonstr_iter(kwargs.get("I")):
+            data["intensity"] = kwargs["I"]
+            kwargs["I"] = ""
+        # Transparency
+        if is_nonstr_iter(transparency):
+            data["transparency"] = transparency
+            transparency = True
         # Symbol must be at the last column
         if is_nonstr_iter(symbol):
             if "S" not in kwargs:
@@ -252,7 +256,7 @@ def plot3d(  # noqa: PLR0912, PLR0913
             ("fill", kwargs.get("G")),
             ("size", size),
             ("intensity", kwargs.get("I")),
-            ("transparency", kwargs.get("t")),
+            ("transparency", transparency),
             ("symbol", symbol),
         ]:
             if is_nonstr_iter(value):
@@ -271,6 +275,7 @@ def plot3d(  # noqa: PLR0912, PLR0913
         J=projection,
         V=verbose,
         c=panel,
+        t=transparency,
     )
     aliasdict.merge(kwargs)
 

pygmt/src/text.py

@@ -37,7 +37,6 @@
     h="header",
     it="use_word",
     p="perspective",
-    t="transparency",
     w="wrap",
 )
 @kwargs_to_strings(R="sequence", p="sequence")
@@ -55,6 +54,7 @@ def text_(  # noqa: PLR0912, PLR0913, PLR0915
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | tuple[int, int] | bool = False,
+    transparency: float | Sequence[float] | bool | None = None,
     **kwargs,
 ):
     r"""
@@ -78,6 +78,7 @@ def text_(  # noqa: PLR0912, PLR0913, PLR0915
        - J = projection
        - V = verbose
        - c = panel
+       - t = transparency
 
     Parameters
     ----------
@@ -181,9 +182,8 @@ def text_(  # noqa: PLR0912, PLR0913, PLR0915
         columns can be specified.
     {perspective}
     {transparency}
-        ``transparency`` can also be a 1-D array to set varying
-        transparency for texts, but this option is only valid if using
-        ``x``/``y`` and ``text``.
+        ``transparency`` can also be a 1-D array to set varying transparency for texts,
+        but this option is only valid if using ``x``/``y`` and ``text``.
     {wrap}
     """
     self._activate_figure()
@@ -252,9 +252,9 @@ def text_(  # noqa: PLR0912, PLR0913, PLR0915
 
         # If an array of transparency is given, GMT will read it from the last numerical
         # column per data record.
-        if is_nonstr_iter(kwargs.get("t")):
-            data["transparency"] = kwargs["t"]
-            kwargs["t"] = True
+        if is_nonstr_iter(transparency):
+            data["transparency"] = transparency
+            transparency = True
 
         # Append text to the last column. Text must be passed in as str type.
         text = np.asarray(text, dtype=np.str_)
@@ -268,7 +268,7 @@ def text_(  # noqa: PLR0912, PLR0913, PLR0915
         if isinstance(position, str):
             kwargs["F"] += f"+c{position}+t{text}"
 
-        for arg, _, name in [*array_args, (kwargs.get("t"), "", "transparency")]:
+        for arg, _, name in [*array_args, (transparency, "", "transparency")]:
             if is_nonstr_iter(arg):
                 raise GMTTypeError(
                     type(arg),
@@ -279,6 +279,7 @@ def text_(  # noqa: PLR0912, PLR0913, PLR0915
         J=projection,
         V=verbose,
         c=panel,
+        t=transparency,
     )
     aliasdict.merge(kwargs)