Merge branch 'main' of https://github.com/mar10/nutree

mar10 · Sep 12, 2024 · bad700c · bad700c
2 parents 3b9841a + 0a29306
commit bad700c
Show file tree

Hide file tree

Showing 46 changed files with 2,135 additions and 869 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,17 +1,20 @@
 # Changelog
 
-## 0.8.1 (unreleased)
+## 0.9.1 (unreleased)
 
+## 0.9.0 (2024-09-12)
+
+- Add `Tree.build_random_tree()` (experimental).
+- Add `GenericNodeData` as wrapper for `dict` data.
 - Fixed #7 Tree.from_dict failing to recreate an arbitrary object tree with a mapper.
 
 ## 0.8.0 (2024-03-29)
 
 - BREAKING: Drop Python 3.7 support (EoL 2023-06-27).
 - `Tree.save()` accepts a `compression` argument that will enable compression.
   `Tree.load()` can detect if the input file has a compression header and will
-  decompress automatically.
-- New traversal methods `LEVEL_ORDER`, `LEVEL_ORDER_RTL`, `ZIGZAG`, `ZIGZAG_RTL`.
   decompress transparently.
+- New traversal methods `LEVEL_ORDER`, `LEVEL_ORDER_RTL`, `ZIGZAG`, `ZIGZAG_RTL`.
 - New compact connector styles `'lines32c'`, `'round43c'`, ...
 - Save as mermaid flow diagram.
 

diff --git a/Pipfile b/Pipfile
@@ -5,10 +5,9 @@ name = "pypi"
 
 [dev-packages]
 black = { version = "~=24.3", extras = ["jupyter"] }
+# coverage = "*"
+fabulist="*"
 isort = "*"
-# pylint = "*"
-# TODO: remove this line:
-# pytest-html = "!=3.2.0" # wait for https://github.com/pytest-dev/pytest-html/pull/583
 pytest = "*"
 pytest-cov = "*"
 PyYAML = "*"
@@ -22,14 +21,13 @@ tox = "*"
 twine = "*"
 wheel = "*"
 yabs = "*"
-nutree = {path = ".",editable = true}
 ipykernel = "*"
 notebook = "*"
+nutree = {path = ".",editable = true}
 
 [packages]
 
 [requires]
 python_version = "3.12"
 
 [pipenv]
-# allow_prereleases = true
diff --git a/Pipfile.lock b/Pipfile.lock
diff --git a/README.md b/README.md
@@ -23,6 +23,7 @@ Nodes can be plain strings or objects <br>
 (De)Serialize to (compressed) JSON <br>
 Save as Mermaid flow diagram <br>
 Different traversal methods <br>
+Generate random trees <br>
 Fully type annotated <br>
 Convert to RDF graph <br>
 Typed child nodes <br>

diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py
@@ -119,7 +119,7 @@
 
 # General information about the project.
 project = u'nutree'
-copyright = u'2021-2023, <a href="https://wwwendt.de">Martin Wendt</a>'
+copyright = u'2021-2024, <a href="https://wwwendt.de">Martin Wendt</a>'
 author = u'Martin Wendt'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -130,19 +130,25 @@
 #version = '1.0'
 # The full version, including alpha/beta/rc tags.
 #release = '1.0'
-import pkg_resources
+import importlib
 
 try:
-    release = pkg_resources.get_distribution('nutree').version
-    # print( "release", release)
-    del pkg_resources
-except pkg_resources.DistributionNotFound:
-    print('To build the documentation, The distribution information')
-    print('Has to be available.  Either install the package into your')
+    # release = pkg_resources.get_distribution("nutree").version
+    release = importlib.metadata.version("nutree")
+except importlib.metadata.PackageNotFoundError:
+    print("To build the documentation, The distribution information")
+    print("has to be available. Either install the package into your")
     print('development environment or run "setup.py develop" to setup the')
-    print('metadata.  A virtualenv is recommended!')
+    print("metadata. A virtualenv is recommended!")
+
+    print(f"sys.path: {sys.path}")
+    print(f"package_root: {package_root}")
+    for fn in os.listdir(package_root):
+        print("-", fn)
     sys.exit(1)
 
+del importlib.metadata
+
 version = '.'.join(release.split('.')[:2])
 
 # The language for content autogenerated by Sphinx. Refer to documentation

diff --git a/docs/sphinx/index.rst b/docs/sphinx/index.rst
@@ -28,8 +28,8 @@ nutree
 
    $ pip install nutree
 
-**Note:** Run ``pip install nutree[graph]`` instead, in order to install 
-additional graph support.
+**Note:** Run ``pip install "nutree[graph]"`` or ``pip install "nutree[all]"`` 
+instead, in order to install additional graph support.
 
 ::
 
@@ -96,8 +96,9 @@ Nutree Facts
   * :ref:`(De)Serialize to (compressed) JSON <serialize>`
   * :ref:`Save as Mermaid flow diagram <save-mermaid>`
   * :ref:`Different traversal methods <traversal>`
-  * :ref:`Fully type annotated <api-reference>`
+  * :ref:`Generate random trees <randomize>`
   * :ref:`Convert to RDF graph <save-rdf>`
+  * :ref:`Fully type annotated <api-reference>`
   * :ref:`Typed child nodes <typed-tree>`
   * :ref:`Pretty print <pretty-print>`
   * :ref:`Navigation <navigate>`

