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