stactools

stactools copied to clipboard

As initially mentioned in #134, we don't have documentation/procedures for adding a new core package. These documents should be developed and included in the readthedocs. They should outline:

• How to stand up a new stactools package (i.e. "clone the template repo into your own user/organization, change the names, etc")
• Expectations for testing, etc
• How to request inclusion as a core package
• The acceptance criteria for a core package (public dataset, possibly usable to people outside of the developing organization, suitability for STAC, etc)
• How to migrate the repo from the user to https://github.com/stactools-packages
• Expectations for keeping core packages up-to-date, passing CI, etc
• Deprecation/removal procedures (no longer maintained, etc)

Another thing that should be on the list is a screenshot or served instance of pip install stactools-browse && stac browse /my/example/catalog.json to demonstrate what the proposed dataset's catalog looks like.

@gadomski seems important to document that stactools is using "native namespace packages" https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages (yes?). If a new plugin package failed to omit stactools/__init__.py then the entire namespace in that installation could be broken.

So we have it in the README and as a part of the stactools package template, but you're right that its not immediately obvious.

I haven't looked into it at all, but do you know of a library way of checking for that offending stactools/__init__.py file and throwing a clear exception (e.g. "Stactools package stactools.foo breaks namespace packaging by including an __init__.py. Please uninstall stactools-foo" or whatever). It could be nice to be defensive programmatically.

In the past I've used custom pre-commit scripts. So you could have a simple Python script that just iterates over each package and raises an error if stactools/__init__.py exists.

I was thinking more from the stac-utils/stactools perspective -- like is there a hook I can put in the plugin mechanism to detect a bad stactools package install?

@gadomski I don't think so, doesn't the offending file corrupt module importing?