Migrate the box parameter to the new alias system (#4073)

Author: seisman

pygmt/src/coast.py

@@ -14,6 +14,7 @@
     kwargs_to_strings,
     use_alias,
 )
+from pygmt.params import Box
 
 __doctest_skip__ = ["coast"]
 
@@ -24,7 +25,6 @@
     B="frame",
     C="lakes",
     E="dcw",
-    F="box",
     G="land",
     I="rivers",
     L="map_scale",
@@ -41,6 +41,7 @@ def coast(
     resolution: Literal[
         "auto", "full", "high", "intermediate", "low", "crude", None
     ] = None,
+    box: Box | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | tuple[int, int] | bool = False,
@@ -68,6 +69,7 @@ def coast(
 
     {aliases}
        - D = resolution
+       - F = box
        - J = projection
        - V = verbose
        - c = panel
@@ -127,24 +129,11 @@ def coast(
     map_scale : str
         [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\ **+w**\ *length*.
         Draw a simple map scale centered on the reference point specified.
-    box : bool or str
-        [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\
-        [**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ [[*dx*/*dy*/][*shade*]]].
-        If set to ``True``, draw a rectangular border around the
-        map scale or rose. Alternatively, specify a different pen with
-        **+p**\ *pen*. Add **+g**\ *fill* to fill the scale panel [Default is
-        no fill]. Append **+c**\ *clearance* where *clearance* is either gap,
-        xgap/ygap, or lgap/rgap/bgap/tgap where these items are uniform,
-        separate x and y, or individual side spacings between scale and
-        border. Append **+i** to draw a secondary, inner border as well.
-        We use a uniform gap between borders of 2 points and the
-        :gmt-term:`MAP_DEFAULTS_PEN` unless other values are specified. Append
-        **+r** to draw rounded rectangular borders instead, with a 6-points
-        corner radius. You can override this radius by appending another value.
-        Finally, append **+s** to draw an offset background shaded region.
-        Here, *dx/dy* indicates the shift relative to the foreground frame
-        [Default is ``"4p/-4p"``] and shade sets the fill style to use for
-        shading [Default is ``"gray50"``].
+    box
+        Draw a background box behind the map scale or rose. If set to ``True``, a simple
+        rectangular box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box
+        appearance, pass a :class:`pygmt.params.Box` object to control style, fill, pen,
+        and other box properties.
     borders : int, str, or list
         *border*\ [/*pen*].
         Draw political boundaries. Specify the type of boundary and
@@ -230,6 +219,7 @@ def coast(
                 "crude": "c",
             },
         ),
+        F=Alias(box, name="box"),
     ).add_common(
         J=projection,
         V=verbose,

pygmt/src/colorbar.py

@@ -4,9 +4,10 @@
 
 from typing import Literal
 
-from pygmt.alias import AliasSystem
+from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
+from pygmt.params import Box
 
 __doctest_skip__ = ["colorbar"]
 
@@ -16,7 +17,6 @@
     B="frame",
     C="cmap",
     D="position",
-    F="box",
     G="truncate",
     I="shading",
     L="equalsize",
@@ -30,6 +30,7 @@
 def colorbar(
     self,
     projection=None,
+    box: Box | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | tuple[int, int] | bool = False,
@@ -50,6 +51,7 @@ def colorbar(
     Full GMT docs at :gmt-docs:`colorbar.html`.
 
     {aliases}
+       - F = box
        - J = projection
        - V = verbose
        - c = panel
@@ -82,23 +84,11 @@ def colorbar(
         be changed by appending **+j** followed by a
         :doc:`2-character justification code </techref/justification_codes>`
         *justify*.
-    box : bool or str
-        [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\
-        [**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ [[*dx*/*dy*/][*shade*]]].
-        If set to ``True``, draw a rectangular border around the color scale.
-        Alternatively, specify a different pen with **+p**\ *pen*. Add
-        **+g**\ *fill* to fill the scale panel [Default is no fill]. Append
-        **+c**\ *clearance* where *clearance* is either gap, xgap/ygap, or
-        lgap/rgap/bgap/tgap where these items are uniform, separate in x- and
-        y-direction, or individual side spacings between scale and border.
-        Append **+i** to draw a secondary, inner border as well. We use a
-        uniform gap between borders of 2p and the :gmt-term:`MAP_DEFAULTS_PEN`
-        unless other values are specified. Append **+r** to draw rounded
-        rectangular borders instead, with a 6p corner radius. You can override
-        this radius by appending another value. Finally, append **+s** to draw
-        an offset background shaded region. Here, *dx/dy* indicates the shift
-        relative to the foreground frame [Default is ``"4p/-4p"``] and shade
-        sets the fill style to use for shading [Default is ``"gray50"``].
+    box
+        Draw a background box behind the colorbar. If set to ``True``, a simple
+        rectangular box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box
+        appearance, pass a :class:`pygmt.params.Box` object to control style, fill, pen,
+        and other box properties.
     truncate : list or str
         *zlo*/*zhi*.
         Truncate the incoming CPT so that the lowest and highest z-levels are
@@ -157,7 +147,9 @@ def colorbar(
     """
     self._activate_figure()
 
-    aliasdict = AliasSystem().add_common(
+    aliasdict = AliasSystem(
+        F=Alias(box, name="box"),
+    ).add_common(
         J=projection,
         V=verbose,
         c=panel,

pygmt/src/image.py

@@ -5,25 +5,20 @@
 from typing import Literal
 
 from pygmt._typing import PathLike
-from pygmt.alias import AliasSystem
+from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
+from pygmt.params import Box
 
 
 @fmt_docstring
-@use_alias(
-    D="position",
-    F="box",
-    G="bitcolor",
-    M="monochrome",
-    R="region",
-    p="perspective",
-)
+@use_alias(D="position", G="bitcolor", M="monochrome", R="region", p="perspective")
 @kwargs_to_strings(R="sequence", p="sequence")
 def image(
     self,
     imagefile: PathLike,
     projection=None,
+    box: Box | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | tuple[int, int] | bool = False,
@@ -39,6 +34,7 @@ def image(
     Full GMT docs at :gmt-docs:`image.html`.
 
     {aliases}
+       - F = box
        - J = projection
        - V = verbose
        - c = panel
@@ -59,11 +55,11 @@ def image(
         **+w**\ [**-**]\ *width*\ [/*height*]\ [**+j**\ *justify*]\
         [**+n**\ *nx*\ [/*ny*]]\ [**+o**\ *dx*\ [/*dy*]].
         Set reference point on the map for the image.
-    box : bool or str
-        [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\
-        [**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ [[*dx*/*dy*/][*shade*]]].
-        If set to ``True``, draw a rectangular border around the image
-        using :gmt-term:`MAP_FRAME_PEN`.
+    box
+        Draw a background box behind the image. If set to ``True``, a simple rectangular
+        box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box appearance,
+        pass a :class:`pygmt.params.Box` object to control style, fill, pen, and other
+        box properties.
     bitcolor : str or list
         [*color*][**+b**\|\ **f**\|\ **t**].
         Change certain pixel values to another color or make them transparent.
