Source code for graphviz.backend.unflattening

"""Pipe DOT source code through ``unflatten``."""

import pathlib
import typing

from ..encoding import DEFAULT_ENCODING
from .. import _tools
from .. import exceptions

from . import execute

__all__ = ['UNFLATTEN_BINARY', 'unflatten']

UNFLATTEN_BINARY = pathlib.Path('unflatten')

[docs]@_tools.deprecate_positional_args(supported_number=1) def unflatten(source: str, stagger: typing.Optional[int] = None, fanout: bool = False, chain: typing.Optional[int] = None, encoding: str = DEFAULT_ENCODING) -> str: """Return DOT ``source`` piped through ``unflatten`` preprocessor as string. Args: source: DOT source to process (improve layout aspect ratio). 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. encoding: Encoding to encode unflatten stdin and decode its stdout. Returns: Decoded stdout of the Graphviz unflatten command. Raises: graphviz.RequiredArgumentError: If ``fanout`` is given but no ``stagger``. graphviz.ExecutableNotFound: If the Graphviz 'unflatten' executable is not found. graphviz.CalledProcessError: If the returncode (exit status) of the unflattening 'unflatten' subprocess is non-zero. See also: Upstream documentation: """ if fanout and stagger is None: raise exceptions.RequiredArgumentError('fanout given without stagger') cmd = [UNFLATTEN_BINARY] if stagger is not None: cmd += ['-l', str(stagger)] if fanout: cmd.append('-f') if chain is not None: cmd += ['-c', str(chain)] proc = execute.run_check(cmd, input=source, encoding=encoding, capture_output=True) return proc.stdout