diff --git a/CHANGELOG.md b/CHANGELOG.md index c0880b6d..e1a30694 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed - Tree Exporter: Relax type hinting using TypeVar for `clone_tree`. - Tree Helper: Accept Iterable instead of List for custom_style attribute of `yield_tree` and `print_tree`. +- Misc: Fix docstring for better presentation of code vs variable vs normal text. ## [0.12.5] - 2023-09-26 ### Added diff --git a/bigtree/binarytree/construct.py b/bigtree/binarytree/construct.py index f6e9c07d..a9081b1b 100644 --- a/bigtree/binarytree/construct.py +++ b/bigtree/binarytree/construct.py @@ -31,7 +31,7 @@ def list_to_binarytree( Args: heapq_list (List[int]): list containing integer node names, ordered in heapq fashion - node_type (Type[BinaryNode]): node type of tree to be created, defaults to BinaryNode + node_type (Type[BinaryNode]): node type of tree to be created, defaults to ``BinaryNode`` Returns: (BinaryNode) diff --git a/bigtree/dag/construct.py b/bigtree/dag/construct.py index 409ba84f..f024ec15 100644 --- a/bigtree/dag/construct.py +++ b/bigtree/dag/construct.py @@ -29,7 +29,7 @@ def list_to_dag( Args: relations (List[Tuple[str, str]]): list containing tuple of parent-child names - node_type (Type[DAGNode]): node type of DAG to be created, defaults to DAGNode + node_type (Type[DAGNode]): node type of DAG to be created, defaults to ``DAGNode`` Returns: (DAGNode) @@ -68,7 +68,7 @@ def dict_to_dag( relation_attrs (Dict[str, Any]): dictionary containing node, node parents, and node attribute information, key: child name, value: dictionary of parent names, node attribute, and attribute value parent_key (str): key of dictionary to retrieve list of parents name, defaults to 'parent' - node_type (Type[DAGNode]): node type of DAG to be created, defaults to DAGNode + node_type (Type[DAGNode]): node type of DAG to be created, defaults to ``DAGNode`` Returns: (DAGNode) @@ -133,7 +133,7 @@ def dataframe_to_dag( if not set, it will take the second column of data attribute_cols (List[str]): columns of data containing child node attribute information, if not set, it will take all columns of data except `child_col` and `parent_col` - node_type (Type[DAGNode]): node type of DAG to be created, defaults to DAGNode + node_type (Type[DAGNode]): node type of DAG to be created, defaults to ``DAGNode`` Returns: (DAGNode) diff --git a/bigtree/tree/construct.py b/bigtree/tree/construct.py index 046df60a..ca86cebe 100644 --- a/bigtree/tree/construct.py +++ b/bigtree/tree/construct.py @@ -44,7 +44,7 @@ def add_path_to_tree( """Add nodes and attributes to existing tree *in-place*, return node of added path. Adds to existing tree from list of path strings. - Path should contain `Node` name, separated by `sep`. + Path should contain ``Node`` name, separated by `sep`. - For example: Path string "a/b" refers to Node("b") with parent Node("a"). - Path separator `sep` is for the input `path` and can differ from existing tree. @@ -67,7 +67,7 @@ def add_path_to_tree( tree (Node): existing tree path (str): path to be added to tree sep (str): path separator for input `path` - duplicate_name_allowed (bool): indicator if nodes with duplicate `Node` name is allowed, defaults to True + duplicate_name_allowed (bool): indicator if nodes with duplicate ``Node`` name is allowed, defaults to True node_attrs (Dict[str, Any]): attributes to add to node, key: attribute name, value: attribute value, optional Returns: @@ -122,7 +122,7 @@ def add_dict_to_tree_by_path( """Add nodes and attributes to tree *in-place*, return root of tree. Adds to existing tree from nested dictionary, ``key``: path, ``value``: dict of attribute name and attribute value. - Path should contain `Node` name, separated by `sep`. + Path should contain ``Node`` name, separated by `sep`. - For example: Path string "a/b" refers to Node("b") with parent Node("a"). - Path separator `sep` is for the input `path` and can differ from existing tree. @@ -160,7 +160,7 @@ def add_dict_to_tree_by_path( path_attrs (Dict[str, Dict[str, Any]]): dictionary containing node path and attribute information, key: node path, value: dict of node attribute name and attribute value sep (str): path separator for input `path_attrs` - duplicate_name_allowed (bool): indicator if nodes with duplicate `Node` name is allowed, defaults to True + duplicate_name_allowed (bool): indicator if nodes with duplicate ``Node`` name is allowed, defaults to True Returns: (Node) @@ -209,7 +209,7 @@ def add_dict_to_tree_by_name( name_attrs (Dict[str, Dict[str, Any]]): dictionary containing node name and attribute information, key: node name, value: dict of node attribute name and attribute value join_type (str): join type with attribute, default of 'left' takes existing tree nodes, - if join_type is set to 'inner' it will only take tree nodes that are in `path_attrs` key and drop others + if join_type is set to 'inner' it will only take tree nodes that are in `name_attrs` key and drop others Returns: (Node) @@ -238,7 +238,7 @@ def add_dataframe_to_tree_by_path( `path_col` and `attribute_cols` specify columns for node path and attributes to add to existing tree. If columns are not specified, `path_col` takes first column and all other columns are `attribute_cols` - Path in path column should contain `Node` name, separated by `sep`. + Path in path column should contain ``Node`` name, separated by `sep`. - For example: Path string "a/b" refers to Node("b") with parent Node("a"). - Path separator `sep` is for the input `path` and can differ from existing tree. @@ -282,7 +282,7 @@ def add_dataframe_to_tree_by_path( attribute_cols (List[str]): columns of data containing node attribute information, if not set, it will take all columns of data except `path_col` sep (str): path separator for input `path_col` - duplicate_name_allowed (bool): indicator if nodes with duplicate `Node` name is allowed, defaults to True + duplicate_name_allowed (bool): indicator if nodes with duplicate ``Node`` name is allowed, defaults to True Returns: (Node) @@ -368,7 +368,7 @@ def add_dataframe_to_tree_by_name( name_col (str): column of data containing `name` information, if not set, it will take the first column of data attribute_cols (List[str]): column(s) of data containing node attribute information, - if not set, it will take all columns of data except path_col + if not set, it will take all columns of data except `path_col` join_type (str): join type with attribute, default of 'left' takes existing tree nodes, if join_type is set to 'inner' it will only take tree nodes with attributes and drop the other nodes @@ -450,7 +450,7 @@ def str_to_tree( tree_string (str): String to construct tree tree_prefix_list (List[str]): List of prefix to mark the end of tree branch/stem and start of node name, optional. If not specified, it will infer unicode characters and whitespace as prefix. - node_type (Type[Node]): node type of tree to be created, defaults to Node + node_type (Type[Node]): node type of tree to be created, defaults to ``Node`` Returns: (Node) @@ -502,7 +502,7 @@ def list_to_tree( ) -> Node: """Construct tree from list of path strings. - Path should contain `Node` name, separated by `sep`. + Path should contain ``Node`` name, separated by `sep`. - For example: Path string "a/b" refers to Node("b") with parent Node("a"). Path can start from root node `name`, or start with `sep`. @@ -527,8 +527,8 @@ def list_to_tree( Args: paths (Iterable[str]): list containing path strings sep (str): path separator for input `paths` and created tree, defaults to `/` - duplicate_name_allowed (bool): indicator if nodes with duplicate `Node` name is allowed, defaults to True - node_type (Type[Node]): node type of tree to be created, defaults to Node + duplicate_name_allowed (bool): indicator if nodes with duplicate ``Node`` name is allowed, defaults to True + node_type (Type[Node]): node type of tree to be created, defaults to ``Node`` Returns: (Node) @@ -581,7 +581,7 @@ def list_to_tree_by_relation( relations (Iterable[Tuple[str, str]]): list containing tuple containing parent-child names allow_duplicates (bool): allow duplicate intermediate nodes such that child node will be tagged to multiple parent nodes, defaults to False - node_type (Type[Node]): node type of tree to be created, defaults to Node + node_type (Type[Node]): node type of tree to be created, defaults to ``Node`` Returns: (Node) @@ -609,7 +609,7 @@ def dict_to_tree( """Construct tree from nested dictionary using path, ``key``: path, ``value``: dict of attribute name and attribute value. - Path should contain `Node` name, separated by `sep`. + Path should contain ``Node`` name, separated by `sep`. - For example: Path string "a/b" refers to Node("b") with parent Node("a"). Path can start from root node `name`, or start with `sep`. @@ -644,8 +644,8 @@ def dict_to_tree( path_attrs (Dict[str, Any]): dictionary containing path and node attribute information, key: path, value: dict of tree attribute and attribute value sep (str): path separator of input `path_attrs` and created tree, defaults to `/` - duplicate_name_allowed (bool): indicator if nodes with duplicate `Node` name is allowed, defaults to True - node_type (Type[Node]): node type of tree to be created, defaults to Node + duplicate_name_allowed (bool): indicator if nodes with duplicate ``Node`` name is allowed, defaults to True + node_type (Type[Node]): node type of tree to be created, defaults to ``Node`` Returns: (Node) @@ -704,7 +704,7 @@ def nested_dict_to_tree( value of `child_key` (List[Dict[str, Any]]): list of dict containing `name_key` and `child_key` (recursive) name_key (str): key of node name, value is type str child_key (str): key of child list, value is type list - node_type (Type[Node]): node type of tree to be created, defaults to Node + node_type (Type[Node]): node type of tree to be created, defaults to ``Node`` Returns: (Node) @@ -747,7 +747,7 @@ def dataframe_to_tree( Path in path column can start from root node `name`, or start with `sep`. - For example: Path string can be "/a/b" or "a/b", if sep is "/". - Path in path column should contain `Node` name, separated by `sep`. + Path in path column should contain ``Node`` name, separated by `sep`. - For example: Path string "a/b" refers to Node("b") with parent Node("a"). All paths should start from the same root node. @@ -785,8 +785,8 @@ def dataframe_to_tree( attribute_cols (List[str]): columns of data containing node attribute information, if not set, it will take all columns of data except `path_col` sep (str): path separator of input `path_col` and created tree, defaults to `/` - duplicate_name_allowed (bool): indicator if nodes with duplicate `Node` name is allowed, defaults to True - node_type (Type[Node]): node type of tree to be created, defaults to Node + duplicate_name_allowed (bool): indicator if nodes with duplicate ``Node`` name is allowed, defaults to True + node_type (Type[Node]): node type of tree to be created, defaults to ``Node`` Returns: (Node) @@ -856,7 +856,7 @@ def dataframe_to_tree_by_relation( This error can be ignored by setting `allow_duplicates` to be True. `child_col` and `parent_col` specify columns for child name and parent name to construct tree. - `attribute_cols` specify columns for node attribute for child name + `attribute_cols` specify columns for node attribute for child name. If columns are not specified, `child_col` takes first column, `parent_col` takes second column, and all other columns are `attribute_cols`. @@ -895,7 +895,7 @@ def dataframe_to_tree_by_relation( if not set, it will take all columns of data except `child_col` and `parent_col` allow_duplicates (bool): allow duplicate intermediate nodes such that child node will be tagged to multiple parent nodes, defaults to False - node_type (Type[Node]): node type of tree to be created, defaults to Node + node_type (Type[Node]): node type of tree to be created, defaults to ``Node`` Returns: (Node) diff --git a/bigtree/tree/export.py b/bigtree/tree/export.py index 972b9129..29c01405 100644 --- a/bigtree/tree/export.py +++ b/bigtree/tree/export.py @@ -417,7 +417,7 @@ def tree_to_dict( parent_key (str): dictionary key for `node.parent.node_name`, optional attr_dict (Dict[str, str]): dictionary mapping node attributes to dictionary key, key: node attributes, value: corresponding dictionary key, optional - all_attrs (bool): indicator whether to retrieve all `Node` attributes, overrides `attr_dict`, defaults to False + all_attrs (bool): indicator whether to retrieve all ``Node`` attributes, overrides `attr_dict`, defaults to False max_depth (int): maximum depth to export tree, optional skip_depth (int): number of initial depths to skip, optional leaf_only (bool): indicator to retrieve only information from leaf nodes @@ -491,7 +491,7 @@ def tree_to_nested_dict( child_key (str): dictionary key for list of children, optional attr_dict (Dict[str, str]): dictionary mapping node attributes to dictionary key, key: node attributes, value: corresponding dictionary key, optional - all_attrs (bool): indicator whether to retrieve all `Node` attributes, overrides `attr_dict`, defaults to False + all_attrs (bool): indicator whether to retrieve all ``Node`` attributes, overrides `attr_dict`, defaults to False max_depth (int): maximum depth to export tree, optional Returns: @@ -573,7 +573,7 @@ def tree_to_dataframe( parent_col (str): column name for `node.parent.node_name`, optional attr_dict (Dict[str, str]): dictionary mapping node attributes to column name, key: node attributes, value: corresponding column in dataframe, optional - all_attrs (bool): indicator whether to retrieve all `Node` attributes, overrides `attr_dict`, defaults to False + all_attrs (bool): indicator whether to retrieve all ``Node`` attributes, overrides `attr_dict`, defaults to False max_depth (int): maximum depth to export tree, optional skip_depth (int): number of initial depths to skip, optional leaf_only (bool): indicator to retrieve only information from leaf nodes @@ -691,9 +691,9 @@ def tree_to_dot( node_shape (str): shape of nodes, defaults to None Possible node_shape include "circle", "square", "diamond", "triangle" edge_colour (str): colour of edges, defaults to None - node_attr (str): `Node` attribute for node style, overrides `node_colour` and `node_shape`, defaults to None + node_attr (str): ``Node`` attribute for node style, overrides `node_colour` and `node_shape`, defaults to None. Possible node style (attribute value) include {"style": "filled", "fillcolor": "gold", "shape": "diamond"} - edge_attr (str): `Node` attribute for edge style, overrides `edge_colour`, defaults to None + edge_attr (str): ``Node`` attribute for edge style, overrides `edge_colour`, defaults to None. Possible edge style (attribute value) include {"style": "bold", "label": "edge label", "color": "black"} Returns: @@ -881,58 +881,60 @@ def tree_to_mermaid( **Accepted Parameter Values** Possible `rankdir` - - TB: top-to-bottom - - BT: bottom-to-top - - LR: left-to-right - - RL: right-to-left + - `TB`: top-to-bottom + - `BT`: bottom-to-top + - `LR`: left-to-right + - `RL`: right-to-left Possible `line_shape` - - basis - - bumpX: used in LR or RL direction - - bumpY - - cardinal: undirected - - catmullRom: undirected - - linear: - - monotoneX: used in LR or RL direction - - monotoneY - - natural - - step: used in LR or RL direction - - stepAfter - - stepBefore: used in LR or RL direction - - Possible node_shape - - rounded_edge: rectangular with rounded edges - - stadium: (_) shape, rectangular with rounded ends - - subroutine: ||_|| shape, rectangular with additional line at the ends - - cylindrical: database node - - circle: circular - - asymmetric: >_| shape - - rhombus: decision node - - hexagon: <_> shape - - parallelogram: /_/ shape - - parallelogram_alt: \\_\\ shape, inverted parallelogram - - trapezoid: /_\\ shape - - trapezoid_alt: \\_/ shape, inverted trapezoid - - double_circle - - Possible edge_arrow - - normal: directed arrow, shaded arrowhead - - bold: bold directed arrow - - dotted: dotted directed arrow - - open: line, undirected arrow - - bold_open: bold line - - dotted_open: dotted line - - invisible: no line - - circle: directed arrow with filled circle arrowhead - - cross: directed arrow with cross arrowhead - - double_normal: bidirectional directed arrow - - double_circle: bidirectional directed arrow with filled circle arrowhead - - double_cross: bidirectional directed arrow with cross arrowhead + - `basis` + - `bumpX`: used in LR or RL direction + - `bumpY` + - `cardinal`: undirected + - `catmullRom`: undirected + - `linear`: + - `monotoneX`: used in LR or RL direction + - `monotoneY` + - `natural` + - `step`: used in LR or RL direction + - `stepAfter` + - `stepBefore`: used in LR or RL direction + + Possible `node_shape` + - `rounded_edge`: rectangular with rounded edges + - `stadium`: (_) shape, rectangular with rounded ends + - `subroutine`: ||_|| shape, rectangular with additional line at the ends + - `cylindrical`: database node + - `circle`: circular + - `asymmetric`: >_| shape + - `rhombus`: decision node + - `hexagon`: <_> shape + - `parallelogram`: /_/ shape + - `parallelogram_alt`: \\_\\ shape, inverted parallelogram + - `trapezoid`: /_\\ shape + - `trapezoid_alt`: \\_/ shape, inverted trapezoid + - `double_circle` + + Possible `edge_arrow` + - `normal`: directed arrow, shaded arrowhead + - `bold`: bold directed arrow + - `dotted`: dotted directed arrow + - `open`: line, undirected arrow + - `bold_open`: bold line + - `dotted_open`: dotted line + - `invisible`: no line + - `circle`: directed arrow with filled circle arrowhead + - `cross`: directed arrow with cross arrowhead + - `double_normal`: bidirectional directed arrow + - `double_circle`: bidirectional directed arrow with filled circle arrowhead + - `double_cross`: bidirectional directed arrow with cross arrowhead Refer to mermaid `documentation`_ for more information. Paste the output into any markdown file renderer to view the flowchart, alternatively visit the mermaid playground `here`_. + .. note:: Advanced mermaid flowchart functionalities such as subgraphs and interactions (script, click) are not supported. + .. _documentation: http://mermaid.js.org/syntax/flowchart.html .. _here: https://mermaid.live/ @@ -979,13 +981,13 @@ def tree_to_mermaid( node_border_colour (str): border colour of nodes, can be colour name or hexcode, defaults to None node_border_width (float): width of node border, defaults to 1 node_shape (str): node shape, sets the shape of every node, defaults to 'rounded_edge' - node_shape_attr (str): `Node` attribute for node shape, sets shape of custom nodes, + node_shape_attr (str): ``Node`` attribute for node shape, sets shape of custom nodes, overrides default `node_shape`, defaults to None edge_arrow (str): edge arrow style from parent to itself, sets the arrow style of every edge, defaults to 'normal' - edge_arrow_attr (str): `Node` attribute for edge arrow style, sets edge arrow style of custom nodes from + edge_arrow_attr (str): ``Node`` attribute for edge arrow style, sets edge arrow style of custom nodes from parent to itself, overrides default `edge_arrow`, defaults to None - edge_label (str): `Node` attribute for edge label from parent to itself, defaults to None - node_attr (str): `Node` attribute for node style, overrides `node_colour`, `node_border_colour`, + edge_label (str): ``Node`` attribute for edge label from parent to itself, defaults to None + node_attr (str): ``Node`` attribute for node style, overrides `node_colour`, `node_border_colour`, and `node_border_width`, defaults to None Returns: diff --git a/bigtree/tree/helper.py b/bigtree/tree/helper.py index 5cbca0be..abc69ba6 100644 --- a/bigtree/tree/helper.py +++ b/bigtree/tree/helper.py @@ -15,7 +15,7 @@ def clone_tree(tree: BaseNode, node_type: Type[BaseNodeT]) -> BaseNodeT: - """Clone tree to another `Node` type. + """Clone tree to another ``Node`` type. If the same type is needed, simply do a tree.copy(). >>> from bigtree import BaseNode, Node, clone_tree @@ -67,7 +67,7 @@ def prune_tree( For pruning by `max_depth`, All nodes that are beyond `max_depth` will be removed. - Path should contain `Node` name, separated by `sep`. + Path should contain ``Node`` name, separated by `sep`. - For example: Path string "a/b" refers to Node("b") with parent Node("a"). >>> from bigtree import Node, prune_tree diff --git a/bigtree/tree/modify.py b/bigtree/tree/modify.py index fb97a539..187c23f9 100644 --- a/bigtree/tree/modify.py +++ b/bigtree/tree/modify.py @@ -117,7 +117,7 @@ def shift_nodes( └── c └── e - In ``merge_children`` case, child nodes are shifted instead of the parent node. + In ``merge_children=True`` case, child nodes are shifted instead of the parent node. - If the path already exists, child nodes are merged with existing children. - If same node is shifted, the child nodes of the node are merged with the node's parent. @@ -156,7 +156,7 @@ def shift_nodes( └── g └── h - In ``merge_leaves`` case, leaf nodes are copied instead of the parent node. + In ``merge_leaves=True`` case, leaf nodes are copied instead of the parent node. - If the path already exists, leaf nodes are merged with existing children. - If same node is copied, the leaf nodes of the node are merged with the node's parent. @@ -198,7 +198,7 @@ def shift_nodes( ├── y └── h - In ``delete_children`` case, only the node is shifted without its accompanying children/descendants. + In ``delete_children=True`` case, only the node is shifted without its accompanying children/descendants. >>> root = Node("a") >>> b = Node("b", parent=root) @@ -345,7 +345,7 @@ def copy_nodes( └── c └── e - In ``merge_children`` case, child nodes are copied instead of the parent node. + In ``merge_children=True`` case, child nodes are copied instead of the parent node. - If the path already exists, child nodes are merged with existing children. - If same node is copied, the child nodes of the node are merged with the node's parent. @@ -388,7 +388,7 @@ def copy_nodes( └── g └── h - In ``merge_leaves`` case, leaf nodes are copied instead of the parent node. + In ``merge_leaves=True`` case, leaf nodes are copied instead of the parent node. - If the path already exists, leaf nodes are merged with existing children. - If same node is copied, the leaf nodes of the node are merged with the node's parent. @@ -433,7 +433,7 @@ def copy_nodes( ├── y └── h - In ``delete_children`` case, only the node is copied without its accompanying children/descendants. + In ``delete_children=True`` case, only the node is copied without its accompanying children/descendants. >>> root = Node("a") >>> b = Node("b", parent=root) @@ -583,7 +583,7 @@ def copy_nodes_from_tree_to_tree( └── c └── d - In ``merge_children`` case, child nodes are copied instead of the parent node. + In ``merge_children=True`` case, child nodes are copied instead of the parent node. - If the path already exists, child nodes are merged with existing children. >>> root_other = Node("aa") @@ -603,7 +603,7 @@ def copy_nodes_from_tree_to_tree( └── f └── g - In ``merge_leaves`` case, leaf nodes are copied instead of the parent node. + In ``merge_leaves=True`` case, leaf nodes are copied instead of the parent node. - If the path already exists, leaf nodes are merged with existing children. >>> root_other = Node("aa") @@ -622,7 +622,7 @@ def copy_nodes_from_tree_to_tree( │ └── d └── g - In ``delete_children`` case, only the node is copied without its accompanying children/descendants. + In ``delete_children=True`` case, only the node is copied without its accompanying children/descendants. >>> root_other = Node("aa") >>> root_other.show() diff --git a/bigtree/utils/iterators.py b/bigtree/utils/iterators.py index 23ff5649..2febc4e3 100644 --- a/bigtree/utils/iterators.py +++ b/bigtree/utils/iterators.py @@ -40,7 +40,7 @@ def inorder_iter( ) -> Iterable[BinaryNodeT]: """Iterate through all children of a tree. - In Iteration Algorithm, LNR + In-Order Iteration Algorithm, LNR 1. Recursively traverse the current node's left subtree. 2. Visit the current node. 3. Recursively traverse the current node's right subtree. @@ -215,7 +215,7 @@ def levelorder_iter( ) -> Iterable[BaseNodeT]: """Iterate through all children of a tree. - Level Order Algorithm + Level-Order Iteration Algorithm 1. Recursively traverse the nodes on same level. >>> from bigtree import Node, list_to_tree, levelorder_iter @@ -279,7 +279,7 @@ def levelordergroup_iter( ) -> Iterable[Iterable[BaseNodeT]]: """Iterate through all children of a tree. - Level Order Group Algorithm + Level-Order Group Iteration Algorithm 1. Recursively traverse the nodes on same level, returns nodes level by level in a nested list. >>> from bigtree import Node, list_to_tree, levelordergroup_iter @@ -344,7 +344,7 @@ def zigzag_iter( ) -> Iterable[BaseNodeT]: """Iterate through all children of a tree. - ZigZag Algorithm + ZigZag Iteration Algorithm 1. Recursively traverse the nodes on same level, in a zigzag manner across different levels. >>> from bigtree import Node, list_to_tree, zigzag_iter @@ -415,7 +415,7 @@ def zigzaggroup_iter( ) -> Iterable[Iterable[BaseNodeT]]: """Iterate through all children of a tree. - ZigZag Group Algorithm + ZigZag Group Iteration Algorithm 1. Recursively traverse the nodes on same level, in a zigzag manner across different levels, returns nodes level by level in a nested list.