api.rst

API Reference

.. toctree::
   :hidden:
   :maxdepth: 2
   :glob:

   api/pystac
   api/*

This API reference is auto-generated from the Python docstrings. The table of contents on the left is organized by module. The sections below are organized based on concepts and sections within the :stac-spec:`STAC Spec <>` and PySTAC itself.

Base Structures & Classes

These are the core Python classes representing entities within the STAC Spec. These classes provide convenient methods for serializing and deserializing from JSON, extracting properties, and creating relationships between entities.

• :class:`pystac.Link`: Represents a :stac-spec:`Link Object <item-spec/item-spec.md#link-object>`.
• :class:`pystac.MediaType`: Provides common values used in the Link and Asset "type" fields.
• :class:`pystac.RelType`: Provides common values used in the Link "rel" field.
• :class:`pystac.STACObject`: Base class implementing functionality common to :class:`Catalog <pystac.Catalog>`, :class:`Collection <pystac.Collection>` and :class:`Item <pystac.Item>`.

Items

Representations of :stac-spec:`Items <item-spec/item-spec.md>` and related structures like :stac-spec:`Asset Objects<item-spec/item-spec.md#asset-object>`.

• :class:`pystac.Asset`: Represents an :stac-spec:`Asset Object <item-spec/item-spec.md#asset-object>`
• :class:`pystac.Item`: Represents an :stac-spec:`Item <item-spec/item-spec.md>`
• :class:`pystac.CommonMetadata`: A container for fields defined in the :stac-spec:`Common Metadata <item-spec/common-metadata.md>` section of the spec. These fields are commonly found in STAC Item properties, but may be found elsewhere.

Collections

These are representations of :stac-spec:`Collections <collection-spec/collectino-spec.md>` and related structures.

• :class:`pystac.Collection`: Represents a :stac-spec:`Collection <collection-spec/collection-spec.md>`.
• :class:`pystac.Extent`: Represents an :stac-spec:`Extent Object <collection-spec/collection-spec.md#extent-object>`, which is composed of :class:`pystac.SpatialExtent` and :class:`pystac.TemporalExtent` instances.
• :class:`pystac.Provider`: Represents a :stac-spec:`Provider Object <collection-spec/collection-spec.md#provider-object>`. The :class:`pystac.ProviderRole` enum provides common values used in the "roles" field.
• :class:`pystac.Summaries`: Class for working with various types of :stac-spec:`CollectionSummaries <collection-spec/collection-spec.md#summaries>`
• :class:`pystac.ItemCollection`: Represents a GeoJSON FeatureCollection in which all Features are STAC Items.

Catalogs

Representations of :stac-spec:`Catalogs <catalog-spec/catalog-spec.md>` and related structures.

• :class:`pystac.Catalog`: Represents a :stac-spec:`Catalog <catalog-spec/catalog-spec.md>`.
• :class:`pystac.CatalogType`: Enum representing the common types of Catalogs described in the :stac-spec:`STAC Best Practices <https://github.com/radiantearth/stac-spec/blob/master/best-practices.md#use-of-links>`

I/O

These classes are used to read and write files from disk or over the network, as well as to serialize and deserialize STAC object to and from JSON.

• :class:`pystac.StacIO`: Base class that can be inherited to provide custom I/O
• :class:`pystac.stac_io.DefaultStacIO`: The default :class:`pystac.StacIO` implementation used throughout the library.

Client

A convenience method for accessing pystac-client

Example:

from pystac.client import Client

Extensions

PySTAC provides support for the following STAC Extensions:

• :mod:`Datacube <pystac.extensions.datacube>`
• :mod:`Electro-Optical <pystac.extensions.eo>`
• :mod:`File Info <pystac.extensions.file>`
• :mod:`Item Assets <pystac.extensions.item_assets>`
• :mod:`MGRS <pystac.extensions.mgrs>`
• :mod:`Point Cloud <pystac.extensions.pointcloud>`
• :mod:`Projection <pystac.extensions.projection>`
• :mod:`Raster <pystac.extensions.raster>`
• :mod:`SAR <pystac.extensions.sar>`
• :mod:`Satellite <pystac.extensions.sat>`
• :mod:`Scientific Citation <pystac.extensions.scientific>`
• :mod:`Solar System<pystac.extensions.ssys>`
• :mod:`Table <pystac.extensions.table>`
• :mod:`Timestamps <pystac.extensions.timestamps>`
• :mod:`Versioning Indicators <pystac.extensions.version>`
• :mod:`View Geometry <pystac.extensions.view>`
• :mod:`Xarray Assets <pystac.extensions.xarray_assets>`

The following classes are used internally to implement these extensions and may be used to create custom implementations of STAC Extensions not supported by the library (see :tutorial:`Adding New and Custom Extensions <adding-new-and-custom-extensions.ipynb>` for details):

• :class:`pystac.extensions.base.SummariesExtension`: Base class for extending the properties in :attr:`pystac.Collection.summaries` to include properties defined by a STAC Extension.
• :class:`pystac.extensions.base.PropertiesExtension`: Abstract base class for extending the properties of an :class:`~pystac.Item` to include properties defined by a STAC Extension.
• :class:`pystac.extensions.base.ExtensionManagementMixin`: Abstract base class with methods for adding and removing extensions from STAC Objects.
• :class:`pystac.extensions.hooks.ExtensionHooks`: Used to implement hooks when extending a STAC Object. Primarily used to implement migrations from one extension version to another.
• :class:`pystac.extensions.hooks.RegisteredExtensionHooks`: Used to register hooks defined in :class:`~pystac.extensions.hooks.ExtensionHooks` instances to ensure they are used in object deserialization.

Catalog Layout

These classes are used to set the HREFs of a STAC according to some layout. The templating functionality is also used when generating subcatalogs based on a template.

• :class:`pystac.layout.LayoutTemplate`: Represents a template that can be used for deriving paths or other information based on properties of STAC objects supplied as a template string.
• :class:`pystac.layout.BestPracticesLayoutStrategy`: Layout strategy that represents the catalog layout described in the :stac-spec:`STAC Best Practices documentation <best-practices.md>`.
• :class:`pystac.layout.APILayoutStrategy`: Layout strategy that represents the catalog layout described in the :stac-api-spec:`STAC API documentation <overview.md#endpoints>`.
• :class:`pystac.layout.TemplateLayoutStrategy`: Layout strategy that can take strings to be supplied to a :class:`~pystac.layout.LayoutTemplate` to derive paths.
• :class:`pystac.layout.CustomLayoutStrategy`: Layout strategy that allows users to supply functions to dictate stac object paths.

Errors

The following exceptions may be raised internally by the library.

• :class:`pystac.STACError`: Generic STAC-related error
• :class:`pystac.STACTypeError`: Raised when a representation of a STAC entity is encountered that is not correct for the context
• :class:`pystac.DuplicateObjectKeyError`: Raised when deserializing a JSON object containing a duplicate key.
• :class:`pystac.ExtensionAlreadyExistsError`: Raised when deserializing a JSON object containing a duplicate key.
• :class:`pystac.ExtensionTypeError`: Raised when an extension is used against an object to which that the extension does not apply to.
• :class:`pystac.ExtensionNotImplemented`: Raised on an attempt to extend a STAC object that does not implement the given extension.
• :class:`pystac.RequiredPropertyMissing`: Raised when a required value is expected to be present but is missing or None.
• :class:`pystac.STACValidationError`: Raised by validation calls if the STAC JSON is invalid.
• :class:`pystac.TemplateError`: Raised when an error occurs while converting a template string into data for :class:`~pystac.layout.LayoutTemplate`.

Serialization

The pystac.serialization sub-package contains tools used internally by PySTAC to identify, serialize, and migrate STAC objects:

• :mod:`pystac.serialization`: Tools for identifying and migrating STAC objects

Validation

Note

The tools described here require that you install PySTAC with the validation extra (see the documentation on :ref:`installing dependencies <installation_dependencies>` for details).

PySTAC includes a pystac.validation package for validating STAC objects, including from PySTAC objects and directly from JSON.

• :class:`pystac.validation.stac_validator.STACValidator`: Abstract base class defining methods for validating STAC JSON. Implementations define methods for validating core objects and extension.
• :class:`pystac.validation.stac_validator.JsonSchemaSTACValidator`: The default :class:`~pystac.validation.stac_validator.STACValidator` implementation used by PySTAC. Uses JSON schemas read from URIs provided by a :class:`~pystac.validation.schema_uri_map.SchemaUriMap`, to validate STAC objects.
• :class:`pystac.validation.schema_uri_map.SchemaUriMap`: Defines methods for mapping STAC versions, object types and extension ids to schema URIs. A default implementation is included that uses known locations; however users can provide their own schema URI maps in a :class:`~pystac.validation.stac_validator.JsonSchemaSTACValidator` to modify the URIs used.
• :class:`pystac.validation.schema_uri_map.DefaultSchemaUriMap`: The default :class:`~pystac.validation.schema_uri_map.SchemaUriMap` used by PySTAC.

Internal Classes

These classes are used internally by PySTAC for caching.

• :class:`pystac.cache.ResolvedObjectCache`