Skip to content

Commit

Permalink
clib.Session: Add type hints and reformat docstrings (part 1) (#3504)
Browse files Browse the repository at this point in the history
  • Loading branch information
seisman committed Oct 16, 2024
1 parent 003d8a1 commit edf80c0
Showing 1 changed file with 25 additions and 31 deletions.
56 changes: 25 additions & 31 deletions pygmt/clib/session.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
--------
Expand All @@ -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.
"""
Expand Down

0 comments on commit edf80c0

Please sign in to comment.