From 08edce29684282d4d504d8d9df5b36f421d57906 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 19 Jan 2024 21:30:40 +0800 Subject: [PATCH] Figure.timestamp: Deprecate parameter 'justification' to 'justify' (remove in v0.13.0) (#3002) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com> --- examples/gallery/embellishments/timestamp.py | 16 +++++++------- pygmt/src/timestamp.py | 21 ++++++++++--------- ...png.dvc => test_timestamp_justify.png.dvc} | 2 +- pygmt/tests/test_timestamp.py | 6 +++--- 4 files changed, 22 insertions(+), 23 deletions(-) rename pygmt/tests/baseline/{test_timestamp_justification.png.dvc => test_timestamp_justify.png.dvc} (63%) diff --git a/examples/gallery/embellishments/timestamp.py b/examples/gallery/embellishments/timestamp.py index 9cda32b19f4..41fa95a67db 100644 --- a/examples/gallery/embellishments/timestamp.py +++ b/examples/gallery/embellishments/timestamp.py @@ -2,11 +2,10 @@ Timestamp ========= -The :meth:`pygmt.Figure.timestamp` method can draw the GMT timestamp logo on -the plot. The timestamp will always be shown relative to the bottom-left corner -of the plot. By default, the ``offset`` and ``justification`` parameters are -set to ``("-54p", "-54p")`` (x, y directions) and ``"BL"`` (bottom-left), -respectively. +The :meth:`pygmt.Figure.timestamp` method can draw the GMT timestamp logo on the plot. +The timestamp will always be shown relative to the bottom-left corner of the plot. By +default, the ``offset`` and ``justify`` parameters are set to ``("-54p", "-54p")`` +(x, y directions) and ``"BL"`` (bottom-left), respectively. """ # %% @@ -20,9 +19,8 @@ fig.show() # %% -# Additionally, a custom label can be added via the ``label`` parameter. The -# font can be defined via the ``font`` parameter and the timestamp string -# format via ``timefmt``. +# Additionally, a custom label can be added via the ``label`` parameter. The font can be +# defined via the ``font`` parameter and the timestamp string format via ``timefmt``. os.environ["TZ"] = "Pacific/Honolulu" # optionally set the time zone @@ -30,7 +28,7 @@ fig.coast(region="d", projection="H10c", land="black", water="cornsilk", frame="afg") fig.timestamp( label="Powered by PyGMT", - justification="TL", + justify="TL", font="Times-Bold", timefmt="%Y-%m-%dT%H:%M:%S%z", ) diff --git a/pygmt/src/timestamp.py b/pygmt/src/timestamp.py index 96c816a67d9..84937a08a2f 100644 --- a/pygmt/src/timestamp.py +++ b/pygmt/src/timestamp.py @@ -8,7 +8,7 @@ from packaging.version import Version from pygmt.clib import Session, __gmt_version__ -from pygmt.helpers import build_arg_string, kwargs_to_strings +from pygmt.helpers import build_arg_string, deprecate_parameter, kwargs_to_strings if TYPE_CHECKING: from collections.abc import Sequence @@ -17,16 +17,17 @@ __doctest_skip__ = ["timestamp"] +@deprecate_parameter("justification", "justify", "v0.11.0", remove_version="v0.13.0") @kwargs_to_strings(offset="sequence") def timestamp( self, text: str | None = None, label: str | None = None, - justification: str = "BL", + justify: str = "BL", offset: float | str | Sequence[float | str] = ("-54p", "-54p"), font: str = "Helvetica,black", timefmt: str = "%Y %b %d %H:%M:%S", -) -> None: +): r""" Plot the GMT timestamp logo. @@ -44,13 +45,13 @@ def timestamp( The text must be no longer than 64 characters. label The text string shown after the GMT timestamp logo. - justification + justify Justification of the timestamp box relative to the plot's bottom-left corner - (i.e., the plot origin). The *justification* is a two-character code that is a - combination of a horizontal (**L**\ (eft), **C**\ (enter), or **R**\ (ight)) and - a vertical (**T**\ (op), **M**\ (iddle), or **B**\ (ottom)) code. For example, - ``justification="TL"`` means choosing the **T**\ op **L**\ eft point of the - timestamp as the anchor point. + (i.e., the plot origin). Give a two-character code that is a combination of a + horizontal (**L**\ (eft), **C**\ (enter), or **R**\ (ight)) and a vertical + (**T**\ (op), **M**\ (iddle), or **B**\ (ottom)) code. For example, + ``justify="TL"`` means choosing the **T**\ op **L**\ eft point of the timestamp + as the anchor point. offset *offset* or (*offset_x*, *offset_y*). Offset the anchor point of the timestamp box by *offset_x* and *offset_y*. If a @@ -86,7 +87,7 @@ def timestamp( kwdict: dict = {"T": True, "U": ""} if label is not None: kwdict["U"] += f"{label}" - kwdict["U"] += f"+j{justification}" + kwdict["U"] += f"+j{justify}" if Version(__gmt_version__) <= Version("6.4.0") and "/" not in str(offset): # Giving a single offset doesn't work in GMT <= 6.4.0. diff --git a/pygmt/tests/baseline/test_timestamp_justification.png.dvc b/pygmt/tests/baseline/test_timestamp_justify.png.dvc similarity index 63% rename from pygmt/tests/baseline/test_timestamp_justification.png.dvc rename to pygmt/tests/baseline/test_timestamp_justify.png.dvc index d7fc8addad1..1dfddb31f0f 100644 --- a/pygmt/tests/baseline/test_timestamp_justification.png.dvc +++ b/pygmt/tests/baseline/test_timestamp_justify.png.dvc @@ -1,5 +1,5 @@ outs: - md5: fcf1511052ece6b0e2ed97b6ae5af772 size: 8828 - path: test_timestamp_justification.png + path: test_timestamp_justify.png hash: md5 diff --git a/pygmt/tests/test_timestamp.py b/pygmt/tests/test_timestamp.py index a22d68ce800..3a5e9506574 100644 --- a/pygmt/tests/test_timestamp.py +++ b/pygmt/tests/test_timestamp.py @@ -35,16 +35,16 @@ def test_timestamp_label(faketime): @pytest.mark.mpl_image_compare -def test_timestamp_justification(): +def test_timestamp_justify(): """ - Check if the "justification" parameter works. + Check if the "justify" parameter works. Only a subset of justification codes are tested to avoid overlapping timestamps. """ fig = Figure() fig.basemap(projection="X10c/5c", region=[0, 10, 0, 5], frame=0) for just in ["BL", "BR", "TL", "TR"]: - fig.timestamp(justification=just, timefmt=just) + fig.timestamp(justify=just, timefmt=just) return fig