Skip to main content
`Ctrl`+`K`

# 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`)