Figure.basemap: Raise a warning on deprecated parameters "map_scale", "rose", and "compass"

pygmt/src/basemap.py

@@ -2,12 +2,14 @@
 basemap - Plot base maps and frames.
 """
 
+import warnings
 from collections.abc import Sequence
 from typing import Literal
 
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.helpers import build_arg_list, fmt_docstring, use_alias
+from pygmt.params import Box
 
 
 @fmt_docstring
@@ -24,7 +26,7 @@ def basemap(  # noqa: PLR0913
     map_scale: str | None = None,
     compass: str | None = None,
     rose: str | None = None,
-    box: str | bool = False,
+    box: Box | str | bool = False,
     panel: int | Sequence[int] | bool = False,
     perspective: float | Sequence[float] | str | bool = False,
     transparency: float | None = None,
@@ -42,15 +44,17 @@ def basemap(  # noqa: PLR0913
 
     .. note::
 
-        Parameters ``map_scale``, ``rose``, ``compass``, and ``box`` are deprecated in
-        favor of the dedicated higher-level methods:
+        Parameters ``map_scale``, ``rose``, and ``compass`` are deprecated since
+        v0.19.0 in favor of the dedicated higher-level methods:
 
         - :meth:`pygmt.Figure.scalebar`: Add a scale bar on the plot.
         - :meth:`pygmt.Figure.directional_rose`: Add a directional rose on the plot.
         - :meth:`pygmt.Figure.magnetic_rose`: Add a magnetic rose on the plot.
 
         These methods provide more comprehensive and flexible APIs for their respective
-        plot elements.
+        plot elements. The ``box`` parameter in :meth:`pygmt.Figure.basemap` is retained
+        only as a compatibility parameter for these legacy parameters. For new code,
+        prefer the ``box`` parameter on the dedicated methods instead.
 
     Full GMT docs at :gmt-docs:`basemap.html`.
 
@@ -110,7 +114,10 @@ def basemap(  # noqa: PLR0913
             Use the ``box`` parameter in :meth:`pygmt.Figure.scalebar`,
             :meth:`pygmt.Figure.directional_rose`, or :meth:`pygmt.Figure.magnetic_rose`
             instead. This parameter is maintained for backward compatibility and accepts
-            raw GMT CLI strings for the ``-F`` option.
+            either a :class:`pygmt.params.Box` object, a raw GMT CLI string, or ``True``
+            for the ``-F`` option. On :meth:`pygmt.Figure.basemap`, it only applies when
+            used together with the legacy ``map_scale``, ``rose``, or ``compass``
+            parameters.
     $verbose
     $panel
     $coltypes
@@ -119,6 +126,18 @@ def basemap(  # noqa: PLR0913
     """
     self._activate_figure()
 
+    for name, value, recommendation in (
+        ("map_scale", map_scale, "Figure.scalebar"),
+        ("compass", compass, "Figure.magnetic_rose"),
+        ("rose", rose, "Figure.directional_rose"),
+    ):
+        if value is not None and value is not False:
+            warnings.warn(
+                f"The {name!r} parameter has been deprecated since v0.19.0. Use {recommendation!r} instead.",
+                category=FutureWarning,
+                stacklevel=2,
+            )
+
     aliasdict = AliasSystem(
         F=Alias(box, name="box"),  # Deprecated.
         Jz=Alias(zscale, name="zscale"),

pygmt/tests/test_basemap.py

@@ -94,9 +94,10 @@ def test_basemap_rose():
     Create a map with a rose.
     """
     fig = Figure()
-    fig.basemap(
-        region=[127.5, 128.5, 26, 27], projection="H15c", frame=True, rose="jMC+w5c"
-    )
+    with pytest.warns(FutureWarning, match="'rose' parameter has been deprecated"):
+        fig.basemap(
+            region=[127.5, 128.5, 26, 27], projection="H15c", frame=True, rose="jMC+w5c"
+        )
     return fig
 
 
@@ -106,12 +107,13 @@ def test_basemap_compass():
     Create a map with a compass.
     """
     fig = Figure()
-    fig.basemap(
-        region=[127.5, 128.5, 26, 27],
-        projection="H15c",
-        frame=True,
-        compass="jMC+w5c+d11.5",
-    )
+    with pytest.warns(FutureWarning, match="'compass' parameter has been deprecated"):
+        fig.basemap(
+            region=[127.5, 128.5, 26, 27],
+            projection="H15c",
+            frame=True,
+            compass="jMC+w5c+d11.5",
+        )
     return fig
 
 
@@ -121,12 +123,13 @@ def test_basemap_map_scale():
     Create a map with a map scale.
     """
     fig = Figure()
-    fig.basemap(
-        region=[127.5, 128.5, 26, 27],
-        projection="H15c",
-        frame=True,
-        map_scale="jMC+c26.5+w10k+f+l",
-    )
+    with pytest.warns(FutureWarning, match="'map_scale' parameter has been deprecated"):
+        fig.basemap(
+            region=[127.5, 128.5, 26, 27],
+            projection="H15c",
+            frame=True,
+            map_scale="jMC+c26.5+w10k+f+l",
+        )
     return fig