From 64db570113dc4a3e895a051fbd85bb175be267ce Mon Sep 17 00:00:00 2001 From: Pete Gadomski Date: Mon, 10 Mar 2025 07:22:16 -0600 Subject: [PATCH 1/3] fix: clean up docs, remove migrate_href --- src/lib.rs | 1 - src/migrate.rs | 17 -------- stacrs.pyi | 109 +++++++++++++++++++++---------------------------- 3 files changed, 46 insertions(+), 81 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 5fd505a..0bccc93 100644 --- a/src/lib.rs +++ b/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)?)?; diff --git a/src/migrate.rs b/src/migrate.rs index 119bbcd..1d7edd8 100644 --- a/src/migrate.rs +++ b/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> { - 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) -} diff --git a/stacrs.pyi b/stacrs.pyi index c04f81b..2aa6a5c 100644 --- a/stacrs.pyi +++ b/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: From 46fe179bc12bf46736b9e3518d5fc9a42e60220f Mon Sep 17 00:00:00 2001 From: Pete Gadomski Date: Mon, 10 Mar 2025 07:23:09 -0600 Subject: [PATCH 2/3] chore: update changelog --- CHANGELOG.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index b50f8d2..4c98aa2 100644 --- a/CHANGELOG.md +++ b/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-beta.0] - 2025-03-03 From 3b8ea0c48ebccac4a18824a7e26b5b21900db14f Mon Sep 17 00:00:00 2001 From: Pete Gadomski Date: Mon, 10 Mar 2025 07:38:48 -0600 Subject: [PATCH 3/3] fix: remove test --- tests/test_migrate.py | 8 -------- 1 file changed, 8 deletions(-) diff --git a/tests/test_migrate.py b/tests/test_migrate.py index c905ece..9793d14 100644 --- a/tests/test_migrate.py +++ b/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"