pygmt.clib.Session

class pygmt.clib.Session[source]

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.

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.

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 lib:
...     # Create a virtual file and link to the memory block of the grid.
...     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.
...             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

Attributes

property Session.info: dict[str, str]: Dictionary with the GMT version and default paths and parameters.

property Session.session_pointer: c_void_p

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 and allocate space to hold data.
`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_virtualfile`(family, geometry, ...)	Open a GMT virtual file associated with a data object for reading or writing.
`Session.put_matrix`(dataset, matrix[, pad])	Attach a 2-D numpy array to a GMT dataset.
`Session.put_strings`(dataset, family, strings)	Attach a 1-D numpy array of dtype str as a column on a GMT dataset.
`Session.put_vector`(dataset, column, vector)	Attach a 1-D numpy 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_grid`(grid)	Store a grid in a virtual file.
`Session.virtualfile_from_matrix`(matrix)	Store a 2-D numpy array as a matrix inside a virtual file.
`Session.virtualfile_from_stringio`(stringio)	Store a `io.StringIO` object in a virtual file.
`Session.virtualfile_from_vectors`(vectors)	Store a sequence of 1-D vectors as columns of a dataset 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.