Add keep_parent parameter to add_child and add_item #1116

Author: m-mohr

CHANGELOG.md

@@ -9,6 +9,7 @@
 - `recursive` to Catalog and Collection `get_items()` to walk the sub-catalogs and sub-collections ([#1075](https://github.com/stac-utils/pystac/pull/1075))
 - MGRS Extension ([#1088](https://github.com/stac-utils/pystac/pull/1088))
 - All HTTP requests are logged when level is set to `logging.DEBUG` ([#1096](https://github.com/stac-utils/pystac/pull/1096))
+- `keep_parent` to Catalog `add_item` and `add_child` to avoid overriding existing parents ([#1117](https://github.com/stac-utils/pystac/pull/1117))
 
 ### Changed
 

pystac/catalog.py

@@ -240,10 +240,12 @@ def add_child(
         child: Union["Catalog", Collection],
         title: Optional[str] = None,
         strategy: Optional[HrefLayoutStrategy] = None,
+        keep_parent: bool = False,
     ) -> None:
         """Adds a link to a child :class:`~pystac.Catalog` or
         :class:`~pystac.Collection`. This method will set the child's parent to this
-        object, and its root to this Catalog's root.
+        object (except if a parent is set and keep_parent is true).
+        It will always set its root to this Catalog's root.
 
         Args:
             child : The child to add.
@@ -261,7 +263,8 @@ def add_child(
             strategy = BestPracticesLayoutStrategy()
 
         child.set_root(self.get_root())
-        child.set_parent(self)
+        if child.get_parent() is None or not keep_parent:
+            child.set_parent(self)
 
         # set self link
         self_href = self.get_self_href()
@@ -287,10 +290,12 @@ def add_item(
         item: Item,
         title: Optional[str] = None,
         strategy: Optional[HrefLayoutStrategy] = None,
+        keep_parent: bool = False,
     ) -> None:
         """Adds a link to an :class:`~pystac.Item`.
-        This method will set the item's parent to this object, and its root to
-        this Catalog's root.
+        This method will set the item's parent to this object (except if a parent
+        is set and keep_parent is true).
+        It will always set its root to this Catalog's root.
 
         Args:
             item : The item to add.
@@ -308,7 +313,8 @@ def add_item(
             strategy = BestPracticesLayoutStrategy()
 
         item.set_root(self.get_root())
-        item.set_parent(self)
+        if item.get_parent() is None or not keep_parent:
+            item.set_parent(self)
 
         # set self link
         self_href = self.get_self_href()

pystac/collection.py

@@ -553,8 +553,9 @@ def add_item(
         item: Item,
         title: Optional[str] = None,
         strategy: Optional[HrefLayoutStrategy] = None,
+        keep_parent: bool = False,
     ) -> None:
-        super().add_item(item, title, strategy)
+        super().add_item(item, title, strategy, keep_parent)
         item.set_collection(self)
 
     def to_dict(

tests/test_catalog.py

@@ -222,6 +222,66 @@ def test_add_child_throws_if_item(self) -> None:
         with pytest.raises(pystac.STACError):
             cat.add_child(item)  # type:ignore
 
+    def test_add_child_override_parent(self) -> None:
+        parent1 = Catalog(id="parent1", description="test1")
+        parent2 = Catalog(id="parent2", description="test2")
+        child = Catalog(id="child", description="test3")
+        assert child.get_parent() is None
+
+        parent1.add_child(child)
+        assert child.get_parent() is parent1
+
+        parent2.add_child(child)
+        assert child.get_parent() is parent2
+
+    def test_add_child_keep_parent(self) -> None:
+        parent1 = Catalog(id="parent1", description="test1")
+        parent2 = Catalog(id="parent2", description="test2")
+        child = Catalog(id="child", description="test3")
+        assert child.get_parent() is None
+
+        parent1.add_child(child, keep_parent=True)
+        assert child.get_parent() is parent1
+
+        parent2.add_child(child, keep_parent=True)
+        assert child.get_parent() is parent1
+
+    def test_add_item_override_parent(self) -> None:
+        parent1 = Catalog(id="parent1", description="test1")
+        parent2 = Catalog(id="parent2", description="test2")
+        child = Item(
+            id="child",
+            geometry=None,
+            bbox=None,
+            datetime=datetime.now(),
+            properties={},
+        )
+        assert child.get_parent() is None
+
+        parent1.add_item(child)
+        assert child.get_parent() is parent1
+
+        parent2.add_item(child)
+        assert child.get_parent() is parent2
+
+    def test_add_item_keep_parent(self) -> None:
+        parent1 = Catalog(id="parent1", description="test1")
+        parent2 = Catalog(id="parent2", description="test2")
+        child = Item(
+            id="child",
+            geometry=None,
+            bbox=None,
+            datetime=datetime.now(),
+            properties={},
+        )
+        assert child.get_parent() is None
+
+        parent1.add_item(child, keep_parent=True)
+        assert child.get_parent() is parent1
+
+        parent2.add_item(child, keep_parent=True)
+        assert child.get_parent() is parent1
+
     def test_add_item_throws_if_child(self) -> None:
         cat = TestCases.case_1()
         child = next(iter(cat.get_children()))