2. Choose STAC library#
Date: 2021-03-01
Status#
Accepted
Context#
We would like to use an existing Python library for working with STAC objects as Python objects. Ideally this library will meet the following requirements:
Actively maintained to ensure that it is up-to-date with the latest STAC spec
Well-documented to reduce the documentation burden for this library
Easily extensible to allow us to take advantage of existing STAC object functionality
The 2 most obvious choices for Python STAC clients are
PySTAC and sat-stac.
PySTAC#
PySTAC is an actively maintained STAC client for Python 3. Its last release was less than 2 months ago and its last
commit was less than 2 weeks ago. It has had 15 contributors within the last year and it supports the latest release
candidate for the STAC spec (as well as previous releases). PySTAC hosts
documentation on ReadTheDocs that includes a description of programming
concepts related to the library, quickstart instructions, tutorials, and an API reference.
PySTAC supports both reading and writing of STAC objects. Extending PySTAC classes through inheritance is made a
bit more difficult by the fact that some class methods (like from_dict) have references to specific classes
(like Catalog) rather than using the cls argument. This will require us to overwrite some of these methods to
implement inheritance. It has robust support for traversing catalogs using links. There is no existing support for the
STAC API spec in PySTAC or any related tooling.
sat-stac#
sat-stac is an actively maintained STAC client for Python 3. Its last release was less than 2 months ago and its
last commit was at that same time. It has had 2 contributors within the last year and it supports the latest release
candidate for the STAC spec (as well as previous releases). sat-stac has installation documented in the GitHub repo’s
main README and has 2 tutorials in the form of Jupyter Notebooks in that repo.
sat-stac supports reading STAC catalogs (support for writing STAC catalogs was removed in v0.4.0). There is also an
existing library for working with STAC API - Item Search results called
sat-search that uses sat-stac as its backend.
Decision#
We will use PySTAC as our “backend” for working with STAC objects in Python. While both libraries are well-maintained,
PySTAC has more thorough documentation and seems to be more widely supported through community contribution.
Consequences#
We will need to create our own implementation of a STAC API - Item Search client since there is not existing tooling
based on PySTAC. We will be able to point to the hosted documentation for PySTAC to guide users through existing
functionality for navigating STAC Catalogs. Special care should be taken to ensure that we do not break any of
PySTAC’s functionality through inheritance.