stac-pydantic

Pydantic models for STAC Catalogs, Collections, Items, and the STAC API spec. Initially developed by arturo-ai.

本库的主要目的是为诸如 fastapi 等工具提供可重用的请求/响应模型。为了更全面的模式验证和强大的扩展支持，请使用 pystac。

安装

python -m pip install stac-pydantic

# or

python -m pip install stac-pydantic["validation"]

对于本地开发

python -m pip install -e '.[dev,lint]'

* 各种beta版本，规格尚未完全实现

开发

安装 pre-commit 钩子

pre-commit install

测试

确保您已安装所有将运行测试的Python版本。如果使用pyenv，请运行

pyenv install 3.8.18
pyenv install 3.9.18
pyenv install 3.10.13
pyenv install 3.11.5
pyenv local 3.8.18 3.9.18 3.10.13 3.11.5

运行整个测试套件

tox

使用标准pytest约定运行单个测试用例

python -m pytest -v tests/test_models.py::test_item_extensions

用法

加载模型

使用标准pydantic将数据加载到模型中

from stac_pydantic import Catalog

stac_catalog = {
  "type": "Catalog",
  "stac_version": "1.0.0",
  "id": "sample",
  "description": "This is a very basic sample catalog.",
  "links": [
    {
      "href": "item.json",
      "rel": "item"
    }
  ]
}

catalog = Catalog(**stac_catalog)
assert catalog.id == "sample"
assert catalog.links[0].href == "item.json"

扩展

STAC定义了许多扩展，允许用户自定义其目录中的数据。stac-pydantic.extensions.validate_extensions 从在stac_extensions属性中提供的URL获取JSON模式（缓存最后获取的），并将dict、Item、Collection或Catalog与获取的这些模式进行验证

from stac_pydantic import Item
from stac_pydantic.extensions import validate_extensions

stac_item = {
    "id": "12345",
    "type": "Feature",
    "stac_extensions": [
        "https://stac-extensions.github.io/eo/v1.0.0/schema.json"
    ],
    "geometry": { "type": "Point", "coordinates": [0, 0] },
    "bbox": [0.0, 0.0, 0.0, 0.0],
    "properties": {
        "datetime": "2020-03-09T14:53:23.262208+00:00",
        "eo:cloud_cover": 25,
    },
    "links": [],
    "assets": {},
}

model = Item(**stac_item)
validate_extensions(model, reraise_exception=True)
assert getattr(model.properties, "eo:cloud_cover") == 25

当前STAC扩展的完整列表可以在这里找到。

供应商扩展

只要可以从公共URL加载，上述描述的相同过程适用于任何STAC扩展模式。

STAC API

STAC API 规范 扩展了核心STAC规范，以实现动态目录。在API上下文中使用的STAC对象应始终从api子包导入模型。该包扩展了目录、集合和项目模型，并引入了集合和项目集合模型以及分页/搜索链接。它还实现了用于定义项目搜索查询的模型。

from stac_pydantic.api import Item, ItemCollection

stac_item = Item(**{
    "id": "12345",
    "type": "Feature",
    "stac_extensions": [],
    "geometry": { "type": "Point", "coordinates": [0, 0] },
    "bbox": [0.0, 0.0, 0.0, 0.0],
    "properties": {
        "datetime": "2020-03-09T14:53:23.262208+00:00",
    },
    "collection": "CS3",
    "links": [
          {
            "rel": "self",
            "href": "http://stac.example.com/catalog/collections/CS3-20160503_132130_04/items/CS3-20160503_132130_04.json"
          },
          {
            "rel": "collection",
            "href": "http://stac.example.com/catalog/CS3-20160503_132130_04/catalog.json"
          },
          {
            "rel": "root",
            "href": "http://stac.example.com/catalog"
          }],
    "assets": {},
    })

stac_item_collection = ItemCollection(**{
    "type": "FeatureCollection",
    "features": [stac_item],
    "links": [
          {
            "rel": "self",
            "href": "http://stac.example.com/catalog/search?collection=CS3",
            "type": "application/geo+json"
          },
          {
            "rel": "root",
            "href": "http://stac.example.com/catalog",
            "type": "application/json"
          }],
    })

导出模型

大多数STAC扩展使用冒号（例如 eo:gsd）进行命名空间，以与其他扩展区分开来。由于Python不支持在变量名中使用冒号，我们在模型导出时使用Pydantic别名生成器来添加命名空间。这需要使用具有by_alias = True参数的模型进行导出。此库中模型的导出方法（model_dump()和model_dump_json()）默认将by_alias和exclude_unset设置为True

item_dict = item.model_dump()
assert item_dict['properties']['landsat:row'] == item.properties.row == 250

命令行界面

Usage: stac-pydantic [OPTIONS] COMMAND [ARGS]...

  stac-pydantic cli group

Options:
  --help  Show this message and exit.

Commands:
  validate-item  Validate STAC Item