clib: Add the virtualfile_out method for creating output virtualfile

doc/api/index.rst

@@ -293,6 +293,7 @@ conversion of Python variables to GMT virtual files:
     clib.Session.virtualfile_from_matrix
     clib.Session.virtualfile_from_vectors
     clib.Session.virtualfile_from_grid
+    clib.Session.virtualfile_out
 
 
 Low level access (these are mostly used by the :mod:`pygmt.clib` package):

pygmt/clib/session.py

@@ -1609,6 +1609,79 @@ def virtualfile_from_data(  # noqa: PLR0912
 
         return file_context
 
+    @contextlib.contextmanager
+    def virtualfile_out(
+        self, kind: Literal["dataset", "grid"] = "dataset", fname: str | None = 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 virutal
+        file. Otherwise, the output data will be written into the specified file and the
+        function simply yields the actual file name.
+
+        Parameters
+        ----------
+        kind
+            The data kind of the virtual file to create. Valid values are ``"dataset"``
+            and ``"grid"``. Ignored if ``fname`` is specified.
+        fname
+            The name of the actual file to write the output data. No virtual file will
+            be created.
+
+        Yields
+        ------
+        vfile : str
+            Name of the virtual file or the actual file.
+
+        Examples
+        --------
+        >>> from pathlib import Path
+        >>> from pygmt.clib import Session
+        >>> from pygmt.datatypes import _GMT_DATASET, _GMT_GRID
+        >>> from pygmt.helpers import GMTTempFile
+        >>>
+        >>> # Create a virtual file for storing the output table.
+        >>> with GMTTempFile(suffix=".txt") as tmpfile:
+        ...     with open(tmpfile.name, mode="w") as fp:
+        ...         print("1.0 2.0 3.0 TEXT", file=fp)
+        ...     with Session() as lib:
+        ...         with lib.virtualfile_out(kind="dataset") as vouttbl:
+        ...             lib.call_module("read", f"{tmpfile.name} {vouttbl} -Td")
+        ...             ds = lib.read_virtualfile(vouttbl, kind="dataset")
+        >>> isinstance(ds.contents, _GMT_DATASET)
+        True
+        >>>
+        >>> # Create a virtual file for storing the output grid.
+        >>> with Session() as lib:
+        ...     with lib.virtualfile_out(kind="grid") as voutgrd:
+        ...         lib.call_module("read", f"@earth_relief_01d_g {voutgrd} -Tg")
+        ...         outgrd = lib.read_virtualfile(voutgrd, kind="grid")
+        >>> isinstance(outgrd.contents, _GMT_GRID)
+        True
+        >>>
+        >>> # Write data to file without creating a virtual file
+        >>> with GMTTempFile(suffix=".nc") as tmpfile:
+        ...     with Session() as lib:
+        ...         with lib.virtualfile_out(
+        ...             kind="grid", fname=tmpfile.name
+        ...         ) as voutgrd:
+        ...             lib.call_module("read", f"@earth_relief_01d_g {voutgrd} -Tg")
+        ...             assert voutgrd == tmpfile.name
+        ...             assert Path(voutgrd).stat().st_size > 0
+        """
+        if fname is not None:  # Yield the actual file name.
+            yield fname
+        else:  # Create a virtual file for storing the output data.
+            # Determine the family and geometry from kind
+            family, geometry = {
+                "grid": ("GMT_IS_GRID", "GMT_IS_SURFACE"),
+                "dataset": ("GMT_IS_DATASET", "GMT_IS_PLP"),
+            }[kind]
+            with self.open_virtualfile(family, geometry, "GMT_OUT", None) as vfile:
+                yield vfile
+
     def read_virtualfile(
         self, vfname: str, kind: Literal["dataset", "grid", None] = None
     ):