verysimpletree 2.0.0__tar.gz → 2.0.2__tar.gz

{verysimpletree-2.0.0 → verysimpletree-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: verysimpletree
-Version: 2.0.0
+Version: 2.0.2
 Summary: lightweight tree data structure
 Author: Alex Gorji
 Author-email: Alex Gorji <aligorji@hotmail.com>
@@ -20,6 +20,29 @@ An abstract lightweight tree class for managing tree structures.
 
 Requires Python 3.11 or newer.
 
+## Typed list representations
+
+`TreeNodeListRepresentation[ValueT]` describes `[value, child, ...]` recursively.
+`create_tree_from_list()` accepts the same value type as
+`get_list_representation()`, including scalar values for a single attribute:
+
+```python
+from verysimpletree.tree import TreeNodeListRepresentation
+
+representation: TreeNodeListRepresentation[int] = [
+    10,
+    [3, [2, [1], [1]], [1]],
+    [7, [4], [3]],
+]
+# For a concrete Tree subclass whose constructor accepts value:
+tree = MyTree.create_tree_from_list(representation, "value")
+```
+
+For multiple attributes, each node value is a list of attribute values, ordered
+to match `represented_attribute_names`. Child representations must be lists.
+The value type checks the representation's contents; it does not verify that
+attribute names or values match the subclass constructor.
+
 ## Development
 
 Use a current uv release; development and package builds are verified with
@@ -51,7 +74,7 @@ To enable publishing on GitLab:
 3. Add `UV_PUBLISH_TOKEN` as a masked, protected CI/CD variable containing a
    PyPI API token scoped to the `verysimpletree` project.
 4. Set the version in `pyproject.toml`, update `uv.lock`, and commit the changes.
-5. Push a matching stable version tag, such as `v2.0.0`.
+5. Push a matching stable version tag, such as `v2.0.1`.
 
 Publishing runs automatically only for protected stable version tags, after
 checks, tests, and the build pass. The tag must match the package version.

{verysimpletree-2.0.0 → verysimpletree-2.0.2}/README.md

@@ -2,6 +2,29 @@ An abstract lightweight tree class for managing tree structures.
 
 Requires Python 3.11 or newer.
 
+## Typed list representations
+
+`TreeNodeListRepresentation[ValueT]` describes `[value, child, ...]` recursively.
+`create_tree_from_list()` accepts the same value type as
+`get_list_representation()`, including scalar values for a single attribute:
+
+```python
+from verysimpletree.tree import TreeNodeListRepresentation
+
+representation: TreeNodeListRepresentation[int] = [
+    10,
+    [3, [2, [1], [1]], [1]],
+    [7, [4], [3]],
+]
+# For a concrete Tree subclass whose constructor accepts value:
+tree = MyTree.create_tree_from_list(representation, "value")
+```
+
+For multiple attributes, each node value is a list of attribute values, ordered
+to match `represented_attribute_names`. Child representations must be lists.
+The value type checks the representation's contents; it does not verify that
+attribute names or values match the subclass constructor.
+
 ## Development
 
 Use a current uv release; development and package builds are verified with
@@ -33,7 +56,7 @@ To enable publishing on GitLab:
 3. Add `UV_PUBLISH_TOKEN` as a masked, protected CI/CD variable containing a
    PyPI API token scoped to the `verysimpletree` project.
 4. Set the version in `pyproject.toml`, update `uv.lock`, and commit the changes.
-5. Push a matching stable version tag, such as `v2.0.0`.
+5. Push a matching stable version tag, such as `v2.0.1`.
 
 Publishing runs automatically only for protected stable version tags, after
 checks, tests, and the build pass. The tag must match the package version.

{verysimpletree-2.0.0 → verysimpletree-2.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "verysimpletree"
-version = "2.0.0"
+version = "2.0.2"
 description = "lightweight tree data structure"
 requires-python = ">=3.11"
 readme = "README.md"

{verysimpletree-2.0.0 → verysimpletree-2.0.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "verysimpletree"
-version = "2.0.0"
+version = "2.0.2"
 description = "lightweight tree data structure"
 authors = [{ name = "Alex Gorji", email = "aligorji@hotmail.com" }]
 requires-python = ">=3.11"

{verysimpletree-2.0.0 → verysimpletree-2.0.2}/verysimpletree/test_tree.py

@@ -4,6 +4,7 @@ from unittest import TestCase
 from verysimpletree.tree import (
     ChildNotFoundError,
     Tree,
+    TreeNodeListRepresentation,
     TreeReferenceError,
     grandchild1,
 )
@@ -68,6 +69,23 @@ class C(Tree[Any]):
         return True
 
 
+class IntegerTree(Tree["IntegerTree"]):
+    def __init__(self, value: int) -> None:
+        super().__init__()
+        self.value = value
+
+    def _check_child_to_be_added(self, child: "IntegerTree") -> bool:
+        if not isinstance(child, IntegerTree):
+            raise TypeError("Expected an IntegerTree node")
+        return True
+
+
+def _node_value(node: Tree[Any]) -> int:
+    if not isinstance(node, IntegerTree):
+        raise TypeError("Expected an IntegerTree node")
+    return node.value
+
+
 def _node_name(node: Tree[Any]) -> str:
     if not isinstance(node, (A, B, C)):
         raise TypeError("Expected an A, B, or C node")
@@ -460,6 +478,41 @@ class Test(TreeTestCase):
 
 
 class TreeListRepresentationTestCase(TreeTestCase):
+    def test_create_tree_from_typed_nested_integer_list(self) -> None:
+        representation: TreeNodeListRepresentation[int] = [
+            10,
+            [3, [2, [1], [1]], [1]],
+            [7, [4], [3, [2], [1]]],
+        ]
+        tree = IntegerTree.create_tree_from_list(representation, "value")
+        assert tree.get_list_representation(key=_node_value) == representation
+        assert [node.value for node in tree.traverse()] == [
+            10,
+            3,
+            2,
+            1,
+            1,
+            1,
+            7,
+            4,
+            3,
+            2,
+            1,
+        ]
+
+    def test_create_tree_from_typed_integer_root(self) -> None:
+        representation: TreeNodeListRepresentation[int] = [10]
+        tree = IntegerTree.create_tree_from_list(representation, "value")
+        assert tree.value == 10
+        assert tree.is_leaf
+
+    def test_create_tree_from_list_rejects_scalar_child(self) -> None:
+        representation: TreeNodeListRepresentation[int] = [10, 3]
+        with self.assertRaisesRegex(
+            TypeError, "Each child representation must be a list"
+        ):
+            IntegerTree.create_tree_from_list(representation, "value")
+
     def test_get_list_representation_all(self) -> None:
         assert self.root.get_list_representation(key=_node_name) == [
             "root",

{verysimpletree-2.0.0 → verysimpletree-2.0.2}/verysimpletree/tree.py

@@ -20,7 +20,7 @@ class ChildNotFoundError(TreeException):
 T = TypeVar("T", bound="Tree[Any]")
 
 ValueT = TypeVar("ValueT")
-TreeNode = list[Union[ValueT, "TreeNode[ValueT]"]]
+TreeNodeListRepresentation = list[Union[ValueT, "TreeNodeListRepresentation[ValueT]"]]
 
 
 class Tree(ABC, Generic[T]):
@@ -218,11 +218,10 @@ class Tree(ABC, Generic[T]):
         self._reset_iterators()
         return child
 
-    # typing with T and Generic[T] etc. seems to be faulty. Return value of _create_node is Tree[T].
     @classmethod
     def create_tree_from_list(
         cls,
-        tree_list_representation: list[list[Any]],
+        tree_list_representation: TreeNodeListRepresentation[ValueT],
         represented_attribute_names: str | list[str],
     ) -> T:
         represented_attribute_names = make_list(represented_attribute_names)
@@ -240,6 +239,8 @@ class Tree(ABC, Generic[T]):
 
         node = _create_node(make_list(tree_list_representation[0]))
         for child_list_representation in tree_list_representation[1:]:
+            if not isinstance(child_list_representation, list):
+                raise TypeError("Each child representation must be a list.")
             child = cls.create_tree_from_list(
                 child_list_representation, represented_attribute_names
             )
@@ -500,13 +501,13 @@ class Tree(ABC, Generic[T]):
 
     def get_list_representation(
         self, key: Callable[["Tree[Any]"], ValueT]
-    ) -> TreeNode[ValueT]:
+    ) -> TreeNodeListRepresentation[ValueT]:
         """Return [value, child, ...], applying key to every node.
 
         Mixed-type trees are supported. Callbacks using subclass attributes
         must narrow the node type before accessing those attributes.
         """
-        result: TreeNode[ValueT] = [key(self)]
+        result: TreeNodeListRepresentation[ValueT] = [key(self)]
         for child in self._children:
             result.append(child.get_list_representation(key=key))
         return result