feat(python): add migrate_href

Author: gadomski

python/CHANGELOG.md

@@ -6,6 +6,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+- `main` and entry point script ([#333](https://github.com/stac-utils/stac-rs/pull/333))
+- `migrate_href` ([#334](https://github.com/stac-utils/stac-rs/pull/334))
+
 ## [0.0.3] - 2024-08-29
 
 ### Added

python/src/lib.rs

@@ -72,6 +72,45 @@ fn migrate<'py>(value: &Bound<'py, PyDict>, version: Option<&str>) -> PyResult<B
     value.downcast_into().map_err(PyErr::from)
 }
 
+/// Migrates a STAC dictionary at the given href to another version.
+///
+/// Migration can be as simple as updating the `stac_version` attribute, but
+/// sometimes can be more complicated. For example, when migrating to v1.1.0,
+/// [eo:bands and raster:bands should be consolidated to the new bands
+/// structure](https://github.com/radiantearth/stac-spec/releases/tag/v1.1.0-beta.1).
+///
+/// See [the stac-rs
+/// documentation](https://docs.rs/stac/latest/stac/enum.Version.html) for
+/// supported versions.
+///
+/// Args:
+///     href (str): The href to read the STAC object from
+///     version (str | None): The version to migrate to. If not provided, the
+///         value will be migrated to the latest stable version.
+///
+/// Examples:
+///     >>> item = stacrs.migrate_href("examples/simple-item.json", "1.1.0-beta.1")
+///     >>> assert item["stac_version"] == "1.1.0-beta.1"
+#[pyfunction]
+#[pyo3(signature = (href, version=None))]
+fn migrate_href<'py>(
+    py: Python<'py>,
+    href: &str,
+    version: Option<&str>,
+) -> PyResult<Bound<'py, PyDict>> {
+    let value: Value = stac::read(href).map_err(|err| StacrsError::new_err(err.to_string()))?;
+    let version = version
+        .map(|version| version.parse())
+        .transpose()
+        .map_err(|err: stac::Error| StacrsError::new_err(err.to_string()))?
+        .unwrap_or_default();
+    let value = value
+        .migrate(version)
+        .map_err(|err| StacrsError::new_err(err.to_string()))?;
+    let value = pythonize::pythonize(py, &value)?;
+    value.downcast_into().map_err(PyErr::from)
+}
+
 /// Validates a single href with json-schema.
 ///
 /// Args:
@@ -134,6 +173,7 @@ fn validate_value(value: Value) -> PyResult<()> {
 fn stacrs(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(main, m)?)?;
     m.add_function(wrap_pyfunction!(migrate, m)?)?;
+    m.add_function(wrap_pyfunction!(migrate_href, m)?)?;
     m.add_function(wrap_pyfunction!(validate_href, m)?)?;
     m.add_function(wrap_pyfunction!(validate, m)?)?;
     m.add("StacrsError", m.py().get_type_bound::<StacrsError>())?;

python/stacrs.pyi

@@ -3,6 +3,7 @@ from typing import Any, Optional
 class StacrsError(Exception): ...
 
 def main() -> int: ...
+def migrate_href(href: str, version: Optional[str] = None) -> dict[str, Any]: ...
 def migrate(value: dict[str, Any], version: Optional[str] = None) -> dict[str, Any]: ...
 def validate_href(href: str) -> None: ...
 def validate(value: dict[str, Any]) -> None: ...

python/tests/test_migrate.py

@@ -1,3 +1,4 @@
+from pathlib import Path
 from typing import Any
 
 import stacrs
@@ -6,3 +7,10 @@
 def test_migrate(item: dict[str, Any]) -> None:
     item = stacrs.migrate(item, version="1.1.0-beta.1")
     assert item["stac_version"] == "1.1.0-beta.1"
+
+
+def test_migrate_href(spec_examples: Path) -> None:
+    item = stacrs.migrate_href(
+        str(spec_examples / "simple-item.json"), version="1.1.0-beta.1"
+    )
+    assert item["stac_version"] == "1.1.0-beta.1"