https://github.com/xflr6/graphviz
Tip revision: 01b22690912bfe43c4c21665e5a257990c084e8d authored by Sebastian Bank on 15 November 2021, 18:22:14 UTC
release 0.18.2
release 0.18.2
Tip revision: 01b2269
api.rst
.. _api:
API Reference
=============
.. autosummary::
:nosignatures:
graphviz.Graph
graphviz.Digraph
graphviz.Source
graphviz.render
graphviz.pipe
graphviz.pipe_string
graphviz.pipe_lines
graphviz.pipe_lines_string
graphviz.unflatten
graphviz.view
.. hint::
The two main classes :class:`.Graph` and :class:`.Digraph` (for creating
`undirected` vs. `directed` graphs) have exactly the same API.
Their division reflects the fact that both graph types cannot be mixed.
Graph
-----
.. autoclass:: graphviz.Graph
:members:
__iter__,
source,
name, comment,
node, edge, edges, attr, subgraph,
format, engine, encoding,
clear, copy, unflatten, pipe, save, render, view,
directed
Digraph
-------
.. autoclass:: graphviz.Digraph
:members:
__iter__,
source,
name, comment,
node, edge, edges, attr, subgraph,
format, engine, encoding,
clear, copy, unflatten, pipe, save, render, view,
directed
Source
------
.. autoclass:: graphviz.Source
:members:
__iter__,
source,
format, engine, encoding,
copy, unflatten, pipe, save, render, view,
from_file
Low-level functions
-------------------
The functions in this section are provided to work directly with existing
files and strings instead of using the object-oriented DOT creation methods
documented above.
.. autofunction:: graphviz.render
.. autofunction:: graphviz.pipe
.. autofunction:: graphviz.pipe_string
.. autofunction:: graphviz.pipe_lines
.. autofunction:: graphviz.pipe_lines_string
.. autofunction:: graphviz.unflatten
.. autofunction:: graphviz.view
Other
-----
.. autodata:: graphviz.ExecutableNotFound
:annotation:
.. autodata:: graphviz.RequiredArgumentError
:annotation:
.. autofunction:: graphviz.version
.. autofunction:: graphviz.escape
.. autofunction:: graphviz.nohtml
Manually maintained whitelists (see https://graphviz.gitlab.io/_pages/pdf/dot.1.pdf,
http://www.graphviz.org/doc/info/output.html, and ``dot -T:`` output):
.. autodata:: graphviz.ENGINES
:annotation:
.. autodata:: graphviz.FORMATS
:annotation:
.. autodata:: graphviz.RENDERERS
:annotation:
.. autodata:: graphviz.FORMATTERS
:annotation:
Names of upstream binaries:
.. autodata:: graphviz.DOT_BINARY
:annotation:
.. autodata:: graphviz.UNFLATTEN_BINARY
:annotation:
Online ``help()`` (internal)
----------------------------
Results of :func:`help` for :class:`.Graph`, :class:`.Digraph`,
and :class:`.Source` for reference.
.. important::
The outputs in this section may contain some **internals** (implementation details).
They serve to record some current implementation details and their changes.
They mainly serve the development process (e.g. checking the MRO).
They might be outdated.
They **may change at any point** in time.
See above for the full (public) API.
First shalt thou take out the Holy Pin.
Then shalt thou count to three, no more, no less.
To update ``help()`` outputs below:
.. code:: bash
$ ./update-help.py
To debug: remove ``+SKIP`` flags below and check output(s):
.. code:: bash
$ ./run-tests.py docs --doctest-report none --doctest-continue-on-failure
Graph
"""""
Partially syntax-highlighted:
https://github.com/xflr6/graphviz/blob/master/docs/api.rst#graph-1
.. code:: python
>>> import graphviz
>>> help(graphviz.Graph) # doctest: +NORMALIZE_WHITESPACE +SKIP
Help on class Graph in module graphviz.graphs:
<BLANKLINE>
class Graph(graphviz.dot.GraphSyntax, BaseGraph)
| Graph(name: Optional[str] = None,
comment: Optional[str] = None,
filename=None,
directory=None,
format: Optional[str] = None,
engine: Optional[str] = None,
encoding: Optional[str] = 'utf-8',
graph_attr=None,
node_attr=None,
edge_attr=None,
body=None,
strict: bool = False, *,
renderer: Optional[str] = None,
formatter: Optional[str] = None) -> None
|
| Graph source code in the DOT language.
|
| Args:
| name: Graph name used in the source code.
| comment: Comment added to the first line of the source.
| filename: Filename for saving the source
| (defaults to ``name`` + ``'.gv'``).
| directory: (Sub)directory for source saving and rendering.
| format: Rendering output format (``'pdf'``, ``'png'``, ...).
| engine: Layout command used (``'dot'``, ``'neato'``, ...).
| renderer: Output renderer used (``'cairo'``, ``'gd'``, ...).
| formatter: Output formatter used (``'cairo'``, ``'gd'``, ...).
| encoding: Encoding for saving the source.
| graph_attr: Mapping of ``(attribute, value)`` pairs for the graph.
| node_attr: Mapping of ``(attribute, value)`` pairs set for all nodes.
| edge_attr: Mapping of ``(attribute, value)`` pairs set for all edges.
| body: Iterable of verbatim lines to add to the graph ``body``.
| strict (bool): Rendering should merge multi-edges.
|
| Note:
| All parameters are `optional` and can be changed under their
| corresponding attribute name after instance creation.
|
| Method resolution order:
| Graph
| graphviz.dot.GraphSyntax
| BaseGraph
| graphviz.dot.Dot
| graphviz.quoting.Quote
| graphviz.rendering.Render
| graphviz.saving.Save
| graphviz.jupyter_integration.JupyterSvgIntegration
| graphviz.piping.Pipe
| graphviz.unflattening.Unflatten
| graphviz.encoding.Encoding
| graphviz.base.Base
| graphviz.base.LineIterable
| graphviz.backend.mixins.Render
| graphviz.backend.mixins.Pipe
| graphviz.parameters.mixins.Parameters
| graphviz.parameters.engines.Engine
| graphviz.parameters.formats.Format
| graphviz.parameters.renderers.Renderer
| graphviz.parameters.formatters.Formatter
| graphviz.parameters.base.ParameterBase
| graphviz.copying.CopyBase
| graphviz.backend.mixins.View
| graphviz.backend.mixins.Unflatten
| builtins.object
|
| Readonly properties defined here:
|
| directed
| ``False``
|
| ----------------------------------------------------------------------
| Data descriptors inherited from graphviz.dot.GraphSyntax:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
|
| ----------------------------------------------------------------------
| Methods inherited from BaseGraph:
|
| __init__(self,
name: Optional[str] = None,
comment: Optional[str] = None,
filename=None,
directory=None,
format: Optional[str] = None,
engine: Optional[str] = None,
encoding: Optional[str] = 'utf-8',
graph_attr=None,
node_attr=None,
edge_attr=None,
body=None,
strict: bool = False, *,
renderer: Optional[str] = None,
formatter: Optional[str] = None) -> None
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from BaseGraph:
|
| source
| The generated DOT source code as string.
|
| ----------------------------------------------------------------------
| Methods inherited from graphviz.dot.Dot:
|
| __iter__(self, subgraph: bool = False) -> Iterator[str]
| Yield the DOT source code line by line (as graph or subgraph).
|
| Yields: Line ending with a newline (``'\n'``).
|
| attr(self, kw: Optional[str] = None, _attributes=None, **attrs) -> None
| Add a general or graph/node/edge attribute statement.
|
| Args:
| kw: Attributes target
| (``None`` or ``'graph'``, ``'node'``, ``'edge'``).
| attrs: Attributes to be set (must be strings, may be empty).
|
| See the :ref:`usage examples in the User Guide <attributes>`.
|
| clear(self, keep_attrs: bool = False) -> None
| Reset content to an empty body, clear graph/node/egde_attr mappings.
|
| Args:
| keep_attrs (bool): preserve graph/node/egde_attr mappings
|
| edge(self,
tail_name: str,
head_name: str,
label: Optional[str] = None,
_attributes=None, **attrs) -> None
| Create an edge between two nodes.
|
| Args:
| tail_name: Start node identifier
| (format: ``node[:port[:compass]]``).
| head_name: End node identifier
| (format: ``node[:port[:compass]]``).
| label: Caption to be displayed near the edge.
| attrs: Any additional edge attributes (must be strings).
|
| Note:
| The ``tail_name`` and ``head_name`` strings are separated
| by (optional) colon(s) into ``node`` name, ``port`` name,
| and ``compass`` (e.g. ``sw``).
| See :ref:`details in the User Guide <ports>`.
|
| edges(self, tail_head_iter) -> None
| Create a bunch of edges.
|
| Args:
| tail_head_iter: Iterable of ``(tail_name, head_name)`` pairs
| (format:``node[:port[:compass]]``).
|
|
| Note:
| The ``tail_name`` and ``head_name`` strings are separated
| by (optional) colon(s) into ``node`` name, ``port`` name,
| and ``compass`` (e.g. ``sw``).
| See :ref:`details in the User Guide <ports>`.
|
| node(self,
name: str,
label: Optional[str] = None,
_attributes=None, **attrs) -> None
| Create a node.
|
| Args:
| name: Unique identifier for the node inside the source.
| label: Caption to be displayed (defaults to the node ``name``).
| attrs: Any additional node attributes (must be strings).
|
| subgraph(self,
graph=None,
name: Optional[str] = None,
comment: Optional[str] = None,
graph_attr=None,
node_attr=None,
edge_attr=None,
body=None)
| Add the current content of the given sole ``graph`` argument
| as subgraph or return a context manager
| returning a new graph instance
| created with the given (``name``, ``comment``, etc.) arguments
| whose content is added as subgraph
| when leaving the context manager's ``with``-block.
|
| Args:
| graph: An instance of the same kind
| (:class:`.Graph`, :class:`.Digraph`) as the current graph
| (sole argument in non-with-block use).
| name: Subgraph name (``with``-block use).
| comment: Subgraph comment (``with``-block use).
| graph_attr: Subgraph-level attribute-value mapping
| (``with``-block use).
| node_attr: Node-level attribute-value mapping
| (``with``-block use).
| edge_attr: Edge-level attribute-value mapping
| (``with``-block use).
| body: Verbatim lines to add to the subgraph ``body``
| (``with``-block use).
|
| See the :ref:`usage examples in the User Guide <subgraphs>`.
|
| When used as a context manager, the returned new graph instance
| uses ``strict=None`` and the parent graph's values
| for ``directory``, ``format``, ``engine``, and ``encoding`` by default.
|
| Note:
| If the ``name`` of the subgraph begins with
| ``'cluster'`` (all lowercase)
| the layout engine will treat it as a special cluster subgraph.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from graphviz.dot.Dot:
|
| __annotations__ = {'directed': <class 'bool'>}
|
| ----------------------------------------------------------------------
| Methods inherited from graphviz.rendering.Render:
|
| render(self,
filename=None,
directory=None,
view: bool = False,
cleanup: bool = False,
format: Optional[str] = None,
renderer: Optional[str] = None,
formatter: Optional[str] = None,
quiet: bool = False,
quiet_view: bool = False, *,
engine: Optional[str] = None) -> str
| 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'``, ...).
| 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).
| engine: Layout engine for rendering
| (``'dot'``, ``'neato'``, ...).
|
| Returns:
| The (possibly relative) path of the rendered file.
|
| Raises:
| ValueError: If ``engine``, ``format``, ``renderer``, or ``formatter``
| are not known.
| graphviz.RequiredArgumentError: If ``formatter`` is given
| but ``renderer`` is None.
| graphviz.ExecutableNotFound: If the Graphviz ``dot`` executable
| is not found.
| subprocess.CalledProcessError: If the returncode (exit status)
| of the rendering ``dot`` subprocess is non-zero.
| RuntimeError: If viewer opening is requested but not supported.
|
| 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.
|
| view(self,
filename=None,
directory=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.
| subprocess.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.
|
| ----------------------------------------------------------------------
| Methods inherited from graphviz.saving.Save:
|
| save(self,
filename=None,
directory=None, *,
skip_existing: Optional[bool] = False) -> str
| Save the DOT source to file. Ensure the file ends with a newline.
|
| Args:
| filename: Filename for saving the source (defaults to ``name`` + ``'.gv'``)
| directory: (Sub)directory for source saving and rendering.
| skip_existing: Skip write if file exists (default: ``False``).
|
| Returns:
| The (possibly relative) path of the saved source file.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from graphviz.saving.Save:
|
| filepath
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from graphviz.saving.Save:
|
| directory = ''
|
| ----------------------------------------------------------------------
| Methods inherited from graphviz.piping.Pipe:
|
| pipe(self,
format: Optional[str] = None,
renderer: Optional[str] = None,
formatter: Optional[str] = None,
quiet: bool = False, *,
engine: Optional[str] = None,
encoding: Optional[str] = None) -> Union[bytes, str]
| Return the source piped through the Graphviz layout command.
|
| Args:
| 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'``, ...).
| quiet (bool): Suppress ``stderr`` output
| from the layout subprocess.
| engine: Layout engine for rendering
| (``'dot'``, ``'neato'``, ...).
| encoding: Encoding for decoding the stdout.
|
| Returns:
| Bytes or if encoding is given decoded string
| (stdout of the layout command).
|
| Raises:
| ValueError: If ``engine``, ``format``, ``renderer``, or ``formatter``
| are not known.
| graphviz.RequiredArgumentError: If ``formatter`` is given
| but ``renderer`` is None.
| graphviz.ExecutableNotFound: If the Graphviz ``dot`` executable
| is not found.
| subprocess.CalledProcessError: If the returncode (exit status)
| of the rendering ``dot`` subprocess is non-zero.
|
| Example:
| >>> import graphviz
|
| >>> source = 'graph { spam }'
|
| >>> doctest_mark_exe()
| >>> graphviz.Source(source, format='svg').pipe()[:14]
| b'<?xml version='
|
| >>> graphviz.Source(source, format='svg').pipe(encoding='ascii')[:14]
| '<?xml version='
|
| >>> graphviz.Source(source, format='svg').pipe(encoding='utf-8')[:14]
| '<?xml version='
|
| ----------------------------------------------------------------------
| Methods inherited from graphviz.unflattening.Unflatten:
|
| unflatten(self,
stagger: Optional[int] = None,
fanout: bool = False,
chain: Optional[int] = None)
| Return a new :class:`.Source` instance with the source
| piped through the Graphviz *unflatten* preprocessor.
|
| Args:
| stagger: Stagger the minimum length
| of leaf edges between 1 and this small integer.
| fanout: Fanout nodes with indegree = outdegree = 1
| when staggering (requires ``stagger``).
| chain: Form disconnected nodes into chains
| of up to this many nodes.
|
| Returns:
| Source: Prepocessed DOT source code (improved layout aspect ratio).
|
| Raises:
| graphviz.RequiredArgumentError: If ``fanout`` is given
| but ``stagger`` is None.
| graphviz.ExecutableNotFound: If the Graphviz ``unflatten`` executable
| is not found.
| subprocess.CalledProcessError: If the returncode (exit status)
| of the unflattening 'unflatten' subprocess is non-zero.
|
| See also:
| https://www.graphviz.org/pdf/unflatten.1.pdf
|
| ----------------------------------------------------------------------
| Data descriptors inherited from graphviz.encoding.Encoding:
|
| encoding
| The encoding for the saved source file.
|
| ----------------------------------------------------------------------
| Methods inherited from graphviz.base.Base:
|
| __str__(self) -> str
| The DOT source code as string.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from graphviz.parameters.engines.Engine:
|
| engine
| The layout engine used for rendering
| (``'dot'``, ``'neato'``, ...).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from graphviz.parameters.formats.Format:
|
| format
| The output format used for rendering
| (``'pdf'``, ``'png'``, ...).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from graphviz.parameters.renderers.Renderer:
|
| renderer
| The output renderer used for rendering
| (``'cairo'``, ``'gd'``, ...).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from graphviz.parameters.formatters.Formatter:
|
| formatter
| The output formatter used for rendering
| (``'cairo'``, ``'gd'``, ...).
|
| ----------------------------------------------------------------------
| Methods inherited from graphviz.copying.CopyBase:
|
| copy(self)
| Return a copied instance of the object.
|
| Returns:
| An independent copy of the current object.
<BLANKLINE>
Digraph
"""""""
Partially symntax-highlighed:
https://github.com/xflr6/graphviz/blob/master/docs/api.rst#digraph-1
.. code:: python
>>> import graphviz
>>> help(graphviz.Digraph) # doctest: +NORMALIZE_WHITESPACE +SKIP
Help on class Digraph in module graphviz.graphs:
<BLANKLINE>
class Digraph(graphviz.dot.DigraphSyntax, BaseGraph)
| Digraph(name: Optional[str] = None,
comment: Optional[str] = None,
filename=None,
directory=None,
format: Optional[str] = None,
engine: Optional[str] = None,
encoding: Optional[str] = 'utf-8',
graph_attr=None,
node_attr=None,
edge_attr=None,
body=None,
strict: bool = False, *,
renderer: Optional[str] = None,
formatter: Optional[str] = None) -> None
|
| Directed graph source code in the DOT language.
|
| Args:
| name: Graph name used in the source code.
| comment: Comment added to the first line of the source.
| filename: Filename for saving the source
| (defaults to ``name`` + ``'.gv'``).
| directory: (Sub)directory for source saving and rendering.
| format: Rendering output format (``'pdf'``, ``'png'``, ...).
| engine: Layout command used (``'dot'``, ``'neato'``, ...).
| renderer: Output renderer used (``'cairo'``, ``'gd'``, ...).
| formatter: Output formatter used (``'cairo'``, ``'gd'``, ...).
| encoding: Encoding for saving the source.
| graph_attr: Mapping of ``(attribute, value)`` pairs for the graph.
| node_attr: Mapping of ``(attribute, value)`` pairs set for all nodes.
| edge_attr: Mapping of ``(attribute, value)`` pairs set for all edges.
| body: Iterable of verbatim lines to add to the graph ``body``.
| strict (bool): Rendering should merge multi-edges.
|
| Note:
| All parameters are `optional` and can be changed under their
| corresponding attribute name after instance creation.
|
| Method resolution order:
| Digraph
| graphviz.dot.DigraphSyntax
| BaseGraph
| graphviz.dot.Dot
| graphviz.quoting.Quote
| graphviz.rendering.Render
| graphviz.saving.Save
| graphviz.jupyter_integration.JupyterSvgIntegration
| graphviz.piping.Pipe
| graphviz.unflattening.Unflatten
| graphviz.encoding.Encoding
| graphviz.base.Base
| graphviz.base.LineIterable
| graphviz.backend.mixins.Render
| graphviz.backend.mixins.Pipe
| graphviz.parameters.mixins.Parameters
| graphviz.parameters.engines.Engine
| graphviz.parameters.formats.Format
| graphviz.parameters.renderers.Renderer
| graphviz.parameters.formatters.Formatter
| graphviz.parameters.base.ParameterBase
| graphviz.copying.CopyBase
| graphviz.backend.mixins.View
| graphviz.backend.mixins.Unflatten
| builtins.object
|
| Readonly properties defined here:
|
| directed
| ``True``
|
| ----------------------------------------------------------------------
| Data descriptors inherited from graphviz.dot.DigraphSyntax:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
|
| ----------------------------------------------------------------------
| Methods inherited from BaseGraph:
|
| __init__(self,
name: Optional[str] = None,
comment: Optional[str] = None,
filename=None,
directory=None,
format: Optional[str] = None,
engine: Optional[str] = None,
encoding: Optional[str] = 'utf-8',
graph_attr=None,
node_attr=None,
edge_attr=None,
body=None,
strict: bool = False, *,
renderer: Optional[str] = None,
formatter: Optional[str] = None) -> None
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from BaseGraph:
|
| source
| The generated DOT source code as string.
|
| ----------------------------------------------------------------------
| Methods inherited from graphviz.dot.Dot:
|
| __iter__(self, subgraph: bool = False) -> Iterator[str]
| Yield the DOT source code line by line (as graph or subgraph).
|
| Yields: Line ending with a newline (``'\n'``).
|
| attr(self, kw: Optional[str] = None, _attributes=None, **attrs) -> None
| Add a general or graph/node/edge attribute statement.
|
| Args:
| kw: Attributes target
| (``None`` or ``'graph'``, ``'node'``, ``'edge'``).
| attrs: Attributes to be set (must be strings, may be empty).
|
| See the :ref:`usage examples in the User Guide <attributes>`.
|
| clear(self, keep_attrs: bool = False) -> None
| Reset content to an empty body, clear graph/node/egde_attr mappings.
|
| Args:
| keep_attrs (bool): preserve graph/node/egde_attr mappings
|
| edge(self,
tail_name: str,
head_name: str,
label: Optional[str] = None,
_attributes=None, **attrs) -> None
| Create an edge between two nodes.
|
| Args:
| tail_name: Start node identifier
| (format: ``node[:port[:compass]]``).
| head_name: End node identifier
| (format: ``node[:port[:compass]]``).
| label: Caption to be displayed near the edge.
| attrs: Any additional edge attributes (must be strings).
|
| Note:
| The ``tail_name`` and ``head_name`` strings are separated
| by (optional) colon(s) into ``node`` name, ``port`` name,
| and ``compass`` (e.g. ``sw``).
| See :ref:`details in the User Guide <ports>`.
|
| edges(self, tail_head_iter) -> None
| Create a bunch of edges.
|
| Args:
| tail_head_iter: Iterable of ``(tail_name, head_name)`` pairs
| (format:``node[:port[:compass]]``).
|
|
| Note:
| The ``tail_name`` and ``head_name`` strings are separated
| by (optional) colon(s) into ``node`` name, ``port`` name,
| and ``compass`` (e.g. ``sw``).
| See :ref:`details in the User Guide <ports>`.
|
| node(self,
name: str,
label: Optional[str] = None,
_attributes=None, **attrs) -> None
| Create a node.
|
| Args:
| name: Unique identifier for the node inside the source.
| label: Caption to be displayed (defaults to the node ``name``).
| attrs: Any additional node attributes (must be strings).
|
| subgraph(self,
graph=None,
name: Optional[str] = None,
comment: Optional[str] = None,
graph_attr=None,
node_attr=None,
edge_attr=None,
body=None)
| Add the current content of the given sole ``graph`` argument
| as subgraph or return a context manager
| returning a new graph instance
| created with the given (``name``, ``comment``, etc.) arguments
| whose content is added as subgraph
| when leaving the context manager's ``with``-block.
|
| Args:
| graph: An instance of the same kind
| (:class:`.Graph`, :class:`.Digraph`) as the current graph
| (sole argument in non-with-block use).
| name: Subgraph name (``with``-block use).
| comment: Subgraph comment (``with``-block use).
| graph_attr: Subgraph-level attribute-value mapping
| (``with``-block use).
| node_attr: Node-level attribute-value mapping
| (``with``-block use).
| edge_attr: Edge-level attribute-value mapping
| (``with``-block use).
| body: Verbatim lines to add to the subgraph ``body``
| (``with``-block use).
|
| See the :ref:`usage examples in the User Guide <subgraphs>`.
|
| When used as a context manager, the returned new graph instance
| uses ``strict=None`` and the parent graph's values
| for ``directory``, ``format``, ``engine``, and ``encoding`` by default.
|
| Note:
| If the ``name`` of the subgraph begins with
| ``'cluster'`` (all lowercase)
| the layout engine will treat it as a special cluster subgraph.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from graphviz.dot.Dot:
|
| __annotations__ = {'directed': <class 'bool'>}
|
| ----------------------------------------------------------------------
| Methods inherited from graphviz.rendering.Render:
|
| render(self,
filename=None,
directory=None,
view: bool = False,
cleanup: bool = False,
format: Optional[str] = None,
renderer: Optional[str] = None,
formatter: Optional[str] = None,
quiet: bool = False,
quiet_view: bool = False, *,
engine: Optional[str] = None) -> str
| 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'``, ...).
| 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).
| engine: Layout engine for rendering
| (``'dot'``, ``'neato'``, ...).
|
| Returns:
| The (possibly relative) path of the rendered file.
|
| Raises:
| ValueError: If ``engine``, ``format``, ``renderer``, or ``formatter``
| are not known.
| graphviz.RequiredArgumentError: If ``formatter`` is given
| but ``renderer`` is None.
| graphviz.ExecutableNotFound: If the Graphviz ``dot`` executable
| is not found.
| subprocess.CalledProcessError: If the returncode (exit status)
| of the rendering ``dot`` subprocess is non-zero.
| RuntimeError: If viewer opening is requested but not supported.
|
| 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.
|
| view(self,
filename=None,
directory=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.
| subprocess.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.
|
| ----------------------------------------------------------------------
| Methods inherited from graphviz.saving.Save:
|
| save(self,
filename=None,
directory=None, *,
skip_existing: Optional[bool] = False) -> str
| Save the DOT source to file. Ensure the file ends with a newline.
|
| Args:
| filename: Filename for saving the source (defaults to ``name`` + ``'.gv'``)
| directory: (Sub)directory for source saving and rendering.
| skip_existing: Skip write if file exists (default: ``False``).
|
| Returns:
| The (possibly relative) path of the saved source file.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from graphviz.saving.Save:
|
| filepath
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from graphviz.saving.Save:
|
| directory = ''
|
| ----------------------------------------------------------------------
| Methods inherited from graphviz.piping.Pipe:
|
| pipe(self,
format: Optional[str] = None,
renderer: Optional[str] = None,
formatter: Optional[str] = None,
quiet: bool = False, *,
engine: Optional[str] = None,
encoding: Optional[str] = None) -> Union[bytes, str]
| Return the source piped through the Graphviz layout command.
|
| Args:
| 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'``, ...).
| quiet (bool): Suppress ``stderr`` output
| from the layout subprocess.
| engine: Layout engine for rendering
| (``'dot'``, ``'neato'``, ...).
| encoding: Encoding for decoding the stdout.
|
| Returns:
| Bytes or if encoding is given decoded string
| (stdout of the layout command).
|
| Raises:
| ValueError: If ``engine``, ``format``, ``renderer``, or ``formatter``
| are not known.
| graphviz.RequiredArgumentError: If ``formatter`` is given
| but ``renderer`` is None.
| graphviz.ExecutableNotFound: If the Graphviz ``dot`` executable
| is not found.
| subprocess.CalledProcessError: If the returncode (exit status)
| of the rendering ``dot`` subprocess is non-zero.
|
| Example:
| >>> import graphviz
|
| >>> source = 'graph { spam }'
|
| >>> doctest_mark_exe()
| >>> graphviz.Source(source, format='svg').pipe()[:14]
| b'<?xml version='
|
| >>> graphviz.Source(source, format='svg').pipe(encoding='ascii')[:14]
| '<?xml version='
|
| >>> graphviz.Source(source, format='svg').pipe(encoding='utf-8')[:14]
| '<?xml version='
|
| ----------------------------------------------------------------------
| Methods inherited from graphviz.unflattening.Unflatten:
|
| unflatten(self,
stagger: Optional[int] = None,
fanout: bool = False,
chain: Optional[int] = None)
| Return a new :class:`.Source` instance with the source
| piped through the Graphviz *unflatten* preprocessor.
|
| Args:
| stagger: Stagger the minimum length
| of leaf edges between 1 and this small integer.
| fanout: Fanout nodes with indegree = outdegree = 1
| when staggering (requires ``stagger``).
| chain: Form disconnected nodes into chains
| of up to this many nodes.
|
| Returns:
| Source: Prepocessed DOT source code (improved layout aspect ratio).
|
| Raises:
| graphviz.RequiredArgumentError: If ``fanout`` is given
| but ``stagger`` is None.
| graphviz.ExecutableNotFound: If the Graphviz ``unflatten`` executable
| is not found.
| subprocess.CalledProcessError: If the returncode (exit status)
| of the unflattening 'unflatten' subprocess is non-zero.
|
| See also:
| https://www.graphviz.org/pdf/unflatten.1.pdf
|
| ----------------------------------------------------------------------
| Data descriptors inherited from graphviz.encoding.Encoding:
|
| encoding
| The encoding for the saved source file.
|
| ----------------------------------------------------------------------
| Methods inherited from graphviz.base.Base:
|
| __str__(self) -> str
| The DOT source code as string.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from graphviz.parameters.engines.Engine:
|
| engine
| The layout engine used for rendering
| (``'dot'``, ``'neato'``, ...).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from graphviz.parameters.formats.Format:
|
| format
| The output format used for rendering
| (``'pdf'``, ``'png'``, ...).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from graphviz.parameters.renderers.Renderer:
|
| renderer
| The output renderer used for rendering
| (``'cairo'``, ``'gd'``, ...).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from graphviz.parameters.formatters.Formatter:
|
| formatter
| The output formatter used for rendering
| (``'cairo'``, ``'gd'``, ...).
|
| ----------------------------------------------------------------------
| Methods inherited from graphviz.copying.CopyBase:
|
| copy(self)
| Return a copied instance of the object.
|
| Returns:
| An independent copy of the current object.
<BLANKLINE>
Source
""""""
Partially syntax-highlighted:
https://github.com/xflr6/graphviz/blob/master/docs/api.rst#source-1
.. code:: python
>>> import graphviz
>>> help(graphviz.Source) # doctest: +NORMALIZE_WHITESPACE +SKIP
Help on class Source in module graphviz.sources:
<BLANKLINE>
class Source(graphviz.rendering.Render,
graphviz.saving.Save,
graphviz.jupyter_integration.JupyterSvgIntegration,
graphviz.piping.Pipe,
graphviz.unflattening.Unflatten)
| Source(source: str,
filename=None,
directory=None,
format: Optional[str] = None,
engine: Optional[str] = None,
encoding: Optional[str] = 'utf-8', *,
renderer: Optional[str] = None,
formatter: Optional[str] = None,
loaded_from_path: Optional[os.PathLike] = None) -> None
|
| Verbatim DOT source code string to be rendered by Graphviz.
|
| Args:
| source: The verbatim DOT source code string.
| filename: Filename for saving the source (defaults to ``'Source.gv'``).
| directory: (Sub)directory for source saving and rendering.
| format: Rendering output format (``'pdf'``, ``'png'``, ...).
| engine: Layout engine used (``'dot'``, ``'neato'``, ...).
| encoding: Encoding for saving the source.
|
| Note:
| All parameters except ``source`` are optional. All of them
| can be changed under their corresponding attribute name
| after instance creation.
|
| Method resolution order:
| Source
| graphviz.rendering.Render
| graphviz.saving.Save
| graphviz.jupyter_integration.JupyterSvgIntegration
| graphviz.piping.Pipe
| graphviz.unflattening.Unflatten
| graphviz.encoding.Encoding
| graphviz.base.Base
| graphviz.base.LineIterable
| graphviz.backend.mixins.Render
| graphviz.backend.mixins.Pipe
| graphviz.parameters.mixins.Parameters
| graphviz.parameters.engines.Engine
| graphviz.parameters.formats.Format
| graphviz.parameters.renderers.Renderer
| graphviz.parameters.formatters.Formatter
| graphviz.parameters.base.ParameterBase
| graphviz.copying.CopyBase
| graphviz.backend.mixins.View
| graphviz.backend.mixins.Unflatten
| builtins.object
|
| Methods defined here:
|
| __init__(self,
source: str,
filename=None,
directory=None,
format: Optional[str] = None,
engine: Optional[str] = None,
encoding: Optional[str] = 'utf-8', *,
renderer: Optional[str] = None,
formatter: Optional[str] = None,
loaded_from_path: Optional[os.PathLike] = None) -> None
| Initialize self. See help(type(self)) for accurate signature.
|
| __iter__(self) -> Iterator[str]
| Yield the DOT source code read from file line by line.
|
| Yields: Line ending with a newline (``'\n'``).
|
| save(self,
filename=None,
directory=None, *,
skip_existing: Optional[bool] = None) -> str
| Save the DOT source to file. Ensure the file ends with a newline.
|
| Args:
| filename: Filename for saving the source (defaults to ``name`` + ``'.gv'``)
| directory: (Sub)directory for source saving and rendering.
| skip_existing: Skip write if file exists (default: ``None``).
| By default skips if instance was loaded from the target path:
| ``.from_file(self.filepath)``.
|
| Returns:
| The (possibly relative) path of the saved source file.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| from_file(filename,
directory=None,
format: Optional[str] = None,
engine: Optional[str] = None,
encoding: Optional[str] = 'utf-8',
renderer: Optional[str] = None,
formatter: Optional[str] = None) -> 'Source' from builtins.type
| Return an instance with the source string read from the given file.
|
| Args:
| filename: Filename for loading/saving the source.
| directory: (Sub)directory for source loading/saving and rendering.
| format: Rendering output format (``'pdf'``, ``'png'``, ...).
| engine: Layout command used (``'dot'``, ``'neato'``, ...).
| encoding: Encoding for loading/saving the source.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| source
| The DOT source code as string (read from file).
|
| Normalizes so that the string always ends in a final newline.
|
| ----------------------------------------------------------------------
| Methods inherited from graphviz.rendering.Render:
|
| render(self,
filename=None,
directory=None,
view: bool = False,
cleanup: bool = False,
format: Optional[str] = None,
renderer: Optional[str] = None,
formatter: Optional[str] = None,
quiet: bool = False,
quiet_view: bool = False, *,
engine: Optional[str] = None) -> str
| 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'``, ...).
| 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).
| engine: Layout engine for rendering
| (``'dot'``, ``'neato'``, ...).
|
| Returns:
| The (possibly relative) path of the rendered file.
|
| Raises:
| ValueError: If ``engine``, ``format``, ``renderer``, or ``formatter``
| are not known.
| graphviz.RequiredArgumentError: If ``formatter`` is given
| but ``renderer`` is None.
| graphviz.ExecutableNotFound: If the Graphviz ``dot`` executable
| is not found.
| subprocess.CalledProcessError: If the returncode (exit status)
| of the rendering ``dot`` subprocess is non-zero.
| RuntimeError: If viewer opening is requested but not supported.
|
| 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.
|
| view(self,
filename=None,
directory=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.
| subprocess.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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from graphviz.saving.Save:
|
| filepath
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from graphviz.saving.Save:
|
| directory = ''
|
| ----------------------------------------------------------------------
| Methods inherited from graphviz.piping.Pipe:
|
| pipe(self,
format: Optional[str] = None,
renderer: Optional[str] = None,
formatter: Optional[str] = None,
quiet: bool = False, *,
engine: Optional[str] = None,
encoding: Optional[str] = None) -> Union[bytes, str]
| Return the source piped through the Graphviz layout command.
|
| Args:
| 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'``, ...).
| quiet (bool): Suppress ``stderr`` output
| from the layout subprocess.
| engine: Layout engine for rendering
| (``'dot'``, ``'neato'``, ...).
| encoding: Encoding for decoding the stdout.
|
| Returns:
| Bytes or if encoding is given decoded string
| (stdout of the layout command).
|
| Raises:
| ValueError: If ``engine``, ``format``, ``renderer``, or ``formatter``
| are not known.
| graphviz.RequiredArgumentError: If ``formatter`` is given
| but ``renderer`` is None.
| graphviz.ExecutableNotFound: If the Graphviz ``dot`` executable
| is not found.
| subprocess.CalledProcessError: If the returncode (exit status)
| of the rendering ``dot`` subprocess is non-zero.
|
| Example:
| >>> import graphviz
|
| >>> source = 'graph { spam }'
|
| >>> doctest_mark_exe()
| >>> graphviz.Source(source, format='svg').pipe()[:14]
| b'<?xml version='
|
| >>> graphviz.Source(source, format='svg').pipe(encoding='ascii')[:14]
| '<?xml version='
|
| >>> graphviz.Source(source, format='svg').pipe(encoding='utf-8')[:14]
| '<?xml version='
|
| ----------------------------------------------------------------------
| Methods inherited from graphviz.unflattening.Unflatten:
|
| unflatten(self,
stagger: Optional[int] = None,
fanout: bool = False,
chain: Optional[int] = None)
| Return a new :class:`.Source` instance with the source
| piped through the Graphviz *unflatten* preprocessor.
|
| Args:
| stagger: Stagger the minimum length
| of leaf edges between 1 and this small integer.
| fanout: Fanout nodes with indegree = outdegree = 1
| when staggering (requires ``stagger``).
| chain: Form disconnected nodes into chains
| of up to this many nodes.
|
| Returns:
| Source: Prepocessed DOT source code (improved layout aspect ratio).
|
| Raises:
| graphviz.RequiredArgumentError: If ``fanout`` is given
| but ``stagger`` is None.
| graphviz.ExecutableNotFound: If the Graphviz ``unflatten`` executable
| is not found.
| subprocess.CalledProcessError: If the returncode (exit status)
| of the unflattening 'unflatten' subprocess is non-zero.
|
| See also:
| https://www.graphviz.org/pdf/unflatten.1.pdf
|
| ----------------------------------------------------------------------
| Data descriptors inherited from graphviz.encoding.Encoding:
|
| encoding
| The encoding for the saved source file.
|
| ----------------------------------------------------------------------
| Methods inherited from graphviz.base.Base:
|
| __str__(self) -> str
| The DOT source code as string.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from graphviz.base.LineIterable:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
|
| ----------------------------------------------------------------------
| Data descriptors inherited from graphviz.parameters.engines.Engine:
|
| engine
| The layout engine used for rendering
| (``'dot'``, ``'neato'``, ...).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from graphviz.parameters.formats.Format:
|
| format
| The output format used for rendering
| (``'pdf'``, ``'png'``, ...).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from graphviz.parameters.renderers.Renderer:
|
| renderer
| The output renderer used for rendering
| (``'cairo'``, ``'gd'``, ...).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from graphviz.parameters.formatters.Formatter:
|
| formatter
| The output formatter used for rendering
| (``'cairo'``, ``'gd'``, ...).
|
| ----------------------------------------------------------------------
| Methods inherited from graphviz.copying.CopyBase:
|
| copy(self)
| Return a copied instance of the object.
|
| Returns:
| An independent copy of the current object.
<BLANKLINE>
