1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230
|
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 <https://github.com/stac-utils/pystac-client>`__
**Example:**
.. code-block:: python
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:`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`
|