Merge branch 'main' into pyarrow/string

Author: weiji14

pygmt/_typing.py

@@ -0,0 +1,8 @@
+"""
+Type aliases for type hints.
+"""
+
+from typing import Literal
+
+# Anchor codes
+AnchorCode = Literal["TL", "TC", "TR", "ML", "MC", "MR", "BL", "BC", "BR"]

pygmt/clib/conversion.py

@@ -7,6 +7,8 @@
 from collections.abc import Sequence
 
 import numpy as np
+import pandas as pd
+from packaging.version import Version
 from pygmt.exceptions import GMTInvalidInput
 
 StringArrayTypes = Sequence[str] | np.ndarray
@@ -187,6 +189,10 @@ def vectors_to_arrays(vectors):
     >>> [i.ndim for i in data]  # Check that they are 1-D arrays
     [1, 1, 1]
 
+    >>> series = pd.Series(data=[0, 4, pd.NA, 8, 6], dtype=pd.Int32Dtype())
+    >>> vectors_to_arrays([series])
+    [array([ 0.,  4., nan,  8.,  6.])]
+
     >>> import datetime
     >>> import pytest
     >>> pa = pytest.importorskip("pyarrow")
@@ -214,8 +220,20 @@ def vectors_to_arrays(vectors):
     }
     arrays = []
     for vector in vectors:
-        vec_dtype = str(getattr(vector, "dtype", ""))
-        arrays.append(np.ascontiguousarray(vector, dtype=dtypes.get(vec_dtype)))
+        if (
+            hasattr(vector, "isna")
+            and vector.isna().any()
+            and Version(pd.__version__) < Version("2.2")
+        ):
+            # Workaround for dealing with pd.NA with pandas < 2.2.
+            # Bug report at: https://github.com/GenericMappingTools/pygmt/issues/2844
+            # Following SPEC0, pandas 2.1 will be dropped in 2025 Q3, so it's likely
+            # we can remove the workaround in PyGMT v0.17.0.
+            array = np.ascontiguousarray(vector.astype(float))
+        else:
+            vec_dtype = str(getattr(vector, "dtype", ""))
+            array = np.ascontiguousarray(vector, dtype=dtypes.get(vec_dtype))
+        arrays.append(array)
     return arrays
 
 

pygmt/clib/session.py

@@ -115,33 +115,28 @@ class Session:
     """
     A GMT API session where most operations involving the C API happen.
 
-    Works as a context manager (for use in a ``with`` block) to create a GMT C
-    API session and destroy it in the end to clean up memory.
+    Works as a context manager (for use in a ``with`` block) to create a GMT C API
+    session and destroy it in the end to clean up memory.
 
-    Functions of the shared library are exposed as methods of this class. Most
-    methods MUST be used with an open session (inside a ``with`` block). If
-    creating GMT data structures to communicate data, put that code inside the
-    same ``with`` block as the API calls that will use the data.
+    Functions of the shared library are exposed as methods of this class. Most methods
+    MUST be used with an open session (inside a ``with`` block). If creating GMT data
+    structures to communicate data, put that code inside the same ``with`` block as the
+    API calls that will use the data.
 
-    By default, will let :mod:`ctypes` try to find the GMT shared library
-    (``libgmt``). If the environment variable :term:`GMT_LIBRARY_PATH` is set, will
-    look for the shared library in the directory specified by it.
+    By default, will let :mod:`ctypes` try to find the GMT shared library (``libgmt``).
+    If the environment variable :term:`GMT_LIBRARY_PATH` is set, will look for the
+    shared library in the directory specified by it.
 
-    A ``GMTVersionError`` exception will be raised if the GMT shared library
-    reports a version older than the required minimum GMT version.
-
-    The ``session_pointer`` attribute holds a ctypes pointer to the currently
-    open session.
+    The ``session_pointer`` attribute holds a ctypes pointer to the currently open
+    session.
 
     Raises
     ------
     GMTCLibNotFoundError
-        If there was any problem loading the library (couldn't find it or
-        couldn't access the functions).
+        If there was any problem loading the library (couldn't find it or couldn't
+        access the functions).
     GMTCLibNoSessionError
-        If you try to call a method outside of a 'with' block.
-    GMTVersionError
-        If the minimum required version of GMT is not found.
+        If you try to call a method outside of a ``with`` block.
 
     Examples
     --------
@@ -151,45 +146,44 @@ class Session:
     >>> grid = load_static_earth_relief()
     >>> type(grid)
     <class 'xarray.core.dataarray.DataArray'>
-    >>> # Create a session and destroy it automatically when exiting the "with"
-    >>> # block.
-    >>> with Session() as ses:
+    >>> # Create a session and destroy it automatically when exiting the "with" block.
+    >>> with Session() as lib:
     ...     # Create a virtual file and link to the memory block of the grid.
-    ...     with ses.virtualfile_from_grid(grid) as fin:
+    ...     with lib.virtualfile_from_grid(grid) as fin:
     ...         # Create a temp file to use as output.
     ...         with GMTTempFile() as fout:
-    ...             # Call the grdinfo module with the virtual file as input
-    ...             # and the temp file as output.
-    ...             ses.call_module("grdinfo", [fin, "-C", f"->{fout.name}"])
+    ...             # Call the grdinfo module with the virtual file as input and the
+    ...             # temp file as output.
+    ...             lib.call_module("grdinfo", [fin, "-C", f"->{fout.name}"])
     ...             # Read the contents of the temp file before it's deleted.
     ...             print(fout.read().strip())
     -55 -47 -24 -10 190 981 1 1 8 14 1 1
     """
 
     @property
