Merge branch 'main' into alias-system

Author: seisman

pygmt/accessors.py

@@ -126,7 +126,7 @@ class GMTDataArrayAccessor:
     (<GridRegistration.GRIDLINE: 0>, <GridType.GEOGRAPHIC: 1>)
     """
 
-    def __init__(self, xarray_obj):
+    def __init__(self, xarray_obj: xr.DataArray):
         self._obj = xarray_obj
 
         # Default to Gridline registration and Cartesian grid type
@@ -137,19 +137,19 @@ def __init__(self, xarray_obj):
         # two columns of the shortened summary information of grdinfo.
         if (_source := self._obj.encoding.get("source")) and Path(_source).exists():
             with contextlib.suppress(ValueError):
-                self._registration, self._gtype = map(
+                self._registration, self._gtype = map(  # type: ignore[assignment]
                     int, grdinfo(_source, per_column="n").split()[-2:]
                 )
 
     @property
-    def registration(self):
+    def registration(self) -> GridRegistration:
         """
         Grid registration type :class:`pygmt.enums.GridRegistration`.
         """
         return self._registration
 
     @registration.setter
-    def registration(self, value):
+    def registration(self, value: GridRegistration | int):
         # TODO(Python>=3.12): Simplify to `if value not in GridRegistration`.
         if value not in GridRegistration.__members__.values():
             msg = (
@@ -160,14 +160,14 @@ def registration(self, value):
         self._registration = GridRegistration(value)
 
     @property
-    def gtype(self):
+    def gtype(self) -> GridType:
         """
         Grid coordinate system type :class:`pygmt.enums.GridType`.
         """
         return self._gtype
 
     @gtype.setter
-    def gtype(self, value):
+    def gtype(self, value: GridType | int):
         # TODO(Python>=3.12): Simplify to `if value not in GridType`.
         if value not in GridType.__members__.values():
             msg = (

pygmt/helpers/utils.py

@@ -174,6 +174,41 @@ def _is_printable_ascii(argstr: str) -> bool:
     return all(32 <= ord(c) <= 126 for c in argstr)
 
 
+def _contains_apostrophe_or_backtick(argstr: str) -> bool:
+    """
+    Check if a string contains apostrophe (') or backtick (`).
+
+    For typographical reasons, apostrophe (') and backtick (`) are mapped to left and
+    right single quotation marks (‘ and ’) in Adobe ISOLatin1+ encoding. To ensure that
+    what you type is what you get (issue #3476), they need special handling in the
+    ``_check_encoding`` and ``non_ascii_to_octal`` functions. More specifically, a
+    string containing printable ASCII characters with apostrophe (') and backtick (`)
+    will not be considered as "ascii" encoding.
+
+    Parameters
+    ----------
+    argstr
+        The string to be checked.
+
+    Returns
+    -------
+    ``True`` if the string contains apostrophe (') or backtick (`). Otherwise, return
+    ``False``.
+
+    Examples
+    --------
+    >>> _contains_apostrophe_or_backtick("12AB±β①②")
+    False
+    >>> _contains_apostrophe_or_backtick("12AB`")
+    True
+    >>> _contains_apostrophe_or_backtick("12AB'")
+    True
+    >>> _contains_apostrophe_or_backtick("12AB'`")
+    True
+    """  # noqa: RUF002
+    return "'" in argstr or "`" in argstr
+
+
 def _check_encoding(argstr: str) -> Encoding:
     """
     Check the charset encoding of a string.
@@ -206,8 +241,9 @@ def _check_encoding(argstr: str) -> Encoding:
     >>> _check_encoding("123AB中文")  # Characters not in any charset encoding
     'ISOLatin1+'
     """
-    # Return "ascii" if the string only contains printable ASCII characters.
-    if _is_printable_ascii(argstr):
+    # Return "ascii" if the string only contains printable ASCII characters, excluding
+    # apostrophe (') and backtick (`).
+    if _is_printable_ascii(argstr) and not _contains_apostrophe_or_backtick(argstr):
         return "ascii"
     # Loop through all supported encodings and check if all characters in the string
     # are in the charset of the encoding. If all characters are in the charset, return
@@ -402,9 +438,14 @@ def non_ascii_to_octal(argstr: str, encoding: Encoding = "ISOLatin1+") -> str:
     'ABC \\261120\\260 DEF @~\\141@~ @%34%\\252@%%'
     >>> non_ascii_to_octal("12ABāáâãäåβ①②", encoding="ISO-8859-4")
     '12AB\\340\\341\\342\\343\\344\\345@~\\142@~@%34%\\254@%%@%34%\\255@%%'
+    >>> non_ascii_to_octal("'‘’\"“”")
+    '\\234\\140\\047"\\216\\217'
     """  # noqa: RUF002
-    # Return the input string if it only contains printable ASCII characters.
-    if encoding == "ascii" or _is_printable_ascii(argstr):
+    # Return the input string if it only contains printable ASCII characters, excluding
+    # apostrophe (') and backtick (`).
+    if encoding == "ascii" or (
+        _is_printable_ascii(argstr) and not _contains_apostrophe_or_backtick(argstr)
+    ):
         return argstr
 
     # Dictionary mapping non-ASCII characters to octal codes
@@ -420,6 +461,11 @@ def non_ascii_to_octal(argstr: str, encoding: Encoding = "ISOLatin1+") -> str:
 
     # Remove any printable characters.
     mapping = {k: v for k, v in mapping.items() if k not in string.printable}
+
+    if encoding == "ISOLatin1+":
+        # Map apostrophe (') and backtick (`) to correct octal codes.
+        # See _contains_apostrophe_or_backtick() for explanations.
+        mapping.update({"'": "\\234", "`": "\\221"})
     return argstr.translate(str.maketrans(mapping))
 
 
@@ -465,16 +511,12 @@ def build_arg_list(  # noqa: PLR0912
     ['-A', '-D0', '-E200', '-F', '-G1/2/3/4']
     >>> build_arg_list(dict(A="1/2/3/4", B=["xaf", "yaf", "WSen"], C=("1p", "2p")))
     ['-A1/2/3/4', '-BWSen', '-Bxaf', '-Byaf', '-C1p', '-C2p']
-    >>> print(
-    ...     build_arg_list(
-    ...         dict(
-    ...             B=["af", "WSne+tBlank Space"],
-    ...             F='+t"Empty Spaces"',
-    ...             l="'Void Space'",
-    ...         )
-    ...     )
-    ... )
-    ['-BWSne+tBlank Space', '-Baf', '-F+t"Empty Spaces"', "-l'Void Space'"]
+    >>> build_arg_list(dict(B=["af", "WSne+tBlank Space"]))
+    ['-BWSne+tBlank Space', '-Baf']
+    >>> build_arg_list(dict(F='+t"Empty Spaces"'))
+    ['-F+t"Empty Spaces"']
+    >>> build_arg_list(dict(l="'Void Space'"))
+    ['-l\\234Void Space\\234', '--PS_CHAR_ENCODING=ISOLatin1+']
     >>> print(
     ...     build_arg_list(
     ...         dict(A="0", B=True, C="rainbow"),

pygmt/src/shift_origin.py

@@ -2,20 +2,41 @@
 shift_origin - Shift plot origin in x and/or y directions.
 """
 
+import contextlib
+
 from pygmt.clib import Session
+from pygmt.helpers import build_arg_list
 
 
 def shift_origin(
     self, xshift: float | str | None = None, yshift: float | str | None = None
 ):
     r"""
-    Shift plot origin in x and/or y directions.
+    Shift the plot origin in x and/or y directions.
+
+    The shifts can be permanent or temporary. If used as a standalone method, the shifts
+    are permanent and apply to all subsequent plots. If used as a context manager, the
+    shifts are temporary and only apply to the block of code within the context manager.
+
+    1.  Use as a standalone method to shift the plot origin permanently:
+
+        .. code-block:: python
+
+            fig.shift_origin(...)
+            ...  # Other plot commands
+
+    2.  Use as a context manager to shift the plot origin temporarily:
+
+        .. code-block:: python
+
+            with fig.shift_origin(...):
+                ...  # Other plot commands
+                ...
 
-    This method shifts the plot origin relative to the current origin by *xshift* and
-    *yshift* in x and y directions, respectively. Optionally, append the length unit
+    The shifts *xshift* and *yshift* in x and y directions are relative to the current
+    plot origin. The default unit for shifts is centimeters (**c**) but can be changed
+    to other units via :gmt-term:`PROJ_LENGTH_UNIT`. Optionally, append the length unit
     (**c** for centimeters, **i** for inches, or **p** for points) to the shifts.
-    Default unit if not explicitly given is **c**, but can be changed to other units via
-    :gmt-term:`PROJ_LENGTH_UNIT`.
 
     For *xshift*, a special character **w** can also be used, which represents the
     bounding box **width** of the previous plot. The full syntax is
@@ -44,23 +65,63 @@ def shift_origin(
 
     Examples
     --------
+
+    Shifting the plot origin permanently:
+
     >>> import pygmt
     >>> fig = pygmt.Figure()
-    >>> fig.basemap(region=[0, 10, 0, 10], projection="X10c/10c", frame=True)
-    >>> # Shift the plot origin in x direction by 12 cm
-    >>> fig.shift_origin(xshift=12)
-    >>> fig.basemap(region=[0, 10, 0, 10], projection="X14c/10c", frame=True)
-    >>> # Shift the plot origin in x direction based on the previous plot width
-    >>> # Here, the width is 14 cm, and xshift is 16 cm
-    >>> fig.shift_origin(xshift="w+2c")
+    >>> fig.basemap(region=[0, 5, 0, 5], projection="X5c/5c", frame=True)
+    >>> # Shift the plot origin in x direction by 6 cm
+    >>> fig.shift_origin(xshift=6)
+    <contextlib._GeneratorContextManager object at ...>
+    >>> fig.basemap(region=[0, 7, 0, 5], projection="X7c/5c", frame=True)
+    >>> # Shift the plot origin in x direction based on the previous plot width.
+    >>> # Here, the width is 7 cm, and xshift is 8 cm.
+    >>> fig.shift_origin(xshift="w+1c")
+    <contextlib._GeneratorContextManager object at ...>
+    >>> fig.basemap(region=[0, 10, 0, 5], projection="X10c/5c", frame=True)
+    >>> fig.show()
+
+    Shifting the plot origin temporarily:
+
+    >>> fig = pygmt.Figure()
+    >>> fig.basemap(region=[0, 5, 0, 5], projection="X5c/5c", frame=True)
+    >>> # Shift the plot origin in x direction by 6 cm temporarily. The plot origin will
+    >>> # revert back to the original plot origin after the block of code is executed.
+    >>> with fig.shift_origin(xshift=6):
+    ...     fig.basemap(region=[0, 5, 0, 5], projection="X5c/5c", frame=True)
+    >>> # Shift the plot origin in y direction by 6 cm temporarily.
+    >>> with fig.shift_origin(yshift=6):
+    ...     fig.basemap(region=[0, 5, 0, 5], projection="X5c/5c", frame=True)
+    >>> # Shift the plot origin in x and y directions by 6 cm temporarily.
+    >>> with fig.shift_origin(xshift=6, yshift=6):
+    ...     fig.basemap(region=[0, 5, 0, 5], projection="X5c/5c", frame=True)
     >>> fig.show()
     """
     self._preprocess()
-    args = ["-T"]
-    if xshift:
-        args.append(f"-X{xshift}")
-    if yshift:
-        args.append(f"-Y{yshift}")
+    kwdict = {"T": True, "X": xshift, "Y": yshift}
 
     with Session() as lib:
-        lib.call_module(module="plot", args=args)
+        lib.call_module(module="plot", args=build_arg_list(kwdict))
+        _xshift = lib.get_common("X")  # False or xshift in inches
+        _yshift = lib.get_common("Y")  # False or yshift in inches
+
+    @contextlib.contextmanager
+    def _shift_origin_context():
+        """
+        An internal context manager to shift the plot origin temporarily.
+        """
+        try:
+            yield
+        finally:
+            # Revert the plot origin to the original plot origin by shifting it by
+            # -xshift and -yshift in inches.
+            kwdict = {
+                "T": True,
+                "X": f"{-1.0 * _xshift}i" if _xshift else None,
+                "Y": f"{-1.0 * _yshift}i" if _yshift else None,
+            }
+            with Session() as lib:
+                lib.call_module(module="plot", args=build_arg_list(kwdict))
+
+    return _shift_origin_context()

pygmt/tests/baseline/test_shift_origin_context_manager.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: 6c63b9935618f607fe22608f7561be22
+  size: 4869
+  hash: md5
+  path: test_shift_origin_context_manager.png

pygmt/tests/baseline/test_shift_origin_mixed_modes.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: 3a31df374874ae00920ada0b311b4266
+  size: 5678
+  hash: md5
+  path: test_shift_origin_mixed_modes.png

pygmt/tests/baseline/test_shift_origin_nested_context_manager.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: cd83745f2657ff7daeaba368143db72f
+  size: 4876
+  hash: md5
+  path: test_shift_origin_nested_context_manager.png

pygmt/tests/baseline/test_text_quotation_marks.png.dvc

@@ -1,5 +1,5 @@
 outs:
-- md5: 90d08c5a11c606abed51b84eafcdea04
-  size: 1662
+- md5: f3ddc9b50f3da1facdbcd32261db3bd6
+  size: 2965
   hash: md5
   path: test_text_quotation_marks.png

pygmt/tests/test_shift_origin.py

@@ -3,8 +3,16 @@
 """
 
 import pytest
+from pygmt import Figure
 from pygmt.exceptions import GMTInvalidInput
-from pygmt.figure import Figure
+
+
+def _numbered_basemap(fig, number, size=3):
+    """
+    A utility function to create a basemap with a number in the center.
+    """
+    fig.basemap(region=[0, 1, 0, 1], projection=f"X{size}c", frame=0)
+    fig.text(position="MC", text=number, font="24p")
 
 
 @pytest.mark.mpl_image_compare
@@ -27,6 +35,69 @@ def test_shift_origin():
     return fig
 
 
+@pytest.mark.mpl_image_compare
+def test_shift_origin_context_manager():
+    """
+    Test if Figure.shift_origin as a context manager shifts origin temporarily.
+
+    Expected output is:
+    | 3 | 4 |
+    | 1 | 2 |
+    """
+    fig = Figure()
+    _numbered_basemap(fig, 1, size=2.5)
+    with fig.shift_origin(xshift=3):
+        _numbered_basemap(fig, 2, size=2.5)
+    with fig.shift_origin(yshift=3):
+        _numbered_basemap(fig, 3, size=2.5)
+    with fig.shift_origin(xshift=3, yshift=3):
+        _numbered_basemap(fig, 4, size=2.5)
+    return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_shift_origin_nested_context_manager():
+    """
+    Test if Figure.shift_origin shifts origin correctly when used in a nested context
+    manager.
+
+    Expected output is:
+    | 4 | 3 |
+    | 1 | 2 |
+    """
+    fig = Figure()
+    _numbered_basemap(fig, 1, size=2.5)
+    with fig.shift_origin(xshift=3):
+        _numbered_basemap(fig, 2, size=2.5)
+        with fig.shift_origin(yshift=3):
+            _numbered_basemap(fig, 3, size=2.5)
+    with fig.shift_origin(yshift=3):
+        _numbered_basemap(fig, 4, size=2.5)
+    return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_shift_origin_mixed_modes():
+    """
+    Test if Figure.shift_origin works when used as a context manager and as a
+    method at the same time.
+
+    Expected output is:
+    |   | 3 | 4 |
+    | 1 | 2 |   |
+    """
+    fig = Figure()
+    _numbered_basemap(fig, 1, size=2.5)
+    with fig.shift_origin(xshift=3):
+        _numbered_basemap(fig, 2, size=2.5)
+    fig.shift_origin(xshift=3)
+    with fig.shift_origin(yshift=3):
+        _numbered_basemap(fig, 3, size=2.5)
+    fig.shift_origin(xshift=3, yshift=3)
+    _numbered_basemap(fig, 4, size=2.5)
+    return fig
+
+
 def test_shift_origin_unsupported_xshift_yshift():
     """
     Raise an exception if X/Y/xshift/yshift is used.