From 9e2b9f4170e7efc2331b50f06dea4aac7c5053c7 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sun, 11 Jan 2026 23:25:36 +0800 Subject: [PATCH 1/2] Figure.basemap/Figure.coast: Deprecate the 'map_scale' parameter. Use 'Figure.scalebar' instead. --- pygmt/src/basemap.py | 47 +++++++++++++++++++++++++++----------------- pygmt/src/coast.py | 22 +++++++++++++++++---- 2 files changed, 47 insertions(+), 22 deletions(-) diff --git a/pygmt/src/basemap.py b/pygmt/src/basemap.py index 8c264f4f3e5..e4309318410 100644 --- a/pygmt/src/basemap.py +++ b/pygmt/src/basemap.py @@ -11,20 +11,15 @@ @fmt_docstring -@use_alias( - L="map_scale", - F="box", - Td="rose", - Tm="compass", - f="coltypes", -) -def basemap( +@use_alias(F="box", Td="rose", Tm="compass", f="coltypes") +def basemap( # noqa: PLR0913 self, projection: str | None = None, zsize: float | str | None = None, zscale: float | str | None = None, frame: str | Sequence[str] | bool = False, region: Sequence[float | str] | str | None = None, + map_scale: str | None = None, verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"] | bool = False, panel: int | Sequence[int] | bool = False, @@ -35,13 +30,17 @@ def basemap( r""" Plot base maps and frames. - Creates a basic or fancy basemap with axes, fill, and titles. Several - map projections are available, and the user may specify separate - tick-mark intervals for boundary annotation, ticking, and [optionally] - gridlines. A simple map scale or directional rose may also be plotted. + Creates a basic or fancy basemap with axes, fill, and titles. Several map + projections are available, and the user may specify separate tick-mark intervals for + boundary annotation, ticking, and [optionally] gridlines. - At least one of the parameters ``frame``, ``map_scale``, ``rose``, or - ``compass`` must be specified if not in subplot mode. + At least one of the parameters ``frame``, ``map_scale``, ``rose``, or ``compass`` + must be specified if not in subplot mode. + + See also the following methods that provide higher-level interfaces to the GMT's + ``basemap`` module: + + - :meth:`pygmt.Figure.scalebar`: Add a scale bar on the plot. Full GMT docs at :gmt-docs:`basemap.html`. @@ -50,6 +49,7 @@ def basemap( - J = projection - Jz = zscale - JZ = zsize + - L = map_scale - R = region - V = verbose - c = panel @@ -64,10 +64,20 @@ def basemap( $region *Required if this is the first plot command.* $frame - map_scale : str - [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\ - **+w**\ *length*. - Draw a simple map scale centered on the reference point specified. + map_scale + Draw a map scale bar on the plot. + + .. deprecated:: v0.19.0 + + The ``map_scale`` parameter is deprecated. Use :meth:`pygmt.Figure.scalebar` + instead, which provides a more comprehensive and flexible API for adding + scale bars to plots. + + .. note:: + + This parameter accepts raw GMT CLI strings for the ``-L`` option of + the ``basemap`` module for backward compatibility. + box : bool or str [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\ [**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ [[*dx*/*dy*/][*shade*]]]. @@ -103,6 +113,7 @@ def basemap( aliasdict = AliasSystem( Jz=Alias(zscale, name="zscale"), JZ=Alias(zsize, name="zsize"), + L=Alias(map_scale, name="map_scale"), # Deprecated. ).add_common( B=frame, J=projection, diff --git a/pygmt/src/coast.py b/pygmt/src/coast.py index 2c94a5403d4..43db462d0de 100644 --- a/pygmt/src/coast.py +++ b/pygmt/src/coast.py @@ -15,7 +15,7 @@ @fmt_docstring -@use_alias(A="area_thresh", C="lakes", E="dcw", L="map_scale") +@use_alias(A="area_thresh", C="lakes", E="dcw") def coast( # noqa: PLR0913 self, resolution: Literal[ @@ -26,6 +26,7 @@ def coast( # noqa: PLR0913 rivers: int | str | Sequence[int | str] | None = None, borders: int | str | Sequence[int | str] | None = None, shorelines: bool | str | Sequence[int | str] = False, + map_scale: str | None = None, box: Box | bool = False, projection: str | None = None, frame: str | Sequence[str] | bool = False, @@ -63,6 +64,7 @@ def coast( # noqa: PLR0913 - G = land - I = rivers - J = projection + - L = map_scale - R = region - S = water - V = verbose @@ -131,9 +133,20 @@ def coast( # noqa: PLR0913 - ``rivers=["1/0.5p,blue", "5/0.3p,cyan,dashed"]``: Draw permanent major rivers with a 0.5-point blue pen and intermittent major rivers with a 0.3-point dashed cyan pen. - map_scale : str - [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\ **+w**\ *length*. - Draw a simple map scale centered on the reference point specified. + map_scale + Draw a map scale bar on the plot. + + .. deprecated:: v0.19.0 + + The ``map_scale`` parameter is deprecated. Use :meth:`pygmt.Figure.scalebar` + instead, which provides a more comprehensive and flexible API for adding + scale bars to plots. + + .. note:: + + This parameter accepts raw GMT CLI strings for the ``-L`` option of + the ``basemap`` module for backward compatibility. + 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 @@ -256,6 +269,7 @@ def coast( # noqa: PLR0913 F=Alias(box, name="box"), G=Alias(land, name="land"), I=Alias(rivers, name="rivers"), + L=Alias(map_scale, name="map_scale"), # Deprecated. N=Alias(borders, name="borders"), S=Alias(water, name="water"), W=Alias(shorelines, name="shorelines"), From 7daad2d8017076409d8161f0fb15d3f5623e4180 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 21 Jan 2026 14:06:49 +0800 Subject: [PATCH 2/2] Fix docstrings --- pygmt/src/basemap.py | 13 ++++--------- pygmt/src/coast.py | 13 ++++--------- 2 files changed, 8 insertions(+), 18 deletions(-) diff --git a/pygmt/src/basemap.py b/pygmt/src/basemap.py index e4309318410..a629c0e207a 100644 --- a/pygmt/src/basemap.py +++ b/pygmt/src/basemap.py @@ -69,15 +69,10 @@ def basemap( # noqa: PLR0913 .. deprecated:: v0.19.0 - The ``map_scale`` parameter is deprecated. Use :meth:`pygmt.Figure.scalebar` - instead, which provides a more comprehensive and flexible API for adding - scale bars to plots. - - .. note:: - - This parameter accepts raw GMT CLI strings for the ``-L`` option of - the ``basemap`` module for backward compatibility. - + This parameter is deprecated. Use :meth:`pygmt.Figure.scalebar` instead, + which provides a more comprehensive and flexible API for adding scale bars + to plots. This parameter still accepts raw GMT CLI strings for the ``-L`` + option of the ``basemap`` module for backward compatibility. box : bool or str [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\ [**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ [[*dx*/*dy*/][*shade*]]]. diff --git a/pygmt/src/coast.py b/pygmt/src/coast.py index 43db462d0de..02f5e1a4fc2 100644 --- a/pygmt/src/coast.py +++ b/pygmt/src/coast.py @@ -138,15 +138,10 @@ def coast( # noqa: PLR0913 .. deprecated:: v0.19.0 - The ``map_scale`` parameter is deprecated. Use :meth:`pygmt.Figure.scalebar` - instead, which provides a more comprehensive and flexible API for adding - scale bars to plots. - - .. note:: - - This parameter accepts raw GMT CLI strings for the ``-L`` option of - the ``basemap`` module for backward compatibility. - + This parameter is deprecated. Use :meth:`pygmt.Figure.scalebar` instead, + which provides a more comprehensive and flexible API for adding scale bars + to plots. This parameter still accepts raw GMT CLI strings for the ``-L`` + option of the ``basemap`` module for backward compatibility. 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