From 64f77e4beb02ac2ecdfc1c7ef7e467dec379a0a9 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 28 Mar 2026 21:52:45 +0800 Subject: [PATCH 1/2] Warn on deprecated basemap embellishment options --- pygmt/src/basemap.py | 20 +++++++++++++++++--- pygmt/tests/test_basemap.py | 33 ++++++++++++++++++--------------- 2 files changed, 35 insertions(+), 18 deletions(-) diff --git a/pygmt/src/basemap.py b/pygmt/src/basemap.py index e505c23c255..854f938c341 100644 --- a/pygmt/src/basemap.py +++ b/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,8 +44,8 @@ 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``, ``compass``, and ``box`` 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. @@ -119,6 +121,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"), diff --git a/pygmt/tests/test_basemap.py b/pygmt/tests/test_basemap.py index bdd2e6def50..42ed3ff7dfe 100644 --- a/pygmt/tests/test_basemap.py +++ b/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 From d0b95a74e471c669c1e1ee68f0f49f5b73163127 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 28 Mar 2026 22:05:41 +0800 Subject: [PATCH 2/2] Refine basemap deprecation docs --- pygmt/src/basemap.py | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/pygmt/src/basemap.py b/pygmt/src/basemap.py index 854f938c341..438078b94f2 100644 --- a/pygmt/src/basemap.py +++ b/pygmt/src/basemap.py @@ -44,15 +44,17 @@ def basemap( # noqa: PLR0913 .. note:: - Parameters ``map_scale``, ``rose``, ``compass``, and ``box`` are deprecated - since v0.19.0 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`. @@ -112,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