pytreeds 0.1.0__tar.gz

pytreeds-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pytreeds contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytreeds-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: pytreeds
+Version: 0.1.0
+Summary: Beginner-friendly rooted trees with consistent string navigation and traversal
+Author: pytreeds contributors
+License-Expression: MIT
+Project-URL: Source, https://gitlab.com/ujen.teaching/pytreeds
+Project-URL: Issues, https://gitlab.com/ujen.teaching/pytreeds/-/issues
+Keywords: tree,data structures,education,dfs,bfs,pyodide
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Education
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pytreeds
+
+A dependency-free Python library for beginners to create, inspect, modify, traverse, and print **non-binary trees**. Students keep only one tree variable. Node identifiers are unique strings, and all node-related operations return strings rather than mixed types.
+
+## Install
+
+~~~bash
+pip install pytreeds
+~~~
+
+Pyodide (from your platform's asynchronous package loader):
+
+~~~python
+import micropip
+await micropip.install("pytreeds")
+~~~
+
+## First example
+
+~~~python
+from pytreeds import Tree
+
+org = Tree("CEO")
+org.add_nodes(["CTO", "CFO", "COO"], parent="CEO")
+org.add_nodes(["Engineering", "DevOps"], parent="CTO")
+org.add_node("Accounting", parent="CFO")
+
+org.show()
+print(org.height())                # 2 edges
+print(org.size())                  # 6
+print(org.children("CTO"))         # ['Engineering', 'DevOps']
+print(org.parent("DevOps"))        # CTO
+print(org.leaves())
+print(list(org.dfs()))
+print(list(org.bfs()))
+
+for name in org:
+    print(name, "->", org.parent(name))
+~~~
+
+Text diagram:
+
+~~~text
+CEO
+├── CTO
+│   ├── Engineering
+│   └── DevOps
+├── CFO
+│   └── Accounting
+└── COO
+~~~
+
+## API reference
+
+### Build and modify
+
+| API | Description |
+|---|---|
+| Tree(root=None) | Create an empty tree or one with a root |
+| add_node(name, parent=None) | Create one node |
+| add_nodes(names, parent) | Add several children in insertion order |
+| remove_node(name) | Remove a leaf; raises an error for internal nodes |
+| remove_subtree(name) | Remove a whole branch; removing root empties tree |
+| move_node(name, parent) | Move a whole branch under a different parent |
+| rename_node(old, new) | Rename a node without changing its location |
+| copy() | Return an independent copy |
+
+### Properties and relationships
+
+| API | Description |
+|---|---|
+| root | Root name, or None if empty |
+| size() | Total number of nodes |
+| height(name=None) | Height in edges; empty tree = -1 |
+| depth(name) | Number of edges from root; root depth = 0 |
+| leaf_count(name=None) | Number of leaves in tree or subtree |
+| is_leaf(name) | True if the node has no children |
+| contains(name) | True if this name exists |
+| parent(name) | Parent name, or None at root |
+| children(name) | List of child names |
+| siblings(name) | List of sibling names |
+| ancestors(name) | Ancestors from root to parent |
+| descendants(name) | Descendant names in DFS order |
+| leaves(name=None) | Leaf names in DFS order |
+| path(name) | Root-to-node list of names |
+
+### Traversal and search
+
+| API | Description |
+|---|---|
+| dfs(name=None) | Preorder DFS iterator of strings |
+| bfs(name=None) | Level-order BFS iterator of strings |
+| dfs_postorder(name=None) | Postorder DFS iterator of strings |
+| nodes(name=None) | List of names in preorder |
+| find(text) | Names containing a case-sensitive substring |
+| for name in tree | Default preorder DFS |
+
+### Print text
+
+| API | Description |
+|---|---|
+| show(name=None, style="unicode") | Print tree or subtree |
+| to_text(name=None, style="unicode") | Return a diagram string |
+| print(tree) | Print the full diagram |
+
+The style option can also be "ascii".
+
+## Design and errors
+
+- Each node has a unique nonempty string name. No UUIDs, extra node variables, overloaded subscripts, or student-defined classes.
+- Parent, children, leaves, DFS, BFS, and ordinary iteration consistently use strings.
+- The first node is the root. Further additions need a parent.
+- Children and traversals preserve insertion order.
+- Height and depth count edges, not levels.
+- Duplicate names and invalid moves raise ValueError; missing names raise KeyError.
+- Batch insertions validate before modifying the tree.
+- Avoid modifying the tree while looping over a traversal.
+
+## Subtree example
+
+~~~python
+from pytreeds import Tree
+org = Tree("CEO")
+org.add_nodes(["CTO", "CFO"], parent="CEO")
+org.add_node("DevOps", parent="CTO")
+org.move_node("DevOps", parent="CFO")
+org.rename_node("DevOps", "Infrastructure")
+org.show()
+print(org.path("Infrastructure"))
+org.remove_subtree("CFO")
+~~~
+
+Run tests locally using: python -m unittest discover -s tests -v
+
+This repository intentionally keeps the existing publishing-only GitLab CI workflow; there is no testing CI job.

pytreeds-0.1.0/README.md

@@ -0,0 +1,135 @@
+# pytreeds
+
+A dependency-free Python library for beginners to create, inspect, modify, traverse, and print **non-binary trees**. Students keep only one tree variable. Node identifiers are unique strings, and all node-related operations return strings rather than mixed types.
+
+## Install
+
+~~~bash
+pip install pytreeds
+~~~
+
+Pyodide (from your platform's asynchronous package loader):
+
+~~~python
+import micropip
+await micropip.install("pytreeds")
+~~~
+
+## First example
+
+~~~python
+from pytreeds import Tree
+
+org = Tree("CEO")
+org.add_nodes(["CTO", "CFO", "COO"], parent="CEO")
+org.add_nodes(["Engineering", "DevOps"], parent="CTO")
+org.add_node("Accounting", parent="CFO")
+
+org.show()
+print(org.height())                # 2 edges
+print(org.size())                  # 6
+print(org.children("CTO"))         # ['Engineering', 'DevOps']
+print(org.parent("DevOps"))        # CTO
+print(org.leaves())
+print(list(org.dfs()))
+print(list(org.bfs()))
+
+for name in org:
+    print(name, "->", org.parent(name))
+~~~
+
+Text diagram:
+
+~~~text
+CEO
+├── CTO
+│   ├── Engineering
+│   └── DevOps
+├── CFO
+│   └── Accounting
+└── COO
+~~~
+
+## API reference
+
+### Build and modify
+
+| API | Description |
+|---|---|
+| Tree(root=None) | Create an empty tree or one with a root |
+| add_node(name, parent=None) | Create one node |
+| add_nodes(names, parent) | Add several children in insertion order |
+| remove_node(name) | Remove a leaf; raises an error for internal nodes |
+| remove_subtree(name) | Remove a whole branch; removing root empties tree |
+| move_node(name, parent) | Move a whole branch under a different parent |
+| rename_node(old, new) | Rename a node without changing its location |
+| copy() | Return an independent copy |
+
+### Properties and relationships
+
+| API | Description |
+|---|---|
+| root | Root name, or None if empty |
+| size() | Total number of nodes |
+| height(name=None) | Height in edges; empty tree = -1 |
+| depth(name) | Number of edges from root; root depth = 0 |
+| leaf_count(name=None) | Number of leaves in tree or subtree |
+| is_leaf(name) | True if the node has no children |
+| contains(name) | True if this name exists |
+| parent(name) | Parent name, or None at root |
+| children(name) | List of child names |
+| siblings(name) | List of sibling names |
+| ancestors(name) | Ancestors from root to parent |
+| descendants(name) | Descendant names in DFS order |
+| leaves(name=None) | Leaf names in DFS order |
+| path(name) | Root-to-node list of names |
+
+### Traversal and search
+
+| API | Description |
+|---|---|
+| dfs(name=None) | Preorder DFS iterator of strings |
+| bfs(name=None) | Level-order BFS iterator of strings |
+| dfs_postorder(name=None) | Postorder DFS iterator of strings |
+| nodes(name=None) | List of names in preorder |
+| find(text) | Names containing a case-sensitive substring |
+| for name in tree | Default preorder DFS |
+
+### Print text
+
+| API | Description |
+|---|---|
+| show(name=None, style="unicode") | Print tree or subtree |
+| to_text(name=None, style="unicode") | Return a diagram string |
+| print(tree) | Print the full diagram |
+
+The style option can also be "ascii".
+
+## Design and errors
+
+- Each node has a unique nonempty string name. No UUIDs, extra node variables, overloaded subscripts, or student-defined classes.
+- Parent, children, leaves, DFS, BFS, and ordinary iteration consistently use strings.
+- The first node is the root. Further additions need a parent.
+- Children and traversals preserve insertion order.
+- Height and depth count edges, not levels.
+- Duplicate names and invalid moves raise ValueError; missing names raise KeyError.
+- Batch insertions validate before modifying the tree.
+- Avoid modifying the tree while looping over a traversal.
+
+## Subtree example
+
+~~~python
+from pytreeds import Tree
+org = Tree("CEO")
+org.add_nodes(["CTO", "CFO"], parent="CEO")
+org.add_node("DevOps", parent="CTO")
+org.move_node("DevOps", parent="CFO")
+org.rename_node("DevOps", "Infrastructure")
+org.show()
+print(org.path("Infrastructure"))
+org.remove_subtree("CFO")
+~~~
+
+Run tests locally using: python -m unittest discover -s tests -v
+
+This repository intentionally keeps the existing publishing-only GitLab CI workflow; there is no testing CI job.

pytreeds-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pytreeds"
+version = "0.1.0"
+description = "Beginner-friendly rooted trees with consistent string navigation and traversal"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{name = "pytreeds contributors"}]
+keywords = ["tree", "data structures", "education", "dfs", "bfs", "pyodide"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Education",
+  "Programming Language :: Python :: 3",
+  "Topic :: Education",
+]
+[project.urls]
+Source = "https://gitlab.com/ujen.teaching/pytreeds"
+Issues = "https://gitlab.com/ujen.teaching/pytreeds/-/issues"
+[tool.setuptools.packages.find]
+where = ["src"]

pytreeds-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pytreeds-0.1.0/src/pytreeds/__init__.py

@@ -0,0 +1,289 @@
+"""Simple, dependency-free rooted trees for Python beginners."""
+
+from __future__ import annotations
+from collections import deque
+from collections.abc import Iterable, Iterator
+
+__version__ = "0.1.0"
+__all__ = ["Tree"]
+
+
+class Tree:
+    """An ordered tree of uniquely named nodes; all public node values are strings."""
+
+    def __init__(self, root: str | None = None):
+        self._root: str | None = None
+        self._children: dict[str, list[str]] = {}
+        self._parents: dict[str, str | None] = {}
+        if root is not None:
+            self.add_node(root)
+
+    @staticmethod
+    def _check_name(name: str) -> None:
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError("Node names must be non-empty strings")
+
+    def _require(self, name: str) -> None:
+        if name not in self._parents:
+            raise KeyError(f"Node not found: {name!r}")
+
+    @property
+    def root(self) -> str | None:
+        """Return the root name, or None if the tree is empty."""
+        return self._root
+
+    def add_node(self, name: str, parent: str | None = None) -> None:
+        """Add the root to an empty tree or add a child under parent."""
+        self._check_name(name)
+        if name in self._parents:
+            raise ValueError(f"Node already exists: {name!r}")
+        if self._root is None:
+            if parent is not None:
+                raise ValueError("The first node cannot have a parent")
+            self._root = name
+        else:
+            if parent is None:
+                raise ValueError("A parent is required for new non-root nodes")
+            self._require(parent)
+            self._children[parent].append(name)
+        self._children[name] = []
+        self._parents[name] = parent
+
+    def add_nodes(self, names: Iterable[str], parent: str) -> None:
+        """Add several children in order, after validating all names."""
+        self._require(parent)
+        if isinstance(names, (str, bytes)):
+            raise TypeError("Pass a list of node names, not a single string")
+        names = list(names)
+        if any(not isinstance(name, str) or not name.strip() for name in names):
+            raise ValueError("Node names must be non-empty strings")
+        if len(names) != len(set(names)) or any(name in self._parents for name in names):
+            raise ValueError("Node names must be unique within the tree")
+        for name in names:
+            self.add_node(name, parent=parent)
+
+    def contains(self, name: str) -> bool:
+        """Test whether a node exists."""
+        return isinstance(name, str) and name in self._parents
+
+    def __contains__(self, name: str) -> bool:
+        return self.contains(name)
+
+    def size(self) -> int:
+        return len(self._parents)
+
+    def depth(self, name: str) -> int:
+        """Count edges from root to node, starting at zero."""
+        self._require(name)
+        result = 0
+        while self._parents[name] is not None:
+            name = self._parents[name]
+            result += 1
+        return result
+
+    def height(self, name: str | None = None) -> int:
+        """Maximum downward edge count; -1 for an empty tree."""
+        if name is None and self._root is None:
+            return -1
+        name = self._start(name)
+        longest = 0
+        queue = deque([(name, 0)])
+        while queue:
+            current, level = queue.popleft()
+            longest = max(longest, level)
+            queue.extend((child, level + 1) for child in self._children[current])
+        return longest
+
+    def is_leaf(self, name: str) -> bool:
+        self._require(name)
+        return not self._children[name]
+
+    def parent(self, name: str) -> str | None:
+        self._require(name)
+        return self._parents[name]
+
+    def children(self, name: str) -> list[str]:
+        self._require(name)
+        return self._children[name].copy()
+
+    def siblings(self, name: str) -> list[str]:
+        self._require(name)
+        parent = self._parents[name]
+        return [] if parent is None else [child for child in self._children[parent] if child != name]
+
+    def ancestors(self, name: str) -> list[str]:
+        """Return ancestors from root to parent, excluding the node."""
+        self._require(name)
+        result = []
+        parent = self._parents[name]
+        while parent is not None:
+            result.append(parent)
+            parent = self._parents[parent]
+        return result[::-1]
+
+    def path(self, name: str) -> list[str]:
+        return self.ancestors(name) + [name]
+
+    def _start(self, name: str | None) -> str | None:
+        if name is not None:
+            self._require(name)
+            return name
+        return self._root
+
+    def dfs(self, name: str | None = None) -> Iterator[str]:
+        """Yield names using preorder depth-first traversal."""
+        start = self._start(name)
+        if start is None:
+            return
+        stack = [start]
+        while stack:
+            current = stack.pop()
+            yield current
+            stack.extend(reversed(self._children[current]))
+
+    def bfs(self, name: str | None = None) -> Iterator[str]:
+        """Yield names in breadth-first (level) order."""
+        start = self._start(name)
+        if start is None:
+            return
+        queue = deque([start])
+        while queue:
+            current = queue.popleft()
+            yield current
+            queue.extend(self._children[current])
+
+    def dfs_postorder(self, name: str | None = None) -> Iterator[str]:
+        """Yield names using depth-first postorder traversal."""
+        start = self._start(name)
+        if start is None:
+            return
+        stack = [(start, False)]
+        while stack:
+            current, ready = stack.pop()
+            if ready:
+                yield current
+            else:
+                stack.append((current, True))
+                stack.extend((child, False) for child in reversed(self._children[current]))
+
+    def __iter__(self) -> Iterator[str]:
+        return self.dfs()
+
+    def nodes(self, name: str | None = None) -> list[str]:
+        return list(self.dfs(name))
+
+    def descendants(self, name: str) -> list[str]:
+        self._require(name)
+        iterator = self.dfs(name)
+        next(iterator)
+        return list(iterator)
+
+    def leaves(self, name: str | None = None) -> list[str]:
+        return [node for node in self.dfs(name) if not self._children[node]]
+
+    def leaf_count(self, name: str | None = None) -> int:
+        return len(self.leaves(name))
+
+    def find(self, text: str) -> list[str]:
+        """Find names containing the given case-sensitive substring."""
+        if not isinstance(text, str):
+            raise TypeError("Search text must be a string")
+        return [name for name in self if text in name]
+
+    def remove_node(self, name: str) -> None:
+        """Remove a leaf; use remove_subtree() to remove a branch."""
+        self._require(name)
+        if self._children[name]:
+            raise ValueError("Node has children; use remove_subtree()")
+        parent = self._parents[name]
+        if parent is None:
+            self._root = None
+        else:
+            self._children[parent].remove(name)
+        del self._parents[name]
+        del self._children[name]
+
+    def remove_subtree(self, name: str) -> None:
+        """Remove a node and all descendants. Removing root empties tree."""
+        self._require(name)
+        parent = self._parents[name]
+        if parent is None:
+            self._root = None
+        else:
+            self._children[parent].remove(name)
+        for node in list(self.dfs(name)):
+            del self._parents[node]
+            del self._children[node]
+
+    def move_node(self, name: str, parent: str) -> None:
+        """Move a whole subtree, appending it to the new parent's children."""
+        self._require(name)
+        self._require(parent)
+        if name == self._root:
+            raise ValueError("Cannot move the root")
+        if parent == name or parent in self.descendants(name):
+            raise ValueError("Cannot move a node below itself or its descendants")
+        old_parent = self._parents[name]
+        self._children[old_parent].remove(name)
+        self._children[parent].append(name)
+        self._parents[name] = parent
+
+    def rename_node(self, old: str, new: str) -> None:
+        """Change a node name without changing its location."""
+        self._require(old)
+        self._check_name(new)
+        if new in self._parents:
+            raise ValueError(f"Node already exists: {new!r}")
+        parent = self._parents.pop(old)
+        children = self._children.pop(old)
+        self._parents[new] = parent
+        self._children[new] = children
+        if parent is None:
+            self._root = new
+        else:
+            siblings = self._children[parent]
+            siblings[siblings.index(old)] = new
+        for child in children:
+            self._parents[child] = new
+
+    def copy(self) -> Tree:
+        """Return an independent copy."""
+        other = Tree()
+        other._root = self._root
+        other._parents = self._parents.copy()
+        other._children = {name: children.copy() for name, children in self._children.items()}
+        return other
+
+    def to_text(self, name: str | None = None, style: str = "unicode") -> str:
+        """Return an indented Unicode or ASCII branch diagram."""
+        if style not in ("unicode", "ascii"):
+            raise ValueError("style must be 'unicode' or 'ascii'")
+        start = self._start(name)
+        if start is None:
+            return "(empty tree)"
+        if style == "unicode":
+            branch, last_branch, middle, blank = "├── ", "└── ", "│   ", "    "
+        else:
+            branch, last_branch, middle, blank = "|-- ", chr(96) + "-- ", "|   ", "    "
+        lines = [start]
+        stack = []
+        children = self._children[start]
+        for i in range(len(children) - 1, -1, -1):
+            stack.append((children[i], "", i == len(children) - 1))
+        while stack:
+            current, prefix, is_last = stack.pop()
+            lines.append(prefix + (last_branch if is_last else branch) + current)
+            next_prefix = prefix + (blank if is_last else middle)
+            children = self._children[current]
+            for i in range(len(children) - 1, -1, -1):
+                stack.append((children[i], next_prefix, i == len(children) - 1))
+        return "\n".join(lines)
+
+    def show(self, name: str | None = None, style: str = "unicode") -> None:
+        print(self.to_text(name, style=style))
+
+    def __str__(self) -> str:
+        return self.to_text()
+
+    def __repr__(self) -> str:
+        return f"Tree(root={self._root!r}, size={self.size()})"

pytreeds-0.1.0/src/pytreeds.egg-info/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: pytreeds
+Version: 0.1.0
+Summary: Beginner-friendly rooted trees with consistent string navigation and traversal
+Author: pytreeds contributors
+License-Expression: MIT
+Project-URL: Source, https://gitlab.com/ujen.teaching/pytreeds
+Project-URL: Issues, https://gitlab.com/ujen.teaching/pytreeds/-/issues
+Keywords: tree,data structures,education,dfs,bfs,pyodide
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Education
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pytreeds
+
+A dependency-free Python library for beginners to create, inspect, modify, traverse, and print **non-binary trees**. Students keep only one tree variable. Node identifiers are unique strings, and all node-related operations return strings rather than mixed types.
+
+## Install
+
+~~~bash
+pip install pytreeds
+~~~
+
+Pyodide (from your platform's asynchronous package loader):
+
+~~~python
+import micropip
+await micropip.install("pytreeds")
+~~~
+
+## First example
+
+~~~python
+from pytreeds import Tree
+
+org = Tree("CEO")
+org.add_nodes(["CTO", "CFO", "COO"], parent="CEO")
+org.add_nodes(["Engineering", "DevOps"], parent="CTO")
+org.add_node("Accounting", parent="CFO")
+
+org.show()
+print(org.height())                # 2 edges
+print(org.size())                  # 6
+print(org.children("CTO"))         # ['Engineering', 'DevOps']
+print(org.parent("DevOps"))        # CTO
+print(org.leaves())
+print(list(org.dfs()))
+print(list(org.bfs()))
+
+for name in org:
+    print(name, "->", org.parent(name))
+~~~
+
+Text diagram:
+
+~~~text
+CEO
+├── CTO
+│   ├── Engineering
+│   └── DevOps
+├── CFO
+│   └── Accounting
+└── COO
+~~~
+
+## API reference
+
+### Build and modify
+
+| API | Description |
+|---|---|
+| Tree(root=None) | Create an empty tree or one with a root |
+| add_node(name, parent=None) | Create one node |
+| add_nodes(names, parent) | Add several children in insertion order |
+| remove_node(name) | Remove a leaf; raises an error for internal nodes |
+| remove_subtree(name) | Remove a whole branch; removing root empties tree |
+| move_node(name, parent) | Move a whole branch under a different parent |
+| rename_node(old, new) | Rename a node without changing its location |
+| copy() | Return an independent copy |
+
+### Properties and relationships
+
+| API | Description |
+|---|---|
+| root | Root name, or None if empty |
+| size() | Total number of nodes |
+| height(name=None) | Height in edges; empty tree = -1 |
+| depth(name) | Number of edges from root; root depth = 0 |
+| leaf_count(name=None) | Number of leaves in tree or subtree |
+| is_leaf(name) | True if the node has no children |
+| contains(name) | True if this name exists |
+| parent(name) | Parent name, or None at root |
+| children(name) | List of child names |
+| siblings(name) | List of sibling names |
+| ancestors(name) | Ancestors from root to parent |
+| descendants(name) | Descendant names in DFS order |
+| leaves(name=None) | Leaf names in DFS order |
+| path(name) | Root-to-node list of names |
+
+### Traversal and search
+
+| API | Description |
+|---|---|
+| dfs(name=None) | Preorder DFS iterator of strings |
+| bfs(name=None) | Level-order BFS iterator of strings |
+| dfs_postorder(name=None) | Postorder DFS iterator of strings |
+| nodes(name=None) | List of names in preorder |
+| find(text) | Names containing a case-sensitive substring |
+| for name in tree | Default preorder DFS |
+
+### Print text
+
+| API | Description |
+|---|---|
+| show(name=None, style="unicode") | Print tree or subtree |
+| to_text(name=None, style="unicode") | Return a diagram string |
+| print(tree) | Print the full diagram |
+
+The style option can also be "ascii".
+
+## Design and errors
+
+- Each node has a unique nonempty string name. No UUIDs, extra node variables, overloaded subscripts, or student-defined classes.
+- Parent, children, leaves, DFS, BFS, and ordinary iteration consistently use strings.
+- The first node is the root. Further additions need a parent.
+- Children and traversals preserve insertion order.
+- Height and depth count edges, not levels.
+- Duplicate names and invalid moves raise ValueError; missing names raise KeyError.
+- Batch insertions validate before modifying the tree.
+- Avoid modifying the tree while looping over a traversal.
+
+## Subtree example
+
+~~~python
+from pytreeds import Tree
+org = Tree("CEO")
+org.add_nodes(["CTO", "CFO"], parent="CEO")
+org.add_node("DevOps", parent="CTO")
+org.move_node("DevOps", parent="CFO")
+org.rename_node("DevOps", "Infrastructure")
+org.show()
+print(org.path("Infrastructure"))
+org.remove_subtree("CFO")
+~~~
+
+Run tests locally using: python -m unittest discover -s tests -v
+
+This repository intentionally keeps the existing publishing-only GitLab CI workflow; there is no testing CI job.

pytreeds-0.1.0/src/pytreeds.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+src/pytreeds/__init__.py
+src/pytreeds.egg-info/PKG-INFO
+src/pytreeds.egg-info/SOURCES.txt
+src/pytreeds.egg-info/dependency_links.txt
+src/pytreeds.egg-info/top_level.txt
+tests/test_tree.py

pytreeds-0.1.0/src/pytreeds.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pytreeds-0.1.0/src/pytreeds.egg-info/top_level.txt

@@ -0,0 +1 @@
+pytreeds

pytreeds-0.1.0/tests/test_tree.py

@@ -0,0 +1,101 @@
+import io
+import unittest
+from contextlib import redirect_stdout
+from pytreeds import Tree
+
+
+class TestTree(unittest.TestCase):
+    def setUp(self):
+        self.t = Tree("A")
+        self.t.add_nodes(["B", "C", "D"], parent="A")
+        self.t.add_nodes(["E", "F", "G"], parent="B")
+        self.t.add_nodes(["H", "I"], parent="C")
+
+    def test_properties(self):
+        t = self.t
+        self.assertEqual(t.size(), 9)
+        self.assertEqual(t.height(), 2)
+        self.assertEqual(t.height("B"), 1)
+        self.assertEqual(t.depth("G"), 2)
+        self.assertEqual(t.parent("G"), "B")
+        self.assertEqual(t.children("B"), ["E", "F", "G"])
+        self.assertEqual(t.siblings("B"), ["C", "D"])
+        self.assertEqual(t.ancestors("G"), ["A", "B"])
+        self.assertEqual(t.path("G"), ["A", "B", "G"])
+        self.assertEqual(t.descendants("B"), ["E", "F", "G"])
+        self.assertEqual(t.leaves(), ["E", "F", "G", "H", "I", "D"])
+        self.assertEqual(t.leaf_count(), 6)
+        self.assertTrue(t.is_leaf("G"))
+        self.assertFalse(t.is_leaf("B"))
+
+    def test_traversal(self):
+        self.assertEqual(list(self.t.dfs()), ["A", "B", "E", "F", "G", "C", "H", "I", "D"])
+        self.assertEqual(list(self.t.bfs()), ["A", "B", "C", "D", "E", "F", "G", "H", "I"])
+        self.assertEqual(list(self.t.dfs_postorder()), ["E", "F", "G", "B", "H", "I", "C", "D", "A"])
+        self.assertEqual(list(self.t), list(self.t.dfs()))
+        self.assertEqual(list(self.t.bfs("C")), ["C", "H", "I"])
+        self.assertEqual(self.t.nodes("B"), ["B", "E", "F", "G"])
+        self.assertEqual(self.t.find("G"), ["G"])
+
+    def test_changes(self):
+        t = self.t
+        with self.assertRaises(ValueError):
+            t.move_node("B", "F")
+        with self.assertRaises(ValueError):
+            t.remove_node("B")
+        t.move_node("F", "C")
+        t.rename_node("C", "X")
+        self.assertEqual(t.path("F"), ["A", "X", "F"])
+        t.remove_node("I")
+        t.remove_subtree("B")
+        self.assertFalse(t.contains("B"))
+        self.assertFalse(t.contains("E"))
+        self.assertTrue(t.contains("X"))
+
+    def test_invalid_and_copy(self):
+        with self.assertRaises(ValueError):
+            self.t.add_node("A", parent="B")
+        with self.assertRaises(KeyError):
+            self.t.add_node("Z", parent="missing")
+        with self.assertRaises(ValueError):
+            self.t.add_nodes(["new", "C"], parent="B")
+        self.assertFalse(self.t.contains("new"))
+        with self.assertRaises(TypeError):
+            self.t.add_nodes("xyz", parent="B")
+        copied = self.t.copy()
+        copied.rename_node("A", "ROOT")
+        self.assertEqual(self.t.root, "A")
+        self.assertEqual(copied.root, "ROOT")
+
+    def test_text(self):
+        expected = "A\n├── B\n│   ├── E\n│   ├── F\n│   └── G\n├── C\n│   ├── H\n│   └── I\n└── D"
+        self.assertEqual(self.t.to_text(), expected)
+        self.assertEqual(self.t.to_text("B"), "B\n├── E\n├── F\n└── G")
+        self.assertIn(chr(96) + "-- D", self.t.to_text(style="ascii"))
+        with io.StringIO() as output, redirect_stdout(output):
+            self.t.show("C")
+            self.assertEqual(output.getvalue(), "C\n├── H\n└── I\n")
+
+    def test_empty(self):
+        t = Tree()
+        self.assertEqual(t.height(), -1)
+        self.assertEqual(list(t.dfs()), [])
+        self.assertEqual(list(t.bfs()), [])
+        self.assertEqual(list(t.dfs_postorder()), [])
+        t.add_node("A")
+        t.remove_node("A")
+        self.assertIsNone(t.root)
+        self.t.remove_subtree("A")
+        self.assertEqual(self.t.size(), 0)
+
+    def test_deep(self):
+        t = Tree("0")
+        for n in range(1, 1200):
+            t.add_node(str(n), parent=str(n - 1))
+        self.assertEqual(t.height(), 1199)
+        self.assertEqual(len(t.to_text().splitlines()), 1200)
+        self.assertEqual(len(list(t.dfs_postorder())), 1200)
+
+
+if __name__ == "__main__":
+    unittest.main()