@@ -82,7 +78,9 @@ def image(
     """
     self._activate_figure()
 
-    aliasdict = AliasSystem().add_common(
+    aliasdict = AliasSystem(
+        F=Alias(box, name="box"),
+    ).add_common(
         J=projection,
         V=verbose,
         c=panel,

pygmt/src/inset.py

@@ -5,26 +5,22 @@
 import contextlib
 from typing import Literal
 
-from pygmt.alias import AliasSystem
+from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
+from pygmt.params import Box
 
 __doctest_skip__ = ["inset"]
 
 
 @fmt_docstring
 @contextlib.contextmanager
-@use_alias(
-    D="position",
-    F="box",
-    M="margin",
-    N="no_clip",
-    R="region",
-)
+@use_alias(D="position", M="margin", N="no_clip", R="region")
 @kwargs_to_strings(D="sequence", M="sequence", R="sequence")
 def inset(
     self,
     projection=None,
+    box: Box | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     **kwargs,
@@ -39,6 +35,7 @@ def inset(
     Full GMT docs at :gmt-docs:`inset.html`.
 
     {aliases}
+       - F = box
        - J = projection
        - V = verbose
 
@@ -83,27 +80,11 @@ def inset(
         as *refpoint*, if **J** is used then *justify* defaults to the
         mirror opposite of *refpoint*. Specify inset box attributes via
         the ``box`` parameter [Default is outline only].
-    box : str or bool
-        [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\
-        *pen*]][**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\
-        [[*dx*/*dy*/][*shade*]]].
-        If set to ``True``, draw a rectangular box around the map
-        inset using the default pen; specify a different pen
-        with **+p**\ *pen*. Add **+g**\ *fill* to fill the inset box
-        [Default is no fill].
-        Append **+c**\ *clearance* where *clearance* is either
-        *gap*, *xgap*\ /\ *ygap*, or *lgap*\ /\ *rgap*\ /\ *bgap*\ /\
-        *tgap* where these items are uniform, separate in x- and
-        y-directions, or individual side spacings between map embellishment
-        and border. Append **+i** to draw a secondary, inner border as well.
-        We use a uniform *gap* between borders of 2p and the default pen
-        unless other values are specified. Append **+r** to draw rounded
-        rectangular borders instead, with a 6p corner radius. You
-        can override this radius by appending another value. Append
-        **+s** to draw an offset background shaded region. Here, *dx*/*dy*
-        indicates the shift relative to the foreground frame [Default is
-        ``"4p/-4p"``] and *shade* sets the fill style to use for
-        shading [Default is ``"gray50"``].
+    box
+        Draw a background box behind the inset. If set to ``True``, a simple rectangular
+        box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box appearance,
+        pass a :class:`pygmt.params.Box` object to control style, fill, pen, and other
+        box properties.
     margin : float, str, or list
         This is clearance that is added around the inside of the inset.
         Plotting will take place within the inner region only. The margins
@@ -147,7 +128,9 @@ def inset(
     """
     self._activate_figure()
 
-    aliasdict = AliasSystem().add_common(
+    aliasdict = AliasSystem(
+        F=Alias(box, name="box"),
+    ).add_common(
         J=projection,
         V=verbose,
     )

pygmt/src/legend.py

@@ -6,7 +6,7 @@
 from typing import Literal
 
 from pygmt._typing import PathLike
-from pygmt.alias import AliasSystem
+from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.exceptions import GMTTypeError
 from pygmt.helpers import (
@@ -17,22 +17,18 @@
     kwargs_to_strings,
     use_alias,
 )
+from pygmt.params import Box
 
 
 @fmt_docstring
-@use_alias(
-    R="region",
-    D="position",
-    F="box",
-    p="perspective",
-)
+@use_alias(R="region", D="position", p="perspective")
 @kwargs_to_strings(R="sequence", p="sequence")
 def legend(
     self,
     spec: PathLike | io.StringIO | None = None,
     projection=None,
     position="JTR+jTR+o0.2c",
-    box="+gwhite+p1p",
+    box: Box | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | tuple[int, int] | bool = False,
@@ -51,6 +47,7 @@ def legend(
     Full GMT docs at :gmt-docs:`legend.html`.
 
     {aliases}
+       - F = box
        - J = projection
        - V = verbose
        - c = panel
@@ -77,24 +74,23 @@ def legend(
         legend. By default, uses **JTR**\ **+jTR**\ **+o**\ 0.2c which
         places the legend at the top-right corner inside the map frame, with a
         0.2 cm offset.
-    box : bool or str
-        [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\
-        [**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ [[*dx*/*dy*/][*shade*]]].
-        If set to ``True``, draw a rectangular border around the legend
-        using :gmt-term:`MAP_FRAME_PEN`. By default, uses
-        **+g**\ white\ **+p**\ 1p which draws a box around the legend using a
-        1p black pen and adds a white background.
+    box
+        Draw a background box behind the legend. If set to ``True``, a simple
+        rectangular box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box
+        appearance, pass a :class:`pygmt.params.Box` object to control style, fill, pen,
+        and other box properties.
     {verbose}
     {panel}
     {perspective}
     {transparency}
     """
     self._activate_figure()
 
+    # Default position and box when not specified.
     if kwargs.get("D") is None:
         kwargs["D"] = position
-        if kwargs.get("F") is None:
-            kwargs["F"] = box
+        if box is False and kwargs.get("F") is None:
+            box = Box(pen="1p", fill="white")  # Default box
 
     kind = data_kind(spec)
     if kind not in {"empty", "file", "stringio"}:
@@ -104,7 +100,9 @@ def legend(
             type(spec), reason="Only one legend specification file is allowed."
         )
 
-    aliasdict = AliasSystem().add_common(
+    aliasdict = AliasSystem(
+        F=Alias(box, name="box"),
+    ).add_common(
         J=projection,
         V=verbose,
         c=panel,