Skip to content

trudag.dotstop.core.graph.trustable_graph

LinkStatus

Bases: Enum

Possible statuses of relationships between a pair of Items in a TrustableGraph.

LINKED class-attribute instance-attribute 

LINKED = 'LINKED'

The two items are linked and both items have not been changed since the link was last reviewed.

SUSPECT class-attribute instance-attribute 

SUSPECT = 'SUSPECT'

The two items are linked, but one or more of the items has changed since the link was last reviewed.

UNLINKED class-attribute instance-attribute 

UNLINKED = 'UNLINKED'

The two items are not linked.

TrustableGraph 

TrustableGraph(
    graph: BaseGraph,
    items: Iterable[Item],
    resolved: bool = False,
)

Construct an instance of TrustableGraph with a BaseGraph and a list of Items. The elements in both the nodes of the graph and the names of the items are expected to be equivalent.

Parameters:

Name Type Description Default
graph BaseGraph

An object describing relationships between items that implements the BaseGraph abstract class.

 required
items list[Items]

A list of Items.

 required

add_items 

add_items(
    new_items: list[Item],
    parent: str | None = None,
    reviews: list[bool] | None = None,
) -> None

Add new items as nodes (and edges, if parent item exists).

Parameters:

Name Type Description Default
new_items list[Item]

a list of Items to insert.

 required
parent str | None

the name of an optional parent/source.

 None
reviews list[bool] | None

a list of booleans of equal length to new_items representing the review status of the items.

 None

Raises a GraphActionError if item already exists.

add_namespace 

add_namespace(namespace: str) -> Self

Modify graph during runtime by adding a namespace to all nodes and edges.

check 

check() -> None

Raise a GraphStructureError if the Graph object contains illegal items or links.

  • The graph does not:
    • contain links to or from non-normative items
    • contain duplicate nodes or edges
  • The list of items has:
    • unique names
    • separator in name
    • names that correspond exactly with the set of node ids in the graph

documents_to_items_map 

documents_to_items_map() -> dict[str, list[Item]]

A dictionary of document names and their constituent Items.

Items are returned in ascending order. Documents are sorted alphabetically by name.

edges 

edges() -> Iterator[tuple[str, str]]

Return a list of all edges (parent, child) in the graph.

find_shortest_path 

find_shortest_path(
    parent: str, child: str
) -> None | list[str]

Find the shortest path between parent and child node. Returns a list of nodes from parent to child, or None if no path exists.

get_expectations 

get_expectations() -> list[Item]

Return the list of Items with no parents.

Items are returned in ascending order.

get_item 

get_item(name: str) -> Item

Return the Item with name.

Raises a GraphActionError if no such item is in the graph.

get_item_children 

get_item_children(name: str) -> list[Item]

Return the list of children of the Item corresponding to name.

Raises a GraphActionError if no item named name is in the graph.

get_item_parents 

get_item_parents(name: str) -> list[Item]

Return the list of parents of the Item corresponding to name.

Raises a GraphActionError if no item named name is in the graph.

get_item_sha 

get_item_sha(name: str) -> str | None

Get the stored sha256 checksum of the Item with name name.

get_link_sha(parent: str, child: str) -> str | None

Get the stored sha256 checksum of the link between items parent and child.

get_link_status(parent: str, child: str) -> LinkStatus

Return the LinkStatus of the edge from parent_name to child_name.

Raises a GraphActionError if either item does not exist.

get_orphaned_items 

get_orphaned_items() -> list[Item]

Returns a list of items with no parent and child nodes

get_premises 

get_premises() -> list[Item]

Return the list of Items with no children.

get_review_status 

get_review_status(name: str) -> bool

Return True if the Item with name name is reviewed, False otherwise.

Raises a GraphActionError if no item named name is in the graph.

namespaces 

namespaces() -> list[str]

Returns the list of all namespaces on nodes and edges in a trustable graph.

remove_item 

remove_item(name: str, delete: bool = False) -> None

Remove the item with name name.

Raises a GraphActionError if the item does not exist.

resolve_all 

resolve_all(workers: int | None = None) -> None

Resolves references and sha's of all items concurrently.

set_link_status(
    parent: str,
    child: str,
    status: LinkStatus,
    force: bool = False,
) -> None

Set the status of a link to status.

Raises a GraphActionError if: - Either item does not exist - The link is set to its current status. - Attempt to set status from unlinked to suspect.

set_review_status 

set_review_status(name: str, status: bool) -> None

Set the reviewed status of item name to status.

Raises a GraphActionError if no item named name is in the graph.

sha_link(parent: str, child: str) -> str

A sha256 checksum of the link between self and child.

Computed from the shas of self and of child.

stamp_needs 

stamp_needs() -> None

Stamps items in a needs graph by adding a node attribute, that is the hash of the item's text.

subgraph 

subgraph(
    nodes_filter_fn: Callable[[str], bool],
    edges_filter_fn: Callable[[str, str], bool],
) -> TrustableGraph

Return a subgraph satisfying any nodes and edges filtering functions.

to_file 

to_file(output_file: Path) -> None

Check the file, then write to specified output_file.