clib.Session: Add type hints and reformat docstrings (part 1) (#3504)

Author: seisman

pygmt/clib/session.py

@@ -105,33 +105,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
     --------
@@ -141,45 +136,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.
         """