API Reference¶
This API reference is auto-generated for the Python docstrings, and organized by the section of the STAC Spec they relate to, if related to a specific spec item.
pystac¶
PySTAC is a library for working with SpatioTemporal Asset Catalogs (STACs)
-
pystac.
read_file
(href)[source]¶ Reads a STAC object from a file.
This method will return either a Catalog, a Collection, or an Item based on what the file contains.
This is a convenience method for
STACObject.from_file
Parameters: href (str) – The HREF to read the object from. Returns: The specific STACObject implementation class that is represented by the JSON read from the file located at HREF.
-
pystac.
write_file
(obj, include_self_link=True, dest_href=None)[source]¶ Writes a STACObject to a file.
This will write only the Catalog, Collection or Item
obj
. It will not attempt to write any other objects that are linked toobj
; if you’d like functionality to save off catalogs recursively seeCatalog.save
.This method will write the JSON of the object to the object’s assigned “self” link or to the dest_href if provided. To set the self link, see
STACObject.set_self_href
.Convenience method for
STACObject.from_file
Parameters: - obj (STACObject) – The STACObject to save.
- include_self_link (bool) – If this is true, include the ‘self’ link with this object. Otherwise, leave out the self link.
- dest_href (str) – Optional HREF to save the file to. If None, the object will be saved to the object’s self href.
-
pystac.
read_dict
(d, href=None, root=None)[source]¶ Reads a STAC object from a dict representing the serialized JSON version of the STAC object.
This method will return either a Catalog, a Collection, or an Item based on what the dict contains.
This is a convenience method for
pystac.serialization.stac_object_from_dict()
Parameters: - d (dict) – The dict to parse.
- href (str) – Optional href that is the file location of the object being parsed.
- root (Catalog or Collection) – Optional root of the catalog for this object. If provided, the root’s resolved object cache can be used to search for previously resolved instances of the STAC object.
-
pystac.
set_stac_version
(stac_version)[source]¶ Sets the STAC version that PySTAC should use.
This is the version that will be set as the “stac_version” property on any JSON STAC objects written by PySTAC. If set to None, the override version will be cleared if previously set and the default or an override taken from the environment will be used.
You can also set the environment variable PYSTAC_STAC_VERSION_OVERRIDE to override the version.
Parameters: stac_version (str) – The STAC version to use instead of the latest STAC version that PySTAC supports (described in STACVersion.DEFAULT_STAC_VERSION) Note
Setting the STAC version to something besides the default version will not effect the format of STAC read or written; it will only override the
stac_version
property of the objects being written. Setting this incorrectly can produce invalid STAC.
-
pystac.
get_stac_version
()[source]¶ Returns the STAC version PySTAC writes as the “stac_version” property for any object it serializes into JSON.
If a call to
set_stac_version
was made, this will return the value it was called with. Next it will check the environment for a PYSTAC_STAC_VERSION_OVERRIDE variable. Otherwise it will return the latest STAC version that this version of PySTAC supports.Returns: The STAC Version PySTAC is set up to use. Return type: str
STACObject¶
STACObject is the base class for Catalog
, Collection
and Item
, and contains a variety of useful methods for dealing with links, copying objects, accessing extensions, and reading and writing files. You shouldn’t use STACObject directly, but instead access this functionality through the implementing classes.
-
class
pystac.
STACObject
(stac_extensions)[source]¶ A STACObject is the base class for any element of STAC that has links e.g. (Catalogs, Collections, or Items). A STACObject has common functionality, can be converted to and from Python
dicts
representing JSON, and can be cloned or copied.-
links
¶ A list of
Link
objects representing all links associated with this STACObject.Type: List[Link]
-
STAC_OBJECT_TYPE
= None¶
-
add_links
(links)¶ Add links to this object’s set of links.
Parameters: links (List[Link]) – The links to add.
-
clear_links
(rel=None)¶ Clears all
Link
instances associated with this object.Parameters: rel (str or None) – If set, only clear links that match this relationship.
-
clone
()[source]¶ Clones this object.
Cloning an object will make a copy of all properties and links of the object; however, it will not make copies of the targets of links (i.e. it is not a deep copy). To copy a STACObject fully, with all linked elements also copied, use
STACObject.full_copy
.Returns: The clone of this object. Return type: STACObject
-
ext
¶ Access extensions for this STACObject.
Example
This example shows accessing a Item’s EO extension functionality that gets the band information for an asset:
item = pystac.read_file("eo_item.json") bands = item.ext.eo.get_asset_bands(item.assets["image"])
Returns: The object that can be used to access extension information and functionality. Return type: ExtensionIndex
-
classmethod
from_dict
(d, href=None, root=None)[source]¶ Parses this STACObject from the passed in dictionary.
Parameters: - d (dict) – The dict to parse.
- href (str) – Optional href that is the file location of the object being parsed.
- root (Catalog or Collection) – Optional root of the catalog for this object. If provided, the root’s resolved object cache can be used to search for previously resolved instances of the STAC object.
Returns: The STACObject parsed from this dict.
Return type:
-
classmethod
from_file
(href)[source]¶ Reads a STACObject implementation from a file.
Parameters: href (str) – The HREF to read the object from. Returns: The specific STACObject implementation class that is represented by the JSON read from the file located at HREF.
-
full_copy
(root=None, parent=None)[source]¶ Create a full copy of this STAC object and any stac objects linked to by this object.
Parameters: - root (STACObject) – Optional root to set as the root of the copied object, and any other copies that are contained by this object.
- parent (STACObject) – Optional parent to set as the parent of the copy of this object.
Returns: - A full copy of this object, as well as any objects this object
links to.
Return type:
-
get_links
(rel=None)¶ Gets the
Link
instances associated with this object.Parameters: rel (str or None) – If set, filter links such that only those matching this relationship are returned. Returns: - A list of links that match
rel
if set, - or else all links associated with this object.
Return type: List[ Link
]- A list of links that match
-
get_parent
()[source]¶ Get the
Catalog
orCollection
to the parent for this object. The root is represented by aLink
withrel == 'parent'
.Returns: The parent object for this object, or None
if no root link is set.Return type: Catalog, Collection, or None
-
get_root
()[source]¶ Get the
Catalog
orCollection
to the root for this object. The root is represented by aLink
withrel == 'root'
.Returns: The root object for this object, or None
if no root link is set.Return type: Catalog, Collection, or None
-
get_root_link
()¶ Get the
Link
representing the root for this object.Returns: The root link for this object, or None
if no root link is set.Return type: Link
or None
-
get_self_href
()¶ Gets the absolute HREF that is represented by the
rel == 'self'
Link
.Returns: The absolute HREF of this object, or None
if there is no self link defined.Return type: str or None Note
A self link can exist for objects, even if the link is not read or written to the JSON-serialized version of the object. Any object read from
STACObject.from_file
will have the HREF the file was read from set as it’s self HREF. All self links have absolute (as opposed to relative) HREFs.
-
get_single_link
(rel)¶ Get single link that match the given
rel
.Parameters: rel (str) – The Link
rel
to match on.
-
get_stac_objects
(rel)[source]¶ Gets the
STACObject
instances that are linked to by links with theirrel
property matching the passed in argument.Parameters: rel (str) – The relation to match each Link
’srel
property against.Returns: A possibly empty generator of STACObjects that are connected to this object through links with the given rel
.Return type: Generator[STACObjects]
-
remove_links
(rel)¶ Remove links to this object’s set of links that match the given
rel
.Parameters: rel (str) – The Link
rel
to match on.
-
resolve_links
()[source]¶ Ensure all STACObjects linked to by this STACObject are resolved. This is important for operations such as changing HREFs.
This method mutates the entire catalog tree.
-
save_object
(include_self_link=True, dest_href=None)[source]¶ Saves this STAC Object to it’s ‘self’ HREF.
Parameters: - include_self_link (bool) – If this is true, include the ‘self’ link with this object. Otherwise, leave out the self link.
- dest_href (str) – Optional HREF to save the file to. If None, the object will be saved to the object’s self href.
Raises: STACError
– If no self href is set, this error will be raised.Note
When to include a self link is described in the Use of Links section of the STAC best practices document
-
set_parent
(parent)[source]¶ Sets the parent
Catalog
orCollection
for this object.Parameters: parent (Catalog, Collection or None) – The parent object to set. Passing in None will clear the parent.
-
set_root
(root)[source]¶ Sets the root
Catalog
orCollection
for this object.Parameters: root (Catalog, Collection or None) – The root object to set. Passing in None will clear the root.
-
set_self_href
(href)¶ Sets the absolute HREF that is represented by the
rel == 'self'
Link
.Parameters: href (str) – The absolute HREF of this object. If the given HREF is not absolute, it will be transformed to an absolute HREF based on the current working directory. If this is None the call will clear the self HREF link.
-
to_dict
(include_self_link=True)[source]¶ Generate a dictionary representing the JSON of this serialized object.
Parameters: include_self_link (bool) – If True, the dict will contain a self link to this object. If False, the self link will be omitted. Returns: A serializion of the object that can be written out as JSON. Return type: dict
-
Catalog Spec¶
These classes are representations of the Catalog Spec.
Catalog¶
-
class
pystac.
Catalog
(id, description, title=None, stac_extensions=None, extra_fields=None, href=None, catalog_type=<CatalogType.ABSOLUTE_PUBLISHED: 'ABSOLUTE_PUBLISHED'>)[source]¶ Bases:
pystac.stac_object.STACObject
A PySTAC Catalog represents a STAC catalog in memory.
A Catalog is a
STACObject
that may contain children, which are instances ofCatalog
orCollection
, as well asItem
s.Parameters: - id (str) – Identifier for the catalog. Must be unique within the STAC.
- description (str) – Detailed multi-line description to fully explain the catalog. CommonMark 0.28 syntax MAY be used for rich text representation.
- title (str or None) – Optional short descriptive one-line title for the catalog.
- stac_extensions (List[str]) – Optional list of extensions the Catalog implements.
- href (str or None) – Optional HREF for this catalog, which be set as the catalog’s self link’s HREF.
- catalog_type (str or None) – Optional catalog type for this catalog. Must be one of the values in :class`~pystac.CatalogType`.
-
id
¶ Identifier for the catalog.
Type: str
-
description
¶ Detailed multi-line description to fully explain the catalog.
Type: str
-
title
¶ Optional short descriptive one-line title for the catalog.
Type: str or None
-
stac_extensions
¶ Optional list of extensions the Catalog implements.
Type: List[str] or None
-
extra_fields
¶ Extra fields that are part of the top-level JSON properties of the Catalog.
Type: dict or None
-
catalog_type
¶ The catalog type, or None if not known.
Type: str or None
-
DEFAULT_FILE_NAME
= 'catalog.json'¶ Default file name that will be given to this STAC object in a cononical format.
-
STAC_OBJECT_TYPE
= 'CATALOG'¶
-
add_child
(child, title=None, strategy=None)[source]¶ Adds a link to a child
Catalog
orCollection
. This method will set the child’s parent to this object, and its root to this Catalog’s root.Parameters: - child (Catalog or Collection) – The child to add.
- title (str) – Optional title to give to the
Link
-
add_children
(children)[source]¶ Adds links to multiple
Catalog
or `~pystac.Collection`s. This method will set each child’s parent to this object, and their root to this Catalog’s root.Parameters: children (Iterable[Catalog or Collection]) – The children to add.
-
add_item
(item, title=None, strategy=None)[source]¶ Adds a link to an
Item
. This method will set the item’s parent to this object, and its root to this Catalog’s root.Parameters:
-
add_items
(items)[source]¶ Adds links to multiple
Item
s. This method will set each item’s parent to this object, and their root to this Catalog’s root.Parameters: items (Iterable[Item]) – The items to add.
-
clear_children
()[source]¶ Removes all children from this catalog.
Returns: Returns self
Return type: Catalog
-
clear_items
()[source]¶ Removes all items from this catalog.
Returns: Returns self
Return type: Catalog
-
clone
()[source]¶ Clones this object.
Cloning an object will make a copy of all properties and links of the object; however, it will not make copies of the targets of links (i.e. it is not a deep copy). To copy a STACObject fully, with all linked elements also copied, use
STACObject.full_copy
.Returns: The clone of this object. Return type: STACObject
-
describe
(include_hrefs=False, _indent=0)[source]¶ Prints out information about this Catalog and all contained STACObjects.
Parameters: include_hrefs (bool) – HREF along with the object ID.
-
classmethod
from_dict
(d, href=None, root=None)[source]¶ Parses this STACObject from the passed in dictionary.
Parameters: - d (dict) – The dict to parse.
- href (str) – Optional href that is the file location of the object being parsed.
- root (Catalog or Collection) – Optional root of the catalog for this object. If provided, the root’s resolved object cache can be used to search for previously resolved instances of the STAC object.
Returns: The STACObject parsed from this dict.
Return type:
-
generate_subcatalogs
(template, defaults=None, parent_ids=None, **kwargs)[source]¶ Walks through the catalog and generates subcatalogs for items based on the template string. See
LayoutTemplate
for details on the construction of template strings. This template string will be applied to the items, and subcatalogs will be created that separate and organize the items based on template values.Parameters: - template (str) – A template string that
can be consumed by a
LayoutTemplate
- defaults (dict) – Default values for the template variables that will be used if the property cannot be found on the item.
- parent_ids (List[str]) – Optional list of the parent catalogs’ identifiers. If the bottom-most subcatalags already match the template, no subcatalog is added.
Returns: List of new catalogs created
Return type: [catalog]
- template (str) – A template string that
can be consumed by a
-
get_all_items
()[source]¶ Get all items from this catalog and all subcatalogs. Will traverse any subcatalogs recursively.
Returns: - All items that belong to this catalog, and all
- catalogs or collections connected to this catalog through child links.
Return type: Generator[Item]
-
get_child
(id, recursive=False)[source]¶ Gets the child of this catalog with the given ID, if it exists.
Parameters: - id (str) – The ID of the child to find.
- recursive (bool) – If True, search this catalog and all children for the item; otherwise, only search the children of this catalog. Defaults to False.
Returns: The item with the given ID, or None if not found.
Return type: Item or None
-
get_child_links
()[source]¶ Return all child links of this catalog.
Returns: List of links of this catalog with rel == 'child'
Return type: List[Link]
-
get_children
()[source]¶ Return all children of this catalog.
Returns: Generator of children who’s parent is this catalog. Return type: Generator[Catalog or Collection]
-
get_item
(id, recursive=False)[source]¶ Returns an item with a given ID.
Parameters: - id (str) – The ID of the item to find.
- recursive (bool) – If True, search this catalog and all children for the item; otherwise, only search the items of this catalog. Defaults to False.
Returns: The item with the given ID, or None if not found.
Return type: Item or None
-
get_item_links
()[source]¶ Return all item links of this catalog.
Returns: List of links of this catalog with rel == 'item'
Return type: List[Link]
-
get_items
()[source]¶ Return all items of this catalog.
Returns: Generator of items who’s parent is this catalog. Return type: Generator[Item]
-
make_all_asset_hrefs_absolute
()[source]¶ Makes all the HREFs of assets belonging to items in this catalog and all children to be absolute, recursively.
-
make_all_asset_hrefs_relative
()[source]¶ Makes all the HREFs of assets belonging to items in this catalog and all children to be relative, recursively.
-
map_assets
(asset_mapper)[source]¶ Creates a copy of a catalog, with each Asset for each Item passed through the asset_mapper function.
Parameters: asset_mapper (Callable) – A function that takes in an key and an Asset, and returns either an Asset, a (key, Asset), or a dictionary of Assets with unique keys. The Asset that is passed into the item_mapper is a copy, so the method can mutate it safely. Returns: A full copy of this catalog, with assets manipulated according to the asset_mapper function. Return type: Catalog
-
map_items
(item_mapper)[source]¶ Creates a copy of a catalog, with each item passed through the item_mapper function.
Parameters: item_mapper (Callable) – A function that takes in an item, and returns either an item or list of items. The item that is passed into the item_mapper is a copy, so the method can mutate it safely. Returns: A full copy of this catalog, with items manipulated according to the item_mapper function. Return type: Catalog
-
normalize_and_save
(root_href, catalog_type=None, strategy=None)[source]¶ Normalizes link HREFs to the given root_href, and saves the catalog.
This is a convenience method that simply calls
Catalog.normalize_hrefs
andCatalog.save
in sequence.Parameters: - root_href (str) – The absolute HREF that all links will be normalized against.
- catalog_type (str) – The catalog type that dictates the structure of
the catalog to save. Use a member of
CatalogType
. Defaults to the root catalog.catalog_type or the current catalog catalog_type if there is no root catalog. - strategy (HrefLayoutStrategy) – The layout strategy to use in setting the HREFS
for this catalog. Defaults to
BestPracticesLayoutStrategy
-
normalize_hrefs
(root_href, strategy=None)[source]¶ Normalize HREFs will regenerate all link HREFs based on an absolute root_href and the canonical catalog layout as specified in the STAC specification’s best practices.
This method mutates the entire catalog tree.
Parameters: - root_href (str) – The absolute HREF that all links will be normalized against.
- strategy (HrefLayoutStrategy) – The layout strategy to use in setting the HREFS
for this catalog. Defaults to
BestPracticesLayoutStrategy
- See:
- STAC best practices document for the canonical layout of a STAC.
-
remove_child
(child_id)[source]¶ Removes an child from this catalog.
Parameters: child_id (str) – The ID of the child to remove.
-
remove_item
(item_id)[source]¶ Removes an item from this catalog.
Parameters: item_id (str) – The ID of the item to remove.
-
save
(catalog_type=None)[source]¶ Save this catalog and all it’s children/item to files determined by the object’s self link HREF.
Parameters: catalog_type (str) – The catalog type that dictates the structure of the catalog to save. Use a member of CatalogType
. If not supplied, the catalog_type of this catalog will be used. If that attribute is not set, an exception will be raised.Note
If the catalog type is
CatalogType.ABSOLUTE_PUBLISHED
, all self links will be included, and hierarchical links be absolute URLs. If the catalog type isCatalogType.RELATIVE_PUBLISHED
, this catalog’s self link will be included, but no child catalog will have self links, and hierarchical links will be relative URLs If the catalog type isCatalogType.SELF_CONTAINED
, no self links will be included and hierarchical links will be relative URLs.
-
set_root
(root)[source]¶ Sets the root
Catalog
orCollection
for this object.Parameters: root (Catalog, Collection or None) – The root object to set. Passing in None will clear the root.
-
to_dict
(include_self_link=True)[source]¶ Generate a dictionary representing the JSON of this serialized object.
Parameters: include_self_link (bool) – If True, the dict will contain a self link to this object. If False, the self link will be omitted. Returns: A serializion of the object that can be written out as JSON. Return type: dict
-
validate_all
()[source]¶ Validates each catalog, collection contained within this catalog.
Walks through the children and items of the catalog and validates each stac object.
Raises: STACValidationError
– Raises this error on any item that is invalid. Will raise on the first invalid stac object encountered.
-
walk
()[source]¶ Walks through children and items of catalogs.
For each catalog in the STAC’s tree rooted at this catalog (including this catalog itself), it yields a 3-tuple (root, subcatalogs, items). The root in that 3-tuple refers to the current catalog being walked, the subcatalogs are any catalogs or collections for which the root is a parent, and items represents any items that have the root as a parent.
This has similar functionality to Python’s
os.walk()
.Returns: A generator that yields a 3-tuple (parent_catalog, children, items). Return type: Generator[(Catalog, Generator[Catalog], Generator[Item])]
CatalogType¶
-
class
pystac.
CatalogType
[source]¶ An enumeration.
-
ABSOLUTE_PUBLISHED
= 'ABSOLUTE_PUBLISHED'¶ Absolute Published Catalog is a catalog that uses absolute links for everything, both in the links objects and in the asset hrefs.
-
RELATIVE_PUBLISHED
= 'RELATIVE_PUBLISHED'¶ Relative Published Catalog is a catalog that uses relative links for everything, but includes an absolute self link at the root catalog, to identify its online location.
-
SELF_CONTAINED
= 'SELF_CONTAINED'¶ A ‘self-contained catalog’ is one that is designed for portability. Users may want to download a catalog from online and be able to use it on their local computer, so all links need to be relative.
-
Collection Spec¶
These classes are representations of the Collection Spec.
Collection¶
-
class
pystac.
Collection
(id, description, extent, title=None, stac_extensions=None, href=None, extra_fields=None, catalog_type=None, license='proprietary', keywords=None, providers=None, properties=None, summaries=None)[source]¶ Bases:
pystac.catalog.Catalog
A Collection extends the Catalog spec with additional metadata that helps enable discovery.
Parameters: - id (str) – Identifier for the collection. Must be unique within the STAC.
- description (str) –
Detailed multi-line description to fully explain the collection. CommonMark 0.28 syntax MAY be used for rich text representation.
- extent (Extent) – Spatial and temporal extents that describe the bounds of all items contained within this Collection.
- title (str or None) – Optional short descriptive one-line title for the collection.
- stac_extensions (List[str]) – Optional list of extensions the Collection implements.
- href (str or None) – Optional HREF for this collection, which be set as the collection’s self link’s HREF.
- catalog_type (str or None) – Optional catalog type for this catalog. Must be one of the values in :class`~pystac.CatalogType`.
- license (str) – Collection’s license(s) as a SPDX License identifier, various, or proprietary. If collection includes data with multiple different licenses, use various and add a link for each. Defaults to ‘proprietary’.
- keywords (List[str]) – Optional list of keywords describing the collection.
- providers (List[Provider]) – Optional list of providers of this Collection.
- properties (dict) – Optional dict of common fields across referenced items.
- summaries (dict) – An optional map of property summaries, either a set of values or statistics such as a range.
- extra_fields (dict or None) – Extra fields that are part of the top-level JSON properties of the Collection.
-
id
¶ Identifier for the collection.
Type: str
-
description
¶ Detailed multi-line description to fully explain the collection.
Type: str
-
extent
¶ Spatial and temporal extents that describe the bounds of all items contained within this Collection.
Type: Extent
-
title
¶ Optional short descriptive one-line title for the collection.
Type: str or None
-
stac_extensions
¶ Optional list of extensions the Collection implements.
Type: List[str]
-
keywords
¶ Optional list of keywords describing the collection.
Type: List[str] or None
-
properties
¶ Optional dict of common fields across referenced items.
Type: dict or None
-
summaries
¶ An optional map of property summaries, either a set of values or statistics such as a range.
Type: dict or None
-
links
¶ A list of
Link
objects representing all links associated with this Collection.Type: List[Link]
-
extra_fields
¶ Extra fields that are part of the top-level JSON properties of the Catalog.
Type: dict or None
-
DEFAULT_FILE_NAME
= 'collection.json'¶ Default file name that will be given to this STAC object in a cononical format.
-
STAC_OBJECT_TYPE
= 'COLLECTION'¶
-
add_item
(item, title=None)[source]¶ Adds a link to an
Item
. This method will set the item’s parent to this object, and its root to this Catalog’s root.Parameters:
-
clone
()[source]¶ Clones this object.
Cloning an object will make a copy of all properties and links of the object; however, it will not make copies of the targets of links (i.e. it is not a deep copy). To copy a STACObject fully, with all linked elements also copied, use
STACObject.full_copy
.Returns: The clone of this object. Return type: STACObject
-
classmethod
from_dict
(d, href=None, root=None)[source]¶ Parses this STACObject from the passed in dictionary.
Parameters: - d (dict) – The dict to parse.
- href (str) – Optional href that is the file location of the object being parsed.
- root (Catalog or Collection) – Optional root of the catalog for this object. If provided, the root’s resolved object cache can be used to search for previously resolved instances of the STAC object.
Returns: The STACObject parsed from this dict.
Return type:
-
to_dict
(include_self_link=True)[source]¶ Generate a dictionary representing the JSON of this serialized object.
Parameters: include_self_link (bool) – If True, the dict will contain a self link to this object. If False, the self link will be omitted. Returns: A serializion of the object that can be written out as JSON. Return type: dict
Extent¶
-
class
pystac.
Extent
(spatial, temporal)[source]¶ Describes the spatio-temporal extents of a Collection.
Parameters: - spatial (SpatialExtent) – Potential spatial extent covered by the collection.
- temporal (TemporalExtent) – Potential temporal extent covered by the collection.
-
spatial
¶ Potential spatial extent covered by the collection.
Type: SpatialExtent
-
temporal
¶ Potential temporal extent covered by the collection.
Type: TemporalExtent
-
static
from_dict
(d)[source]¶ Constructs an Extent from a dict.
Returns: The Extent deserialized from the JSON dict. Return type: Extent
SpatialExtent¶
-
class
pystac.
SpatialExtent
(bboxes)[source]¶ Describes the spatial extent of a Collection.
Parameters: bboxes (List[List[float]]) – A list of bboxes that represent the spatial extent of the collection. Each bbox can be 2D or 3D. The length of the bbox array must be 2*n where n is the number of dimensions. For example, a 2D Collection with only one bbox would be [[xmin, ymin, xmax, ymax]] -
bboxes
¶ A list of bboxes that represent the spatial extent of the collection. Each bbox can be 2D or 3D. The length of the bbox array must be 2*n where n is the number of dimensions. For example, a 2D Collection with only one bbox would be [[xmin, ymin, xmax, ymax]]
Type: List[List[float]]
-
clone
()[source]¶ Clones this object.
Returns: The clone of this object. Return type: SpatialExtent
-
static
from_coordinates
(coordinates)[source]¶ Constructs a SpatialExtent from a set of coordinates.
This method will only produce a single bbox that covers all points in the coordinate set.
Parameters: coordinates (List[float]) – Coordinates to derive the bbox from. Returns: A SpatialExtent with a single bbox that covers the given coordinates. Return type: SpatialExtent
-
static
from_dict
(d)[source]¶ Constructs an SpatialExtent from a dict.
Returns: The SpatialExtent deserialized from the JSON dict. Return type: SpatialExtent
-
TemporalExtent¶
-
class
pystac.
TemporalExtent
(intervals)[source]¶ Describes the temporal extent of a Collection.
Parameters: - intervals (List[List[datetime]]) – A list of two datetimes wrapped in a list,
- the temporal extent of a Collection. Open date ranges are supported (representing) –
- setting either the start (by) –
- element of the interval) to None. (second) –
-
intervals
¶ A list of two datetimes wrapped in a list,
Type: List[List[datetime]]
-
representing the temporal extent of a Collection. Open date ranges are represented
-
by either the start
Type: the first element of the interval
-
second element of the interval) being None.
Note
Datetimes are required to be in UTC.
-
clone
()[source]¶ Clones this object.
Returns: The clone of this object. Return type: TemporalExtent
-
static
from_dict
(d)[source]¶ Constructs an TemporalExtent from a dict.
Returns: The TemporalExtent deserialized from the JSON dict. Return type: TemporalExtent
-
static
from_now
()[source]¶ Constructs an TemporalExtent with a single open interval that has the start time as the current time.
Returns: The resulting TemporalExtent. Return type: TemporalExtent
Provider¶
-
class
pystac.
Provider
(name, description=None, roles=None, url=None)[source]¶ Provides information about a provider of STAC data. A provider is any of the organizations that captured or processed the content of the collection and therefore influenced the data offered by this collection. May also include information about the final storage provider hosting the data.
Parameters: - name (str) – The name of the organization or the individual.
- description (str) – Optional multi-line description to add further provider information such as processing details for processors and producers, hosting details for hosts or basic contact information.
- roles (List[str]) – Optional roles of the provider. Any of licensor, producer, processor or host.
- url (str) – Optional homepage on which the provider describes the dataset and publishes contact information.
-
name
¶ The name of the organization or the individual.
Type: str
-
description
¶ Optional multi-line description to add further provider information such as processing details for processors and producers, hosting details for hosts or basic contact information.
Type: str
-
roles
¶ Optional roles of the provider. Any of licensor, producer, processor or host.
Type: List[str]
-
url
¶ Optional homepage on which the provider describes the dataset and publishes contact information.
Type: str
-
static
from_dict
(d)[source]¶ Constructs an Provider from a dict.
Returns: The Provider deserialized from the JSON dict. Return type: TemporalExtent
Item Spec¶
These classes are representations of the Item Spec.
Item¶
-
class
pystac.
Item
(id, geometry, bbox, datetime, properties, stac_extensions=None, href=None, collection=None, extra_fields=None)[source]¶ Bases:
pystac.stac_object.STACObject
An Item is the core granular entity in a STAC, containing the core metadata that enables any client to search or crawl online catalogs of spatial ‘assets’ - satellite imagery, derived data, DEM’s, etc.
Parameters: - id (str) – Provider identifier. Must be unique within the STAC.
- geometry (dict) – Defines the full footprint of the asset represented by this item, formatted according to RFC 7946, section 3.1 (GeoJSON).
- bbox (List[float] or None) – Bounding Box of the asset represented by this item using either 2D or 3D geometries. The length of the array must be 2*n where n is the number of dimensions. Could also be None in the case of a null geometry.
- datetime (datetime or None) – Datetime associated with this item. If None, a start_datetime and end_datetime must be supplied in the properties.
- properties (dict) – A dictionary of additional metadata for the item.
- stac_extensions (List[str]) – Optional list of extensions the Item implements.
- href (str or None) – Optional HREF for this item, which be set as the item’s self link’s HREF.
- collection (Collection or str) – The Collection or Collection ID that this item belongs to.
- extra_fields (dict or None) – Extra fields that are part of the top-level JSON properties of the Item.
-
id
¶ Provider identifier. Unique within the STAC.
Type: str
-
geometry
¶ Defines the full footprint of the asset represented by this item, formatted according to RFC 7946, section 3.1 (GeoJSON).
Type: dict
-
bbox
¶ Bounding Box of the asset represented by this item using either 2D or 3D geometries. The length of the array is 2*n where n is the number of dimensions. Could also be None in the case of a null geometry.
Type: List[float] or None
-
datetime
¶ Datetime associated with this item. If None, the start_datetime and end_datetime in the common_metadata will supply the datetime range of the Item.
Type: datetime or None
-
properties
¶ A dictionary of additional metadata for the item.
Type: dict
-
stac_extensions
¶ Optional list of extensions the Item implements.
Type: List[str] or None
-
collection
¶ Collection that this item is a part of.
Type: Collection or None
-
links
¶ A list of
Link
objects representing all links associated with this STACObject.Type: List[Link]
-
assets
¶ Dictionary of asset objects that can be downloaded, each with a unique key.
Type: Dict[str, Asset]
-
collection_id
¶ The Collection ID that this item belongs to, if any.
Type: str or None
-
extra_fields
¶ Extra fields that are part of the top-level JSON properties of the Item.
Type: dict or None
-
STAC_OBJECT_TYPE
= 'ITEM'¶
-
add_asset
(key, asset)[source]¶ Adds an Asset to this item.
Parameters: - key (str) – The unique key of this asset.
- asset (Asset) – The Asset to add.
-
clone
()[source]¶ Clones this object.
Cloning an object will make a copy of all properties and links of the object; however, it will not make copies of the targets of links (i.e. it is not a deep copy). To copy a STACObject fully, with all linked elements also copied, use
STACObject.full_copy
.Returns: The clone of this object. Return type: STACObject
-
common_metadata
¶ Access the item’s common metadat fields as a CommonMetadata object
Returns: contains all common metadata fields in the items properties Return type: CommonMetada
-
classmethod
from_dict
(d, href=None, root=None)[source]¶ Parses this STACObject from the passed in dictionary.
Parameters: - d (dict) – The dict to parse.
- href (str) – Optional href that is the file location of the object being parsed.
- root (Catalog or Collection) – Optional root of the catalog for this object. If provided, the root’s resolved object cache can be used to search for previously resolved instances of the STAC object.
Returns: The STACObject parsed from this dict.
Return type:
-
get_assets
()[source]¶ Get this item’s assets.
Returns: A copy of the dictionary of this item’s assets. Return type: Dict[str, Asset]
-
get_collection
()[source]¶ Gets the collection of this item, if one exists.
Returns: If this item belongs to a collection, returns a reference to the collection. Otherwise returns None. Return type: Collection or None
-
get_datetime
(asset=None)[source]¶ Gets an Item or an Asset datetime.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value.
Returns: datetime or None
-
make_asset_hrefs_absolute
()[source]¶ Modify each asset’s HREF to be absolute.
Any asset HREFs that are relative will be modified to absolute based on this item’s self HREF.
Returns: self Return type: Item
-
make_asset_hrefs_relative
()[source]¶ Modify each asset’s HREF to be relative to this item’s self HREF.
Returns: self Return type: Item
-
set_collection
(collection)[source]¶ Set the collection of this item.
This method will replace any existing Collection link and attribute for this item.
Parameters: collection (Collection or None) – The collection to set as this item’s collection. If None, will clear the collection. Returns: self Return type: Item
-
set_datetime
(datetime, asset=None)[source]¶ Set an Item or an Asset datetime.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_self_href
(href)[source]¶ Sets the absolute HREF that is represented by the
rel == 'self'
Link
.Changing the self HREF of the item will ensure that all asset HREFs remain valid. If asset HREFs are relative, the HREFs will change to point to the same location based on the new item self HREF, either by making them relative to the new location or making them absolute links if the new location does not share the same protocol as the old location.
Parameters: href (str) – The absolute HREF of this object. If the given HREF is not absolute, it will be transformed to an absolute HREF based on the current working directory. If this is None the call will clear the self HREF link.
-
to_dict
(include_self_link=True)[source]¶ Generate a dictionary representing the JSON of this serialized object.
Parameters: include_self_link (bool) – If True, the dict will contain a self link to this object. If False, the self link will be omitted. Returns: A serializion of the object that can be written out as JSON. Return type: dict
Asset¶
-
class
pystac.
Asset
(href, title=None, description=None, media_type=None, roles=None, properties=None)[source]¶ An object that contains a link to data associated with the Item that can be downloaded or streamed.
Parameters: - href (str) – Link to the asset object. Relative and absolute links are both allowed.
- title (str) – Optional displayed title for clients and users.
- description (str) – A description of the Asset providing additional details, such as how it was processed or created. CommonMark 0.29 syntax MAY be used for rich text representation.
- media_type (str) – Optional description of the media type. Registered Media Types
are preferred. See
MediaType
for common media types. - roles ([str]) – Optional, Semantic roles (i.e. thumbnail, overview, data, metadata) of the asset.
- properties (dict) – Optional, additional properties for this asset. This is used by extensions as a way to serialize and deserialize properties on asset object JSON.
-
href
¶ Link to the asset object. Relative and absolute links are both allowed.
Type: str
-
title
¶ Optional displayed title for clients and users.
Type: str
-
description
¶ A description of the Asset providing additional details, such as how it was processed or created. CommonMark 0.29 syntax MAY be used for rich text representation.
Type: str
-
media_type
¶ Optional description of the media type. Registered Media Types are preferred. See
MediaType
for common media types.Type: str
-
properties
¶ Optional, additional properties for this asset. This is used by extensions as a way to serialize and deserialize properties on asset object JSON.
Type: dict
-
static
from_dict
(d)[source]¶ Constructs an Asset from a dict.
Returns: The Asset deserialized from the JSON dict. Return type: Asset
-
get_absolute_href
()[source]¶ Gets the absolute href for this asset, if possible.
If this Asset has no associated Item, this will return whatever the href is (as it cannot determine the absolute path, if the asset href is relative).
Returns: The absolute HREF of this asset, or a relative HREF is an abslolute HREF cannot be determined. Return type: str
CommonMetadata¶
-
class
pystac.
CommonMetadata
(properties)[source]¶ Object containing fields that are not included in core item schema but are still commonly used. All attributes are defined within the properties of this item and are optional
Parameters: properties (dict) – Dictionary of attributes that is the Item’s properties -
constellation
¶ Get or set the name of the constellation associate with an item
Returns: Name of the constellation to which the platform belongs Return type: str
-
created
¶ Get or set the metadata file’s creation date. All datetime attributes have setters that can take either a string or a datetime, but always stores the attribute as a string
Returns: Creation date and time of the metadata file Return type: datetime
-
description
¶ Get or set the item’s description
Returns: Detailed description of the item Return type: str
-
end_datetime
¶ Get or set the item’s end_datetime. All datetime attributes have setters that can take either a string or a datetime, but always stores the attribute as a string
Returns: End date and time for the item Return type: datetime
-
get_constellation
(asset=None)[source]¶ Gets an Item or an Asset constellation.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: str
-
get_created
(asset=None)[source]¶ Gets an Item or an Asset created time.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value.
Note
created
andupdated
have different meaning depending on where they are used. If those fields are available in the Item properties, it’s referencing to the creation and update times of the metadata. Having those fields in the Item assets refers to the creation and update times of the actual data linked to in the Asset Object.Returns: datetime
-
get_end_datetime
(asset=None)[source]¶ Gets an Item or an Asset end_datetime.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: datetime
-
get_gsd
(asset=None)[source]¶ Gets an Item or an Asset gsd.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: float
-
get_instruments
(asset=None)[source]¶ Gets an Item or an Asset instruments.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: List[str]
-
get_license
(asset=None)[source]¶ Gets an Item or an Asset license.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: str
-
get_mission
(asset=None)[source]¶ Gets an Item or an Asset mission.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: str
-
get_platform
(asset=None)[source]¶ Gets an Item or an Asset platform.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: str
-
get_providers
(asset=None)[source]¶ Gets an Item or an Asset providers.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: List[Provider]
-
get_start_datetime
(asset=None)[source]¶ Gets an Item or an Asset start_datetime.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: datetime
-
get_updated
(asset=None)[source]¶ Gets an Item or an Asset updated time.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value.
Note
created
andupdated
have different meaning depending on where they are used. If those fields are available in the Item properties, it’s referencing to the creation and update times of the metadata. Having those fields in the Item assets refers to the creation and update times of the actual data linked to in the Asset Object.Returns: datetime
-
gsd
¶ Get or sets the Ground Sample Distance at the sensor.
Returns: Ground Sample Distance at the senso Return type: [float]
-
instruments
¶ Get or set the names of the instruments used
Returns: Name(s) of instrument(s) used Return type: List[str]
-
license
¶ Get or set the current license
Returns: Item’s license(s), either SPDX identifier of ‘various’ Return type: str
-
mission
¶ Get or set the name of the mission associated with an item
Returns: Name of the mission in which data are collected Return type: str
-
platform
¶ Get or set the item’s platform attribute
Returns: Unique name of the specific platform to which the instrument is attached Return type: str
-
providers
¶ Get or set a list of the item’s providers. The setter can take either a Provider object or a dict but always stores each provider as a dict
Returns: List of organizations that captured or processed the data, encoded as Provider objects Return type: List[Provider]
-
set_constellation
(constellation, asset=None)[source]¶ Set an Item or an Asset constellation.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_created
(created, asset=None)[source]¶ Set an Item or an Asset created time.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_end_datetime
(end_datetime, asset=None)[source]¶ Set an Item or an Asset end_datetime.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_gsd
(gsd, asset=None)[source]¶ Set an Item or an Asset gsd.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_instruments
(instruments, asset=None)[source]¶ Set an Item or an Asset instruments.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_license
(license, asset=None)[source]¶ Set an Item or an Asset license.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_mission
(mission, asset=None)[source]¶ Set an Item or an Asset mission.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_platform
(platform, asset=None)[source]¶ Set an Item or an Asset platform.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_providers
(providers, asset=None)[source]¶ Set an Item or an Asset providers.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_start_datetime
(start_datetime, asset=None)[source]¶ Set an Item or an Asset start_datetime.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_updated
(updated, asset=None)[source]¶ Set an Item or an Asset updated time.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
start_datetime
¶ Get or set the item’s start_datetime. All datetime attributes have setters that can take either a string or a datetime, but always stores the attribute as a string
Returns: Start date and time for the item Return type: datetime
-
title
¶ Get or set the item’s title
Returns: Human readable title describing the item Return type: str
-
updated
¶ Get or set the metadata file’s update date. All datetime attributes have setters that can take either a string or a datetime, but always stores the attribute as a string
Note
created
andupdated
have different meaning depending on where they are used. If those fields are available in the Item properties, it’s referencing to the creation and update times of the metadata. Having those fields in the Item assets refers to the creation and update times of the actual data linked to in the Asset Object.Returns: - Date and time that the metadata file was most recently
- updated
Return type: datetime
-
Links¶
Catalogs, Collections and Items have links, which allow users to crawl catalogs.
Link¶
-
class
pystac.
Link
(rel, target, media_type=None, title=None, properties=None)[source]¶ A link is connects a
STACObject
to another entity.The target of a link can be either another STACObject, or an HREF. When serialized, links always refer to the HREF of the target. Links are lazily deserialized - this is, when you read in a link, it does not automatically load in the STACObject that is the target (if the link is pointing to a STACObject). When a user is crawling through a catalog or when additional metadata is required, PySTAC uses the
Link.resolve_stac_object
method to load in and deserialize STACObjects. This mechanism is used within the PySTAC codebase and normally does not need to be considered by the user - ideally the lazy deserialization of STACObjects is transparent to clients of PySTAC.Parameters: - rel (str) – The relation of the link (e.g. ‘child’, ‘item’)
- target (str or STACObject) – The target of the link. If the link is unresolved, or the link is to something that is not a STACObject, the target is an HREF. If resolved, the target is a STACObject.
- media_type (str) – Optional description of the media type. Registered Media Types
are preferred. See
MediaType
for common media types. - title (str) – Optional title for this link.
- properties (dict) – Optional, additional properties for this link. This is used by extensions as a way to serialize and deserialize properties on link object JSON.
-
rel
¶ The relation of the link (e.g. ‘child’, ‘item’)
Type: str
-
target
¶ The target of the link. If the link is unresolved, or the link is to something that is not a STACObject, the target is an HREF. If resolved, the target is a STACObject.
Type: str or STACObject
-
media_type
¶ Optional description of the media type. Registered Media Types are preferred. See
MediaType
for common media types.Type: str or None
-
title
¶ Optional title for this link.
Type: str or None
-
properties
¶ Optional, additional properties for this link. This is used by extensions as a way to serialize and deserialize properties on link object JSON.
Type: dict or None
-
owner
¶ The owner of this link. The link will use its owner’s root catalog
ResolvedObjectCache
to resolve objects, and will create absolute HREFs from relative HREFs against the owner’s self HREF.Type: STACObject or None
-
clone
()[source]¶ Clones this link.
This makes a copy of all link information, but does not clone a STACObject if one is the target of this link.
Returns: The cloned link. Return type: Link
-
static
from_dict
(d)[source]¶ Deserializes a Link from a dict.
Parameters: d (dict) – The dict that represents the Link in JSON Returns: Link instance constructed from the dict. Return type: Link
-
get_absolute_href
()[source]¶ Gets the absolute href for this link, if possible.
Returns: Returns this link’s HREF. It attempts to derive an absolute HREF from this link; however, if the link is relative, has no owner, and has an unresolved target, this will return a relative HREF. Return type: str
-
get_href
()[source]¶ Gets the HREF for this link.
Returns: Returns this link’s HREF. If there is an owner of the link and the root catalog (if there is one) is of type RELATIVE_PUBLISHED, then the HREF returned will be relative. In all other cases, this method will return an absolute HREF. Return type: str
-
is_resolved
()[source]¶ Determines if the link’s target is a resolved STACObject.
Returns: True if this link is resolved. Return type: bool
-
resolve_stac_object
(root=None)[source]¶ Resolves a STAC object from the HREF of this link, if the link is not already resolved.
Parameters: root (Catalog or Collection) – Optional root of the catalog for this link. If provided, the root’s resolved object cache is used to search for previously resolved instances of the STAC object.
-
set_owner
(owner)[source]¶ Sets the owner of this link.
Parameters: owner (STACObject) – The owner of this link.
LinkType¶
MediaType¶
-
class
pystac.
MediaType
[source]¶ A list of common media types that can be used in STAC Asset and Link metadata.
-
COG
= 'image/tiff; application=geotiff; profile=cloud-optimized'¶
-
GEOJSON
= 'application/geo+json'¶
-
GEOPACKAGE
= 'application/geopackage+sqlite3'¶
-
GEOTIFF
= 'image/tiff; application=geotiff'¶
-
HDF
= 'application/x-hdf'¶
-
HDF5
= 'application/x-hdf5'¶
-
JPEG
= 'image/jpeg'¶
-
JPEG2000
= 'image/jp2'¶
-
JSON
= 'application/json'¶
-
PNG
= 'image/png'¶
-
TEXT
= 'text/plain'¶
-
TIFF
= 'image/tiff'¶
-
XML
= 'application/xml'¶
-
IO¶
STAC_IO¶
STAC_IO is the utility mechanism that PySTAC uses for reading and writing. Users of PySTAC can hook into PySTAC by overriding members to utilize their own IO methods.
-
class
pystac.
STAC_IO
[source]¶ Methods used to read and save STAC json. Allows users of the library to set their own methods (e.g. for reading and writing from cloud storage)
-
default_write_text_method
(txt)[source]¶ Default method for writing text. Only handles local file paths.
-
classmethod
read_json
(uri)[source]¶ Read a dict from the given URI.
Parameters: uri (str) – The URI from which to read. Returns: A dict representation of the JSON contained in the file at the given uri. Return type: dict Note
This method uses the
STAC_IO.read_text_method
. If you want to modify the behavior of STAC_IO in order to enable additional URI types, replace that member with your own implementation.
-
classmethod
read_stac_object
(uri, root=None)[source]¶ Read a STACObject from a JSON file at the given URI.
Parameters: - uri (str) – The URI from which to read.
- root (Catalog or Collection) – Optional root of the catalog for this object. If provided, the root’s resolved object cache can be used to search for previously resolved instances of the STAC object.
Returns: The deserialized STACObject from the serialized JSON contained in the file at the given uri.
Return type: Note
This method uses the
STAC_IO.read_text_method
. If you want to modify the behavior of STAC_IO in order to enable additional URI types, replace that member with your own implementation.
-
classmethod
read_text
(uri)[source]¶ Read text from the given URI.
Parameters: uri (str) – The URI from which to read text. Returns: The text contained in the file at the location specified by the uri. Return type: str Note
This method uses the
STAC_IO.read_text_method
. If you want to modify the behavior of STAC_IO in order to enable additional URI types, replace that member with your own implementation.
-
read_text_method
()¶ Users of PySTAC can replace the read_text_method in order to expand the ability of PySTAC to read different file systems. For example, a client of the library might replace this class member in it’s own __init__.py with a method that can read from cloud storage.
-
classmethod
save_json
(uri, json_dict)[source]¶ Write a dict to the given URI as JSON.
Parameters: - uri (str) – The URI of the file to write the text to.
- json_dict (dict) – The JSON dict to write.
Note
This method uses the
STAC_IO.write_text_method
. If you want to modify the behavior of STAC_IO in order to enable additional URI types, replace that member with your own implementation.
-
stac_object_from_dict
(href=None, root=None)¶ Determines how to deserialize a dictionary into a STAC object.
Parameters: - d (dict) – The dict to parse.
- href (str) – Optional href that is the file location of the object being parsed.
- root (Catalog or Collection) – Optional root of the catalog for this object. If provided, the root’s resolved object cache can be used to search for previously resolved instances of the STAC object.
Note: This is used internally in STAC_IO to deserialize STAC Objects. It is in the top level __init__ in order to avoid circular dependencies.
-
classmethod
write_text
(uri, txt)[source]¶ Write the given text to a file at the given URI.
Parameters: - uri (str) – The URI of the file to write the text to.
- txt (str) – The text to write.
Note
This method uses the
STAC_IO.write_text_method
. If you want to modify the behavior of STAC_IO in order to enable additional URI types, replace that member with your own implementation.
-
write_text_method
(txt)¶ Users of PySTAC can replace the writte_text_method in order to expand the ability of PySTAC to write to different file systems. For example, a client of the library might replace this class member in it’s own __init__.py with a method that can read from cloud storage.
-
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.
Templating¶
-
class
pystac.layout.
LayoutTemplate
(template, defaults=None)[source]¶ Represents a template that can be used for deriving paths or other information based on properties of STAC objects supplied as a template string.
Template strings use variables that can be pulled out of Catalogs, Collections and Items. The variable names can represent properties on the object itself, or keys in the dictionaries of the properties or extra_fields on the object (if they exist). The search order is as follows:
- The object’s attributes
- Keys in the
properties
attribute, if it exists. - Keys in the
extra_fields
attribute, if it exists.
Some special keys can be used in template variables:
Template variable Meaning year
The year of an Item’s datetime, or start_datetime if datetime is null month
The month of an Item’s datetime, or start_datetime if datetime is null day
The day of an Item’s datetime, or start_datetime if datetime is null date
The date (iso format) of an Item’s datetime, or start_datetime if datetime is null collection
The collection ID of an Item’s collection. Examples:
# Uses the year, month and day of the item template = LayoutTemplate("${year}/${month}/${day}") # Uses a custom extension properties found on in the item properties. template = LayoutTemplate("${landsat:path}/${landsat:row}") # Uses the collection ID and a common metadata property for an item. template = LayoutTemplate("${collection}/${common_metadata.license}")
Parameters: - template (str) – The template string to use.
- defaults (dict) – A dictionary of template vars to values. These values will be used in case a value cannot be derived from a stac object.
-
get_template_values
(stac_object)[source]¶ Gets a dictionary of template variables to values derived from the given stac_object. If the template vars cannot be found in the stac object, and defaults was supplied to this template, a default value is used; if there is no default then this will raise an error.
Parameters: stac_object (STACObject) – The STACObject to derive template variable values from. Returns: - A dictionary with keys being the template variables
- and values being the respective values based on the given stac object.
Return type: [dict] Raises: TemplateError
– If a value for a template variable cannot be derived from the stac object and there is no default, this error will be raised.
-
substitute
(stac_object)[source]¶ Substitutes the values derived from
get_template_values()
into the template string for this template.Parameters: stac_object (STACObject) – The STACObject to derive template variable values from. Returns: - The original template supplied to this LayoutTemplate
- with template variables replaced by the values derived from this stac object.
Return type: [str] Raises: TemplateError
– If a value for a template variable cannot be derived from the stac object and there is no default, this error will be raised.
-
class
pystac.layout.
TemplateError
[source]¶ Exception thrown when an error occurs during converting a template string into data for
LayoutTemplate
HREF Layout Strategies¶
-
class
pystac.layout.
BestPracticesLayoutStrategy
[source]¶ Layout strategy that represents the catalog layout described in the STAC Best Practices documentation
For a root catalog or collection, this will use the filename ‘catalog.json’ or ‘collection.json’ to the given directory. For a non-root catalog or collection, the ID will be used as a subdirectory, e.g.
${id}/catalog.json
or${id}/collection.json
. For items, a subdirectory with a name of the item ID will be made, and the item ID will be used in the filename, i.e.${id}/${id}.json
All paths are appended to the parent directory.
-
class
pystac.layout.
TemplateLayoutStrategy
(catalog_template=None, collection_template=None, item_template=None, fallback_strategy=None)[source]¶ Layout strategy that can take strings to be supplied to
LayoutTemplate
s to derive paths. Template strings can be supplied for catalogs, collections and items separately. If no template is supplied, a fallback layout strategy is supplied, which defaults to theBestPracticesLayoutStrategy
.All templated paths will be joined with the parent directory of the stac object.
Parameters: - catalog_template (str) – The template string to use for catalog paths.
Must be a valid template string that can be used by
LayoutTemplate
- collection_template (str) – The template string to use for collection paths.
Must be a valid template string that can be used by
LayoutTemplate
- item_template (str) – The template string to use for item paths.
Must be a valid template string that can be used by
LayoutTemplate
- fallback_strategy (HrefLayoutStrategy) – The fallback strategy to
use if a template is not provided. Defaults to
BestPracticesLayoutStrategy
- catalog_template (str) – The template string to use for catalog paths.
Must be a valid template string that can be used by
-
class
pystac.layout.
CustomLayoutStrategy
(catalog_func=None, collection_func=None, item_func=None, fallback_strategy=None)[source]¶ Layout strategy that allows users to supply functions to dictate stac object paths.
Parameters: - catalog_func (Callable[Catalog, str, bool] -> str) – A function that takes an catalog, a parent directory, and a flag specifying whether or not this catalog is the root. If it is the root, its usually best to not create a subdirectory and put the Catalog file directly in the parent directory. Must return the string path.
- collection_func (Callable[Catalog, str, bool] -> str) – A function that
is used for collections in the same manner at
catalog_func
. This takes the same parameters. - item_func (Callable[Catalog, str] -> str) – A function that takes an item and a parent directory and returns the path to be used for the item.
- fallback_strategy (HrefLayoutStrategy) – The fallback strategy to
use if a function is not provided for a stac object type. Defaults to
BestPracticesLayoutStrategy
Extensions¶
-
class
pystac.extensions.
Extensions
[source]¶ Enumerates the IDs of common extensions.
-
CHECKSUM
= 'checksum'¶
-
COLLECTION_ASSETS
= 'collection-assets'¶
-
DATACUBE
= 'datacube'¶
-
EO
= 'eo'¶
-
FILE
= 'file'¶
-
ITEM_ASSETS
= 'item-assets'¶
-
LABEL
= 'label'¶
-
POINTCLOUD
= 'pointcloud'¶
-
PROJECTION
= 'projection'¶
-
SAR
= 'sar'¶
-
SAT
= 'sat'¶
-
SCIENTIFIC
= 'scientific'¶
-
SINGLE_FILE_STAC
= 'single-file-stac'¶
-
TILED_ASSETS
= 'tiled-assets'¶
-
TIMESTAMPS
= 'timestamps'¶
-
VERSION
= 'version'¶
-
VIEW
= 'view'¶
-
ExtensionIndex¶
An ExtensionIndex is accessed through the STACObject.ext
property and is the primary way to access information and functionality around STAC extensions.
-
class
pystac.stac_object.
ExtensionIndex
(stac_object)[source]¶ Defines methods for accessing extension functionality.
To access a specific extension, use the __getitem__ on this class with the extension ID:
# Access the "bands" property on the eo extension. item.ext['eo'].bands
-
__getattr__
(extension_id)[source]¶ Gets an extension based on a dynamic attribute.
This takes the attribute name and passes it to __getitem__.
This allows the following two lines to be equivalent:
item.ext["label"].label_properties item.ext.label.label_properties
-
__getitem__
(extension_id)[source]¶ Gets the extension object for the given extension.
Returns: The extension object through which you can access the extension functionality for the extension represented by the extension_id. Return type: CatalogExtension or CollectionExtension or ItemExtension
-
enable
(extension_id)[source]¶ Enables a stac extension for the given object. If the object already enables the extension, no action is taken. If it does not, the extension ID is added to the object’s stac_extension property.
Parameters: - extension_id (str) – The extension ID representing the extension
- object should implement (the) –
-
EO Extension¶
These classes are representations of the EO Extension Spec.
EOItemExt¶
-
class
pystac.extensions.eo.
EOItemExt
(item)[source]¶ Bases:
pystac.extensions.base.ItemExtension
EOItemExt is the extension of the Item in the eo extension which represents a snapshot of the earth for a single date and time.
Parameters: item (Item) – The item to be extended. Note
Using EOItemExt to directly wrap an item will add the ‘eo’ extension ID to the item’s stac_extensions.
-
apply
(bands, cloud_cover=None)[source]¶ Applies label extension properties to the extended Item.
Parameters: - bands (List[Band]) – a list of
Band
objects that represent the available bands. - cloud_cover (float or None) – The estimate of cloud cover as a percentage (0-100) of the entire scene. If not available the field should not be provided.
- bands (List[Band]) – a list of
-
bands
¶ - Get or sets a list of
Band
objects that represent - the available bands.
Returns: List[Band] - Get or sets a list of
-
cloud_cover
¶ - Get or sets the estimate of cloud cover as a percentage (0-100) of the
- entire scene. If not available the field should not be provided.
Returns: float or None
-
get_bands
(asset=None)[source]¶ Gets an Item or an Asset bands.
If an Asset is supplied and the bands property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value or all the asset’s eo bands
Returns: List[Band]
-
get_cloud_cover
(asset=None)[source]¶ Gets an Item or an Asset cloud_cover.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: float
-
Band¶
-
class
pystac.extensions.eo.
Band
(properties)[source]¶ Represents Band information attached to an Item that implements the eo extension.
Use Band.create to create a new Band.
-
apply
(name, common_name=None, description=None, center_wavelength=None, full_width_half_max=None)[source]¶ Sets the properties for this Band.
Parameters: - name (str) – The name of the band (e.g., “B01”, “B02”, “B1”, “B5”, “QA”).
- common_name (str) – The name commonly used to refer to the band to make it easier to search for bands across instruments. See the list of accepted common names.
- description (str) – Description to fully explain the band.
- center_wavelength (float) – The center wavelength of the band, in micrometers (μm).
- full_width_half_max (float) – Full width at half maximum (FWHM). The width of the band, as measured at half the maximum transmission, in micrometers (μm).
-
static
band_description
(common_name)[source]¶ Returns a description of the band for one with a common name.
Parameters: common_name (str) – The common band name. Must be one of the list of accepted common names.
Returns: If a recognized common name, returns a description including the band range. Otherwise returns None. Return type: str or None
-
static
band_range
(common_name)[source]¶ Gets the band range for a common band name.
Parameters: common_name (str) – The common band name. Must be one of the list of accepted common names.
Returns: The band range for this name as (min, max), or None if this is not a recognized common name. Return type: Tuple[float, float] or None
-
center_wavelength
¶ Get or sets the center wavelength of the band, in micrometers (μm).
Returns: float
-
common_name
¶ - Get or sets the name commonly used to refer to the band to make it easier
- to search for bands across instruments. See the list of accepted common names.
Returns: str
-
classmethod
create
(name, common_name=None, description=None, center_wavelength=None, full_width_half_max=None)[source]¶ Creates a new band.
Parameters: - name (str) – The name of the band (e.g., “B01”, “B02”, “B1”, “B5”, “QA”).
- common_name (str) –
The name commonly used to refer to the band to make it easier to search for bands across instruments. See the list of accepted common names.
- description (str) – Description to fully explain the band.
- center_wavelength (float) – The center wavelength of the band, in micrometers (μm).
- full_width_half_max (float) – Full width at half maximum (FWHM). The width of the band, as measured at half the maximum transmission, in micrometers (μm).
-
description
¶ Get or sets the description to fully explain the band. CommonMark 0.29 syntax MAY be used for rich text representation.
Returns: str
-
full_width_half_max
¶ - Get or sets the full width at half maximum (FWHM). The width of the band,
- as measured at half the maximum transmission, in micrometers (μm).
Returns: [float]
-
name
¶ Get or sets the name of the band (e.g., “B01”, “B02”, “B1”, “B5”, “QA”).
Returns: str
-
Label Extension¶
These classes are representations of the Label Extension Spec.
LabelItemExt¶
-
class
pystac.extensions.label.
LabelItemExt
(item)[source]¶ Bases:
pystac.extensions.base.ItemExtension
A LabelItemExt is the extension of the Item in the label extension which represents a polygon, set of polygons, or raster data defining labels and label metadata and should be part of a Collection.
Parameters: item (Item) – The item to be extended. Note
Using LabelItemExt to directly wrap an item will add the ‘label’ extension ID to the item’s stac_extensions.
-
add_geojson_labels
(href, title=None, properties=None)[source]¶ Adds a GeoJSON label asset to this LabelItem.
Parameters: - href (str) – Link to the asset object. Relative and absolute links are both allowed.
- title (str) – Optional displayed title for clients and users.
- properties (dict) – Optional, additional properties for this asset. This is used by extensions as a way to serialize and deserialize properties on asset object JSON.
-
add_labels
(href, title=None, media_type=None, properties=None)[source]¶ Adds a label asset to this LabelItem.
Parameters: - href (str) – Link to the asset object. Relative and absolute links are both allowed.
- title (str) – Optional displayed title for clients and users.
- media_type (str) – Optional description of the media type. Registered Media Types
are preferred. See
MediaType
for common media types. - properties (dict) – Optional, additional properties for this asset. This is used by extensions as a way to serialize and deserialize properties on asset object JSON.
-
add_source
(source_item, title=None, assets=None)[source]¶ Adds a link to a source item.
Parameters: - source_item (Item) – Source imagery that the LabelItem applies to.
- title (str) – Optional title for the link.
- assets (List[str]) – Optional list of assets that determine what assets in the source item this label item data applies to.
-
apply
(label_description, label_type, label_properties=None, label_classes=None, label_tasks=None, label_methods=None, label_overviews=None)[source]¶ Applies label extension properties to the extended Item.
Parameters: - label_description (str) – A description of the label, how it was created, and what it is recommended for
- label_type (str) – An ENUM of either vector label type or raster label type. Use
one of
LabelType
. - label_properties (list or None) – These are the names of the property field(s) in each Feature of the label asset’s FeatureCollection that contains the classes (keywords from label:classes if the property defines classes). If labels are rasters, this should be None.
- label_classes (List[LabelClass]) – Optional, but reqiured if ussing categorical data. A list of LabelClasses defining the list of possible class names for each label:properties. (e.g., tree, building, car, hippo)
- label_tasks (List[str]) – Recommended to be a subset of ‘regression’, ‘classification’, ‘detection’, or ‘segmentation’, but may be an arbitrary value.
- label_methods – Recommended to be a subset of ‘automated’ or ‘manual’, but may be an arbitrary value.
- label_overviews (List[LabelOverview]) – Optional list of LabelOverview classes that store counts (for classification-type data) or summary statistics (for continuous numerical/regression data).
-
get_sources
()[source]¶ Gets any source items that describe the source imagery used to generate this LabelItem.
Returns: A possibly empty list of source imagery items. Determined by links of this LabelItem that have rel=='source'
.Return type: Generator[Items]
-
label_classes
¶ Get or set a list of LabelClasses defining the list of possible class names for each label:properties. (e.g., tree, building, car, hippo).
Optional, but reqiured if using categorical data.
Returns: List[LabelClasses] or None
-
label_description
¶ Get or sets a description of the label, how it was created, and what it is recommended for.
Returns: str
-
label_methods
¶ - Get or set a list of methods used for labeling. Usually a subset of ‘automated’ or ‘manual’,
- but may be arbitrary values.
Returns: List[str] or None
-
label_overviews
¶ Get or set a list of LabelOverview classes that store counts (for classification-type data) or summary statistics (for continuous numerical/regression data).
Returns: List[LabelOverview] or None
-
label_properties
¶ Label Properties
Gets or sets the names of the property field(s) in each Feature of the label asset’s FeatureCollection that contains the classes (keywords from label:classes if the property defines classes). If labels are rasters, this should be None.
Returns: List[str] or None
-
label_tasks
¶ - Get or set a list of tasks these labels apply to. Usually a subset of ‘regression’,
- ‘classification’, ‘detection’, or ‘segmentation’, but may be arbitrary values.
Returns: List[str] or None
-
label_type
¶ Gets or sets an ENUM of either vector label type or raster label type (one of
LabelType
).Returns: str
-
LabelType¶
LabelClasses¶
-
class
pystac.extensions.label.
LabelClasses
(properties)[source]¶ Defines the list of possible class names (e.g., tree, building, car, hippo)
Use LabelClasses.create to create a new instance of LabelClasses from property values.
-
apply
(classes, name=None)[source]¶ Sets the properties for this LabelClasses.
Parameters: - classes (List[str] or List[int] or List[float]) – The different possible class values.
- name (str) – The property key within the asset’s each Feature corresponding to class labels. If labels are raster-formatted, do not supply; required otherwise.
-
classes
¶ Get or sets the class values.
Returns: List[str] or List[int] or List[float]
-
classmethod
create
(classes, name=None)[source]¶ Creates a new LabelClasses.
Parameters: - classes (List[str] or List[int] or List[float]) – The different possible class values.
- name (str) – The property key within the asset’s each Feature corresponding to class labels. If labels are raster-formatted, do not supply; required otherwise.
Returns: LabelClasses
-
name
¶ Get or sets the property key within the asset’s each Feature corresponding to class labels. If labels are raster-formatted, do not supply; required otherwise.
Returns: str
-
LabelOverview¶
-
class
pystac.extensions.label.
LabelOverview
(properties)[source]¶ Stores counts (for classification-type data) or summary statistics (for continuous numerical/regression data).
Use LabelOverview.create to create a new LabelOverview.
-
apply
(property_key, counts=None, statistics=None)[source]¶ Sets the properties for this LabelOverview.
Either
counts
orstatistics
, or both, can be placed in an overview; at least one is required.Parameters: - property_key (str) – The property key within the asset corresponding to class labels.
- counts (List[LabelCounts]) – Optional list of LabelCounts containing counts for categorical data.
- statistics (List[Statistics]) – Optional list of Statistics containing statistics for regression/continuous numeric value data.
-
counts
¶ Get or sets the list of LabelCounts containing counts for categorical data.
Returns: List[LabelCount]
-
classmethod
create
(property_key, counts=None, statistics=None)[source]¶ Creates a new LabelOverview.
Either
counts
orstatistics
, or both, can be placed in an overview; at least one is required.Parameters: - property_key (str) – The property key within the asset corresponding to class labels.
- counts (List[LabelCounts]) – Optional list of LabelCounts containing counts for categorical data.
- statistics (List[Statistics]) – Optional list of Statistics containing statistics for regression/continuous numeric value data.
-
merge_counts
(other)[source]¶ Merges the counts associated with this overview with another overview. Creates a new LabelOverview.
Parameters: other (LabelOverview) – The other LabelOverview to merge. Returns: A new LabelOverview with the counts merged. This will drop any statistics associated with either of the LabelOverviews. Return type: LabelOverview
-
property_key
¶ Get or sets the property key within the asset corresponding to class labels.
Returns: str
-
statistics
¶ Get or sets the list of Statistics containing statistics for regression/continuous numeric value data.
Returns: List[Statistics]
-
LabelCount¶
-
class
pystac.extensions.label.
LabelCount
(properties)[source]¶ Contains counts for categorical data.
Use LabelCount.create to create a new LabelCount
-
apply
(name, count)[source]¶ Sets the properties for this LabelCount.
Parameters: - name (str) – One of the different possible classes within the property.
- count (int) – The number of occurrences of the class.
-
count
¶ Get or sets the number of occurrences of the class.
Returns: int
-
classmethod
create
(name, count)[source]¶ Creates a LabelCount.
Parameters: - name (str) – One of the different possible classes within the property.
- count (int) – The number of occurrences of the class.
-
name
¶ Get or sets the class that this count represents.
Returns: str
-
LabelStatistics¶
-
class
pystac.extensions.label.
LabelStatistics
(properties)[source]¶ Contains statistics for regression/continuous numeric value data.
Use LabelStatistics.create to create a new instance.
-
apply
(name, value)[source]¶ Sets the property values for this instance.
Parameters: - name (str) – The name of the statistic being reported.
- value (float) – The value of the statistic
-
classmethod
create
(name, value)[source]¶ Sets the property values for this instance.
Parameters: - name (str) – The name of the statistic being reported.
- value (float) – The value of the statistic
-
name
¶ Get or sets the name of the statistic being reported.
Returns: str
-
to_dict
()[source]¶ Returns the dictionary representing the JSON of this LabelStatistics.
Returns: The wrapped dict of the LabelStatistics that can be written out as JSON. Return type: dict
-
value
¶ Get or sets the value of the statistic
Returns: int or float
-
Pointcloud Extension¶
Implements the Point Cloud Extension.
PointcloudItemExt¶
-
class
pystac.extensions.pointcloud.
PointcloudItemExt
(item)[source]¶ Bases:
pystac.extensions.base.ItemExtension
PointcloudItemExt is the extension of an Item in the PointCloud Extension. The Pointclout extension adds pointcloud information to STAC Items.
Parameters: item (Item) – The item to be extended. -
apply
(count, type, encoding, schemas, density=None, statistics=None, epsg=None)[source]¶ Applies Pointcloud extension properties to the extended Item.
Parameters: - count (int) – REQUIRED. The number of points in the cloud.
- type (str) – REQUIRED. Phenomenology type for the point cloud. Possible valid values might include lidar, eopc, radar, sonar, or otherThe type of file or data format of the cloud.
- encoding (str) – REQUIRED. Content encoding or format of the data.
- schemas (List[dict]) – REQUIRED. A sequential array of items that define the dimensions and their types.
- density (dict or None) – Number of points per square unit area.
- statistics (List[int] or None) – A sequential array of items mapping to pc:schemas defines per-channel statistics.
- epsg (str) – An EPSG code for the projected coordinates of the pointcloud.
-
count
¶ Get or sets the count property of the datasource.
Returns: int
-
density
¶ Get or sets the density for the item.
Density is defined as the number of points per square unit area.
Returns: int
-
encoding
¶ Get or sets the content-encoding for the item.
The content-encoding is the underlying encoding format for the point cloud. Examples may include: laszip, ascii, binary, etc.
Returns: str
-
get_count
(asset=None)[source]¶ Gets an Item or an Asset count.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: int
-
get_density
(asset=None)[source]¶ Gets an Item or an Asset density.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: int
-
get_encoding
(asset=None)[source]¶ Gets an Item or an Asset encoding.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: str
-
get_schemas
(asset=None)[source]¶ Gets an Item or an Asset projection geometry.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: List[PointcloudSchema]
-
get_statistics
(asset=None)[source]¶ Gets an Item or an Asset centroid.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: List[PointCloudStatistics] or None
-
get_type
(asset=None)[source]¶ Gets an Item or an Asset type.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: str
-
schemas
¶ Get or sets a
The schemas represent the structure of the data attributes in the pointcloud, and is represented as a sequential array of items that define the dimensions and their types,
Returns: List[PointcloudSchema]
-
set_count
(count, asset=None)[source]¶ Set an Item or an Asset count.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_density
(density, asset=None)[source]¶ Set an Item or an Asset density property.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_encoding
(encoding, asset=None)[source]¶ Set an Item or an Asset encoding.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_schemas
(schemas, asset=None)[source]¶ Set an Item or an Asset schema
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_statistics
(statistics, asset=None)[source]¶ Set an Item or an Asset centroid.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_type
(type, asset=None)[source]¶ Set an Item or an Asset type.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
statistics
¶ Get or sets the statistics for each property of the dataset.
A sequential array of items mapping to pc:schemas defines per-channel statistics.
Example:
item.ext.pointcloud.statistics = [{ 'name': 'red', 'min': 0, 'max': 255 }]
Returns: List[dict]
-
type
¶ type prop on the Item
Returns: str Type: Get or sets the pc
-
Projection Extension¶
Implements the Projection Extension.
ProjectionItemExt¶
-
class
pystac.extensions.projection.
ProjectionItemExt
(item)[source]¶ Bases:
pystac.extensions.base.ItemExtension
ProjectionItemExt is the extension of an Item in the Projection Extension. The Projection extension adds projection information to STAC Items.
Parameters: item (Item) – The item to be extended. Note
Using ProjectionItemExt to directly wrap an item will add the ‘proj’ extension ID to the item’s stac_extensions.
-
apply
(epsg, wkt2=None, projjson=None, geometry=None, bbox=None, centroid=None, shape=None, transform=None)[source]¶ Applies Projection extension properties to the extended Item.
Parameters: - epsg (int or None) – REQUIRED. EPSG code of the datasource.
- wkt2 (str or None) – WKT2 string representing the Coordinate Reference System (CRS) that
the
geometry
andbbox
fields represent - projjson (dict or None) – PROJJSON dict representing the
Coordinate Reference System (CRS) that the
geometry
andbbox
fields represent - geometry (dict or None) – GeoJSON Polygon dict that defines the footprint of this Item.
- bbox (List[float] or None) – Bounding box of the Item in the asset CRS in 2 or 3 dimensions.
- centroid (dict or None) – A dict with members ‘lat’ and ‘lon’ that defines coordinates representing the centroid of the item in the asset data CRS. Coordinates are defined in latitude and longitude, even if the data coordinate system may not use lat/long.
- shape (List[int] or None) – Number of pixels in Y and X directions for the default grid.
- transform (List[float] or None) – The affine transformation coefficients for the default grid
-
bbox
¶ Get or sets the bounding box of the assets represented by this item in the asset data CRS.
Specified as 4 or 6 coordinates based on the CRS defined in the
epsg
,projjson
orwkt2
properties. First two numbers are coordinates of the lower left corner, followed by coordinates of upper right corner, e.g., [west, south, east, north], [xmin, ymin, xmax, ymax], [left, down, right, up], or [west, south, lowest, east, north, highest]. The length of the array must be 2*n where n is the number of dimensions.Returns: List[float]
-
centroid
¶ Get or sets coordinates representing the centroid of the item in the asset data CRS.
Coordinates are defined in latitude and longitude, even if the data coordinate system does not use lat/long.
Exmample:
item.ext.proj.centroid = { 'lat': 0.0, 'lon': 0.0 }
Returns: dict
-
epsg
¶ Get or sets the EPSG code of the datasource.
A Coordinate Reference System (CRS) is the data reference system (sometimes called a ‘projection’) used by the asset data, and can usually be referenced using an EPSG code. If the asset data does not have a CRS, such as in the case of non-rectified imagery with Ground Control Points, epsg should be set to None. It should also be set to null if a CRS exists, but for which there is no valid EPSG code.
Returns: int
-
geometry
¶ Get or sets a Polygon GeoJSON dict representing the footprint of this item.
This dict should be formatted according the Polygon object format specified in RFC 7946, sections 3.1.6, except not necessarily in EPSG:4326 as required by RFC7946. Specified based on the
epsg
,projjson
orwkt2
fields (not necessarily EPSG:4326). Ideally, this will be represented by a Polygon with five coordinates, as the item in the asset data CRS should be a square aligned to the original CRS grid.Returns: dict
-
get_bbox
(asset=None)[source]¶ Gets an Item or an Asset projection bbox.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: List[float]
-
get_centroid
(asset=None)[source]¶ Gets an Item or an Asset centroid.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: dict
-
get_epsg
(asset=None)[source]¶ Gets an Item or an Asset epsg.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: int
-
get_geometry
(asset=None)[source]¶ Gets an Item or an Asset projection geometry.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: dict
-
get_projjson
(asset=None)[source]¶ Gets an Item or an Asset projjson.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: dict
-
get_shape
(asset=None)[source]¶ Gets an Item or an Asset shape.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: List[int]
-
get_transform
(asset=None)[source]¶ Gets an Item or an Asset transform.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: List[float]
-
get_wkt2
(asset=None)[source]¶ Gets an Item or an Asset wkt2.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: str
-
projjson
¶ Get or sets the PROJJSON string representing the Coordinate Reference System (CRS) that the proj:geometry and proj:bbox fields represent
This value is a PROJJSON object. If the data does not have a CRS, such as in the case of non-rectified imagery with Ground Control Points, projjson should be set to null. It should also be set to null if a CRS exists, but for which a PROJJSON string does not exist.
The schema for this object can be found here.
Returns: dict
-
set_bbox
(bbox, asset=None)[source]¶ Set an Item or an Asset projection bbox.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_centroid
(centroid, asset=None)[source]¶ Set an Item or an Asset centroid.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_epsg
(epsg, asset=None)[source]¶ Set an Item or an Asset epsg.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_geometry
(geometry, asset=None)[source]¶ Set an Item or an Asset projection geometry.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_projjson
(projjson, asset=None)[source]¶ Set an Item or an Asset projjson.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_shape
(shape, asset=None)[source]¶ Set an Item or an Asset shape.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_transform
(transform, asset=None)[source]¶ Set an Item or an Asset transform.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_wkt2
(wkt2, asset=None)[source]¶ Set an Item or an Asset wkt2.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
shape
¶ Get or sets the number of pixels in Y and X directions for the default grid.
The shape is an array of integers that represents the number of pixels in the most common pixel grid used by the item’s assets. The number of pixels should be specified in Y, X order. If the shape is defined in an item’s properties it is used as the default shape for all assets that don’t have an overriding shape.
Returns: List[int]
-
transform
¶ Get or sets the the affine transformation coefficients for the default grid.
The transform is a linear mapping from pixel coordinate space (Pixel, Line) to projection coordinate space (Xp, Yp). It is a 3x3 matrix stored as a flat array of 9 elements in row major order. Since the last row is always 0,0,1 it can be omitted, in which case only 6 elements are recorded. This mapping can be obtained from GDAL GetGeoTransform or the Rasterio Transform.
Returns: List[float]
-
wkt2
¶ Get or sets the WKT2 string representing the Coordinate Reference System (CRS) that the proj:geometry and proj:bbox fields represent
This value is a WKT2 string. If the data does not have a CRS, such as in the case of non-rectified imagery with Ground Control Points, wkt2 should be set to null. It should also be set to null if a CRS exists, but for which a WKT2 string does not exist.
Returns: str
-
Timestamps Extension¶
Implements the Timestamps Extension.
TimestampsItemExt¶
-
class
pystac.extensions.timestamps.
TimestampsItemExt
(item)[source]¶ Bases:
pystac.extensions.base.ItemExtension
TimestampsItemExt is the extension of an Item in that allows to specify additional timestamps for assets and metadata.
Parameters: item (Item) – The item to be extended. Note
Using TimestampsItemExt to directly wrap an item will add the ‘timestamps’ extension ID to the item’s stac_extensions.
-
apply
(published=None, expires=None, unpublished=None)[source]¶ Applies timestamps extension properties to the extended Item.
Parameters: - published (datetime or None) – Date and time the corresponding data was published the first time.
- expires (datetime or None) – Date and time the corresponding data expires (is not valid any longer).
- unpublished (datetime or None) – Date and time the corresponding data was unpublished.
-
expires
¶ - Get or sets a datetime objects that represent
- the date and time the corresponding data expires (is not valid any longer).
Returns: datetime
-
get_expires
(asset=None)[source]¶ Get an Item or Asset expires datetime
If an Asset is supplied and the expires property exists on the Asset, return the Asset’s value. Otherwise return the Item’s value. ‘Unpublished’ has a different meaning depending on where it is used. If available in the asset properties, it refers to the timestamps valid for the actual data linked to the Asset Object. If it comes from the Item properties, it’s referencing to the timestamp valid for the metadata.
Returns: datetime
-
get_published
(asset=None)[source]¶ Get an Item or Asset published datetime
If an Asset is supplied and the published property exists on the Asset, return the Asset’s value. Otherwise return the Item’s value. ‘Published’ has a different meaning depending on where it is used. If available in the asset properties, it refers to the timestamps valid for the actual data linked to the Asset Object. If it comes from the Item properties, it’s referencing to the timestamp valid for the metadata.
Returns: datetime
-
get_unpublished
(asset=None)[source]¶ Get an Item or Asset unpublished datetime
If an Asset is supplied and the unpublished property exists on the Asset, return the Asset’s value. Otherwise return the Item’s value. ‘Unpublished’ has a different meaning depending on where it is used. If available in the asset properties, it refers to the timestamps valid for the actual data linked to the Asset Object. If it comes from the Item properties, it’s referencing to the timestamp valid for the metadata.
Returns: datetime
-
published
¶ - Get or sets a datetime objects that represent
- the date and time that the corresponding data was published the first time.
Returns: datetime
-
set_expires
(expires, asset=None)[source]¶ Set an Item or asset expires datetime
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_published
(published, asset=None)[source]¶ Set an Item or asset published datetime
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_unpublished
(unpublished, asset=None)[source]¶ Set an Item or asset unpublished datetime
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
unpublished
¶ Get or sets a datetime objects that represent the Date and time the corresponding data was unpublished.
Returns: datetime
-
SAR Extension¶
Implements the SAR Extension.
SarItemExt¶
-
class
pystac.extensions.sar.
SarItemExt
(an_item: pystac.item.Item)[source]¶ Bases:
pystac.extensions.base.ItemExtension
SarItemExt extends Item to add sar properties to a STAC Item.
Parameters: item (Item) – The item to be extended. Note
Using SarItemExt to directly wrap an item will add the ‘sar’ extension ID to the item’s stac_extensions.
-
apply
(instrument_mode: str, frequency_band: pystac.extensions.sar.FrequencyBand, polarizations: List[pystac.extensions.sar.Polarization], product_type: str, center_frequency: Optional[float] = None, resolution_range: Optional[float] = None, resolution_azimuth: Optional[float] = None, pixel_spacing_range: Optional[float] = None, pixel_spacing_azimuth: Optional[float] = None, looks_range: Optional[int] = None, looks_azimuth: Optional[int] = None, looks_equivalent_number: Optional[float] = None, observation_direction: Optional[pystac.extensions.sar.ObservationDirection] = None)[source]¶ Applies sar extension properties to the extended Item.
Parameters: - instrument_mode (str) – The name of the sensor acquisition mode that is commonly used. This should be the short name, if available. For example, WV for “Wave mode.”
- frequency_band (FrequencyBand) – The common name for the frequency band to make it easier to search for bands across instruments. See section “Common Frequency Band Names” for a list of accepted names.
- polarizations (List[Polarization]) – Any combination of polarizations.
- product_type (str) – The product type, for example SSC, MGD, or SGC.
- center_frequency (float) – Optional center frequency of the instrument in gigahertz (GHz).
- resolution_range (float) – Optional range resolution, which is the maximum ability to distinguish two adjacent targets perpendicular to the flight path, in meters (m).
- resolution_azimuth (float) – Optional azimuth resolution, which is the maximum ability to distinguish two adjacent targets parallel to the flight path, in meters (m).
- pixel_spacing_range (float) – Optional range pixel spacing, which is the distance between adjacent pixels perpendicular to the flight path, in meters (m). Strongly RECOMMENDED to be specified for products of type GRD.
- pixel_spacing_azimuth (float) – Optional azimuth pixel spacing, which is the distance between adjacent pixels parallel to the flight path, in meters (m). Strongly RECOMMENDED to be specified for products of type GRD.
- looks_range (int) – Optional number of groups of signal samples (looks) perpendicular to the flight path.
- looks_azimuth (int) – Optional number of groups of signal samples (looks) parallel to the flight path.
- looks_equivalent_number (float) – Optional equivalent number of looks (ENL).
- observation_direction (ObservationDirection) – Optional Antenna pointing direction relative to the flight trajectory of the satellite.
-
center_frequency
¶ Get or sets a center frequency for the item.
Returns: float
-
frequency_band
¶ Get or sets a FrequencyBand for the item.
Returns: FrequencyBand
-
instrument_mode
¶ Get or sets an instrument mode string for the item.
Returns: str
-
looks_azimuth
¶ Get or sets a looks azimuth for the item.
Returns: int
-
looks_equivalent_number
¶ Get or sets a looks equivalent number for the item.
Returns: float
-
looks_range
¶ Get or sets a looks range for the item.
Returns: int
-
observation_direction
¶ Get or sets an observation direction for the item.
Returns: ObservationDirection
-
pixel_spacing_azimuth
¶ Get or sets a pixel spacing azimuth for the item.
Returns: float
-
pixel_spacing_range
¶ Get or sets a pixel spacing range for the item.
Returns: float
-
polarizations
¶ Get or sets a list of polarizations for the item.
Returns: List[Polarization]
-
product_type
¶ Get or sets a product type string for the item.
Returns: str
-
resolution_azimuth
¶ Get or sets a resolution azimuth for the item.
Returns: float
-
resolution_range
¶ Get or sets a resolution range for the item.
Returns: float
-
Single File STAC Extension¶
These classes are representations of the Single File STAC Extension.
-
pystac.extensions.single_file_stac.
create_single_file_stac
(catalog)[source]¶ Creates a Single File STAC from a STAC catalog.
This method will recursively collect any collections and items in the catalog and return a new catalog with the same properties as the old one, with cleared links and the ‘collections’ and ‘features’ property of the Single File STAC holding each of the respective collected STAC objects.
Collections will be filtered to only those referenced by items via the collection_id. All links in the items and collections will be cleared in the Single File STAC.
Parameters: catalog (Catalog) – Catalog to walk while constructin the Single File STAC
SingleFileSTACCatalogExt¶
-
class
pystac.extensions.single_file_stac.
SingleFileSTACCatalogExt
(catalog)[source]¶ An extension of Catalog that provides a set of Collections and Items as a single file catalog. A SingleFileSTAC is a self contained catalog that contains everything that would normally be in a linked set of STAC files.
Parameters: catalog (Catalog) – The catalog to be extended. Note
Using SingleFileSTACCatalogExt to directly wrap a Catalog will add the ‘proj’ extension ID to the catalog’s stac_extensions.
-
apply
(features, collections=None)[source]¶ Parameters: - features (List[Item]) – List of items contained by this SingleFileSTAC.
- collections (List[Collection]) – Optional list of collections that are used by any of the Items in the catalog.
-
collections
¶ Get or sets a list of
Collection
objects contained in this Single File STAC.Returns: List[Band]
-
Version Extension¶
Implements the Version Extension.
VersionCollectionExt¶
-
class
pystac.extensions.version.
VersionCollectionExt
(a_collection)[source]¶ Bases:
pystac.extensions.base.CollectionExtension
VersionCollectionExt extends Collection to add version and deprecated properties along with links to the latest, predecessor, and successor Collections.
Parameters: a_collection (Collection) – The collection to be extended. -
collection
¶ The collection that is being extended.
Type: Collection
Note
Using VersionCollectionExt to directly wrap a collection will add the ‘version’ extension ID to the collections’s stac_extensions.
-
apply
(version: str, deprecated: Optional[str] = None, latest: Optional[pystac.collection.Collection] = None, predecessor=None, successor=None) → None[source]¶ Applies version extension properties to the extended Collection.
Parameters: - version (str) – The version string for the collection.
- deprecated (bool) – Optional flag set to True if an Collection is deprecated with the potential to be removed. Defaults to false if not present.
- latest (Collection) – Collection with the latest (e.g., current) version.
- predecessor (Collection) – Collection with the previous version.
- successor (Collection) – Collection with the next most recent version.
-
deprecated
¶ Get or sets is the collection is deprecated.
Returns: bool
-
latest
¶ Get or sets the most recent collection.
Returns: Collection or None
-
predecessor
¶ Get or sets the previous collection.
Returns: Collection or None
-
successor
¶ Get or sets the next collection.
Returns: Collection or None
-
version
¶ Get or sets a version string of the collection.
Returns: str
-
VersionItemExt¶
-
class
pystac.extensions.version.
VersionItemExt
(an_item)[source]¶ Bases:
pystac.extensions.base.ItemExtension
VersionItemExt extends Item to add version and deprecated properties along with links to the latest, predecessor, and successor Items.
Parameters: item (Item) – The item to be extended. Note
Using VersionItemExt to directly wrap an item will add the ‘version’ extension ID to the item’s stac_extensions.
-
apply
(version: str, deprecated: Optional[bool] = None, latest: Optional[pystac.item.Item] = None, predecessor: Optional[pystac.item.Item] = None, successor: Optional[pystac.item.Item] = None) → None[source]¶ Applies version extension properties to the extended Item.
Parameters: - version (str) – The version string for the item.
- deprecated (bool) – Optional flag set to True if an Item is deprecated with the potential to be removed. Defaults to false if not present.
- latest (Item) – Item with the latest (e.g., current) version.
- predecessor (Item) – Item with the previous version.
- successor (Item) – Item with the next most recent version.
-
deprecated
¶ Get or sets is the item is deprecated.
Returns: bool
-
latest
¶ Get or sets the most recent item.
Returns: Item or None
-
predecessor
¶ Get or sets the previous item.
Returns: Item or None
-
successor
¶ Get or sets the next item.
Returns: Item or None
-
version
¶ Get or sets a version string of the item.
Returns: str
-
View Geometry Extension¶
Implements the View Geometry Extension.
ViewItemExt¶
-
class
pystac.extensions.view.
ViewItemExt
(item)[source]¶ Bases:
pystac.extensions.base.ItemExtension
ViewItemExt is the extension of the Item in the View Geometry Extension. View Geometry adds metadata related to angles of sensors and other radiance angles that affect the view of resulting data. It will often be combined with other extensions that describe the actual data, such as the eo, sat or sar extensions.
Parameters: item (Item) – The item to be extended. Note
Using ViewItemExt to directly wrap an item will add the ‘view’ extension ID to the item’s stac_extensions.
-
apply
(off_nadir: Optional[float] = None, incidence_angle: Optional[float] = None, azimuth: Optional[float] = None, sun_azimuth: Optional[float] = None, sun_elevation: Optional[float] = None)[source]¶ Applies View Geometry extension properties to the extended Item.
Parameters: - off_nadir (float) – The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90).
- incidence_angle (float) – The incidence angle is the angle between the vertical (normal) to the intercepting surface and the line of sight back to the satellite at the scene center. Measured in degrees (0-90).
- azimuth (float) – Viewing azimuth angle. The angle measured from the sub-satellite point (point on the ground below the platform) between the scene center and true north. Measured clockwise from north in degrees (0-360).
- sun_azimuth (float) – Sun azimuth angle. From the scene center point on the ground, this is the angle between truth north and the sun. Measured clockwise in degrees (0-360).
- sun_elevation (float) – Sun elevation angle. The angle from the tangent of the scene center point to the sun. Measured from the horizon in degrees (0-90).
-
azimuth
¶ Get or sets the viewing azimuth angle. The angle measured from the sub-satellite point (point on the ground below the platform) between the scene center and true north. Measured clockwise from north in degrees (0-360).
Returns: float
-
get_azimuth
(asset=None)[source]¶ Gets an Item or an Asset azimuth.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: float
-
get_incidence_angle
(asset=None)[source]¶ Gets an Item or an Asset incidence_angle.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: float
-
get_off_nadir
(asset=None)[source]¶ Gets an Item or an Asset off_nadir.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: float
-
get_sun_azimuth
(asset=None)[source]¶ Gets an Item or an Asset sun_azimuth.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: float
-
get_sun_elevation
(asset=None)[source]¶ Gets an Item or an Asset sun_elevation.
If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value
Returns: float
-
incidence_angle
¶ Get or sets the incidence angle is the angle between the vertical (normal) to the intercepting surface and the line of sight back to the satellite at the scene center. Measured in degrees (0-90).
Returns: float
-
off_nadir
¶ Get or sets the angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90).
Returns: float
-
set_azimuth
(azimuth, asset=None)[source]¶ Set an Item or an Asset azimuth.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_incidence_angle
(incidence_angle, asset=None)[source]¶ Set an Item or an Asset incidence_angle.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_off_nadir
(off_nadir, asset=None)[source]¶ Set an Item or an Asset off_nadir.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_sun_azimuth
(sun_azimuth, asset=None)[source]¶ Set an Item or an Asset sun_azimuth.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
set_sun_elevation
(sun_elevation, asset=None)[source]¶ Set an Item or an Asset sun_elevation.
If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.
-
sun_azimuth
¶ Get or sets the sun azimuth angle. From the scene center point on the ground, this is the angle between truth north and the sun. Measured clockwise in degrees (0-360).
Returns: float
-
sun_elevation
¶ Get or sets the sun elevation angle. The angle from the tangent of the scene center point to the sun. Measured from the horizon in degrees (0-90).
Returns: float
-
Serialization¶
PySTAC includes a pystac.serialization
package for serialization concerns that
are used internally, but may also be useful to external tools.
Identification¶
-
pystac.serialization.
identify_stac_object
(json_dict)[source]¶ Determines the STACJSONDescription of the provided JSON dict.
Parameters: json_dict (dict) – The dict of STAC JSON to identify. Returns: The description of the STAC object serialized in the given dict. Return type: STACJSONDescription
-
class
pystac.serialization.
STACJSONDescription
(object_type, version_range, common_extensions, custom_extensions)[source]¶ Describes the STAC object information for a STAC object represented in JSON
-
object_type
¶ Describes the STAC object type. One of
STACObjectType
.Type: str
-
version_range
¶ The STAC version range that describes what has been identified as potential valid versions of the stac object.
Type: STACVersionRange
-
common_extensions
¶ List of common extension IDs implemented by this STAC object.
Type: List[str]
-
custom_extensions
¶ List of custom extensions (URIs to JSON Schemas) used by this STAC Object.
Type: List[str]
-
Migration¶
-
pystac.serialization.migrate.
migrate_to_latest
(json_dict, info)[source]¶ Migrates the STAC JSON to the latest version
Parameters: - json_dict (dict) – The dict of STAC JSON to identify.
- info (STACJSONDescription) – The info from
identify_stac_object()
that describes the STAC object contained in the JSON dict.
Returns: A copy of the dict that is migrated to the latest version (the version that is pystac.version.STACVersion.DEFAULT_STAC_VERSION)
Return type: dict
Common Properties¶
-
pystac.serialization.
merge_common_properties
(item_dict, collection_cache=None, json_href=None)[source]¶ Merges Collection properties into an Item.
Parameters: - item_dict (dict) – JSON dict of the Item which properties should be merged into.
- collection_cache (CollectionCache) – Optional CollectionCache that will be used to read and write cached collections.
- json_href – The HREF of the file that this JSON comes from. Used to resolve relative paths.
Returns: True if Collection properties have been merged, otherwise False.
Return type: bool
Validation¶
pystac.validation¶
PySTAC includes a pystac.validation
package for validating STAC objects, including
from PySTAC objects and directly from JSON.
-
pystac.validation.
validate
(stac_object)[source]¶ Validates a
STACObject
.Parameters: stac_object (STACObject) – The stac object to validate. Returns: - List of return values from the validation calls for the
- core object and any extensions. Element type is specific to the STACValidator implementation.
Return type: List[Object] Raises: STACValidationError
-
pystac.validation.
validate_dict
(stac_dict, stac_object_type=None, stac_version=None, extensions=None, href=None)[source]¶ Validate a stac object serialized as JSON into a dict.
This method delegates to the call to
pystac.validation.STACValidator.validate()
for the STACValidator registered viaset_validator()
orJsonSchemaSTACValidator
by default.Parameters: - stac_dict (dict) – Dictionary that is the STAC json of the object.
- stac_object_type (str) – The stac object type of the object encoded in stac_dict.
One of
STACObjectType
. If not supplied, this will use PySTAC’s identification logic to identify the object type. - stac_version (str) – The version of STAC to validate the object against. If not supplied, this will use PySTAC’s identification logic to identify the stac version
- extensions (List[str]) – Extension IDs for this stac object. If not supplied, PySTAC’s identification logic to identify the extensions.
- href (str) – Optional HREF of the STAC object being validated.
Returns: - List of return values from the validation calls for the
core object and any extensions. Element type is specific to the STACValidator implementation.
Return type: List[Object]
Raises:
-
pystac.validation.
validate_all
(stac_dict, href)[source]¶ Validate STAC JSON and all contained catalogs, collections and items.
If this stac_dict represents a catalog or collection, this method will recursively be called for each child link and all contained items.
Parameters: - stac_dict (dict) – Dictionary that is the STAC json of the object.
- href (str) – HREF of the STAC object being validated. Used for error reporting and resolving relative links.
Raises: STACValidationError
– This will raise a STACValidationError if this or any contained catalog, collection or item has a validation error.
-
pystac.validation.
set_validator
(validator)[source]¶ Sets the STACValidator to use in PySTAC.
TKTK
Parameters: validator (STACValidator) – The STACVlidator implementation to use for validation.
-
exception
pystac.validation.
STACValidationError
(message, source=None)[source]¶ Represents a validation error. Thrown by validation calls if the STAC JSON is invalid.
Parameters: source (object) – Source of the exception. Type will be determined by the validation implementation. For the default JsonSchemaValidator this will a the jsonschema.ValidationError
.
STACValidator¶
-
class
pystac.validation.
STACValidator
[source]¶ STACValidator defines methods for validating STAC JSON. Implementations define methods for validating core objects and extension. By default the JsonSchemaSTACValidator is used by PySTAC; users can define their own STACValidator implementation and set that validator to be used by pystac by using the
set_validator()
method.-
validate
(stac_dict, stac_object_type, stac_version, extensions, href=None)[source]¶ Validate a STAC object JSON.
Parameters: - stac_dict (dict) – Dictionary that is the STAC json of the object.
- stac_object_type (str) – The stac object type of the object encoded in stac_dict.
One of
STACObjectType
. - stac_version (str) – The version of STAC to validate the object against.
- extensions (List[str]) – Extension IDs for this stac object.
- href (str) – Optional href of the STAC object being validated.
Returns: - List of return values from the validation calls for the
core object and any extensions. Element type is specific to the STACValidator implementation.
Return type: List[Object]
-
validate_core
(stac_dict, stac_object_type, stac_version, href=None)[source]¶ Validate a core stac object.
Return value can be None or specific to the implementation.
Parameters: - stac_dict (dict) – Dictionary that is the STAC json of the object.
- stac_object_type (str) – The stac object type of the object encoded in stac_dict.
One of
STACObjectType
. - stac_version (str) – The version of STAC to validate the object against.
- href (str) – Optional HREF of the STAC object being validated.
-
validate_extension
(stac_dict, stac_object_type, stac_version, extension_id, href=None)[source]¶ Validate an extension stac object.
Return value can be None or specific to the implementation.
Parameters: - stac_dict (dict) – Dictionary that is the STAC json of the object.
- stac_object_type (str) – The stac object type of the object encoded in stac_dict.
One of
STACObjectType
. - stac_version (str) – The version of STAC to validate the object against.
- extension_id (str) – The extension ID of the extension to validate against.
- href (str) – Optional HREF of the STAC object being validated.
-
-
class
pystac.validation.
JsonSchemaSTACValidator
(schema_uri_map=None)[source]¶ Validate STAC based on JSON Schemas.
This validator uses JSON schemas, read from URIs provided by a
SchemaUriMap
, to validate STAC core objects and extensions.Parameters: schema_uri_map (SchemaUriMap) – The SchemaUriMap that defines where the validator will retrieve the JSON schemas for validation. Defaults to an instance of DefaultSchemaUriMap
Note: This class requires the
jsonschema
library to be installed.-
validate_core
(stac_dict, stac_object_type, stac_version, href=None)[source]¶ Validate a core stac object.
Return value can be None or specific to the implementation.
Parameters: - stac_dict (dict) – Dictionary that is the STAC json of the object.
- stac_object_type (str) – The stac object type of the object encoded in stac_dict.
One of
STACObjectType
. - stac_version (str) – The version of STAC to validate the object against.
- href (str) – Optional HREF of the STAC object being validated.
Returns: - URI for the JSON schema that was validated against, or None if
no validation occurred.
Return type: str
-
validate_extension
(stac_dict, stac_object_type, stac_version, extension_id, href=None)[source]¶ Validate an extension stac object.
Return value can be None or specific to the implementation.
Parameters: - stac_dict (dict) – Dictionary that is the STAC json of the object.
- stac_object_type (str) – The stac object type of the object encoded in stac_dict.
One of
STACObjectType
. - stac_version (str) – The version of STAC to validate the object against.
- extension_id (str) – The extension ID to validate against.
- href (str) – Optional HREF of the STAC object being validated.
Returns: - URI for the JSON schema that was validated against, or None if
no validation occurred.
Return type: str
-
SchemaUriMap¶
A SchemaMapUri
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 JsonSchemaSTACValidator
to modify the URIs used.
-
class
pystac.validation.
SchemaUriMap
[source]¶ Abstract class defining schema URIs for STAC core objects and extensions.
-
get_core_schema_uri
(object_type, stac_version)[source]¶ Get the schema URI for the given object type and stac version.
Parameters: - object_type (str) – STAC object type. One of
STACObjectType
- stac_version (str) – The STAC version of the schema to return.
Returns: The URI of the schema, or None if not found.
Return type: str
- object_type (str) – STAC object type. One of
-
get_extension_schema_uri
(extension_id, object_type, stac_version)[source]¶ Get the extension’s schema URI for the given object type, stac version.
Parameters: - extension_id (str) – The Extension ID of the extension of the schema.
- object_type (str) – STAC object type. One of
STACObjectType
- stac_version (str) – The STAC version of the schema to return.
Returns: The URI of the schema, or None if not found.
Return type: str
-
-
class
pystac.validation.schema_uri_map.
DefaultSchemaUriMap
[source]¶ Implementation of SchemaUriMap that uses schemas hosted by https://schemas.stacspec.org.
For STAC Versions 0.9.0 or earlier this will use the schemas hosted on the radiantearth/stac-spec GitHub repo.
-
get_core_schema_uri
(object_type, stac_version)[source]¶ Get the schema URI for the given object type and stac version.
Parameters: - object_type (str) – STAC object type. One of
STACObjectType
- stac_version (str) – The STAC version of the schema to return.
Returns: The URI of the schema, or None if not found.
Return type: str
- object_type (str) – STAC object type. One of
-
get_extension_schema_uri
(extension_id, object_type, stac_version)[source]¶ Get the extension’s schema URI for the given object type, stac version.
Parameters: - extension_id (str) – The Extension ID of the extension of the schema.
- object_type (str) – STAC object type. One of
STACObjectType
- stac_version (str) – The STAC version of the schema to return.
Returns: The URI of the schema, or None if not found.
Return type: str
-
PySTAC Internal Classes¶
ResolvedObjectCache¶
-
class
pystac.cache.
ResolvedObjectCache
(id_keys_to_objects=None, hrefs_to_objects=None, ids_to_collections=None)[source]¶ This class tracks resolved objects tied to root catalogs. A STAC object is ‘resolved’ when it is a Python Object; a link to a STAC object such as a Catalog or Item is considered “unresolved” if it’s target is pointed at an HREF of the object.
Tracking resolved objects allows us to tie together the same instances when there are loops in the Graph of the STAC catalog (e.g. a LabelItem can link to a rel:source, and if that STAC Item exists in the same root catalog they should refer to the same Python object).
Resolution tracking is important when copying STACs in-memory: In order for object links to refer to the copy of STAC Objects rather than their originals, we have to keep track of the resolved STAC Objects and replace them with their copies.
Parameters: - id_keys_to_objects (Dict[str, STACObject]) – Existing cache of a key made up of the STACObject and it’s parents IDs mapped to the cached STACObject.
- hrefs_to_objects (Dict[str, STACObject]) – STAC Object HREFs matched to their cached object.
- ids_to_collections (Dict[str, Collection]) – Map of collection IDs to collections.
-
cache
(obj)[source]¶ Set the given object into the cache.
Parameters: obj (STACObject) – The object to cache
-
contains_collection_id
(collection_id)[source]¶ Returns True if there is a collection with given collection ID is cached.
-
get
(obj)[source]¶ Get the cached object that has the same cache key as the given object.
Parameters: obj (STACObject) – The given object who’s cache key will be checked against the cache. Returns: Either the cached object that has the same cache key as the given object, or None Return type: STACObject or None
-
get_by_href
(href)[source]¶ Gets the cached object at href.
Parameters: href (str) – The href to use as the key for the cached object. Returns: Returns the STACObject if cached, otherwise None. Return type: STACObject or None
-
get_collection_by_id
(id)[source]¶ Retrieved a cached Collection by its ID.
Parameters: id (str) – The ID of the collection. Returns: - Returns the collection if there is one cached
- with the given ID, otherwise None.
Return type: Collection or None
-
get_or_cache
(obj)[source]¶ Gets the STACObject that is the cached version of the given STACObject; or, if none exists, sets the cached object to the given object.
Parameters: obj (STACObject) – The given object who’s cache key will be checked against the cache. Returns: Either the cached object that has the same cache key as the given object, or the given object. Return type: STACObject
-
static
merge
(first, second)[source]¶ Merges two ResolvedObjectCache.
The merged cache will give preference to the first argument; that is, if there are cached keys that exist in both the first and second cache, the object cached in the first will be cached in the resulting merged ResolvedObjectCache.
Parameters: - first (ResolvedObjectCache) – The first cache to merge. This cache will be the preferred cache for objects in the case of ID conflicts.
- second (ResolvedObjectCache) – The second cache to merge.
Returns: The resulting merged cache.
Return type:
-
remove
(obj)[source]¶ Removes any cached object that matches the given object’s cache key.
Parameters: obj (STACObject) – The object to remove