From 60b8ecaf2afb874b733c1c61be26da68df51d989 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Thu, 11 May 2023 10:46:20 +0200 Subject: Adding upstream version 1.6.4. Signed-off-by: Daniel Baumann --- docs/source/index.rst | 241 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 docs/source/index.rst (limited to 'docs/source/index.rst') diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..2834bec --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,241 @@ +.. treelib documentation master file, created by + sphinx-quickstart on Thu Dec 20 16:30:18 2018. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to treelib's documentation! +*********************************** + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + +Introduction +============ + +`Tree `_ is an +important data structure in computer science. Examples are shown in ML algorithm designs such as random forest tree and software engineering such as file system index. `treelib `_ is created to provide an efficient implementation of tree data structure in Python. + +The main features of `treelib` includes: + * Efficient operation of node searching, O(1). + * Support common tree operations like **traversing**, **insertion**, **deletion**, **node moving**, **shallow/deep copying**, **subtree cutting** etc. + * Support user-defined data payload to accelerate your model construction. + * Pretty tree showing and text/json dump for pretty show and offline analysis. + * Compatible with Python 2 and 3. + +Installation +============ + +The rapidest way to install treelib is using the package management tools like +``easy_install`` or ``pip`` with command + + .. code-block:: sh + + $ sudo easy_install -U treelib + +or the setup script + + .. code-block:: sh + + $ sudo python setup.py install + +**Note**: With the package management tools, the hosted version may be falling +behind current development branch on `Github +`_. If you encounter some problems, try +the freshest version on Github or open `issues +`_ to let me know your problem. + +Examples +======== + +Basic Usage +------------- + +.. code-block:: sh + + >>> from treelib import Node, Tree + >>> tree = Tree() + >>> tree.create_node("Harry", "harry") # root node + >>> tree.create_node("Jane", "jane", parent="harry") + >>> tree.create_node("Bill", "bill", parent="harry") + >>> tree.create_node("Diane", "diane", parent="jane") + >>> tree.create_node("Mary", "mary", parent="diane") + >>> tree.create_node("Mark", "mark", parent="jane") + >>> tree.show() + Harry + ├── Bill + └── Jane + ├── Diane + │ └── Mary + └── Mark + + +API Examples +-------------- + +**Example 1**: Expand a tree with specific mode (Tree.DEPTH [default], +Tree.WIDTH, Tree.ZIGZAG). + +.. code-block:: sh + + >>> print(','.join([tree[node].tag for node in \ + tree.expand_tree(mode=Tree.DEPTH)])) + Harry,Bill,Jane,Diane,Mary,Mark + +**Example 2**: Expand tree with custom filter. + +.. code-block:: sh + + >>> print(','.join([tree[node].tag for node in \ + tree.expand_tree(filter = lambda x: \ + x.identifier != 'diane')])) + Harry,Bill,Jane,Mark + +**Example 3**: Get a subtree with the root of 'diane'. + +.. code-block:: sh + + >>> sub_t = tree.subtree('diane') + >>> sub_t.show() + Diane + └── Mary + +**Example 4**: Paste a new tree to the original one. + +.. code-block:: sh + + >>> new_tree = Tree() + >>> new_tree.create_node("n1", 1) # root node + >>> new_tree.create_node("n2", 2, parent=1) + >>> new_tree.create_node("n3", 3, parent=1) + >>> tree.paste('bill', new_tree) + >>> tree.show() + Harry + ├── Bill + │ └── n1 + │ ├── n2 + │ └── n3 + └── Jane + ├── Diane + │ └── Mary + └── Mark + +**Example 5**: Remove the existing node from the tree + +.. code-block:: sh + + >>> tree.remove_node(1) + >>> tree.show() + Harry + ├── Bill + └── Jane + ├── Diane + │ └── Mary + └── Mark + +**Example 6**: Move a node to another parent. + +.. code-block:: sh + + >>> tree.move_node('mary', 'harry') + >>> tree.show() + Harry + ├── Bill + ├── Jane + │ ├── Diane + │ └── Mark + └── Mary + +**Example 7**: Get the height of the tree. + +.. code-block:: sh + + >>> tree.depth() + 2 + +**Example 8**: Get the level of a node. + +.. code-block:: sh + + >>> node = tree.get_node("bill") + >>> tree.depth(node) + 1 + +**Example 9**: Print or dump tree structure. For example, the same tree in + basic example can be printed with 'ascii-em': + +.. code-block:: sh + + >>> tree.show(line_type="ascii-em") + Harry + ╠══ Bill + ╠══ Jane + ║ ╠══ Diane + ║ ╚══ Mark + ╚══ Mary + +In the JSON form, to_json() takes optional parameter with_data to trigger if +the data field is appended into JSON string. For example, + +.. code-block:: sh + + >>> print(tree.to_json(with_data=True)) + {"Harry": {"data": null, "children": [{"Bill": {"data": null}}, {"Jane": {"data": null, "children": [{"Diane": {"data": null}}, {"Mark": {"data": null}}]}}, {"Mary": {"data": null}}]}} + +**Example 10**: Save tree into file + The function save2file require a filename. + The file is opened to write using mode 'ab'. + +.. code-block:: sh + + >>> tree.save2file('tree.txt') + + +Advanced Usage +---------------- + +Sometimes, you need trees to store your own data. The newest version of +:mod:`treelib` supports ``.data`` variable to store whatever you want. For +example, to define a flower tree with your own data: + +.. code-block:: sh + + >>> class Flower(object): \ + def __init__(self, color): \ + self.color = color + +You can create a flower tree now: + +.. code-block:: sh + + >>> ftree = Tree() + >>> ftree.create_node("Root", "root", data=Flower("black")) + >>> ftree.create_node("F1", "f1", parent='root', data=Flower("white")) + >>> ftree.create_node("F2", "f2", parent='root', data=Flower("red")) + +Printing the colors of the tree: + +.. code-block:: sh + + >>> ftree.show(data_property="color") + black + ├── white + └── red + +**Notes:** Before version 1.2.5, you may need to inherit and modify the behaviors of tree. Both are supported since then. For flower example, + +.. code-block:: sh + + >>> class FlowerNode(treelib.Node): \ + def __init__(self, color): \ + self.color = color + >>> # create a new node + >>> fnode = FlowerNode("white") + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` -- cgit v1.2.3