pystac.item_collection

class pystac.item_collection.ItemCollection(items: Iterable[Item | dict[str, Any]], extra_fields: dict[str, Any] | None = None, clone_items: bool = True)

Implementation of a GeoJSON FeatureCollection whose features are all STAC Items.

All Item instances passed to the ItemCollection instance during instantiation are cloned and have their "root" URL cleared. Instances of this class implement the abstract methods of 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 extra_fields by the from_dict() and from_file() methods and will be present in the serialized file from save_object().

Parameters:

• items – List of Item instances to include in the ItemCollection.

• extra_fields – Dictionary of additional top-level fields included in the ItemCollection.

• clone_items – Optional flag indicating whether Item instances should be cloned before storing in the ItemCollection. Setting to False will result in faster instantiation, but changes made to Item instances in the ItemCollection will mutate the original Item. Defaults to True.

Examples

Loop over all items in the :class`ItemCollection`

>>> item_collection: ItemCollection = ...
>>> for item in item_collection:
...     ...

Get the number of Item instances in the ItemCollection

>>> length: int = len(item_collection)

Check if an Item is in the ItemCollection. Note that the clone_items argument must be False for this to return True, since equality of PySTAC objects is currently evaluated using default object equality (i.e. item_1 is item_2).

>>> item: Item = ...
>>> item_collection = ItemCollection(items=[item], clone_items=False)
>>> assert item in item_collection

Combine ItemCollection instances

>>> item_1: Item = ...
>>> item_2: Item = ...
>>> item_3: Item = ...
>>> item_collection_1 = ItemCollection(items=[item_1, item_2])
>>> item_collection_2 = ItemCollection(items=[item_2, item_3])
>>> combined = item_collection_1 + item_collection_2
>>> assert len(combined) == 4
# If an item is present in both ItemCollections it will occur twice

clone() → ItemCollection

Creates a clone of this instance. This clone is a deep copy; all Item instances are cloned and all additional top-level fields are deep copied.

extra_fields: dict[str, Any]

Dictionary of additional top-level fields for the GeoJSON FeatureCollection.

classmethod from_dict(d: dict[str, Any], preserve_dict: bool = True, root: Catalog | None = None) → C

Creates a ItemCollection instance from a dictionary.

Parameters:

• d – The dictionary from which the ItemCollection will be created

• preserve_dict – If False, the dict parameter d may be modified during this method call. Otherwise the dict is not mutated. Defaults to True, which results results in a deepcopy of the parameter. Set to False when possible to avoid the performance hit of a deepcopy.

classmethod from_file(href: str | PathLike[str], stac_io: StacIO | None = None) → C

Reads a ItemCollection from a JSON file.

Parameters:

• href – Path to the file.

• stac_io – A StacIO instance to use for file I/O

static is_item_collection(d: dict[str, Any]) → bool

Checks if the given dictionary represents a valid ItemCollection.

Parameters:

d – Dictionary to check

items: list[Item]

List of pystac.Item instances contained in this ItemCollection.

save_object(dest_href: str, stac_io: StacIO | None = None) → None

Saves this instance to the dest_href location.

Parameters:

• dest_href – Location to which the file will be saved.

• stac_io – Optional StacIO instance to use. If not provided, will use the default instance.

to_dict(transform_hrefs: bool = False) → dict[str, Any]

Serializes an ItemCollection instance to a dictionary.

Parameters:

transform_hrefs – If True, transform the HREF of hierarchical links of Items based on the type of catalog the Item belongs to (if any). I.e. if the item belongs to a root catalog that is RELATIVE_PUBLISHED or SELF_CONTAINED, hierarchical link HREFs will be transformed to be relative to the catalog root. This can be slow if the Items have root links that have not yet been resolved. Defaults to False.

class pystac.item_collection.C

Generalized version of ItemCollection

alias of TypeVar(‘C’, bound=ItemCollection)