pygmt.clib.Session.virtualfile_out

Session.virtualfile_out(kind='dataset', fname=None)

Create a virtual file or an actual file for storing output data.

If fname is not given, a virtual file will be created to store the output data into a GMT data container and the function yields the name of the virtual file. Otherwise, the output data will be written into the specified file and the function simply yields the actual file name.

Parameters:

• kind (Literal['dataset', 'grid', 'image'], default: 'dataset') – The data kind of the virtual file to create. Valid values are "dataset", "grid", and "image". Ignored if fname is specified.

• fname (str | None, default: None) – The name of the actual file to write the output data. No virtual file will be created.

Yields:

vfile – Name of the virtual file or the actual file.

Return type:

Generator[str, None, None]

Examples

>>> from pathlib import Path
>>> from pygmt.clib import Session
>>> from pygmt.datatypes import _GMT_DATASET
>>> from pygmt.helpers import GMTTempFile
>>>
>>> with GMTTempFile(suffix=".txt") as tmpfile:
...     with Path(tmpfile.name).open(mode="w") as fp:
...         print("1.0 2.0 3.0 TEXT", file=fp)
...
...     # Create a virtual file for storing the output table.
...     with Session() as lib:
...         with lib.virtualfile_out(kind="dataset") as vouttbl:
...             lib.call_module("read", [tmpfile.name, vouttbl, "-Td"])
...             ds = lib.read_virtualfile(vouttbl, kind="dataset")
...             assert isinstance(ds.contents, _GMT_DATASET)
...
...     # Write data to an actual file without creating a virtual file.
...     with Session() as lib:
...         with lib.virtualfile_out(fname=tmpfile.name) as vouttbl:
...             assert vouttbl == tmpfile.name
...             lib.call_module("read", [tmpfile.name, vouttbl, "-Td"])
...         line = Path(vouttbl).read_text()
...         assert line == "1\t2\t3\tTEXT\n"