Document LibGMT.log_to_file with an example
Add a docstring to this method with an example application.
@@ -265,10 +265,39 @@ class LibGMT(): # pylint: disable=too-many-instance-attributes
@contextmanager
def log_to_file(self, logfile=None):
"""
- Set the given session to log to a file.
+ Set the next API call in this session to log to a file.
+
+ Use it as a context manager (in a ``with`` block) to capture the error
+ messages from GMT API calls. Mostly useful with ``GMT_Call_Module``
+ because most others don't print error messages.
+
+ The log file will be deleted when exiting the ``with`` block.
+
+ Calls the GMT API function ``GMT_Handle_Messages`` using
+ ``GMT_LOG_ONCE`` mode (to only log errors from the next API call).
+ Only works for a **single API call**, so make calls like
+ ``get_constant`` outside of the ``with`` block.
+
+ Parameters
+ ----------
+ * logfile : str or None
+ The name of the logfile. If ``None`` (default),
+ the file name is automatically generated by the tempfile module.
+
+ Examples
+ --------
+
+ >>> with LibGMT() as lib:
+ ... mode = lib.get_constant('GMT_MODULE_CMD')
+ ... with lib.log_to_file() as logfile:
+ ... status = lib._c_call_module(lib.current_session,
+ ... 'psxy'.encode(),
+ ... mode,
+ ... '-JM6i'.encode())
+ ... with open(logfile) as flog:
+ ... print(flog.read().strip())
+ gmtinfo [ERROR]: No input data found!
- The file name is automatically generated by tempfile and stored in the
- ``_logfile`` attribute.
"""
if logfile is None:
tmp_file = NamedTemporaryFile(prefix='gmt-python-', suffix='.log',
