pystac.layout#
- 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.CustomLayoutStrategy(catalog_func: Optional[Callable[[Catalog_Type, str, bool], str]] = None, collection_func: Optional[Callable[[Collection_Type, str, bool], str]] = None, item_func: Optional[Callable[[Item_Type, str], str]] = None, fallback_strategy: Optional[pystac.layout.HrefLayoutStrategy] = None)[source]#
Layout strategy that allows users to supply functions to dictate stac object paths.
- Parameters
catalog_func – 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 – A function that is used for collections in the same manner at
catalog_func
. This takes the same parameters.item_func – A function that takes an item and a parent directory and returns the path to be used for the item.
fallback_strategy – The fallback strategy to use if a function is not provided for a stac object type. Defaults to
BestPracticesLayoutStrategy
- catalog_func: Optional[Callable[[Catalog_Type, str, bool], str]]#
A function that takes a
Catalog
, a parent directory, and a boolean specifying whether or not this Catalog is the root. If it is the root, it is usually best to not create a subdirectory and put the Catalog file directly in the parent directory. Must return the string path.
- collection_func: Optional[Callable[[Collection_Type, str, bool], str]]#
A function that is used for collections in the same manner as
catalog_func
. This takes the same parameters.
- fallback_strategy: pystac.layout.HrefLayoutStrategy#
The fallback strategy to use if a function is not provided for a stac object type. Defaults to
BestPracticesLayoutStrategy
.
- class pystac.layout.LayoutTemplate(template: str, defaults: Optional[Dict[str, str]] = 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.
The forward slash (
/
) should be used as path separator in the template string regardless of the system path separator (thus both in POSIX-compliant and Windows environments).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 – The template string to use.
defaults – A dictionary of template vars to values. These values will be used in case a value cannot be derived from a stac object.
- ITEM_TEMPLATE_VARS = ['date', 'year', 'month', 'day', 'collection']#
- defaults: Dict[str, str]#
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: STACObject_Type) Dict[str, Any] [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 – 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: STACObject_Type) str [source]#
Substitutes the values derived from
get_template_values()
into the template string for this template.- Parameters
stac_object – 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
- 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.
- exception pystac.layout.TemplateError[source]#
Exception thrown when an error occurs during converting a template string into data for
LayoutTemplate
- class pystac.layout.TemplateLayoutStrategy(catalog_template: Optional[str] = None, collection_template: Optional[str] = None, item_template: Optional[str] = None, fallback_strategy: Optional[pystac.layout.HrefLayoutStrategy] = 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 – The template string to use for catalog paths. Must be a valid template string that can be used by
LayoutTemplate
collection_template – The template string to use for collection paths. Must be a valid template string that can be used by
LayoutTemplate
item_template – The template string to use for item paths. Must be a valid template string that can be used by
LayoutTemplate
fallback_strategy – The fallback strategy to use if a template is not provided. Defaults to
BestPracticesLayoutStrategy
- catalog_template: Optional[pystac.layout.LayoutTemplate]#
The template string to use for catalog paths. Must be a valid template string that can be used by
LayoutTemplate
.
- collection_template: Optional[pystac.layout.LayoutTemplate]#
The template string to use for collection paths. Must be a valid template string that can be used by
LayoutTemplate
.
- fallback_strategy: pystac.layout.HrefLayoutStrategy#
The fallback strategy to use if a template is not provided. Defaults to
BestPracticesLayoutStrategy
.
- item_template: Optional[pystac.layout.LayoutTemplate]#
The template string to use for item paths. Must be a valid template string that can be used by
LayoutTemplate
.