- class pystac.item_collection.ItemCollection(items: Iterable[ItemLike], extra_fields: dict[str, Any] | None = None, clone_items: bool = True)
Implementation of a GeoJSON FeatureCollection whose features are all STAC Items.
Iteminstances passed to the
ItemCollectioninstance during instantiation are cloned and have their
"root"URL cleared. Instances of this class implement the abstract methods of
typing.Collectionand can also be added together (see below for examples using these methods).
Any additional top-level fields in the FeatureCollection are retained in
from_file()methods and will be present in the serialized file from
extra_fields – Dictionary of additional top-level fields included in the
clone_items – Optional flag indicating whether
Iteminstances should be cloned before storing in the
ItemCollection. Setting to
Falsewill result in faster instantiation, but changes made to
Iteminstances in the
ItemCollectionwill mutate the original
Item. Defaults to
Loop over all items in the :class`~ItemCollection`
>>> item_collection: ItemCollection = ... >>> for item in item_collection: ... ...
Get the number of
Iteminstances in the
>>> length: int = len(item_collection)
Check if an
Itemis in the
ItemCollection. Note that the
clone_itemsargument must be
Falsefor 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
>>> 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
Iteminstances 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: pystac.Catalog | None = None) C
ItemCollectioninstance from a dictionary.
d – The dictionary from which the
ItemCollectionwill be created
preserve_dict – If False, the dict parameter
dmay 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: HREF, stac_io: pystac.StacIO | None = None) C
ItemCollectionfrom a JSON file.
href – Path to the file.
stac_io – A
StacIOinstance to use for file I/O
- static is_item_collection(d: dict[str, Any]) bool
Checks if the given dictionary represents a valid
d – Dictionary to check
- save_object(dest_href: str, stac_io: pystac.StacIO | None = None) None
Saves this instance to the
dest_href – Location to which the file will be saved.
stac_io – Optional
StacIOinstance to use. If not provided, will use the default instance.
- to_dict(transform_hrefs: bool = False) dict[str, Any]
ItemCollectioninstance to a dictionary.
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.