Skip to main content
`Ctrl`+`K`

# pystac.layout

class pystac.layout.APILayoutStrategy

  Layout strategy that represents the STAC API endpoint layout described in the STAC API Specifications

  The URL of the root catalog will be the base URL of the API. Other catalogs will be listed underneath their parent catalog at `./${id}`. Collections will be found underneath the root or their parent catalog at `./collections/${id}`. Collection cannot be the root themselves. Items will be found underneath their collections at `./collections/${collection}/items/${id}`.

  get_catalog_href(cat: Catalog | str, parent_dir: str, is_root: bool) → str

    Generate a catalog href based on the provided parameters.

    Parameters: cat (Catalog | str): The catalog object or its ID. parent_dir (str): The parent directory for the catalog. is_root (bool): A flag indicating whether the catalog is a root catalog.

    Returns: str: The generated catalog href.

  get_collection_href(col: Collection | str, parent_dir: str, is_root: bool) → str

    Generate a collection href based on the provided parameters.

    Parameters: col (Collection | str): The collection object or its ID. parent_dir (str): The parent directory for the collection. is_root (bool): A flag indicating whether the collection is a root collection.

    Returns: str: The generated collection href.

    Raises: ValueError: If the collection is set as root.

  get_collections_href(parent_dir: str) → str

    Generate a collections href based on the provided parent directory.

    Parameters: parent_dir (str): The parent directory for the collections.

    Returns: str: The generated collections href.

  get_conformance_href(parent_dir: str) → str

    Generate a conformance href based on the provided parent directory.

    Parameters: parent_dir (str): The parent directory for the conformance.

    Returns: str: The generated conformance href.

  get_item_href(item: Item | str, parent_dir: str) → str

    Generate an item href based on the provided parameters.

    Parameters: item (Item | str): The item object or its ID. parent_dir (str): The parent directory for the item.

    Returns: str: The generated item href.

  get_items_href(parent_dir: str) → str

    Generate an items href based on the provided parent directory.

    Parameters: parent_dir (str): The parent directory for the items.

    Returns: str: The generated items href.

  get_search_href(parent_dir: str) → str

    Generate a search href based on the provided parent directory.

    Parameters: parent_dir (str): The parent directory for the search.

    Returns: str: The generated search href.

  get_service_desc_href(parent_dir: str) → str

    Generate an API service description href based on the provided parent directory.

    Parameters: parent_dir (str): The parent directory for the API.

    Returns: str: The generated API href.

  get_service_doc_href(parent_dir: str) → str

    Generate an API service documentation href based on the provided parent directory.

    Parameters: parent_dir (str): The parent directory for the API.

    Returns: str: The generated API href.

class pystac.layout.AsIsLayoutStrategy

  Layout strategy that simply preserves the current href of all objects.

  If any object doesn’t have a self href, a ValueError is raised.

  get_catalog_href(cat: Catalog, parent_dir: str, is_root: bool) → str
  get_collection_href(col: Collection, parent_dir: str, is_root: bool) → str
  get_item_href(item: Item, parent_dir: str) → str

class pystac.layout.BestPracticesLayoutStrategy

  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.

  get_catalog_href(cat: Catalog, parent_dir: str, is_root: bool) → str
  get_collection_href(col: Collection, parent_dir: str, is_root: bool) → str
  get_item_href(item: Item, parent_dir: str) → str

class pystac.layout.CustomLayoutStrategy(catalog_func: Callable[[Catalog, str, bool], str] | None = None, collection_func: Callable[[Collection, str, bool], str] | None = None, item_func: Callable[[Item, str], str] | None = None, fallback_strategy: HrefLayoutStrategy | None = None)

  Layout strategy that allows users to supply functions to dictate stac object paths.

  Parameters:

    - catalog_func – A function that takes a catalog, a parent directory, and a flag 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 – 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: Callable[[Catalog, str, bool], str] | None

    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: Callable[[Collection, str, bool], str] | None

    A function that is used for collections in the same manner as `catalog_func`. This takes the same parameters.

  fallback_strategy: HrefLayoutStrategy

    The fallback strategy to use if a function is not provided for a stac object type. Defaults to `BestPracticesLayoutStrategy`.

  get_catalog_href(cat: Catalog, parent_dir: str, is_root: bool) → str
  get_collection_href(col: Collection, parent_dir: str, is_root: bool) → str
  get_item_href(item: Item, parent_dir: str) → str
  item_func: Callable[[Item, str], str] | None

    An optional function that takes an `Item` and a parent directory and returns the path to be used for the Item.

class pystac.layout.HrefLayoutStrategy

  Base class for HREF Layout strategies.

  abstractmethod get_catalog_href(cat: Catalog, parent_dir: str, is_root: bool) → str
  abstractmethod get_collection_href(col: Collection, parent_dir: str, is_root: bool) → str
  get_href(stac_object: STACObject, parent_dir: str, is_root: bool = False) → str
  abstractmethod get_item_href(item: Item, parent_dir: str) → str

class pystac.layout.LayoutTemplate(template: str, defaults: dict[str, str] | None = None)

  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) → dict[str, Any]

    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:

      pystac.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) → str

    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:

      str

    Raises:

      pystac.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.

  template: str

    The template string to use.

  template_vars: list[str]

    List of template vars to use when templating.

exception pystac.layout.TemplateError(*args, **kwargs)

  DEPRECATED.

  Deprecated since version 1.7.0: Use `pystac.errors.TemplateError` instead.

  Exception thrown when an error occurs during converting a template string into data for `LayoutTemplate`

class pystac.layout.TemplateLayoutStrategy(catalog_template: str | None = None, collection_template: str | None = None, item_template: str | None = None, fallback_strategy: HrefLayoutStrategy | None = None)

  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 the `BestPracticesLayoutStrategy`.

  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: LayoutTemplate | None

    The template string to use for catalog paths. Must be a valid template string that can be used by `LayoutTemplate`.

  collection_template: LayoutTemplate | None

    The template string to use for collection 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`.

  get_catalog_href(cat: Catalog, parent_dir: str, is_root: bool) → str
  get_collection_href(col: Collection, parent_dir: str, is_root: bool) → str
  get_item_href(item: Item, parent_dir: str) → str
  item_template: LayoutTemplate | None

    The template string to use for item paths. Must be a valid template string that can be used by `LayoutTemplate`.