diff --git a/docs/sphinx/installation.rst b/docs/sphinx/installation.rst
@@ -5,8 +5,8 @@ Installation is straightforward::
 
   $ pip install nutree
 
-**Note:** Run ``pip install nutree[graph]`` instead, in order to install 
-additional graph support.
+**Note:** Run ``pip install "nutree[graph]"`` or ``pip install "nutree[all]"`` 
+instead, in order to install additional graph support.
 
 Installing `nutree` and its dependencies into a 'sandbox' will help to keep
 your system Python clean, but requires to activate the virtual environment::

diff --git a/docs/sphinx/reference_guide.rst b/docs/sphinx/reference_guide.rst
@@ -5,10 +5,18 @@ Reference Guide
 Class Overview
 ==============
 
+Nutree Classes
+--------------
+
 .. inheritance-diagram:: nutree.tree nutree.node nutree.typed_tree nutree.common
    :parts: 2
    :private-bases:
-   :caption: nutree classes
+
+Random Tree Generator
+---------------------
+
+.. inheritance-diagram:: nutree.tree_generator
+   :parts: 2
 
 
 .. API

diff --git a/docs/sphinx/rg_modules.rst b/docs/sphinx/rg_modules.rst
@@ -42,3 +42,12 @@ nutree.common module
     :show-inheritance:
     :inherited-members:
 
+nutree.tree_generator module
+----------------------------
+
+.. automodule:: nutree.tree_generator
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:
+
diff --git a/docs/sphinx/ug_basics.rst b/docs/sphinx/ug_basics.rst
@@ -4,6 +4,12 @@ Basics
 
 .. py:currentmodule:: nutree
 
+.. admonition:: TL;DR
+
+    Nutree is a Python library for managing hierarchical data structures.
+    It stores arbitrary data objects in nodes and provides methods for
+    navigation, searching, and iteration.
+
 
 Adding Nodes
 ------------
@@ -35,8 +41,8 @@ Nodes are usually created by adding a new data instance to a parent::
 
 .. seealso::
 
-    See :doc:`ug_objects` for details on how to manage arbitrary objects instead
-    of plain strings.
+    See :doc:`ug_objects` for details on how to manage arbitrary objects, dicts,
+    etc. instead of plain strings.
 
 
 Info and Navigation

diff --git a/docs/sphinx/ug_clones.rst b/docs/sphinx/ug_clones.rst
@@ -6,6 +6,10 @@ Multiple Instances ('Clones')
 
 .. py:currentmodule:: nutree
 
+.. admonition:: TL;DR
+
+    Nutree allows to store multiple references to the same data object in a tree.
+
 Every :class:`~nutree.node.Node` instance is unique within the tree and
 also has a unique `node.node_id` value.
 

diff --git a/docs/sphinx/ug_diff.rst b/docs/sphinx/ug_diff.rst
@@ -6,6 +6,10 @@ Diff and Merge
 
 .. py:currentmodule:: nutree
 
+.. admonition:: TL;DR
+
+    Nutree provides a `diff` method to compare two trees and calculate the differences.
+
 The :meth:`~nutree.tree.Tree.diff` method compares a tree (`T0`) against another 
 one (`T1`) and returns a merged, annotated copy.
 

diff --git a/docs/sphinx/ug_graphs.rst b/docs/sphinx/ug_graphs.rst
@@ -6,6 +6,15 @@ Graphs
 
 .. py:currentmodule:: nutree
 
+.. admonition:: TL;DR
+
+    Nutree implements conversion to `DOT <https://en.wikipedia.org/wiki/DOT_(graph_description_language)>`_
+    and `Mermaid <https://mermaid.js.org>`_ formats. |br|
+    This allows to visualize trees as graphs in various formats like `png`, `svg`, etc. |br|
+    The :class:`~nutree.typed_tree.TypedTree` class introduces the concept of
+    `typed nodes`, which allows to generate labelled edges in the graph representation.
+
+
 .. note::
     :class:`~nutree.tree.Tree` (and :class:`~nutree.typed_tree.TypedTree` even 
     more so) has features that make mapping to a graph easy. 
@@ -166,7 +175,7 @@ Let's visualize the result of the :ref:`diff-and-merge` example::
     of `pydot <https://github.com/pydot/pydot>`_ 
     and `Graphwiz <https://www.graphviz.org>`_. |br|
     Either install them separately or install nutree with extras: 
-    ``pip install nutree[graph]``.
+    ``pip install "nutree[graph]"`` or ``pip install "nutree[all]"``.
 
 .. _save-mermaid:
 
@@ -452,5 +461,5 @@ This would be the 'turtle' formatted serialization::
 
 .. note::
     Converting to RDF requires an installation of `rdflib <https://rdflib.readthedocs.io/>`_ |br|
-    Either install it separately or install nutree with extras: 
-    ``pip install nutree[graph]``.
+    Either install them separately or install nutree with extras: 
+    ``pip install "nutree[graph]"`` or ``pip install "nutree[all]"``.
diff --git a/docs/sphinx/ug_mutation.rst b/docs/sphinx/ug_mutation.rst
@@ -6,6 +6,12 @@ Mutation
 
 .. py:currentmodule:: nutree
 
+.. admonition:: TL;DR
+
+    Nutree provides methods to modify the tree structure in-place. |br|
+    This includes adding, moving, and deleting nodes, as well as filtering and sorting.
+
+
 Some in-place modifications are available::
 
     # Tree