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

CHANGELOG.md

@@ -1,6 +1,10 @@
 # Changelog
 
-## 0.8.0 (unreleased)
+## 0.8.1 (unreleased)
+
+- 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.

Pipfile

@@ -4,9 +4,9 @@ verify_ssl = true
 name = "pypi"
 
 [dev-packages]
-black = { version = "~=23.10", extras = ["jupyter"] }
+black = { version = "~=24.3", extras = ["jupyter"] }
 isort = "*"
-pylint = "*"
+# pylint = "*"
 # TODO: remove this line:
 # pytest-html = "!=3.2.0" # wait for https://github.com/pytest-dev/pytest-html/pull/583
 pytest = "*"

docs/sphinx/index.rst

@@ -4,7 +4,7 @@
 nutree
 ######
 
-|travis_badge| |nbsp| |pypi_badge| |nbsp| |lic_badge| |nbsp| |rtd_badge| |nbsp|
+|gha_badge| |nbsp| |pypi_badge| |nbsp| |lic_badge| |nbsp| |rtd_badge| |nbsp|
 |coverage_badge| |nbsp| |black_badge| |nbsp| |so_badge|
 
 *A Python library for tree data structures with an intuitive, yet powerful, API.*
@@ -107,9 +107,13 @@ Nutree Facts
 `Read more <installation.html>`_ ...
 
 
-.. |travis_badge| image:: https://travis-ci.com/mar10/nutree.svg?branch=main
+.. .. |travis_badge| image:: https://travis-ci.com/mar10/nutree.svg?branch=main
+..    :alt: Build Status
+..    :target: https://app.travis-ci.com/github/mar10/nutree
+
+.. |gha_badge| image:: https://github.com/mar10/nutree/actions/workflows/tests.yml/badge.svg
    :alt: Build Status
-   :target: https://app.travis-ci.com/github/mar10/nutree
+   :target: https://github.com/mar10/nutree/actions/workflows/tests.yml
 
 .. |pypi_badge| image:: https://img.shields.io/pypi/v/nutree.svg
    :alt: PyPI Version

docs/sphinx/ug_graphs.rst

@@ -173,12 +173,13 @@ Let's visualize the result of the :ref:`diff-and-merge` example::
 Mermaid Format
 --------------
 
-Mermaid is a diagramming and charting tool that uses Markdown-inspired text 
-for defining diagrams. |br|
-It is a popular choice for documentation and is supported by many `Markdown`_ editors. |br|
-Nutree can convert trees to Mermaid format.
+`Mermaid <https://mermaid.js.org>`_ is a diagramming and charting tool that uses 
+`Markdown <https://www.markdownguide.org>`_ -inspired text for defining diagrams. |br|
+It is a popular choice for documentation and is supported by many Markdown 
+editors. 
 
-Nutree implements conversion to `Mermaid flowchart format <https://mermaid.js.org/syntax/flowchart.html>`_.
+Nutree implements conversion to 
+`Mermaid flowchart format <https://mermaid.js.org/syntax/flowchart.html>`_. |br|
 Given this tree ::
 
     Tree<'Root'>
@@ -227,20 +228,34 @@ we can write a Markdown file with embedded Mermaid flowchart like so::
     7 --> 8
     ```
 
+A preview application would render a graph from this markdown definition. |br|
+However we can also create a rendered image file instead:: 
+
+    tree.to_mermaid_flowchart("graph.png", format="png")
+
+.. image:: test_mermaid.png
+
 
 This graph may be rendered in different formats like so (using a TypedTree
 example here)::
 
     tree.to_mermaid_flowchart(
-        "/path/to/tree_1.png",
+        "/path/to/tree_1.svg",
         title="Typed Tree",
         direction="LR",
-        format="png",
+        format="svg",
         mmdc_options={"--theme": "forest"},
     )
 
 .. image:: test_mermaid_typed.png
 
+.. note::
+    Writing of plain Markdown format is natively implemented by `nutree`.
+
+    Rendering output formats like `png`, `svg`, or `pdf` requires the 
+    installation of the Node.js based command-line interface (CLI) ``mmdc``. |br|
+    See `mermaid.cli <https://github.com/mermaid-js/mermaid-cli>`_ for details.
+
 
 .. _typed-tree:
 

nutree/__init__.py

