Metadata-Version: 2.4
Name: pystac_monty
Version: 0.2.4
Summary: Python library for working with the SpatioTemporal Asset Catalog (STAC) extension for Montandon
Author-email: Emmanuel Mathot <emmanuel.mathot@gmail.com>
License: Apache-2.0
Project-URL: Documentation, https://ifrcgo.org/monty-stac-extension/
Project-URL: Repository, https://github.com/IFRCGo/pystac-monty
Project-URL: Issues, https://github.com/IFRCGo/pystac-monty/issues
Project-URL: Changelog, https://github.com/IFRCGo/pystac-monty/blob/main/CHANGELOG.md
Project-URL: Discussions, https://github.com/radiantearth/stac-spec/discussions/categories/stac-software
Keywords: pystac,disaster,hazard,catalog,STAC,Montandon,Monty
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-dateutil>=2.7.0
Requires-Dist: pystac>=1.11.0
Requires-Dist: geojson>=2.5.0
Requires-Dist: markdownify>=0.14.1
Requires-Dist: pytz>=2021.1
Requires-Dist: pandas>=2.2.0
Requires-Dist: lxml>=5.3.0
Requires-Dist: pydantic>=2.10.6
Requires-Dist: ijson>=3.4.0
Requires-Dist: pyarrow>=22.0.0
Requires-Dist: shapely>=2.0.0
Dynamic: license-file

# Montandon Extension for PySTAC

This project provides a Python library for working with the SpatioTemporal Asset Catalog (STAC) extension for Montandon. It extends the capabilities of PySTAC to handle disaster and hazard-related data using the Montandon schema.

## Features

- Extend STAC Collections and Items with Montandon-specific properties.
- Support for hazard detail objects.
- Integration with GDACS data sources.
- Utilities for pairing and correlation ID generation.

## Installation

To install the library, use pip:

```sh
pip install pystac_monty
```

To install the tool `jq`, use the following:

Debian/Ubuntu/Mint environment
```sh
sudo apt-get update
sudo apt-get install jq
```

MacOS environment
```sh
brew install jq
```

To check if it is install correctly

```sh
jq --version
```

## Usage

### Batch export (CLI)

To export upstream source files to on-disk Monty STAC, first initialise the submodule:

```sh
git submodule update --init --recursive
```

Then run the CLI. `SOURCE` is one of `glide`, `gfd`, `gdacs`; `--input` accepts a source-specific file (see the `convert_*` docstrings in `pystac_monty/sources/batch_export.py`):

```sh
pystac-monty SOURCE --input path/to/input --output path/to/output/
```

The output directory will contain role collections (`{slug}-events/`, `{slug}-hazards/`, etc.), each with a collection JSON and flat item files. Raw source payloads live in `monty-stac-extension/docs/model/sources/` — the `examples/` folders are published STAC output, not inputs.

To add more sources or use the exporter programmatically, see `pystac_monty/exporter.py`.

### Extending a STAC Item

The library provides classes and functions to work with Montandon STAC objects. Here is an example of how to create a Montandon Item:

```python
import pystac
from pystac_monty.extension import MontyExtension

item = pystac.Item(...)  # Create or load a STAC Item
monty_ext = MontyExtension.ext(item)
monty_ext.episode_number = 1
print(monty_ext.episode_number)
```

### Working with GDACS data

To transform GDACS event data into STAC Items:

```python
from pystac_monty.sources.gdacs import GDACSTransformer, GDACSDataSource

data_source = GDACSDataSource(source_url="...", data="...", type=GDACSDataSourceType.EVENT)
transformer = GDACSTransformer(data=[data_source])
items = transformer.make_items()
```

## Development

To set up the development environment:

```sh
pip install uv
uv sync
```

To run the tests:

1. Make the test with actual calls to http and write them in the cassette files:

```sh
uv run pytest -v -s --record-mode rewrite
```

2. Run the tests with the recorded calls:

```sh
uv run pytest -v -s
```

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

## License

This project is licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for more details.

### Links

- [Documentation](https://pystac.readthedocs.io)
- [Repository](https://github.com/IFRCGo/monty-stac-extension)
- [Issues](https://github.com/IFRCGo/monty-stac-extension/issues)
