pystac.item_collection#
- class pystac.item_collection.ItemCollection(items: Iterable[ItemLike], extra_fields: dict[str, Any] | None = None, clone_items: bool = True)[source]
Implementation of a GeoJSON FeatureCollection whose features are all STAC Items.
All
Item
instances passed to theItemCollection
instance during instantiation are cloned and have their"root"
URL cleared. Instances of this class implement the abstract methods oftyping.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 thefrom_dict()
andfrom_file()
methods and will be present in the serialized file fromsave_object()
.- Parameters:
items – List of
Item
instances to include in theItemCollection
.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 theItemCollection
. Setting toFalse
will result in faster instantiation, but changes made toItem
instances in theItemCollection
will mutate the originalItem
. Defaults toTrue
.
Examples
Loop over all items in the :class`~ItemCollection`
>>> item_collection: ItemCollection = ... >>> for item in item_collection: ... ...
Get the number of
Item
instances in theItemCollection
>>> length: int = len(item_collection)
Check if an
Item
is in theItemCollection
. Note that theclone_items
argument must beFalse
for this to returnTrue
, 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 [source]
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: pystac.Catalog | None = None) C [source]
Creates a
ItemCollection
instance from a dictionary.- Parameters:
d – The dictionary from which the
ItemCollection
will be createdpreserve_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: HREF, stac_io: pystac.StacIO | None = None) C [source]
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 [source]
Checks if the given dictionary represents a valid
ItemCollection
.- Parameters:
d – Dictionary to check
- items: list[pystac.item.Item]
List of
pystac.Item
instances contained in thisItemCollection
.
- save_object(dest_href: str, stac_io: pystac.StacIO | None = None) None [source]
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] [source]
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.