Figure.timestamp: Deprecate parameter 'justification' to 'justify' (r…

…emove in v0.13.0) (#3002)

Co-authored-by: Yvonne Fröhlich <[email protected]>

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,17 +19,16 @@
 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
 
 fig = pygmt.Figure()
 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",
 )

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.

pygmt/tests/baseline/test_timestamp_justification.png.dvc → 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

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