trudag.plot

A library for creating graphical summaries of trustable software projects.

Functions for creating .dot files, and interfacing between graphviz and dotstop.

break_line_at

break_line_at(line: str, char_limit: int) -> str

Take a one-line string and add line breaks at the first whitespace after every char_limit characters.

This will allow words to overrun where necessary.

Raises a ValueError if the input string is multiline.

Parameters:

Name	Type	Description	Default
`line`	`str`	Line to break.	required
`char_limit`	`int`	Soft limit on line length.	required

Returns:

Type	Description
`str`	`line` with newlines at the first whitespace after every `char_limit` characters

build_subgraph

build_subgraph(
    graph: TrustableGraph,
    pick: list[tuple[str, int | None, int | None]],
    include_orphan_nodes: bool,
) -> int

Creates a slice of the original graph through arguments.

!!! THIS FUNCTION IS DESTRUCTIVE !!! The slice of the graph is directly operated on the graph passed through the argument. If the original graph is needed, make sure to make a copy.

The intention behind this function is to create a reduced graph for projects that generates dense graphs that is hard to view and navigate, and to allow for focusing on a slice of interest.

This function will do nothing if none of the filtering arguments are effective.

To allow combining the filter operations together, instead of removing items from the graph on each operation being processed, it will initially track which items must be retained per filter. This item retaining tracking gets used at the end of this operation to remove all items from the graph except for those that are marked to be retained.

pick and orphan_nodes filters are added as a basic set of operations to allow focusing on points of interest in the graph.

Parameters:

Name	Type	Description	Default
`graph`	`TrustableGraph`	Dotstop Graph to filter.	required
`pick`	`list[tuple[str, int \| None, int \| None]]`	(list[tuple[str, int, int]]): Picks nodes to be retained in the graph, specified by item name and levels of parent / child.	required
`include_orphan_nodes`	`bool`	Retain nodes that isn't linked with anything else.	required

Returns:

Type	Description
`int`	Number of items removed.

format_source_from_graph

format_source_from_graph(
    graph: TrustableGraph,
    line_length: int,
    same_rank: list[list[str]],
    invis_deps: list[tuple[str, str]],
    base_url: str = "",
    body: bool = True,
) -> str

Return a string of dot source code including formatting metadata.

Parameters:

Name	Type	Description	Default
`graph`	`TrustableGraph`	Dotstop Graph to generate source from	required
`line_length`	`int`	Soft limit for characters-per-line in node labels.	required
`same_rank`	`list[list[str]]`	List of lists of item uids that should appear on the same rank in the plotted graph.	required
`invis_deps`	`list[tuple[str, str]]`	(list[tuple[str, str]]): List of tuples of item uids that should be invisibly linked.	required
`base_url`	`str`	Base url for tooltips. If "", no tooltips are added.	`''`

plot

plot(
    graph: TrustableGraph,
    line_length: int,
    same_rank: list[list[str]],
    invis_deps: list[tuple[str, str]],
    pick: list[tuple[str, int | None, int | None]],
    orphan_nodes: bool,
    output_file_path: Path = Path("./graph.svg"),
    base_url: str = "",
    body: bool = True,
) -> None

Given a dotstop graph in cwd, plot the tree using Graphviz.

Parameters:

Name	Type	Description	Default
`graph`	`TrustableGraph`	dotstop.Graph to work on	required
`line_length`	`int`	Soft limit for characters-per-line in node labels.	required
`same_rank`	`list[list[str]]`	List of lists of item uids that should appear on the same rank in the plotted graph.	required
`invis_deps`	`list[tuple[str, str]]`	(list[tuple[str, str]]): List of tuples of item uids that should be invisibly linked.	required
`pick`	`list[tuple[str, int \| None, int \| None]]`	(list[tuple[str, int \| None, int \| None]]): Picks nodes to be retained in the graph, specified by item name and levels of parent / child to be picked.	required
`orphan_nodes`	`bool`	Retain nodes that isn't linked with anything else.	required
`output_file_path`	`Path`	Output path for the plot file.	`Path('./graph.svg')`
`base_url`	`str`	Base url for tooltips. If "", no tooltips are added.	`''`