| Name | stac-pydantic JSON |
| Version |
3.0.0
JSON |
| download |
| home_page | |
| Summary | Pydantic data models for the STAC spec |
| upload_time | 2024-01-25 13:16:05 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
stac
pydantic
validation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# stac-pydantic
[](https://github.com/stac-utils/stac-pydantic/actions/workflows/cicd.yml)
[Pydantic](https://pydantic-docs.helpmanual.io/) models for [STAC](https://github.com/radiantearth/stac-spec) Catalogs, Collections, Items, and the [STAC API](https://github.com/radiantearth/stac-api-spec) spec.
Initially developed by [arturo-ai](https://github.com/arturo-ai).
The main purpose of this library is to provide reusable request/response models for tools such as [fastapi](https://fastapi.tiangolo.com/).
For more comprehensive schema validation and robust extension support, use [pystac](https://github.com/stac-utils/pystac).
## Installation
```shell
pip install stac-pydantic
```
For local development:
```shell
pip install -e '.[dev,lint]'
```
| stac-pydantic | STAC Version | STAC API Version | Pydantic Version |
|--------------|---------------|------------------|-----------------|
| 1.2.x | 1.0.0-beta.1 | <1* | ^1.6 |
| 1.3.x | 1.0.0-beta.2 | <1* | ^1.6 |
| 2.0.x | 1.0.0 | <1* | ^1.6 |
| 3.0.x | 1.0.0 | 1.0.0 | ^2.4 |
\* various beta releases, specs not fully implemented
## Development
Install the [pre-commit](https://pre-commit.com/) hooks:
```shell
pre-commit install
```
## Testing
Ensure you have all Python versions installed that the tests will be run against. If using pyenv, run:
```shell
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
```
Run the entire test suite:
```shell
tox
```
Run a single test case using the standard pytest convention:
```shell
pytest -v tests/test_models.py::test_item_extensions
```
## Usage
### Loading Models
Load data into models with standard pydantic:
```python
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"
```
### Extensions
STAC defines many extensions which let the user customize the data in their catalog. `stac-pydantic.extensions.validate_extensions` will validate a `dict`, `Item`, `Collection` or `Catalog` against the schema urls provided in the `stac_extensions` property:
```python
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
```
The complete list of current STAC Extensions can be found [here](https://stac-extensions.github.io/).
#### Vendor Extensions
The same procedure described above works for any STAC Extension schema as long as it can be loaded from a public url.
### STAC API
The [STAC API Specs](https://github.com/radiantearth/stac-api-spec) extent the core STAC specification for implementing dynamic catalogs. STAC Objects used in an API context should always import models from the `api` subpackage. This package extends
Catalog, Collection, and Item models with additional fields and validation rules and introduces Collections and ItemCollections models and Pagination/ Search Links.
It also implements models for defining ItemSeach queries.
```python
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"
}],
})
```
### Exporting Models
Most STAC extensions are namespaced with a colon (ex `eo:gsd`) to keep them distinct from other extensions. Because
Python doesn't support the use of colons in variable names, we use [Pydantic aliasing](https://pydantic-docs.helpmanual.io/usage/model_config/#alias-generator)
to add the namespace upon model export. This requires [exporting](https://pydantic-docs.helpmanual.io/usage/exporting_models/)
the model with the `by_alias = True` parameter. Export methods (`model_dump()` and `model_dump_json()`) for models in this library have `by_alias` and `exclude_unset` st to `True` by default:
```python
item_dict = item.model_dump()
assert item_dict['properties']['landsat:row'] == item.properties.row == 250
```
### CLI
```text
Usage: stac-pydantic [OPTIONS] COMMAND [ARGS]...
stac-pydantic cli group
Options:
--help Show this message and exit.
Commands:
validate-item Validate STAC Item
```
Raw data
{
"_id": null,
"home_page": "",
"name": "stac-pydantic",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "stac,pydantic,validation",
"author": "",
"author_email": "Arturo Engineering <engineering@arturo.ai>",
"download_url": "https://files.pythonhosted.org/packages/28/5e/f9d515368343a304efaa403ebbf5d30eaea099376d84dd2b43e388180942/stac-pydantic-3.0.0.tar.gz",
"platform": null,
"description": "# stac-pydantic\n\n[](https://github.com/stac-utils/stac-pydantic/actions/workflows/cicd.yml)\n\n[Pydantic](https://pydantic-docs.helpmanual.io/) models for [STAC](https://github.com/radiantearth/stac-spec) Catalogs, Collections, Items, and the [STAC API](https://github.com/radiantearth/stac-api-spec) spec.\nInitially developed by [arturo-ai](https://github.com/arturo-ai).\n\nThe main purpose of this library is to provide reusable request/response models for tools such as [fastapi](https://fastapi.tiangolo.com/).\nFor more comprehensive schema validation and robust extension support, use [pystac](https://github.com/stac-utils/pystac).\n\n## Installation\n\n```shell\npip install stac-pydantic\n```\n\nFor local development:\n\n```shell\npip install -e '.[dev,lint]'\n```\n\n| stac-pydantic | STAC Version | STAC API Version | Pydantic Version |\n|--------------|---------------|------------------|-----------------|\n| 1.2.x | 1.0.0-beta.1 | <1* | ^1.6 |\n| 1.3.x | 1.0.0-beta.2 | <1* | ^1.6 |\n| 2.0.x | 1.0.0 | <1* | ^1.6 |\n| 3.0.x | 1.0.0 | 1.0.0 | ^2.4 |\n\n\\* various beta releases, specs not fully implemented\n\n## Development\n\nInstall the [pre-commit](https://pre-commit.com/) hooks:\n\n```shell\npre-commit install\n```\n\n## Testing\n\nEnsure you have all Python versions installed that the tests will be run against. If using pyenv, run:\n\n```shell\npyenv install 3.8.18\npyenv install 3.9.18\npyenv install 3.10.13\npyenv install 3.11.5\npyenv local 3.8.18 3.9.18 3.10.13 3.11.5\n```\n\nRun the entire test suite:\n\n```shell\ntox\n```\n\nRun a single test case using the standard pytest convention:\n\n```shell\npytest -v tests/test_models.py::test_item_extensions\n```\n\n## Usage\n\n### Loading Models\n\nLoad data into models with standard pydantic:\n\n```python\nfrom stac_pydantic import Catalog\n\nstac_catalog = {\n \"type\": \"Catalog\",\n \"stac_version\": \"1.0.0\",\n \"id\": \"sample\",\n \"description\": \"This is a very basic sample catalog.\",\n \"links\": [\n {\n \"href\": \"item.json\",\n \"rel\": \"item\"\n }\n ]\n}\n\ncatalog = Catalog(**stac_catalog)\nassert catalog.id == \"sample\"\nassert catalog.links[0].href == \"item.json\"\n```\n\n### Extensions\n\nSTAC defines many extensions which let the user customize the data in their catalog. `stac-pydantic.extensions.validate_extensions` will validate a `dict`, `Item`, `Collection` or `Catalog` against the schema urls provided in the `stac_extensions` property:\n\n```python\nfrom stac_pydantic import Item\nfrom stac_pydantic.extensions import validate_extensions\n\nstac_item = {\n \"id\": \"12345\",\n \"type\": \"Feature\",\n \"stac_extensions\": [\n \"https://stac-extensions.github.io/eo/v1.0.0/schema.json\"\n ],\n \"geometry\": { \"type\": \"Point\", \"coordinates\": [0, 0] },\n \"bbox\": [0.0, 0.0, 0.0, 0.0],\n \"properties\": {\n \"datetime\": \"2020-03-09T14:53:23.262208+00:00\",\n \"eo:cloud_cover\": 25,\n },\n \"links\": [],\n \"assets\": {},\n}\n\nmodel = Item(**stac_item)\nvalidate_extensions(model, reraise_exception=True)\nassert getattr(model.properties, \"eo:cloud_cover\") == 25\n```\n\nThe complete list of current STAC Extensions can be found [here](https://stac-extensions.github.io/).\n\n#### Vendor Extensions\n\nThe same procedure described above works for any STAC Extension schema as long as it can be loaded from a public url.\n\n### STAC API\n\nThe [STAC API Specs](https://github.com/radiantearth/stac-api-spec) extent the core STAC specification for implementing dynamic catalogs. STAC Objects used in an API context should always import models from the `api` subpackage. This package extends\nCatalog, Collection, and Item models with additional fields and validation rules and introduces Collections and ItemCollections models and Pagination/ Search Links.\nIt also implements models for defining ItemSeach queries.\n\n```python\nfrom stac_pydantic.api import Item, ItemCollection\n\nstac_item = Item(**{\n \"id\": \"12345\",\n \"type\": \"Feature\",\n \"stac_extensions\": [],\n \"geometry\": { \"type\": \"Point\", \"coordinates\": [0, 0] },\n \"bbox\": [0.0, 0.0, 0.0, 0.0],\n \"properties\": {\n \"datetime\": \"2020-03-09T14:53:23.262208+00:00\",\n },\n \"collection\": \"CS3\",\n \"links\": [\n {\n \"rel\": \"self\",\n \"href\": \"http://stac.example.com/catalog/collections/CS3-20160503_132130_04/items/CS3-20160503_132130_04.json\"\n },\n {\n \"rel\": \"collection\",\n \"href\": \"http://stac.example.com/catalog/CS3-20160503_132130_04/catalog.json\"\n },\n {\n \"rel\": \"root\",\n \"href\": \"http://stac.example.com/catalog\"\n }],\n \"assets\": {},\n })\n\nstac_item_collection = ItemCollection(**{\n \"type\": \"FeatureCollection\",\n \"features\": [stac_item],\n \"links\": [\n {\n \"rel\": \"self\",\n \"href\": \"http://stac.example.com/catalog/search?collection=CS3\",\n \"type\": \"application/geo+json\"\n },\n {\n \"rel\": \"root\",\n \"href\": \"http://stac.example.com/catalog\",\n \"type\": \"application/json\"\n }],\n })\n```\n\n### Exporting Models\n\nMost STAC extensions are namespaced with a colon (ex `eo:gsd`) to keep them distinct from other extensions. Because\nPython doesn't support the use of colons in variable names, we use [Pydantic aliasing](https://pydantic-docs.helpmanual.io/usage/model_config/#alias-generator)\nto add the namespace upon model export. This requires [exporting](https://pydantic-docs.helpmanual.io/usage/exporting_models/)\nthe model with the `by_alias = True` parameter. Export methods (`model_dump()` and `model_dump_json()`) for models in this library have `by_alias` and `exclude_unset` st to `True` by default:\n\n```python\nitem_dict = item.model_dump()\nassert item_dict['properties']['landsat:row'] == item.properties.row == 250\n```\n\n### CLI\n\n```text\nUsage: stac-pydantic [OPTIONS] COMMAND [ARGS]...\n\n stac-pydantic cli group\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n validate-item Validate STAC Item\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Pydantic data models for the STAC spec",
"version": "3.0.0",
"project_urls": {
"homepage": "https://github.com/stac-utils/stac-pydantic",
"repository": "https://github.com/stac-utils/stac-pydantic.git"
},
"split_keywords": [
"stac",
"pydantic",
"validation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "640c6eb8036ad988a908a5d39a4c7094db7adcb1d521eecd3b4e6eda8dbc98e3",
"md5": "b8c275a29f5738885a43f6b25ff1b661",
"sha256": "5696aa2a44073b1c1bc985afbe85ce6c6e76040161d8b8ccbe4e94177f06a7a4"
},
"downloads": -1,
"filename": "stac_pydantic-3.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b8c275a29f5738885a43f6b25ff1b661",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22893,
"upload_time": "2024-01-25T13:16:03",
"upload_time_iso_8601": "2024-01-25T13:16:03.175947Z",
"url": "https://files.pythonhosted.org/packages/64/0c/6eb8036ad988a908a5d39a4c7094db7adcb1d521eecd3b4e6eda8dbc98e3/stac_pydantic-3.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "285ef9d515368343a304efaa403ebbf5d30eaea099376d84dd2b43e388180942",
"md5": "79fa67448427326ee52df543c411f408",
"sha256": "6e527e1a79aaf48d506586bd8e59ca52298cc6ece55d863c96cf0a9433fe44e1"
},
"downloads": -1,
"filename": "stac-pydantic-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "79fa67448427326ee52df543c411f408",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19599,
"upload_time": "2024-01-25T13:16:05",
"upload_time_iso_8601": "2024-01-25T13:16:05.428207Z",
"url": "https://files.pythonhosted.org/packages/28/5e/f9d515368343a304efaa403ebbf5d30eaea099376d84dd2b43e388180942/stac-pydantic-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-25 13:16:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stac-utils",
"github_project": "stac-pydantic",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "stac-pydantic"
}
