Skip to content

feat!: pystac v2#1524

Draft
gadomski wants to merge 66 commits intomainfrom
v2
Draft

feat!: pystac v2#1524
gadomski wants to merge 66 commits intomainfrom
v2

Conversation

@gadomski
Copy link
Copy Markdown
Member

@gadomski gadomski commented Feb 13, 2025

PySTAC v2.0 is a ground-up re-write of PySTAC. Our high-level design goals are a form of Postel's law:

  • Help people make the best STAC possible
  • Help people interact with existing (even poorly constructed or invalid) STAC as easily as possible

To do so, we have some specific implementation strategies.

  • Keep the core data structure APIs basically the same: People are used to the basic methods on Item, Catalog, Collection, etc. We shouldn't change the external APIs unless there's a good reason to.
  • Relax core data structure initializers to accept almost anything, with warnings if something's being changed to make it valid
  • Stay low-dependency by default: This keeps our maintenance burden lower, at the cost of having to hand-roll more stuff ourselves.
  • Replace "implementation" APIs: Item, Catalog, etc are the "what" of pystac. Things like StacIO are the "how". We should create replacement structures for any of these "how" interfaces that we want to dramatically change, rather than try to "fix" the existing ones. Backwards compatibility will be much more difficult for these "how" interfaces, so we shouldn't even try. If possible we should re-write the existing "how" structure (e.g. StacIO) to use the new API, but this should be a lower-priority objective.
  • Do fewer things at once: One of the biggest design problems of PySTAC v1.0 (in this author's opinion) was that many functions tried to be "helpful" by doing a lot of things at once. When possible, we should simplify methods to do just one thing, and provide intuitive patterns for doing complex operations using multiple method calls. Top-level functions can be used to "synthesize" complex operations, e.g. pystac.read_file.

We've got v2 docs here: https://stac-utils.github.io/pystac/

v1 test compatibility

To break the API as little as possible, we're keeping the v1 test suite in tests/v1. As we build v2, we'll update this table to show how close we are to passing all1 v1 tests:

Status Count
❌ Failed 553
✅ Passing 1015
✅ Xfailed 48
✅ Xpassed 2
❌ Errors 8

Footnotes

  1. Some tests, such as those that check for exceptions that we've relaxed, we mark as xfail

@gadomski gadomski changed the title feat: pystac v2 feat!: pystac v2 Jan 7, 2026
@gadomski gadomski marked this pull request as ready for review January 8, 2026 03:57
* Add bands as a top-level constuct
* Add repr for bands
* New implementation of CommonMetadata
* Add common metadata protocols to Item and Asset
Getting `test_asset.py` passing and `test_item_assets` passing with the old `ItemAssetDefinition`. Adds a new `test_item_assets.py` for the new `ItemAsset`. I think we should deprecate `ItemAssetDefiniton` it is unlikely people are really using it since it only came in a year or so ago to replace the old `item_assets` extension.
* refactor(test_posix_path): uses self-href instead of self-link

* make hrefs to be posix-style on load

on load of stac item, initial call to set_self_href has start_href=None, so
make asset hrefs posix style instead of trying to update location

* refactor: self._href must be absolute
 This PR make all the regular datetime fields convert to `dt.datetime` on initialization and when setting. This is not the case for `collection.extent.temporal.interval` yet because it looked like there was some intentional logic there. Also because of rounding you can't guarantee that roundtripping from str -> dt.datetime -> str will give exactly the same string.

---------

Co-authored-by: Ian Cooke <ircwaves@users.noreply.github.com>
* test: verifies self links exist

* feat: restore convenience methods for Link

clone
get_absolute_href (reconsider this)
target.setter (deprecated w/ warning)
collection, self, child, item, derived_from, and canonical

* test: v2 compatibility update of v1/test_link

* test: make link check windows compatible

* test: re-enable test that relative self hrefs are promoted to absolute

* feat: restore Link.resolve_stac_object

* cleanup: revert unnecessary changes

* doc: comment around link target/href handling subtlety

* restore methods with deprecation to minimize friction

* restore additional convenience methods

* feedback: consume and warn if extra_fields in Link init kwargs

* remove unnecessary typing change
@jsignell
Copy link
Copy Markdown
Member

I just ran: uv run pytest tests/v1/extensions/ --v1 on this branch to see where we are at. As it stands right now

244 failed, 305 passed, 7 errors

After #1710 this improves to:

179 failed, 370 passed, 7 errors

* Fix static fields file

* Make Item Properties a `MutableMapping`

* Simplify `Summaries`

* Fix RangeSummary coersion
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants