feat(python): add search

.github/workflows/stacrs.yml

@@ -4,6 +4,9 @@ on:
   push:
     tags:
       - 'python-*'
+  pull_request:
+    paths:
+      - python/**
   workflow_dispatch:
 
 permissions:
@@ -25,7 +28,7 @@ jobs:
       - name: Install dev requirements
         run: pip install -r python/requirements-dev.txt
       - name: Build
-        run: maturin build --manifest-path python/Cargo.toml --out dist
+        run: maturin build --manifest-path python/Cargo.toml --out dist -F geoparquet
       - name: Install stacrs
         run: pip install stacrs --find-links dist --no-index
       - name: Check
@@ -60,7 +63,7 @@ jobs:
         uses: PyO3/maturin-action@v1
         with:
           target: ${{ matrix.platform.target }}
-          args: --release --out dist --find-interpreter --manifest-path python/Cargo.toml
+          args: --release --out dist --find-interpreter --manifest-path python/Cargo.toml -F geoparquet
           sccache: 'true'
       - name: Upload wheels
         uses: actions/upload-artifact@v4
@@ -120,7 +123,7 @@ jobs:
         uses: PyO3/maturin-action@v1
         with:
           target: ${{ matrix.platform.target }}
-          args: --release --out dist --find-interpreter --manifest-path python/Cargo.toml
+          args: --release --out dist --find-interpreter --manifest-path python/Cargo.toml -F geoparquet
           sccache: 'true'
       - name: Upload wheels
         uses: actions/upload-artifact@v4
@@ -148,7 +151,7 @@ jobs:
         uses: PyO3/maturin-action@v1
         with:
           target: ${{ matrix.platform.target }}
-          args: --release --out dist --find-interpreter --manifest-path python/Cargo.toml
+          args: --release --out dist --find-interpreter --manifest-path python/Cargo.toml -F geoparquet
           sccache: 'true'
       - name: Upload wheels
         uses: actions/upload-artifact@v4

api/CHANGELOG.md

@@ -9,6 +9,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ### Added
 
 - `Client` (from now-defunkt **stac-async**) ([#372](https://github.com/stac-utils/stac-rs/pull/372))
+- `BlockingClient` ([#387](https://github.com/stac-utils/stac-rs/pull/387))
 
 ## [0.5.0] - 2024-09-05
 

api/src/client.rs

@@ -1,3 +1,5 @@
+//! A STAC API client.
+
 use crate::{Error, GetItems, Item, ItemCollection, Items, Result, Search, UrlBuilder};
 use async_stream::try_stream;
 use futures::{pin_mut, Stream, StreamExt};
@@ -6,7 +8,9 @@ use reqwest::{header::HeaderMap, IntoUrl, Method, StatusCode};
 use serde::{de::DeserializeOwned, Serialize};
 use serde_json::{Map, Value};
 use stac::{Collection, Href, Link, Links};
+use std::pin::Pin;
 use tokio::{
+    runtime::{Builder, Runtime},
     sync::mpsc::{self, error::SendError},
     task::JoinHandle,
 };
@@ -21,6 +25,17 @@ pub struct Client {
     url_builder: UrlBuilder,
 }
 
+/// A client for interacting with STAC APIs without async.
+#[derive(Debug)]
+pub struct BlockingClient(Client);
+
+/// A blocking iterator over items.
+#[allow(missing_debug_implementations)]
+pub struct BlockingIterator {
+    runtime: Runtime,
+    stream: Pin<Box<dyn Stream<Item = Result<Item>>>>,
+}
+
 impl Client {
     /// Creates a new API client.
     ///
@@ -127,12 +142,12 @@ impl Client {
     ///
     /// let client = Client::new("https://planetarycomputer.microsoft.com/api/stac/v1").unwrap();
     /// let mut search = Search { collections: Some(vec!["sentinel-2-l2a".to_string()]), ..Default::default() };
-    /// search.items.limit = Some(1);
     /// # tokio_test::block_on(async {
     /// let items: Vec<_> = client
     ///     .search(search)
     ///     .await
     ///     .unwrap()
+    ///     .take(1)
     ///     .map(|result| result.unwrap())
     ///     .collect()
     ///     .await;
@@ -226,6 +241,57 @@ impl Client {
     }
 }
 
+impl BlockingClient {
+    /// Creates a new blocking client.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use stac_api::BlockingClient;
+    ///
+    /// let client = BlockingClient::new("https://planetarycomputer.microsoft.com/api/stac/vi").unwrap();
+    /// ```
+    pub fn new(url: &str) -> Result<BlockingClient> {
+        Client::new(url).map(Self)
+    }
+
+    /// Searches an API, returning an iterable of items.
+    ///
+    /// To prevent fetching _all_ the items (which might be a lot), it is recommended to pass a `max_items`.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use stac_api::{Search, BlockingClient};
+    ///
+    /// let client = BlockingClient::new("https://planetarycomputer.microsoft.com/api/stac/v1").unwrap();
+    /// let mut search = Search { collections: Some(vec!["sentinel-2-l2a".to_string()]), ..Default::default() };
+    /// let items: Vec<_> = client
+    ///     .search(search)
+    ///     .unwrap()
+    ///     .map(|result| result.unwrap())
+    ///     .take(1)
+    ///     .collect();
+    /// assert_eq!(items.len(), 1);
+    /// ```
+    pub fn search(&self, search: Search) -> Result<BlockingIterator> {
+        let runtime = Builder::new_current_thread().enable_all().build()?;
+        let stream = runtime.block_on(async move { self.0.search(search).await })?;
+        Ok(BlockingIterator {
+            runtime,
+            stream: Box::pin(stream),
+        })
+    }
+}
+
+impl Iterator for BlockingIterator {
+    type Item = Result<Item>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        self.runtime.block_on(self.stream.next())
+    }
+}
+
 fn stream_items(
     client: Client,
     page: ItemCollection,

api/src/error.rs

@@ -52,6 +52,11 @@ pub enum Error {
     #[cfg(feature = "client")]
     InvalidMethod(#[from] http::method::InvalidMethod),
 
+    /// [std::io::Error]
+    #[error(transparent)]
+    #[cfg(feature = "client")]
+    Io(#[from] std::io::Error),
+
     /// [tokio::task::JoinError]
     #[error(transparent)]
     #[cfg(feature = "client")]

api/src/filter.rs

@@ -1,3 +1,5 @@
+use std::{convert::Infallible, str::FromStr};
+
 use serde::{Deserialize, Serialize};
 use serde_json::{Map, Value};
 
@@ -20,6 +22,13 @@ impl Default for Filter {
     }
 }
 
+impl FromStr for Filter {
+    type Err = Infallible;
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Ok(Filter::Cql2Text(s.to_string()))
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::Filter;

api/src/lib.rs

@@ -64,7 +64,7 @@
 )]
 
 #[cfg(feature = "client")]
-mod client;
+pub mod client;
 mod collections;
 mod conformance;
 mod error;
@@ -78,7 +78,7 @@ mod sort;
 mod url_builder;
 
 #[cfg(feature = "client")]
-pub use client::Client;
+pub use client::{BlockingClient, Client};
 pub use {
     collections::Collections,
     conformance::{

python/CHANGELOG.md

@@ -7,6 +7,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ## [Unreleased]
 
 - `migrate_href` ([#334](https://github.com/stac-utils/stac-rs/pull/334))
+- `search` and `search_to` ([#387](https://github.com/stac-utils/stac-rs/pull/387))
 
 ## [0.0.3] - 2024-08-29
 

python/CODE_OF_CONDUCT

@@ -0,0 +1 @@
+../CODE_OF_CONDUCT

python/Cargo.toml

@@ -12,8 +12,16 @@ publish = false
 name = "stacrs"
 crate-type = ["cdylib"]
 
+[features]
+geoparquet = ["stac/geoparquet-compression"]
+
 [dependencies]
+geojson = "0.24"
 pyo3 = "0.22"
 pythonize = "0.22"
-stac = { path = "../core", features = ["reqwest"] }
+serde = "1"
+serde_json = "1"
+stac = { path = "../core", features = ["reqwest", "object-store-full"] }
+stac-api = { path = "../api", features = ["client"] }
 stac-validate = { path = "../validate" }
+tokio = { version = "1", features = ["rt"] }

python/README.md

@@ -21,6 +21,16 @@ Then:
 ```python
 import stacrs
 
+# Searches a STAC API
+items = stacrs.search(
+    "https://landsatlook.usgs.gov/stac-server",
+    collections="landsat-c2l2-sr",
+    intersects={"type": "Point", "coordinates": [-105.119, 40.173]},
+    sortby="-properties.datetime",
+    max_items=1,
+)
+
+# Validates a href using json-schema
 stacrs.validate_href("https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0/examples/simple-item.json")
 ```
 

python/docs/CODE_OF_CONDUCT

@@ -0,0 +1 @@
+../CODE_OF_CONDUCT

python/docs/api.md

@@ -2,12 +2,9 @@
 
 API documentation for **stacrs**.
 
-## Migrate
-
 ::: stacrs.migrate
 ::: stacrs.migrate_href
-
-## Validate
-
+::: stacrs.search
+::: stacrs.search_to
 ::: stacrs.validate
 ::: stacrs.validate_href

python/docs/index.md

@@ -0,0 +1 @@
+../README.md

python/requirements-dev.in

@@ -2,3 +2,4 @@ maturin
 mypy
 ruff
 pytest
+stac-geoparquet