ENH: Add remove_from_tree (#1432)

The remove_from_tree method can be used to remove an outline item

Fixes #1427

PyPDF2/generic/_data_structures.py

@@ -490,6 +490,15 @@ def remove_child(self, child: Any) -> None:
 
         _reset_node_tree_relationship(child_obj)
 
+    def remove_from_tree(self) -> None:
+        """
+        remove the object from the tree it is in
+        """
+        if NameObject("/Parent") not in self:
+            raise ValueError("Removed child does not appear to be a tree item")
+        else:
+            cast("TreeObject", self["/Parent"]).remove_child(self)
+
     def emptyTree(self) -> None:  # pragma: no cover
         deprecate_with_replacement("emptyTree", "empty_tree", "4.0.0")
         self.empty_tree()

tests/test_generic.py

@@ -475,7 +475,11 @@ def test_remove_child_not_in_that_tree():
 
     tree = TreeObject()
     tree.indirect_ref = NullObject()
-    child = ChildDummy(TreeObject())
+    # child = ChildDummy(TreeObject())
+    child = TreeObject()
+    with pytest.raises(ValueError) as exc:
+        child.remove_from_tree()
+    assert exc.value.args[0] == "Removed child does not appear to be a tree item"
     tree.add_child(child, ReaderDummy())
     with pytest.raises(ValueError) as exc:
         tree.remove_child(child)
@@ -558,7 +562,8 @@ def test_remove_child_found_in_tree():
     assert len([el for el in tree.children()]) == 3
 
     # Remove middle child
-    tree.remove_child(child4)
+    # tree.remove_child(child4)
+    child4.remove_from_tree()
     assert tree[NameObject("/Count")] == 2
     assert len([el for el in tree.children()]) == 2