"""Save DOT code objects, render with Graphviz ``dot``, and open in viewer."""
import logging
import os
import pathlib
import typing
from . import _tools
from . import backend
from . import saving
__all__ = ['Render']
log = logging.getLogger(__name__)
class Render(saving.Save, backend.Render, backend.View):
"""Write source lines to file and render with Graphviz."""
@_tools.deprecate_positional_args(supported_number=2)
def render(self,
filename: typing.Union[os.PathLike, str, None] = None,
directory: typing.Union[os.PathLike, str, None] = None,
view: bool = False,
cleanup: bool = False,
format: typing.Optional[str] = None,
renderer: typing.Optional[str] = None,
formatter: typing.Optional[str] = None,
neato_no_op: typing.Union[bool, int, None] = None,
quiet: bool = False,
quiet_view: bool = False, *,
outfile: typing.Union[os.PathLike, str, None] = None,
engine: typing.Optional[str] = None,
raise_if_result_exists: bool = False,
overwrite_source: bool = False) -> str:
r"""Save the source to file and render with the Graphviz engine.
Args:
filename: Filename for saving the source
(defaults to ``name`` + ``'.gv'``).s
directory: (Sub)directory for source saving and rendering.
view (bool): Open the rendered result
with the default application.
cleanup (bool): Delete the source file
after successful rendering.
format: The output format used for rendering
(``'pdf'``, ``'png'``, etc.).
renderer: The output renderer used for rendering
(``'cairo'``, ``'gd'``, ...).
formatter: The output formatter used for rendering
(``'cairo'``, ``'gd'``, ...).
neato_no_op: Neato layout engine no-op flag.
quiet (bool): Suppress ``stderr`` output
from the layout subprocess.
quiet_view (bool): Suppress ``stderr`` output
from the viewer process
(implies ``view=True``, ineffective on Windows platform).
outfile: Path for the rendered output file.
engine: Layout engine for rendering
(``'dot'``, ``'neato'``, ...).
raise_if_result_exits: Raise :exc:`graphviz.FileExistsError`
if the result file exists.
overwrite_source: Allow ``dot`` to write to the file it reads from.
Incompatible with ``raise_if_result_exists``.
Returns:
The (possibly relative) path of the rendered file.
Raises:
ValueError: If ``engine``, ``format``, ``renderer``, or ``formatter``
are unknown.
graphviz.RequiredArgumentError: If ``formatter`` is given
but ``renderer`` is None.
ValueError: If ``outfile`` is the same file as the source file
unless ``overwite_source=True``.
graphviz.ExecutableNotFound: If the Graphviz ``dot`` executable
is not found.
graphviz.CalledProcessError: If the returncode (exit status)
of the rendering ``dot`` subprocess is non-zero.
RuntimeError: If viewer opening is requested but not supported.
Example:
>>> doctest_mark_exe()
>>> import graphviz
>>> dot = graphviz.Graph(name='spam', directory='doctest-output')
>>> dot.render(format='png').replace('\\', '/')
'doctest-output/spam.gv.png'
>>> dot.render(outfile='spam.svg').replace('\\', '/')
'doctest-output/spam.svg'
Note:
The layout command is started from the directory of ``filepath``,
so that references to external files
(e.g. ``[image=images/camelot.png]``)
can be given as paths relative to the DOT source file.
"""
outfile = _tools.promote_pathlike(outfile)
if outfile is not None:
format = self._get_format(outfile, format=format)
if directory is None:
outfile = pathlib.Path(self.directory, outfile)
args, kwargs = self._get_render_parameters(engine=engine,
format=format,
renderer=renderer,
formatter=formatter,
neato_no_op=neato_no_op,
quiet=quiet,
outfile=outfile,
raise_if_result_exists=raise_if_result_exists,
overwrite_source=overwrite_source,
verify=True)
if outfile is not None and filename is None:
filename = self._get_filepath(outfile)
filepath = self.save(filename, directory=directory, skip_existing=None)
args.append(filepath)
rendered = self._render(*args, **kwargs)
if cleanup:
log.debug('delete %r', filepath)
os.remove(filepath)
if quiet_view or view:
self._view(rendered, format=self._format, quiet=quiet_view)
return rendered
def _view(self, filepath: typing.Union[os.PathLike, str], *,
format: str, quiet: bool) -> None:
"""Start the right viewer based on file format and platform."""
methodnames = [
f'_view_{format}_{backend.viewing.PLATFORM}',
f'_view_{backend.viewing.PLATFORM}',
]
for name in methodnames:
view_method = getattr(self, name, None)
if view_method is not None:
break
else:
raise RuntimeError(f'{self.__class__!r} has no built-in viewer'
f' support for {format!r}'
f' on {backend.viewing.PLATFORM!r} platform')
view_method(filepath, quiet=quiet)
@_tools.deprecate_positional_args(supported_number=2)
def view(self,
filename: typing.Union[os.PathLike, str, None] = None,
directory: typing.Union[os.PathLike, str, None] = None,
cleanup: bool = False,
quiet: bool = False,
quiet_view: bool = False) -> str:
"""Save the source to file, open the rendered result in a viewer.
Convenience short-cut for running ``.render(view=True)``.
Args:
filename: Filename for saving the source
(defaults to ``name`` + ``'.gv'``).
directory: (Sub)directory for source saving and rendering.
cleanup (bool): Delete the source file after successful rendering.
quiet (bool): Suppress ``stderr`` output from the layout subprocess.
quiet_view (bool): Suppress ``stderr`` output
from the viewer process (ineffective on Windows).
Returns:
The (possibly relative) path of the rendered file.
Raises:
graphviz.ExecutableNotFound: If the Graphviz executable
is not found.
graphviz.CalledProcessError: If the exit status is non-zero.
RuntimeError: If opening the viewer is not supported.
Short-cut method for calling :meth:`.render` with ``view=True``.
Note:
There is no option to wait for the application to close,
and no way to retrieve the application's exit status.
"""
return self.render(filename=filename, directory=directory, view=True,
cleanup=cleanup, quiet=quiet, quiet_view=quiet_view)