Ability to add ItemCollections

Author: duckontheweb

pystac/item_collection.py

@@ -16,8 +16,8 @@ class ItemCollection(Collection[pystac.Item]):
 
     All :class:`~pystac.Item` instances passed to the :class:`~ItemCollection` instance
     during instantiation are cloned and have their ``"root"`` URL cleared. Instances of
-    this class implement the abstract methods of :class:`typing.Collection` (see
-    below for examples using these methods).
+    this class implement the abstract methods of :class:`typing.Collection` and can also
+    be added together (see below for examples using these methods).
 
     Any additional top-level fields in the FeatureCollection are retained in
     :attr:`~ItemCollection.extra_fields` by the :meth:`~ItemCollection.from_dict` and
@@ -58,6 +58,22 @@ class ItemCollection(Collection[pystac.Item]):
         >>> item_collection = ItemCollection(items=[item], clone_items=False)
         >>> assert item in item_collection
 
+        Combine :class:`~ItemCollection` instances
+
+        >>> item_1: Item = ...
+        >>> item_2: Item = ...
+        >>> item_3: Item = ...
+        >>> item_collection_1 = ItemCollection(
+        ...     items=[item_1, item_2],
+        ...     clone_items=False
+        ... )
+        >>> item_collection_2 = ItemCollection(
+        ...     items=[item_2, item_3],
+        ...     clone_items=False
+        ... )
+        >>> combined = item_collection_1 + item_collection_2
+        >>> assert len(combined) == 3
+        # If an item is present in both ItemCollections it will only be added once
     """
 
     items: List[pystac.Item]
@@ -95,6 +111,17 @@ def __len__(self) -> int:
     def __contains__(self, __x: object) -> bool:
         return __x in self.items
 
+    def __add__(self, other: object) -> "ItemCollection":
+        if not isinstance(other, ItemCollection):
+            return NotImplemented
+
+        combined = []
+        for item in self.items + other.items:
+            if item not in combined:
+                combined.append(item)
+
+        return ItemCollection(items=combined, clone_items=False)
+
     def to_dict(self) -> Dict[str, Any]:
         """Serializes an :class:`ItemCollection` instance to a JSON-like dictionary."""
         return {

tests/test_item_collection.py

@@ -1,5 +1,4 @@
 import json
-from pystac.item_collection import ItemCollection
 from typing import cast
 import unittest
 import pystac
@@ -119,6 +118,28 @@ def test_from_relative_path(self) -> None:
 
     def test_from_list_of_dicts(self) -> None:
         item_dict = self.stac_io.read_json(self.SIMPLE_ITEM)
-        item_collection = ItemCollection(items=[item_dict])
+        item_collection = pystac.ItemCollection(items=[item_dict])
 
         self.assertEqual(item_collection[0].id, item_dict.get("id"))
+
+    def test_add_item_collections(self) -> None:
+        item_1 = pystac.Item.from_file(self.SIMPLE_ITEM)
+        item_2 = pystac.Item.from_file(self.EXTENDED_ITEM)
+        item_3 = pystac.Item.from_file(self.CORE_ITEM)
+
+        item_collection_1 = pystac.ItemCollection(
+            items=[item_1, item_2], clone_items=False
+        )
+        item_collection_2 = pystac.ItemCollection(
+            items=[item_2, item_3], clone_items=False
+        )
+
+        combined = item_collection_1 + item_collection_2
+
+        self.assertEqual(len(combined), 3)
+
+    def test_add_other_raises_error(self) -> None:
+        item_collection = pystac.ItemCollection.from_file(self.ITEM_COLLECTION)
+
+        with self.assertRaises(TypeError):
+            _ = item_collection + 2