-    def session_pointer(self):
+    def session_pointer(self) -> ctp.c_void_p:
         """
         The :class:`ctypes.c_void_p` pointer to the current open GMT session.
 
         Raises
         ------
         GMTCLibNoSessionError
-            If trying to access without a currently open GMT session (i.e.,
-            outside of the context manager).
+            If trying to access without a currently open GMT session (i.e., outside of
+            the context manager).
         """
         if not hasattr(self, "_session_pointer") or self._session_pointer is None:
             raise GMTCLibNoSessionError("No currently open GMT API session.")
         return self._session_pointer
 
     @session_pointer.setter
-    def session_pointer(self, session):
+    def session_pointer(self, session: ctp.c_void_p):
         """
         Set the session void pointer.
         """
         self._session_pointer = session
 
     @property
-    def info(self):
+    def info(self) -> dict[str, str]:
         """
         Dictionary with the GMT version and default paths and parameters.
         """

pygmt/helpers/utils.py

@@ -11,7 +11,7 @@
 import sys
 import time
 import webbrowser
-from collections.abc import Iterable, Sequence
+from collections.abc import Iterable, Mapping, Sequence
 from typing import Any, Literal
 
 import xarray as xr
@@ -395,7 +395,7 @@ def non_ascii_to_octal(
 
 def build_arg_list(  # noqa: PLR0912
     kwdict: dict[str, Any],
-    confdict: dict[str, str] | None = None,
+    confdict: Mapping[str, Any] | None = None,
     infile: str | pathlib.PurePath | Sequence[str | pathlib.PurePath] | None = None,
     outfile: str | pathlib.PurePath | None = None,
 ) -> list[str]:

pygmt/src/text.py

@@ -2,7 +2,10 @@
 text - Plot text on a figure.
 """
 
+from collections.abc import Sequence
+
 import numpy as np
+from pygmt._typing import AnchorCode
 from pygmt.clib import Session
 from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import (
@@ -44,11 +47,11 @@ def text_(  # noqa: PLR0912
     textfiles=None,
     x=None,
     y=None,
-    position=None,
+    position: AnchorCode | None = None,
     text=None,
     angle=None,
     font=None,
-    justify=None,
+    justify: bool | None | AnchorCode | Sequence[AnchorCode] = None,
     **kwargs,
 ):
     r"""
@@ -90,14 +93,14 @@ def text_(  # noqa: PLR0912
     x/y : float or 1-D arrays
         The x and y coordinates, or an array of x and y coordinates to plot
         the text.
-    position : str
+    position
         Set reference point on the map for the text by using x, y
         coordinates extracted from ``region`` instead of providing them
         through ``x``/``y``. Specify with a two-letter (order independent)
         code, chosen from:
 
-        * Horizontal: **L**\ (eft), **C**\ (entre), **R**\ (ight)
         * Vertical: **T**\ (op), **M**\ (iddle), **B**\ (ottom)
+        * Horizontal: **L**\ (eft), **C**\ (entre), **R**\ (ight)
 
         For example, ``position="TL"`` plots the text at the Top Left corner
         of the map.
@@ -116,7 +119,7 @@ def text_(  # noqa: PLR0912
         font. If no font info is explicitly given (i.e. ``font=True``), then
         the input to ``textfiles`` must have this information in one of its
         columns.
-    justify : str, bool or list of str
+    justify
         Set the alignment which refers to the part of the text string that
         will be mapped onto the (x, y) point. Choose a two-letter
         combination of **L**, **C**, **R** (for left, center, or right) and

pygmt/src/timestamp.py

@@ -6,6 +6,7 @@
 from collections.abc import Sequence
 
 from packaging.version import Version
+from pygmt._typing import AnchorCode
 from pygmt.clib import Session, __gmt_version__
 from pygmt.helpers import build_arg_list, kwargs_to_strings
 
@@ -17,7 +18,7 @@ def timestamp(
     self,
     text: str | None = None,
     label: str | None = None,
-    justify: str = "BL",
+    justify: AnchorCode = "BL",
     offset: float | str | Sequence[float | str] = ("-54p", "-54p"),
     font: str = "Helvetica,black",
     timefmt: str = "%Y %b %d %H:%M:%S",