feat: add read, write, and search *_sync (#232)

Closes #96

Author: gadomski

python/rustac/rustac.pyi

@@ -299,6 +299,30 @@ async def read(
         >>> item = await rustac.read("item.json")
     """
 
+def read_sync(
+    href: str,
+    *,
+    format: str | None = None,
+    store: AnyObjectStore | None = None,
+    set_self_link: bool = True,
+) -> dict[str, Any]:
+    """
+    Reads STAC from a href synchronously.
+
+    Args:
+        href: The href to write to
+        format: The input format. If not provided, will be inferred
+            from the href's extension.
+        store: An optional [ObjectStore][]
+        set_self_link: If True, set the `self` link to the value of `href`.
+
+    Returns:
+        The STAC value
+
+    Examples:
+        >>> item = rustac.read_sync("item.json")
+    """
+
 def from_arrow(
     table: arro3.core.Table,
 ) -> dict[str, Any]:
@@ -405,6 +429,82 @@ async def search(
         ... )
     """
 
+def search_sync(
+    href: str,
+    *,
+    intersects: str | dict[str, Any] | None = None,
+    ids: str | list[str] | None = None,
+    collections: str | list[str] | None = None,
+    max_items: int | None = None,
+    limit: int | None = None,
+    bbox: list[float] | None = None,
+    datetime: str | None = None,
+    include: str | list[str] | None = None,
+    exclude: str | list[str] | None = None,
+    sortby: str | list[str | dict[str, str]] | None = None,
+    filter: str | dict[str, Any] | None = None,
+    query: dict[str, Any] | None = None,
+    use_duckdb: bool | None = None,
+    **kwargs: str,
+) -> list[dict[str, Any]]:
+    """
+    Searches a STAC API server or a stac-geoparquet file synchronously.
+
+    Args:
+        href: The STAC API to search.
+        intersects: Searches items
+            by performing intersection between their geometry and provided GeoJSON
+            geometry.
+        ids: Array of Item ids to return.
+        collections: Array of one or more Collection IDs that
+            each matching Item must be in.
+        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: 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.
+
+            Partial dates are also supported and will be automatically expanded
+            to full RFC 3339 datetime ranges:
+
+            - Year only (e.g., "2023") expands to 2023-01-01T00:00:00Z/2023-12-31T23:59:59Z
+            - Year-Month (e.g., "2023-06") expands to 2023-06-01T00:00:00Z/2023-06-30T23:59:59Z
+            - ISO 8601 date (e.g., "2023-06-15") expands to 2023-06-15T00:00:00Z/2023-06-15T23:59:59Z
+            - Ranges also support partial dates (e.g., "2017/2018", "2017-06/2017-07")
+        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: 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: 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: Additional filtering based on properties.
+            It is recommended to use filter instead, if possible.
+        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.
+
+    Returns:
+        STAC items
+
+    Examples:
+        >>> items = rustac.search_sync(
+        ...     "https://landsatlook.usgs.gov/stac-server",
+        ...     collections=["landsat-c2l2-sr"],
+        ...     intersects={"type": "Point", "coordinates": [-105.119, 40.173]},
+        ...     sortby="-properties.datetime",
+        ...     max_items=1,
+        ... )
+    """
+
 async def iter_search(
     href: str,
     *,
@@ -613,6 +713,39 @@ async def write(
         >>> await rustac.write("items.parquet", items)
     """
 
+def write_sync(
+    href: str,
+    value: dict[str, Any] | Sequence[dict[str, Any]],
+    *,
+    format: str | None = None,
+    parquet_compression: str | None = None,
+    store: AnyObjectStore | None = None,
+) -> dict[str, str] | None:
+    """
+    Writes STAC to a href synchronously.
+
+    Args:
+        href: The href to write to
+        value: The value to write. This
+            can be a STAC dictionary or a list of items.
+        format: The output format to write. If not provided, will be
+            inferred from the href's extension.
+        parquet_compression: If writing stac-geoparquet, sets the compression
+            algorithm.
+            https://docs.rs/parquet/latest/parquet/basic/enum.Compression.html
+            is a list of what's available.
+        store: The object store to use for writing.
+
+    Returns:
+        The result of putting data into an object store, e.g. the e_tag and the
+            version. None is returned if the file was written locally.
+
+    Examples:
+        >>> with open("items.json") as f:
+        ...     items = json.load(f)
+        >>> rustac.write_sync("items.parquet", items)
+    """
+
 def version(
     name: Literal["stac"]
     | Literal["stac-api"]

src/lib.rs

@@ -38,13 +38,16 @@ fn rustac(py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
     )?)?;
     m.add_function(wrap_pyfunction!(migrate::migrate, m)?)?;
     m.add_function(wrap_pyfunction!(read::read, m)?)?;
+    m.add_function(wrap_pyfunction!(read::read_sync, m)?)?;
     m.add_function(wrap_pyfunction!(search::iter_search, m)?)?;
     m.add_function(wrap_pyfunction!(search::search, m)?)?;
+    m.add_function(wrap_pyfunction!(search::search_sync, m)?)?;
     m.add_function(wrap_pyfunction!(search::search_to, m)?)?;
     m.add_function(wrap_pyfunction!(version::sha, m)?)?;
     m.add_function(wrap_pyfunction!(version::version, m)?)?;
     m.add_function(wrap_pyfunction!(walk::walk, m)?)?;
     m.add_function(wrap_pyfunction!(write::write, m)?)?;
+    m.add_function(wrap_pyfunction!(write::write_sync, m)?)?;
 
     pyo3_object_store::register_store_module(py, m, "rustac", "store")?;
     pyo3_object_store::register_exceptions_module(py, m, "rustac", "exceptions")?;

src/read.rs

@@ -4,6 +4,35 @@ use pyo3_object_store::AnyObjectStore;
 use stac::{Link, Links, SelfHref, Value};
 use stac_io::{Format, StacStore};
 
+async fn read_inner(
+    href: String,
+    format: Format,
+    store: Option<AnyObjectStore>,
+    set_self_link: bool,
+) -> PyResult<Json<Value>> {
+    let mut value: Value = if let Some(store) = store {
+        StacStore::from(store)
+            .get_format(&href, format)
+            .await
+            .map_err(Error::from)?
+    } else {
+        let (store, path) = stac_io::parse_href(&href).map_err(Error::from)?;
+        store.get_format(path, format).await.map_err(Error::from)?
+    };
+    if set_self_link {
+        value.set_link(Link::self_(href.clone()));
+    }
+    *value.self_href_mut() = Some(href.into());
+    Ok(Json(value))
+}
+
+fn parse_format(format: Option<String>, href: &str) -> Format {
+    format
+        .and_then(|f| f.parse::<Format>().ok())
+        .or_else(|| Format::infer_from_href(href))
+        .unwrap_or_default()
+}
+
 #[pyfunction]
 #[pyo3(signature = (href, *, format=None, store=None, set_self_link=true))]
 pub fn read(
@@ -13,24 +42,24 @@ pub fn read(
     store: Option<AnyObjectStore>,
     set_self_link: bool,
 ) -> PyResult<Bound<'_, PyAny>> {
-    let format = format
-        .and_then(|f| f.parse::<Format>().ok())
-        .or_else(|| Format::infer_from_href(&href))
-        .unwrap_or_default();
+    let format = parse_format(format, &href);
     pyo3_async_runtimes::tokio::future_into_py(py, async move {
-        let mut value: Value = if let Some(store) = store {
-            StacStore::from(store)
-                .get_format(&href, format)
-                .await
-                .map_err(Error::from)?
-        } else {
-            let (store, path) = stac_io::parse_href(&href).map_err(Error::from)?;
-            store.get_format(path, format).await.map_err(Error::from)?
-        };
-        if set_self_link {
-            value.set_link(Link::self_(href.clone()));
-        }
-        *value.self_href_mut() = Some(href.into());
-        Ok(Json(value))
+        read_inner(href, format, store, set_self_link).await
+    })
+}
+
+#[pyfunction]
+#[pyo3(signature = (href, *, format=None, store=None, set_self_link=true))]
+pub fn read_sync(
+    py: Python<'_>,
+    href: String,
+    format: Option<String>,
+    store: Option<AnyObjectStore>,
+    set_self_link: bool,
+) -> PyResult<Json<Value>> {
+    let format = parse_format(format, &href);
+    py.detach(|| {
+        pyo3_async_runtimes::tokio::get_runtime()
+            .block_on(async { read_inner(href, format, store, set_self_link).await })
     })
 }

src/search.rs

@@ -110,9 +110,9 @@ pub fn search<'py>(
         query,
         kwargs,
     )?;
-    if use_duckdb
-        .unwrap_or_else(|| matches!(Format::infer_from_href(&href), Some(Format::Geoparquet(_))))
-    {
+    let use_duckdb = use_duckdb
+        .unwrap_or_else(|| matches!(Format::infer_from_href(&href), Some(Format::Geoparquet(_))));
+    if use_duckdb {
         pyo3_async_runtimes::tokio::future_into_py(py, async move {
             let value = search_duckdb(href, search, max_items)?;
             Ok(Json(value.items))
@@ -125,6 +125,56 @@ pub fn search<'py>(
     }
 }
 
+#[pyfunction]
+#[pyo3(signature = (href, *, intersects=None, ids=None, collections=None, max_items=None, limit=None, bbox=None, datetime=None, include=None, exclude=None, sortby=None, filter=None, query=None, use_duckdb=None, **kwargs))]
+#[allow(clippy::too_many_arguments)]
+pub fn search_sync<'py>(
+    py: Python<'py>,
+    href: String,
+    intersects: Option<StringOrDict>,
+    ids: Option<StringOrList>,
+    collections: Option<StringOrList>,
+    max_items: Option<usize>,
+    limit: Option<u64>,
+    bbox: Option<Vec<f64>>,
+    datetime: Option<String>,
+    include: Option<StringOrList>,
+    exclude: Option<StringOrList>,
+    sortby: Option<PySortby<'py>>,
+    filter: Option<StringOrDict>,
+    query: Option<Bound<'py, PyDict>>,
+    use_duckdb: Option<bool>,
+    kwargs: Option<Bound<'_, PyDict>>,
+) -> PyResult<Json<Vec<Map<String, Value>>>> {
+    let search = build(
+        intersects,
+        ids,
+        collections,
+        limit,
+        bbox,
+        datetime,
+        include,
+        exclude,
+        sortby,
+        filter,
+        query,
+        kwargs,
+    )?;
+    let use_duckdb = use_duckdb
+        .unwrap_or_else(|| matches!(Format::infer_from_href(&href), Some(Format::Geoparquet(_))));
+    if use_duckdb {
+        let value = search_duckdb(href, search, max_items)?;
+        Ok(Json(value.items))
+    } else {
+        py.detach(|| {
+            pyo3_async_runtimes::tokio::get_runtime().block_on(async {
+                let value = search_api(href, search, max_items).await?;
+                Ok(Json(value.items))
+            })
+        })
+    }
+}
+
 #[pyfunction]
 #[pyo3(signature = (outfile, href, *, intersects=None, ids=None, collections=None, max_items=None, limit=None, bbox=None, datetime=None, include=None, exclude=None, sortby=None, filter=None, query=None, format=None, parquet_compression=None, store=None, use_duckdb=None, **kwargs))]
 #[allow(clippy::too_many_arguments)]