From 335cd1dc4735e66177498453716ad7abc228ad51 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 8 Dec 2023 18:31:49 +0800 Subject: [PATCH 1/4] Figure.timestamp: Add type hints --- pygmt/src/timestamp.py | 34 ++++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/pygmt/src/timestamp.py b/pygmt/src/timestamp.py index 6ed3ee39fb4..35c76be316d 100644 --- a/pygmt/src/timestamp.py +++ b/pygmt/src/timestamp.py @@ -1,7 +1,13 @@ """ timestamp - Plot the GMT timestamp logo. """ +from __future__ import annotations + import warnings +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from collections.abc import Sequence from packaging.version import Version from pygmt.clib import Session, __gmt_version__ @@ -13,13 +19,13 @@ @kwargs_to_strings(offset="sequence") def timestamp( self, - text=None, - label=None, - justification="BL", - offset=("-54p", "-54p"), - font="Helvetica,black", - timefmt="%Y %b %d %H:%M:%S", -): + text: str | None = None, + label: str | None = None, + justification: 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. @@ -32,13 +38,13 @@ def timestamp( Parameters ---------- - text : None or str + text If ``None``, the current UNIX timestamp is shown in the GMT timestamp logo. Set this parameter to replace the UNIX timestamp with a custom text string instead. The text must be no longer than 64 characters. - label : None or str + label The text string shown after the GMT timestamp logo. - justification : str + justification 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), @@ -46,17 +52,17 @@ def timestamp( **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. - offset : str or list + offset *offset* or [*offset_x*, *offset_y*]. Offset the anchor point of the timestamp box by *offset_x* and *offset_y*. If a single value *offset* is given, *offset_y* = *offset_x* = *offset*. - font : str + font Font of the timestamp and the optional label. Since the GMT logo has a fixed height, the font sizes are fixed to be 8-point for the timestamp and 7-point for the label. The parameter can't change the font color for GMT<=6.4.0, only the font style. - timefmt : str + timefmt Format string for the UNIX timestamp. The format string is parsed by the C function ``strftime``, so that virtually any text can be used (even not containing any time information). @@ -79,7 +85,7 @@ def timestamp( self._preprocess() # Build the options passed to the "plot" module - kwdict = {"T": True, "U": ""} + kwdict: dict = {"T": True, "U": ""} if label is not None: kwdict["U"] += f"{label}" kwdict["U"] += f"+j{justification}" From 0f2568edd80b1f3a549aa90d8634ba3aeea4e34a Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Thu, 21 Dec 2023 17:02:50 +0800 Subject: [PATCH 2/4] Always put TYPE_CHECKING at the end --- pygmt/src/timestamp.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/pygmt/src/timestamp.py b/pygmt/src/timestamp.py index 35c76be316d..41972d40735 100644 --- a/pygmt/src/timestamp.py +++ b/pygmt/src/timestamp.py @@ -6,13 +6,14 @@ import warnings from typing import TYPE_CHECKING -if TYPE_CHECKING: - from collections.abc import Sequence - from packaging.version import Version from pygmt.clib import Session, __gmt_version__ from pygmt.helpers import build_arg_string, kwargs_to_strings +if TYPE_CHECKING: + from collections.abc import Sequence + + __doctest_skip__ = ["timestamp"] From e5140edd995357deaecf81ee1600c6daa66694c2 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Mon, 25 Dec 2023 21:06:19 +0800 Subject: [PATCH 3/4] Use a tuple instead of a list --- pygmt/src/timestamp.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pygmt/src/timestamp.py b/pygmt/src/timestamp.py index 41972d40735..62aac9405b7 100644 --- a/pygmt/src/timestamp.py +++ b/pygmt/src/timestamp.py @@ -54,7 +54,7 @@ def timestamp( ``justification="TL"`` means choosing the **T**\ op **L**\ eft point of the timestamp as the anchor point. offset - *offset* or [*offset_x*, *offset_y*]. + *offset* or (*offset_x*, *offset_y*). Offset the anchor point of the timestamp box by *offset_x* and *offset_y*. If a single value *offset* is given, *offset_y* = *offset_x* = *offset*. From 3e0100a05a179573c8a2ac67972627724aa69635 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Tue, 2 Jan 2024 13:50:21 +0800 Subject: [PATCH 4/4] Rewrap docstrings to 88 characters --- pygmt/src/timestamp.py | 49 ++++++++++++++++++++---------------------- 1 file changed, 23 insertions(+), 26 deletions(-) diff --git a/pygmt/src/timestamp.py b/pygmt/src/timestamp.py index 62aac9405b7..96c816a67d9 100644 --- a/pygmt/src/timestamp.py +++ b/pygmt/src/timestamp.py @@ -30,43 +30,40 @@ def timestamp( r""" Plot the GMT timestamp logo. - Add the GMT timestamp logo with an optional label at the bottom-left corner - of a plot with an offset of ``("-54p", "-54p")``. The timestamp will be - in the locale set by the environment variable **TZ** (generally local time - but can be changed via ``os.environ["TZ"]``) and its format is controlled - by the ``timefmt`` parameter. It can also be replaced with any custom - text string using the ``text`` parameter. + Add the GMT timestamp logo with an optional label at the bottom-left corner of a + plot with an offset of ``("-54p", "-54p")``. The timestamp will be in the locale set + by the environment variable **TZ** (generally local time but can be changed via + ``os.environ["TZ"]``) and its format is controlled by the ``timefmt`` parameter. It + can also be replaced with any custom text string using the ``text`` parameter. Parameters ---------- text - If ``None``, the current UNIX timestamp is shown in the GMT timestamp - logo. Set this parameter to replace the UNIX timestamp with a custom - text string instead. The text must be no longer than 64 characters. + If ``None``, the current UNIX timestamp is shown in the GMT timestamp logo. Set + this parameter to replace the UNIX timestamp with a custom text string instead. + The text must be no longer than 64 characters. label The text string shown after the GMT timestamp logo. justification - 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. + 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. offset *offset* or (*offset_x*, *offset_y*). - Offset the anchor point of the timestamp box by *offset_x* and - *offset_y*. If a single value *offset* is given, *offset_y* = - *offset_x* = *offset*. + Offset the anchor point of the timestamp box by *offset_x* and *offset_y*. If a + single value *offset* is given, *offset_y* = *offset_x* = *offset*. font - Font of the timestamp and the optional label. Since the GMT logo has a - fixed height, the font sizes are fixed to be 8-point for the timestamp - and 7-point for the label. The parameter can't change the font color - for GMT<=6.4.0, only the font style. + Font of the timestamp and the optional label. Since the GMT logo has a fixed + height, the font sizes are fixed to be 8-point for the timestamp and 7-point for + the label. The parameter can't change the font color for GMT<=6.4.0, only the + font style. timefmt - Format string for the UNIX timestamp. The format string is parsed by - the C function ``strftime``, so that virtually any text can be used - (even not containing any time information). + Format string for the UNIX timestamp. The format string is parsed by the C + function ``strftime``, so that virtually any text can be used (even not + containing any time information). Examples --------