fix: clean up docs, remove migrate_href (#78)

Author: gadomski

CHANGELOG.md

@@ -9,6 +9,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ### Fixed
 
 - Swallow broken pipe errors ([#73](https://github.com/stac-utils/stacrs/pull/73))
+- Clean up docs ([#78](https://github.com/stac-utils/stacrs/pull/78))
+
+### Removed
+
+- `migrate_href` ([#78](https://github.com/stac-utils/stacrs/pull/78))
 
 ## [0.5.9] - 2025-03-03
 

src/lib.rs

@@ -28,7 +28,6 @@ fn stacrs(py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(arrow::to_arrow, m)?)?;
     m.add_function(wrap_pyfunction!(cli::main, m)?)?;
     m.add_function(wrap_pyfunction!(migrate::migrate, m)?)?;
-    m.add_function(wrap_pyfunction!(migrate::migrate_href, m)?)?;
     m.add_function(wrap_pyfunction!(read::read, m)?)?;
     m.add_function(wrap_pyfunction!(search::search, m)?)?;
     m.add_function(wrap_pyfunction!(search::search_to, m)?)?;

src/migrate.rs

@@ -18,20 +18,3 @@ pub fn migrate<'py>(
     let value = value.extract()?;
     Ok(value)
 }
-
-#[pyfunction]
-#[pyo3(signature = (href, version=None))]
-pub fn migrate_href<'py>(
-    py: Python<'py>,
-    href: &str,
-    version: Option<&str>,
-) -> Result<Bound<'py, PyDict>> {
-    let value: Value = stac::read(href).map_err(Error::from)?;
-    let version = version
-        .map(|version| version.parse().unwrap())
-        .unwrap_or_default();
-    let value = value.migrate(&version)?;
-    let value = pythonize::pythonize(py, &value)?;
-    let value = value.extract()?;
-    Ok(value)
-}

stacrs.pyi

@@ -1,4 +1,4 @@
-from typing import Any, AsyncIterator, Optional, Tuple
+from typing import Any, AsyncIterator, Literal, Optional, Tuple
 
 import arro3.core
 
@@ -142,29 +142,6 @@ class DuckdbClient:
             A list of STAC Collections
         """
 
-def migrate_href(href: str, version: Optional[str] = None) -> dict[str, Any]:
-    """
-    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"
-    """
-
 def migrate(value: dict[str, Any], version: Optional[str] = None) -> dict[str, Any]:
     """
     Migrates a STAC dictionary to another version.
@@ -179,8 +156,8 @@ def migrate(value: dict[str, Any], version: Optional[str] = None) -> dict[str, A
     supported versions.
 
     Args:
-        value (dict[str, Any]): The STAC value to migrate
-        version (str | None): The version to migrate to. If not provided, the
+        value: The STAC value to migrate
+        version: The version to migrate to. If not provided, the
             value will be migrated to the latest stable version.
 
     Returns:
@@ -270,35 +247,35 @@ async def search(
     Searches a STAC API server.
 
     Args:
-        href (str): The STAC API to search.
-        intersects (str | dict[str, Any] | GeoInterface | None): Searches items
+        href: The STAC API to search.
+        intersects: Searches items
             by performing intersection between their geometry and provided GeoJSON
             geometry.
-        ids (list[str] | None): Array of Item ids to return.
-        collections (list[str] | None): Array of one or more Collection IDs that
+        ids: Array of Item ids to return.
+        collections: Array of one or more Collection IDs that
             each matching Item must be in.
-        max_items (int | None): The maximum number of items to iterate through.
-        limit (int | None): The page size returned from the server. Use
+        max_items: The maximum number of items to iterate through.
+        limit: The page size returned from the server. Use
             `max_items` to actually limit the number of items returned from this
             function.
-        bbox (list[float] | None): Requested bounding box.
-        datetime (str | None): Single date+time, or a range (`/` separator),
+        bbox: Requested bounding box.
+        datetime: Single date+time, or a range (`/` separator),
             formatted to RFC 3339, section 5.6.  Use double dots .. for open
             date ranges.
-        include (list[str]] | None): fields to include in the response (see [the
+        include: fields to include in the response (see [the
             extension
             docs](https://github.com/stac-api-extensions/fields?tab=readme-ov-file#includeexclude-semantics))
             for more on the semantics).
-        exclude (list[str]] | None): fields to exclude from the response (see [the
+        exclude: fields to exclude from the response (see [the
             extension
             docs](https://github.com/stac-api-extensions/fields?tab=readme-ov-file#includeexclude-semantics))
             for more on the semantics).
-        sortby (list[str] | None): Fields by which to sort results (use `-field` to sort descending).
-        filter (str | dict[str, Any] | none): CQL2 filter expression. Strings
+        sortby: Fields by which to sort results (use `-field` to sort descending).
+        filter: CQL2 filter expression. Strings
             will be interpreted as cql2-text, dictionaries as cql2-json.
-        query (dict[str, Any] | None): Additional filtering based on properties.
+        query: Additional filtering based on properties.
             It is recommended to use filter instead, if possible.
-        use_duckdb (bool | None): Query with DuckDB. If None and the href has a
+        use_duckdb: Query with DuckDB. If None and the href has a
             'parquet' or 'geoparquet' extension, will be set to True. Defaults
             to None.
         kwargs: Additional parameters to pass in to the search.
@@ -340,40 +317,40 @@ async def search_to(
     Searches a STAC API server and saves the result to an output file.
 
     Args:
-        outfile (str): The output href. This can be a local file path, or any
+        outfile: The output href. This can be a local file path, or any
             url scheme supported by [stac::object_store::write].
-        href (str): The STAC API to search.
-        intersects (str | dict[str, Any] | GeoInterface | None): Searches items
+        href: The STAC API to search.
+        intersects: Searches items
             by performing intersection between their geometry and provided GeoJSON
             geometry.
-        ids (list[str] | None): Array of Item ids to return.
-        collections (list[str] | None): Array of one or more Collection IDs that
+        ids: Array of Item ids to return.
+        collections: Array of one or more Collection IDs that
             each matching Item must be in.
-        max_items (int | None): The maximum number of items to iterate through.
-        limit (int | None): The page size returned from the server. Use
+        max_items: The maximum number of items to iterate through.
+        limit: The page size returned from the server. Use
             `max_items` to actually limit the number of items returned from this
             function.
-        bbox (list[float] | None): Requested bounding box.
-        datetime (str | None): Single date+time, or a range ('/' separator),
+        bbox: Requested bounding box.
+        datetime: Single date+time, or a range ('/' separator),
             formatted to RFC 3339, section 5.6.  Use double dots .. for open
             date ranges.
-        include (list[str]] | None): fields to include in the response (see [the
+        include: fields to include in the response (see [the
             extension
             docs](https://github.com/stac-api-extensions/fields?tab=readme-ov-file#includeexclude-semantics))
             for more on the semantics).
-        exclude (list[str]] | None): fields to exclude from the response (see [the
+        exclude: fields to exclude from the response (see [the
             extension
             docs](https://github.com/stac-api-extensions/fields?tab=readme-ov-file#includeexclude-semantics))
             for more on the semantics).
-        sortby (list[str] | None): Fields by which to sort results (use `-field` to sort descending).
-        filter (str | dict[str, Any] | none): CQL2 filter expression. Strings
+        sortby: Fields by which to sort results (use `-field` to sort descending).
+        filter: CQL2 filter expression. Strings
             will be interpreted as cql2-text, dictionaries as cql2-json.
-        query (dict[str, Any] | None): Additional filtering based on properties.
+        query: Additional filtering based on properties.
             It is recommended to use filter instead, if possible.
-        format (str | None): The output format. If none, will be inferred from
+        format: The output format. If none, will be inferred from
             the outfile extension, and if that fails will fall back to compact JSON.
-        options (list[tuple[str, str]] | None): Configuration values to pass to the object store backend.
-        use_duckdb (bool | None): Query with DuckDB. If None and the href has a
+        options: Configuration values to pass to the object store backend.
+        use_duckdb: Query with DuckDB. If None and the href has a
             'parquet' or 'geoparquet' extension, will be set to True. Defaults
             to None.
 
@@ -417,12 +394,12 @@ async def write(
     Writes STAC to a href.
 
     Args:
-        href (str): The href to write to
-        value (dict[str, Any] | list[dict[str, Any]]): The value to write. This
+        href: The href to write to
+        value: The value to write. This
             can be a STAC dictionary or a list of items.
-        format (str | None): The output format to write. If not provided, will be
+        format: The output format to write. If not provided, will be
             inferred from the href's extension.
-        options (list[tuple[str, str]] | None): Options for configuring an
+        options: Options for configuring an
             object store, e.g. your AWS credentials.
 
     Returns:
@@ -435,12 +412,18 @@ async def write(
         >>> await stacrs.write("items.parquet", items)
     """
 
-def version(name: str | None = None) -> str | None:
+def version(
+    name: Literal["stac"]
+    | Literal["stac-api"]
+    | Literal["stac-duckdb"]
+    | Literal["duckdb"]
+    | None = None,
+) -> str | None:
     """
     Returns this package's version, or the version of a upstream.
 
     Args:
-        name (str | None): The name of the upstream version to return. Valid
+        name: The name of the upstream version to return. Valid
             values are "stac", "stac-api", "stac-duckdb", or "duckdb".
 
     Returns:

tests/test_migrate.py

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