stepps 0.2.0__tar.gz → 0.3.0__tar.gz

{stepps-0.2.0 → stepps-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stepps
-Version: 0.2.0
+Version: 0.3.0
 Summary: Useful algorithms in Python
 Author-email: Suhas Krishna Srivastava <suhas.srivastava@vaastav.tech>, Trinay Mitra <trinay.mitra@vaastav.tech>
 Maintainer-email: Suhas Krishna Srivastava <suhas.srivastava@vaastav.tech>

{stepps-0.2.0 → stepps-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stepps"
-version = "0.2.0"
+version = "0.3.0"
 description = "Useful algorithms in Python"
 requires-python = ">=3.12"
 readme = "README.md"

stepps-0.3.0/src/stepps/tree_builder/__init__.py

@@ -0,0 +1,21 @@
+from stepps.tree_builder.inorder_tree_builder import InOrderTreeBuilder
+from stepps.tree_builder.inorder_tree_builder_impl import InOrderTreeBuilderImpl
+from stepps.tree_builder.level_order_tree_builder import LevelOrderTreeBuilder
+from stepps.tree_builder.level_order_tree_builder_impl import LevelOrderTreeBuilderImpl
+from stepps.tree_builder.postorder_tree_builder import PostOrderTreeBuilder
+from stepps.tree_builder.postorder_tree_builder_impl import PostOrderTreeBuilderImpl
+from stepps.tree_builder.preorder_tree_builder import PreOrderTreeBuilder
+from stepps.tree_builder.preorder_tree_builder_impl import PreOrderTreeBuilderImpl
+from stepps.tree_builder.tree_builder import TreeBuilder
+
+__all__ = [
+    "InOrderTreeBuilder",
+    "InOrderTreeBuilderImpl",
+    "LevelOrderTreeBuilder",
+    "LevelOrderTreeBuilderImpl",
+    "PostOrderTreeBuilder",
+    "PostOrderTreeBuilderImpl",
+    "PreOrderTreeBuilder",
+    "PreOrderTreeBuilderImpl",
+    "TreeBuilder",
+]

stepps-0.3.0/src/stepps/tree_builder/inorder_tree_builder.py

@@ -0,0 +1,10 @@
+from typing import Protocol
+
+from stepps.tree_builder.tree_builder import TreeBuilder
+
+
+class InOrderTreeBuilder[T](TreeBuilder[T], Protocol):
+    """
+    Define the interface for building a binary tree from a sequence
+    using inorder traversal.
+    """

{stepps-0.2.0/src/stepps/TreeBuilder → stepps-0.3.0/src/stepps/tree_builder}/inorder_tree_builder_impl.py

@@ -2,7 +2,7 @@ from collections.abc import Sequence
 from typing import override
 
 from stepps.nodes import BinaryNode
-from stepps.TreeBuilder.inorder_tree_builder import InOrderTreeBuilder
+from stepps.tree_builder.inorder_tree_builder import InOrderTreeBuilder
 
 
 class InOrderTreeBuilderImpl[T](InOrderTreeBuilder[T]):

stepps-0.3.0/src/stepps/tree_builder/level_order_tree_builder.py

@@ -0,0 +1,10 @@
+from typing import Protocol
+
+from stepps.tree_builder.tree_builder import TreeBuilder
+
+
+class LevelOrderTreeBuilder[T](TreeBuilder[T], Protocol):
+    """
+    Define the interface for building a binary tree from a sequence
+    using level-order traversal.
+    """

{stepps-0.2.0/src/stepps/TreeBuilder → stepps-0.3.0/src/stepps/tree_builder}/level_order_tree_builder_impl.py

@@ -3,7 +3,7 @@ from collections.abc import Sequence
 from typing import override
 
 from stepps.nodes import BinaryNode
-from stepps.TreeBuilder.level_order_tree_builder import LevelOrderTreeBuilder
+from stepps.tree_builder.level_order_tree_builder import LevelOrderTreeBuilder
 
 
 class LevelOrderTreeBuilderImpl[T](LevelOrderTreeBuilder[T]):

stepps-0.3.0/src/stepps/tree_builder/postorder_tree_builder.py

@@ -0,0 +1,10 @@
+from typing import Protocol
+
+from stepps.tree_builder.tree_builder import TreeBuilder
+
+
+class PostOrderTreeBuilder[T](TreeBuilder[T], Protocol):
+    """
+    Define the interface for building a binary tree from a sequence
+    using postorder traversal.
+    """

{stepps-0.2.0/src/stepps/TreeBuilder → stepps-0.3.0/src/stepps/tree_builder}/postorder_tree_builder_impl.py

@@ -2,7 +2,7 @@ from collections.abc import Sequence
 from typing import override
 
 from stepps.nodes import BinaryNode
-from stepps.TreeBuilder.postorder_tree_builder import PostOrderTreeBuilder
+from stepps.tree_builder.postorder_tree_builder import PostOrderTreeBuilder
 
 
 class PostOrderTreeBuilderImpl[T](PostOrderTreeBuilder[T]):

stepps-0.3.0/src/stepps/tree_builder/preorder_tree_builder.py

@@ -0,0 +1,10 @@
+from typing import Protocol
+
+from stepps.tree_builder.tree_builder import TreeBuilder
+
+
+class PreOrderTreeBuilder[T](TreeBuilder[T], Protocol):
+    """
+    Define the interface for building a binary tree from a sequence
+    using preorder traversal.
+    """

{stepps-0.2.0/src/stepps/TreeBuilder → stepps-0.3.0/src/stepps/tree_builder}/preorder_tree_builder_impl.py

@@ -2,7 +2,7 @@ from collections.abc import Sequence
 from typing import override
 
 from stepps.nodes import BinaryNode
-from stepps.TreeBuilder.preorder_tree_builder import PreOrderTreeBuilder
+from stepps.tree_builder.preorder_tree_builder import PreOrderTreeBuilder
 
 
 class PreOrderTreeBuilderImpl[T](PreOrderTreeBuilder[T]):

{stepps-0.2.0/src/stepps/TreeBuilder → stepps-0.3.0/src/stepps/tree_builder}/tree_builder.py

@@ -1,10 +1,11 @@
-from abc import ABC, abstractmethod
+from abc import abstractmethod
 from collections.abc import Sequence
+from typing import Protocol
 
 from stepps.nodes import BinaryNode
 
 
-class TreeBuilder[T](ABC):
+class TreeBuilder[T](Protocol):
     """
     Define the interface for building a binary tree from a sequence.
     """

stepps-0.3.0/src/stepps/trees/balanced/__init__.py

@@ -0,0 +1,4 @@
+from stepps.trees.balanced.avl import AVL
+from stepps.trees.balanced.avl_impl import AVLImpl
+
+__all__ = ["AVL", "AVLImpl"]

stepps-0.3.0/src/stepps/trees/balanced/avl.py

@@ -0,0 +1,19 @@
+from abc import abstractmethod
+from typing import Protocol
+
+from stepps.trees.binary_tree import BinaryTree
+
+
+class AVL[T](BinaryTree[T], Protocol):
+    """
+    Define the interface for balancing a binary tree.
+    """
+
+    @abstractmethod
+    def balance(self) -> BinaryTree[T]:
+        """
+        Balance the binary tree.
+
+        :return: The balanced binary tree.
+        """
+        ...

stepps-0.3.0/src/stepps/trees/balanced/avl_impl.py

@@ -0,0 +1,245 @@
+from typing import override
+
+from stepps.nodes import BinaryNode
+from stepps.trees.balanced.avl import AVL
+from stepps.trees.binary_tree import BinaryTree
+
+
+class AVLImpl[T](AVL[T]):
+    """
+    Provide the default implementation for balancing a binary tree using AVL
+    rotations.
+    """
+
+    def __init__(
+        self,
+        tree: BinaryTree[T],
+        balance_factor: int = 1,
+    ) -> None:
+        self.tree = tree
+        self.balance_factor = balance_factor
+
+    @override
+    def balance(self) -> BinaryTree[T]:
+        """
+        Balance the tree using AVL rotations.
+
+        :return: The balanced tree.
+        """
+        self.tree = self._balance(self.tree)
+        return self.tree
+
+    def insert(self, value: T) -> BinaryNode[T]:
+        """
+        Insert a value into the tree and balance it.
+
+        :param value: The value to insert.
+        :return: The inserted node.
+        """
+        node = self.tree.insert(value)
+        self.balance()
+        return node
+
+    def delete(self, value: T) -> bool:
+        """
+        Delete a value from the tree and balance it.
+
+        :param value: The value to delete.
+        :return: True if the value was deleted, otherwise False.
+        """
+        deleted = self.tree.delete(value)
+        self.balance()
+        return deleted
+
+    def find(self, value: T) -> BinaryNode[T] | None:
+        """
+        Find a value in the tree.
+
+        :param value: The value to find.
+        :return: The node containing the value, or None if not found.
+        """
+        return self.tree.find(value)
+
+    def contains(self, value: T) -> bool:
+        """
+        Check whether the tree contains a value.
+
+        :param value: The value to check.
+        :return: True if the value exists, otherwise False.
+        """
+        return self.tree.contains(value)
+
+    def __contains__(self, value: T) -> bool:
+        return value in self.tree
+
+    def height(self) -> int:
+        """
+        Return the height of the tree.
+
+        :return: The tree height.
+        """
+        return self.tree.height()
+
+    def count_leaves(self) -> int:
+        """
+        Count the leaf nodes in the tree.
+
+        :return: The number of leaf nodes.
+        """
+        return self.tree.count_leaves()
+
+    def count_internal_nodes(self) -> int:
+        """
+        Count the internal nodes in the tree.
+
+        :return: The number of internal nodes.
+        """
+        return self.tree.count_internal_nodes()
+
+    def get_root(self) -> BinaryNode[T] | None:
+        """
+        Return the root node.
+
+        :return: The root node, or None if the tree is empty.
+        """
+        return self.tree.get_root()
+
+    def get_left_subtree(self) -> BinaryTree[T]:
+        """
+        Return the left subtree.
+
+        :return: The left subtree.
+        """
+        return self.tree.get_left_subtree()
+
+    def get_right_subtree(self) -> BinaryTree[T]:
+        """
+        Return the right subtree.
+
+        :return: The right subtree.
+        """
+        return self.tree.get_right_subtree()
+
+    def _set_left_subtree(self, subtree: BinaryTree[T]) -> None:
+        """
+        Set the left subtree.
+
+        :param subtree: The tree to use as the left subtree.
+        """
+        self.tree._set_left_subtree(subtree)
+
+    def _set_right_subtree(self, subtree: BinaryTree[T]) -> None:
+        """
+        Set the right subtree.
+
+        :param subtree: The tree to use as the right subtree.
+        """
+        self.tree._set_right_subtree(subtree)
+
+    def right_rotate(self) -> BinaryTree[T]:
+        """
+        Perform a right rotation.
+
+        :return: The tree after the rotation.
+        """
+        self.tree = self.tree.right_rotate()
+        return self.tree
+
+    def left_rotate(self) -> BinaryTree[T]:
+        """
+        Perform a left rotation.
+
+        :return: The tree after the rotation.
+        """
+        self.tree = self.tree.left_rotate()
+        return self.tree
+
+    def invert_tree(self) -> None:
+        """
+        Invert the tree.
+        """
+        self.tree.invert_tree()
+
+    def is_empty(self) -> bool:
+        """
+        Check whether the tree is empty.
+
+        :return: True if the tree is empty, otherwise False.
+        """
+        return self.tree.is_empty()
+
+    def clear(self) -> None:
+        """
+        Clear the tree.
+        """
+        self.tree.clear()
+
+    def size(self) -> int:
+        """
+        Return the number of nodes in the tree.
+
+        :return: The tree size.
+        """
+        return self.tree.size()
+
+    def __len__(self) -> int:
+        return len(self.tree)
+
+    def __bool__(self) -> bool:
+        return bool(self.tree)
+
+    def _balance(self, tree: BinaryTree[T]) -> BinaryTree[T]:
+        """
+        Recursively balance the given tree.
+
+        :param tree: The tree to balance.
+        :return: The balanced tree.
+        """
+        if tree.is_empty():
+            return tree
+
+        left_subtree = self._balance(tree.get_left_subtree())
+        right_subtree = self._balance(tree.get_right_subtree())
+
+        tree._set_left_subtree(left_subtree)
+        tree._set_right_subtree(right_subtree)
+
+        return self._rebalance(tree)
+
+    def _rebalance(self, tree: BinaryTree[T]) -> BinaryTree[T]:
+        """
+        Rebalance the given tree if it violates the AVL balance condition.
+
+        :param tree: The tree to rebalance.
+        :return: The rebalanced tree.
+        """
+        balance_factor = self._calculate_balance_factor(tree)
+
+        if balance_factor > self.balance_factor:
+            left_subtree = tree.get_left_subtree()
+
+            if self._calculate_balance_factor(left_subtree) < 0:
+                left_subtree.left_rotate()
+                tree._set_left_subtree(left_subtree)
+
+            return tree.right_rotate()
+
+        if balance_factor < -self.balance_factor:
+            right_subtree = tree.get_right_subtree()
+
+            if self._calculate_balance_factor(right_subtree) > 0:
+                right_subtree.right_rotate()
+                tree._set_right_subtree(right_subtree)
+
+            return tree.left_rotate()
+
+        return tree
+
+    def _calculate_balance_factor(self, tree: BinaryTree[T]) -> int:
+        """
+        Return the AVL balance factor of the tree.
+
+        :param tree: The tree whose balance factor is calculated.
+        :return: The height difference between the left and right subtrees.
+        """
+        return tree.get_left_subtree().height() - tree.get_right_subtree().height()

{stepps-0.2.0 → stepps-0.3.0}/src/stepps/trees/binary_tree.py

@@ -1,10 +1,11 @@
 from abc import abstractmethod
+from typing import Protocol
 
 from stepps.nodes import BinaryNode
 from stepps.trees.tree import Tree
 
 
-class BinaryTree[T](Tree[T]):
+class BinaryTree[T](Tree[T], Protocol):
     """
     Define the interface for binary tree implementations.
     """
@@ -116,19 +117,39 @@ class BinaryTree[T](Tree[T]):
         ...
 
     @abstractmethod
-    def right_rotate(self) -> "BinaryTree[T] | None":
+    def right_rotate(self) -> "BinaryTree[T]":
         """
         Perform a right rotation on the tree.
 
-        :return: The new root node after the rotation.
+        :return: The tree after the rotation.
         """
         ...
 
     @abstractmethod
-    def left_rotate(self) -> "BinaryTree[T] | None":
+    def left_rotate(self) -> "BinaryTree[T]":
         """
         Perform a left rotation on the tree.
 
-        :return: The new root node after the rotation.
+        :return: The tree after the rotation.
+        """
+        ...
+
+    @abstractmethod
+    def _set_left_subtree(self, subtree: "BinaryTree[T]") -> None:
+        """
+        Set the left subtree.
+
+        :param subtree: The tree to use as the left subtree.
+        :return: ``None``.
+        """
+        ...
+
+    @abstractmethod
+    def _set_right_subtree(self, subtree: "BinaryTree[T]") -> None:
+        """
+        Set the right subtree.
+
+        :param subtree: The tree to use as the right subtree.
+        :return: ``None``.
         """
         ...

{stepps-0.2.0 → stepps-0.3.0}/src/stepps/trees/binary_tree_impl.py

@@ -305,3 +305,27 @@ class BinaryTreeImpl[T](BinaryTree[T]):
         self.root = new_root
 
         return self
+
+    @override
+    def _set_left_subtree(self, subtree: BinaryTree[T]) -> None:
+        """
+        Set the left subtree.
+
+        :param subtree: The tree to use as the left subtree.
+        """
+        if self.root is None:
+            return
+
+        self.root.left = subtree.get_root()
+
+    @override
+    def _set_right_subtree(self, subtree: BinaryTree[T]) -> None:
+        """
+        Set the right subtree.
+
+        :param subtree: The tree to use as the right subtree.
+        """
+        if self.root is None:
+            return
+
+        self.root.right = subtree.get_root()

{stepps-0.2.0 → stepps-0.3.0}/src/stepps/trees/bst.py

@@ -15,7 +15,7 @@ class Comparable(Protocol):
     def __gt__(self, other: object, /) -> bool: ...
 
 
-class BST[T: Comparable](BinaryTree[T]):
+class BST[T: Comparable](BinaryTree[T], Protocol):
     """
     Define the interface for binary search tree implementations.
 

{stepps-0.2.0 → stepps-0.3.0}/src/stepps/trees/tree.py

@@ -1,9 +1,10 @@
-from abc import ABC, abstractmethod
+from abc import abstractmethod
+from typing import Protocol
 
 from stepps.nodes import BinaryNode
 
 
-class Tree[T](ABC):
+class Tree[T](Protocol):
     """
     Define the common interface for tree implementations.
     """

{stepps-0.2.0 → stepps-0.3.0}/src/stepps/visualizer/cli_visualizer.py

@@ -1,10 +1,11 @@
 from abc import abstractmethod
+from typing import Protocol
 
 from stepps.nodes import BinaryNode
 from stepps.visualizer.tree_visualizer import TreeVisualizer
 
 
-class CliTreeVisualizer[T](TreeVisualizer[BinaryNode[T] | None]):
+class CliTreeVisualizer[T](TreeVisualizer[BinaryNode[T] | None], Protocol):
     """
     Define the interface for CLI-based binary tree visualization.
     """

{stepps-0.2.0 → stepps-0.3.0}/src/stepps/visualizer/tree_visualizer.py

@@ -1,7 +1,8 @@
-from abc import ABC, abstractmethod
+from abc import abstractmethod
+from typing import Protocol
 
 
-class TreeVisualizer[T](ABC):
+class TreeVisualizer[T](Protocol):
     """
     Define the interface for tree visualization.
     """

{stepps-0.2.0 → stepps-0.3.0}/src/stepps.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stepps
-Version: 0.2.0
+Version: 0.3.0
 Summary: Useful algorithms in Python
 Author-email: Suhas Krishna Srivastava <suhas.srivastava@vaastav.tech>, Trinay Mitra <trinay.mitra@vaastav.tech>
 Maintainer-email: Suhas Krishna Srivastava <suhas.srivastava@vaastav.tech>

{stepps-0.2.0 → stepps-0.3.0}/src/stepps.egg-info/SOURCES.txt

@@ -7,16 +7,6 @@ src/stepps.egg-info/PKG-INFO
 src/stepps.egg-info/SOURCES.txt
 src/stepps.egg-info/dependency_links.txt
 src/stepps.egg-info/top_level.txt
-src/stepps/TreeBuilder/__init__.py
-src/stepps/TreeBuilder/inorder_tree_builder.py
-src/stepps/TreeBuilder/inorder_tree_builder_impl.py
-src/stepps/TreeBuilder/level_order_tree_builder.py
-src/stepps/TreeBuilder/level_order_tree_builder_impl.py
-src/stepps/TreeBuilder/postorder_tree_builder.py
-src/stepps/TreeBuilder/postorder_tree_builder_impl.py
-src/stepps/TreeBuilder/preorder_tree_builder.py
-src/stepps/TreeBuilder/preorder_tree_builder_impl.py
-src/stepps/TreeBuilder/tree_builder.py
 src/stepps/iterators/__init__.py
 src/stepps/iterators/base_iterator.py
 src/stepps/iterators/inorder.py
@@ -25,16 +15,30 @@ src/stepps/iterators/postorder.py
 src/stepps/iterators/preorder.py
 src/stepps/nodes/__init__.py
 src/stepps/nodes/binary_node.py
+src/stepps/tree_builder/__init__.py
+src/stepps/tree_builder/inorder_tree_builder.py
+src/stepps/tree_builder/inorder_tree_builder_impl.py
+src/stepps/tree_builder/level_order_tree_builder.py
+src/stepps/tree_builder/level_order_tree_builder_impl.py
+src/stepps/tree_builder/postorder_tree_builder.py
+src/stepps/tree_builder/postorder_tree_builder_impl.py
+src/stepps/tree_builder/preorder_tree_builder.py
+src/stepps/tree_builder/preorder_tree_builder_impl.py
+src/stepps/tree_builder/tree_builder.py
 src/stepps/trees/__init__.py
 src/stepps/trees/binary_tree.py
 src/stepps/trees/binary_tree_impl.py
 src/stepps/trees/bst.py
 src/stepps/trees/bst_impl.py
 src/stepps/trees/tree.py
+src/stepps/trees/balanced/__init__.py
+src/stepps/trees/balanced/avl.py
+src/stepps/trees/balanced/avl_impl.py
 src/stepps/visualizer/__init__.py
 src/stepps/visualizer/cli_visualizer.py
 src/stepps/visualizer/cli_visualizer_impl.py
 src/stepps/visualizer/tree_visualizer.py
+tests/test_avl.py
 tests/test_binary_tree.py
 tests/test_bst.py
 tests/test_inorder_tree_builder.py

stepps-0.3.0/tests/test_avl.py

@@ -0,0 +1,368 @@
+from stepps.iterators.levelorder import LevelOrderIterator
+from stepps.nodes import BinaryNode
+from stepps.trees.balanced.avl_impl import AVLImpl
+from stepps.trees.binary_tree_impl import BinaryTreeImpl
+
+
+def create_tree(root: BinaryNode[int], size: int) -> BinaryTreeImpl[int]:
+    tree = BinaryTreeImpl[int](LevelOrderIterator)
+    tree.root = root
+    tree._size = size
+
+    return tree
+
+
+# =====================================================
+# Basic Cases
+# =====================================================
+
+
+def test_balance_empty_tree():
+    tree = BinaryTreeImpl[int](LevelOrderIterator)
+    avl = AVLImpl[int](tree)
+
+    result = avl.balance()
+
+    assert result is tree
+    assert result.is_empty()
+    assert result.size() == 0
+
+
+def test_balance_single_node_tree():
+    tree = create_tree(BinaryNode(10), 1)
+    avl = AVLImpl[int](tree)
+
+    result = avl.balance()
+
+    assert result is tree
+    assert result.root is not None
+    assert result.root.value == 10
+    assert result.root.left is None
+    assert result.root.right is None
+    assert result.size() == 1
+
+
+def test_balance_already_balanced_tree():
+    root = BinaryNode(20)
+    root.left = BinaryNode(10)
+    root.right = BinaryNode(30)
+
+    tree = create_tree(root, 3)
+    avl = AVLImpl[int](tree)
+
+    result = avl.balance()
+
+    assert result is tree
+    assert result.root is not None
+    assert result.root.value == 20
+
+    assert result.root.left is not None
+    assert result.root.left.value == 10
+
+    assert result.root.right is not None
+    assert result.root.right.value == 30
+
+
+# =====================================================
+# Basic AVL Rotation Cases
+# =====================================================
+
+
+def test_balance_ll_case():
+    root = BinaryNode(30)
+    root.left = BinaryNode(20)
+    root.left.left = BinaryNode(10)
+
+    tree = create_tree(root, 3)
+    avl = AVLImpl[int](tree)
+
+    result = avl.balance()
+
+    assert result.root is not None
+    assert result.root.value == 20
+
+    assert result.root.left is not None
+    assert result.root.left.value == 10
+
+    assert result.root.right is not None
+    assert result.root.right.value == 30
+
+
+def test_balance_rr_case():
+    root = BinaryNode(10)
+    root.right = BinaryNode(20)
+    root.right.right = BinaryNode(30)
+
+    tree = create_tree(root, 3)
+    avl = AVLImpl[int](tree)
+
+    result = avl.balance()
+
+    assert result.root is not None
+    assert result.root.value == 20
+
+    assert result.root.left is not None
+    assert result.root.left.value == 10
+
+    assert result.root.right is not None
+    assert result.root.right.value == 30
+
+
+def test_balance_lr_case():
+    root = BinaryNode(30)
+    root.left = BinaryNode(10)
+    root.left.right = BinaryNode(20)
+
+    tree = create_tree(root, 3)
+    avl = AVLImpl[int](tree)
+
+    result = avl.balance()
+
+    assert result.root is not None
+    assert result.root.value == 20
+
+    assert result.root.left is not None
+    assert result.root.left.value == 10
+
+    assert result.root.right is not None
+    assert result.root.right.value == 30
+
+
+def test_balance_rl_case():
+    root = BinaryNode(10)
+    root.right = BinaryNode(30)
+    root.right.left = BinaryNode(20)
+
+    tree = create_tree(root, 3)
+    avl = AVLImpl[int](tree)
+
+    result = avl.balance()
+
+    assert result.root is not None
+    assert result.root.value == 20
+
+    assert result.root.left is not None
+    assert result.root.left.value == 10
+
+    assert result.root.right is not None
+    assert result.root.right.value == 30
+
+
+# =====================================================
+# Nested Subtree Cases
+# =====================================================
+
+
+def test_balance_ll_case_in_left_subtree():
+    root = BinaryNode(100)
+    root.left = BinaryNode(50)
+    root.left.left = BinaryNode(30)
+    root.left.left.left = BinaryNode(20)
+
+    tree = create_tree(root, 4)
+    avl = AVLImpl[int](tree)
+
+    result = avl.balance()
+
+    assert result.root is not None
+    assert result.root.value == 30
+
+    assert result.root.left is not None
+    assert result.root.left.value == 20
+
+    assert result.root.right is not None
+    assert result.root.right.value == 100
+
+    assert result.root.right.left is not None
+    assert result.root.right.left.value == 50
+
+
+def test_balance_rr_case_in_right_subtree():
+    root = BinaryNode(100)
+    root.right = BinaryNode(150)
+    root.right.right = BinaryNode(170)
+    root.right.right.right = BinaryNode(180)
+
+    tree = create_tree(root, 4)
+    avl = AVLImpl[int](tree)
+
+    result = avl.balance()
+
+    assert result.root is not None
+    assert result.root.value == 170
+
+    assert result.root.left is not None
+    assert result.root.left.value == 100
+
+    assert result.root.left.right is not None
+    assert result.root.left.right.value == 150
+
+    assert result.root.right is not None
+    assert result.root.right.value == 180
+
+
+def test_balance_lr_case_in_left_subtree():
+    root = BinaryNode(100)
+    root.left = BinaryNode(50)
+    root.left.left = BinaryNode(30)
+    root.left.left.right = BinaryNode(40)
+
+    tree = create_tree(root, 4)
+    avl = AVLImpl[int](tree)
+
+    result = avl.balance()
+
+    assert result.root is not None
+    assert result.root.value == 40
+
+    assert result.root.left is not None
+    assert result.root.left.value == 30
+
+    assert result.root.right is not None
+    assert result.root.right.value == 100
+
+    assert result.root.right.left is not None
+    assert result.root.right.left.value == 50
+
+
+def test_balance_rl_case_in_right_subtree():
+    root = BinaryNode(100)
+    root.right = BinaryNode(150)
+    root.right.right = BinaryNode(170)
+    root.right.right.left = BinaryNode(160)
+
+    tree = create_tree(root, 4)
+    avl = AVLImpl[int](tree)
+
+    result = avl.balance()
+
+    assert result.root is not None
+    assert result.root.value == 160
+
+    assert result.root.left is not None
+    assert result.root.left.value == 100
+
+    assert result.root.left.right is not None
+    assert result.root.left.right.value == 150
+
+    assert result.root.right is not None
+    assert result.root.right.value == 170
+
+
+# =====================================================
+# Larger Trees
+# =====================================================
+
+
+def test_balance_left_heavy_tree():
+    root = BinaryNode(50)
+
+    root.left = BinaryNode(30)
+    root.left.left = BinaryNode(20)
+    root.left.left.left = BinaryNode(10)
+    root.left.right = BinaryNode(40)
+
+    root.right = BinaryNode(70)
+    root.right.left = BinaryNode(60)
+    root.right.right = BinaryNode(80)
+
+    tree = create_tree(root, 8)
+    avl = AVLImpl[int](tree)
+
+    result = avl.balance()
+
+    assert result.root is not None
+    assert result.height() <= 3
+    assert result.size() == 8
+
+    for value in (10, 20, 30, 40, 50, 60, 70, 80):
+        assert result.contains(value)
+
+
+def test_balance_right_heavy_tree():
+    root = BinaryNode(50)
+
+    root.left = BinaryNode(30)
+    root.left.left = BinaryNode(20)
+    root.left.right = BinaryNode(40)
+
+    root.right = BinaryNode(70)
+    root.right.right = BinaryNode(80)
+    root.right.right.right = BinaryNode(90)
+
+    tree = create_tree(root, 7)
+    avl = AVLImpl[int](tree)
+
+    result = avl.balance()
+
+    assert result.root is not None
+    assert result.height() <= 3
+    assert result.size() == 7
+
+    for value in (20, 30, 40, 50, 70, 80, 90):
+        assert result.contains(value)
+
+
+def test_balance_complex_tree():
+    root = BinaryNode(50)
+
+    root.left = BinaryNode(30)
+    root.left.left = BinaryNode(20)
+    root.left.right = BinaryNode(40)
+    root.left.left.left = BinaryNode(10)
+
+    root.right = BinaryNode(70)
+    root.right.right = BinaryNode(80)
+    root.right.right.right = BinaryNode(90)
+
+    tree = create_tree(root, 8)
+    avl = AVLImpl[int](tree)
+
+    result = avl.balance()
+
+    assert result.root is not None
+    assert result.height() <= 3
+    assert result.size() == 8
+
+    for value in (10, 20, 30, 40, 50, 70, 80, 90):
+        assert result.contains(value)
+
+
+# =====================================================
+# Tree Structure Preservation
+# =====================================================
+
+
+def test_balance_preserves_all_nodes():
+    root = BinaryNode(50)
+
+    root.left = BinaryNode(30)
+    root.left.left = BinaryNode(20)
+    root.left.right = BinaryNode(40)
+
+    root.right = BinaryNode(70)
+    root.right.left = BinaryNode(60)
+    root.right.right = BinaryNode(80)
+
+    tree = create_tree(root, 7)
+    avl = AVLImpl[int](tree)
+
+    result = avl.balance()
+
+    assert result.size() == 7
+
+    for value in (20, 30, 40, 50, 60, 70, 80):
+        assert result.contains(value)
+
+
+def test_balance_returns_same_tree_object():
+    root = BinaryNode(30)
+    root.left = BinaryNode(20)
+    root.left.left = BinaryNode(10)
+
+    tree = create_tree(root, 3)
+    avl = AVLImpl[int](tree)
+
+    result = avl.balance()
+
+    assert result is tree

{stepps-0.2.0 → stepps-0.3.0}/tests/test_binary_tree.py

@@ -390,3 +390,78 @@ def test_left_rotate_without_right_child():
     assert result is tree
     assert tree.root is not None
     assert tree.root.value == 30
+
+
+# =====================================================
+# Tree Subtree Assignment
+# =====================================================
+
+
+def test_set_left_subtree(tree):
+    subtree = BinaryTreeImpl[int](LevelOrderIterator)
+
+    subtree.root = BinaryNode(30)
+    subtree.root.left = BinaryNode(20)
+    subtree.root.right = BinaryNode(40)
+    subtree._size = 3
+
+    tree._set_left_subtree(subtree)
+
+    assert tree.root is not None
+    assert tree.root.left is subtree.root
+    assert tree.root.left.value == 30
+
+    assert tree.root.left.left is not None
+    assert tree.root.left.left.value == 20
+
+    assert tree.root.left.right is not None
+    assert tree.root.left.right.value == 40
+
+
+def test_set_right_subtree(tree):
+    subtree = BinaryTreeImpl[int](LevelOrderIterator)
+
+    subtree.root = BinaryNode(70)
+    subtree.root.left = BinaryNode(60)
+    subtree.root.right = BinaryNode(80)
+    subtree._size = 3
+
+    tree._set_right_subtree(subtree)
+
+    assert tree.root is not None
+    assert tree.root.right is subtree.root
+    assert tree.root.right.value == 70
+
+    assert tree.root.right.left is not None
+    assert tree.root.right.left.value == 60
+
+    assert tree.root.right.right is not None
+    assert tree.root.right.right.value == 80
+
+
+def test_right_rotate_nested_subtree():
+    tree = BinaryTreeImpl[int](LevelOrderIterator)
+
+    root = BinaryNode(100)
+    root.left = BinaryNode(50)
+    root.left.left = BinaryNode(30)
+    root.left.left.left = BinaryNode(20)
+
+    tree.root = root
+    tree._size = 4
+
+    subtree = tree.get_left_subtree()
+    subtree.right_rotate()
+    tree._set_left_subtree(subtree)
+
+    assert tree.root is not None
+    assert tree.root.value == 100
+
+    assert tree.root.left is not None
+    assert tree.root.left.value == 30
+
+    assert tree.root.left.left is not None
+    assert tree.root.left.left.value == 20
+
+    assert tree.root.left.right is not None
+    assert tree.root.left.right.value == 50

{stepps-0.2.0 → stepps-0.3.0}/tests/test_inorder_tree_builder.py

@@ -1,5 +1,5 @@
 from stepps.iterators.inorder import InOrderIterator
-from stepps.TreeBuilder.inorder_tree_builder_impl import InOrderTreeBuilderImpl
+from stepps.tree_builder.inorder_tree_builder_impl import InOrderTreeBuilderImpl
 
 
 def test_build_empty_sequence():

{stepps-0.2.0 → stepps-0.3.0}/tests/test_level_order_tree_builder.py

@@ -1,5 +1,5 @@
 from stepps.iterators.levelorder import LevelOrderIterator
-from stepps.TreeBuilder.level_order_tree_builder_impl import LevelOrderTreeBuilderImpl
+from stepps.tree_builder.level_order_tree_builder_impl import LevelOrderTreeBuilderImpl
 
 
 def test_build_empty_sequence():

{stepps-0.2.0 → stepps-0.3.0}/tests/test_postorder_tree_builder.py

@@ -1,5 +1,5 @@
 from stepps.iterators.postorder import PostOrderIterator
-from stepps.TreeBuilder.postorder_tree_builder_impl import PostOrderTreeBuilderImpl
+from stepps.tree_builder.postorder_tree_builder_impl import PostOrderTreeBuilderImpl
 
 
 def test_build_empty_sequence():

{stepps-0.2.0 → stepps-0.3.0}/tests/test_preorder_tree_builder.py

@@ -1,5 +1,5 @@
 from stepps.iterators.preorder import PreOrderIterator
-from stepps.TreeBuilder.preorder_tree_builder_impl import PreOrderTreeBuilderImpl
+from stepps.tree_builder.preorder_tree_builder_impl import PreOrderTreeBuilderImpl
 
 
 def test_build_empty_sequence():

stepps-0.2.0/src/stepps/TreeBuilder/__init__.py

@@ -1,13 +0,0 @@
-from stepps.TreeBuilder.inorder_tree_builder import InOrderTreeBuilder
-from stepps.TreeBuilder.inorder_tree_builder_impl import InOrderTreeBuilderImpl
-from stepps.TreeBuilder.level_order_tree_builder import LevelOrderTreeBuilder
-from stepps.TreeBuilder.level_order_tree_builder_impl import LevelOrderTreeBuilderImpl
-from stepps.TreeBuilder.tree_builder import TreeBuilder
-
-__all__ = [
-    "InOrderTreeBuilder",
-    "InOrderTreeBuilderImpl",
-    "LevelOrderTreeBuilder",
-    "LevelOrderTreeBuilderImpl",
-    "TreeBuilder",
-]

stepps-0.2.0/src/stepps/TreeBuilder/inorder_tree_builder.py

@@ -1,8 +0,0 @@
-from stepps.TreeBuilder.tree_builder import TreeBuilder
-
-
-class InOrderTreeBuilder[T](TreeBuilder[T]):
-    """
-    Define the interface for building a binary tree from a sequence
-    using inorder traversal.
-    """

stepps-0.2.0/src/stepps/TreeBuilder/level_order_tree_builder.py

@@ -1,8 +0,0 @@
-from stepps.TreeBuilder.tree_builder import TreeBuilder
-
-
-class LevelOrderTreeBuilder[T](TreeBuilder[T]):
-    """
-    Define the interface for building a binary tree from a sequence
-    using level-order traversal.
-    """

stepps-0.2.0/src/stepps/TreeBuilder/postorder_tree_builder.py

@@ -1,8 +0,0 @@
-from stepps.TreeBuilder.tree_builder import TreeBuilder
-
-
-class PostOrderTreeBuilder[T](TreeBuilder[T]):
-    """
-    Define the interface for building a binary tree from a sequence
-    using postorder traversal.
-    """

stepps-0.2.0/src/stepps/TreeBuilder/preorder_tree_builder.py

@@ -1,8 +0,0 @@
-from stepps.TreeBuilder.tree_builder import TreeBuilder
-
-
-class PreOrderTreeBuilder[T](TreeBuilder[T]):
-    """
-    Define the interface for building a binary tree from a sequence
-    using preorder traversal.
-    """