pygmt.clib.Session

class pygmt.clib.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.

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 ctypes try to find the GMT shared library (libgmt). If the environment variable 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.

Raises:

• GMTCLibNotFoundError – 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.

Examples

>>> from pygmt.helpers.testing import load_static_earth_relief
>>> from pygmt.helpers import GMTTempFile
>>> 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 virtual file and link to the memory block of the grid.
...     with ses.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}"])
...             # 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

Attributes

property Session.info

Dictionary with the GMT version and default paths and parameters.

property Session.session_pointer

The 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).

Methods Summary

Session.call_module(module, args)	Call a GMT module with the given arguments.
Session.create(name)	Create a new GMT C API session.
Session.create_data(family, geometry, mode)	Create an empty GMT data container.
Session.destroy()	Destroy the currently open GMT API session.
Session.extract_region()	Extract the region of the currently active figure.
Session.get_common(option)	Inquire if a GMT common option has been set and return its current value if possible.
Session.get_default(name)	Get the value of a GMT configuration parameter or a GMT API parameter.
Session.get_enum(name)	Get the value of a GMT constant (C enum) from gmt_resources.h.
Session.get_libgmt_func(name[, argtypes, ...])	Get a ctypes function from the libgmt shared library.
Session.inquire_virtualfile(vfname)	Get the family of a virtual file.
Session.open_virtual_file(family, geometry, ...)	Open a GMT virtual file to pass data to and from a module.
Session.open_virtualfile(family, geometry, ...)	Open a GMT virtual file to pass data to and from a module.
Session.put_matrix(dataset, matrix[, pad])	Attach a numpy 2-D array to a GMT dataset.
Session.put_strings(dataset, family, strings)	Attach a numpy 1-D array of dtype str as a column on a GMT dataset.
Session.put_vector(dataset, column, vector)	Attach a numpy 1-D array as a column on a GMT dataset.
Session.read_data(infile, kind[, family, ...])	Read a data file into a GMT data container.
Session.read_virtualfile(vfname[, kind])	Read data from a virtual file and optionally cast into a GMT data container.
Session.virtualfile_from_data([check_kind, ...])	Store any data inside a virtual file.
Session.virtualfile_from_grid(grid)	Store a grid in a virtual file.
Session.virtualfile_from_matrix(matrix)	Store a 2-D array as a table inside a virtual file.
Session.virtualfile_from_vectors(*vectors)	Store 1-D arrays as columns of a table inside a virtual file.
Session.virtualfile_in([check_kind, data, ...])	Store any data inside a virtual file.
Session.virtualfile_out([kind, fname])	Create a virtual file or an actual file for storing output data.
Session.virtualfile_to_dataset(vfname[, ...])	Output a tabular dataset stored in a virtual file to a different format.
Session.virtualfile_to_raster(vfname[, ...])	Output raster data stored in a virtual file to an xarray.DataArray object.
Session.write_data(family, geometry, mode, ...)	Write a GMT data container to a file.