@@ -14,8 +14,9 @@
     When pywin32 is installed, number must be a.b.c for MSI builds?
     "3.0.0a4" seems not to work in this case!
 """
+
 # flake8: noqa
-__version__ = "0.7.2-a1"
+__version__ = "0.8.1-a1"
 
 from .common import (
     AmbiguousMatchError,

nutree/common.py

@@ -13,18 +13,7 @@
 from contextlib import contextmanager
 from enum import Enum
 from pathlib import Path
-from typing import (
-    IO,
-    TYPE_CHECKING,
-    Any,
-    Callable,
-    Dict,
-    List,
-    Optional,
-    Tuple,
-    Type,
-    Union,
-)
+from typing import IO, TYPE_CHECKING, Any, Callable, Dict, List, Type, Union
 
 if TYPE_CHECKING:  # Imported by type checkers, but prevent circular includes
     from .node import Node
@@ -176,7 +165,7 @@ def get_version() -> str:
     return __version__
 
 
-def check_python_version(min_version: Tuple[str]) -> bool:
+def check_python_version(min_version: tuple[str]) -> bool:
     """Check for deprecated Python version."""
     if sys.version_info < min_version:
         min_ver = ".".join([str(s) for s in min_version[:3]])
@@ -190,7 +179,7 @@ def check_python_version(min_version: Tuple[str]) -> bool:
     return True
 
 
-def call_mapper(fn: Optional[MapperCallbackType], node: Node, data: dict) -> Any:
+def call_mapper(fn: MapperCallbackType | None, node: Node, data: dict) -> Any:
     """Call the function and normalize result and exceptions.
 
     Handles `MapperCallbackType`:
@@ -264,13 +253,13 @@ def call_traversal_cb(fn: Callable, node: Node, memo: Any) -> False | None:
             RuntimeWarning,
             stacklevel=3,
         )
-        raise StopTraversal(e.value)
+        raise StopTraversal(e.value) from None
     return None
 
 
 @contextmanager
 def open_as_uncompressed_input_stream(
-    path: Union[str, Path],
+    path: str | Path,
     *,
     encoding: str = "utf8",
     auto_uncompress: bool = True,
@@ -303,7 +292,7 @@ def open_as_uncompressed_input_stream(
 
 @contextmanager
 def open_as_compressed_output_stream(
-    path: Union[str, Path],
+    path: str | Path,
     *,
     compression: bool | int = True,
     encoding: str = "utf8",

nutree/dot.py

@@ -7,7 +7,7 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import IO, TYPE_CHECKING, Iterator, Optional, Union
+from typing import IO, TYPE_CHECKING, Iterator
 
 from .common import MapperCallbackType, call_mapper
 
@@ -109,16 +109,16 @@ def _attr_str(attr_def: dict, mapper=None, node=None):
 
 def tree_to_dotfile(
     tree: Tree,
-    target: Union[IO[str], str, Path],
+    target: IO[str] | str | Path,
     *,
     format=None,
     add_root=True,
     unique_nodes=True,
     graph_attrs=None,
     node_attrs=None,
     edge_attrs=None,
-    node_mapper: Optional[MapperCallbackType] = None,
-    edge_mapper: Optional[MapperCallbackType] = None,
+    node_mapper: MapperCallbackType | None = None,
+    edge_mapper: MapperCallbackType | None = None,
 ) -> None:
     if isinstance(target, str):
         target = Path(target)

nutree/mermaid.py

@@ -10,16 +10,7 @@
 
 from pathlib import Path
 from subprocess import CalledProcessError, check_output
-from typing import (
-    IO,
-    TYPE_CHECKING,
-    Callable,
-    Iterable,
-    Iterator,
-    Literal,
-    Optional,
-    Union,
-)
+from typing import IO, TYPE_CHECKING, Callable, Iterable, Iterator, Literal
 
 from .common import DataIdType
 
@@ -56,8 +47,8 @@ def _node_to_mermaid_flowchart_iter(
     add_root: bool = True,
     unique_nodes: bool = True,
     headers: Iterable[str] | None = None,
-    node_mapper: Optional[MermaidNodeMapperCallbackType] | str = None,
-    edge_mapper: Optional[MermaidEdgeMapperCallbackType] | str = None,
+    node_mapper: MermaidNodeMapperCallbackType | None | str = None,
+    edge_mapper: MermaidEdgeMapperCallbackType | None | str = None,
 ) -> Iterator[str]:
     """Generate Mermaid formatted output line-by-line.
 
@@ -158,7 +149,7 @@ def edge_mapper(from_id, from_node, to_id, to_node):
 
 def node_to_mermaid_flowchart(
     node: Node,
-    target: Union[IO[str], str, Path],
+    target: IO[str] | str | Path,
     *,
     as_markdown: bool = True,
     direction: MermaidDirectionType = "TD",
@@ -168,8 +159,8 @@ def node_to_mermaid_flowchart(
     add_root: bool = True,
     unique_nodes: bool = True,
     headers: Iterable[str] | None = None,
-    node_mapper: Optional[MermaidNodeMapperCallbackType] = None,
-    edge_mapper: Optional[MermaidEdgeMapperCallbackType] = None,
+    node_mapper: MermaidNodeMapperCallbackType | None = None,
+    edge_mapper: MermaidEdgeMapperCallbackType | None = None,
 ) -> None:
     """Write a Mermaid flowchart to a file or stream."""
     if format: