Add geoparquet support to stac::read

stac/CHANGELOG.md

@@ -11,7 +11,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - `Bbox` ([#303](https://github.com/stac-utils/stac-rs/pull/303))
 - Functions to create collections from items ([#304](https://github.com/stac-utils/stac-rs/pull/304))
 - Default implementation for `Version` ([#309](https://github.com/stac-utils/stac-rs/pull/309))
-- Experimental GeoParquet and GeoArrow support ([#316](https://github.com/stac-utils/stac-rs/pull/316))
+- Experimental GeoParquet and GeoArrow support ([#316](https://github.com/stac-utils/stac-rs/pull/316), [#319](https://github.com/stac-utils/stac-rs/pull/319))
+- Public `stac::io` module ([#319](https://github.com/stac-utils/stac-rs/pull/319))
 
 ### Changed
 

stac/src/io/geoparquet.rs

@@ -0,0 +1,30 @@
+//! Input and output (IO) functions for geoparquet data.
+
+use super::Read;
+use crate::{ItemCollection, Result};
+#[cfg(feature = "reqwest")]
+use reqwest::blocking::Response;
+use std::fs::File;
+
+/// Reads an [ItemCollection] from a geoparquet href.
+///
+/// # Examples
+///
+/// ```
+/// let item_collection = stac::io::geoparquet::read("examples/extended-item.parquet").unwrap();
+/// ```
+pub fn read(href: impl ToString) -> Result<ItemCollection> {
+    GeoparquetReader::read(href)
+}
+
+struct GeoparquetReader;
+
+impl Read<ItemCollection> for GeoparquetReader {
+    fn read_from_file(file: File) -> Result<ItemCollection> {
+        crate::geoparquet::from_reader(file)
+    }
+    #[cfg(feature = "reqwest")]
+    fn from_response(response: Response) -> Result<ItemCollection> {
+        crate::geoparquet::from_reader(response.bytes()?)
+    }
+}

stac/src/io/json.rs

@@ -0,0 +1,31 @@
+//! Input and output (IO) functions for JSON data.
+
+use super::Read;
+use crate::{Error, Href, Result};
+#[cfg(feature = "reqwest")]
+use reqwest::blocking::Response;
+use serde::de::DeserializeOwned;
+use std::fs::File;
+
+/// Reads any STAC value from a JSON href.
+///
+/// # Examples
+///
+/// ```
+/// let item: stac::Item = stac::io::json::read("data/simple-item.json").unwrap();
+/// ```
+pub fn read<T: Href + DeserializeOwned>(href: impl ToString) -> Result<T> {
+    JsonReader::read(href)
+}
+
+struct JsonReader;
+
+impl<T: Href + DeserializeOwned> Read<T> for JsonReader {
+    fn read_from_file(file: File) -> Result<T> {
+        serde_json::from_reader(file).map_err(Error::from)
+    }
+    #[cfg(feature = "reqwest")]
+    fn from_response(response: Response) -> Result<T> {
+        response.json().map_err(Error::from)
+    }
+}

stac/src/io/mod.rs

@@ -0,0 +1,157 @@
+//! Input and output (IO) functions.
+
+#[cfg(feature = "geoparquet")]
+pub mod geoparquet;
+pub mod json;
+
+use crate::{Href, Result};
+#[cfg(feature = "reqwest")]
+use reqwest::blocking::Response;
+use serde::de::DeserializeOwned;
+use std::{fs::File, path::Path};
+use url::Url;
+
+/// Reads any STAC object from an href.
+///
+/// If the `geoparquet` feature is enabled, and the href's extension is
+/// `geoparquet` or `parquet`, the data will be read as
+/// [stac-geoparquet](https://github.com/stac-utils/stac-geoparquet). This is
+/// more inefficient than using [crate::io::geoparquet::read], so prefer that if you
+/// know your href points to geoparquet data.
+///
+/// Use [crate::io::json::read] if you want to ensure that your data are read as JSON.
+///
+/// # Examples
+///
+/// ```
+/// let item: stac::Item = stac::read("data/simple-item.json").unwrap();
+/// ```
+pub fn read<T: Href + DeserializeOwned>(href: impl ToString) -> Result<T> {
+    let href = href.to_string();
+    if href
+        .rsplit_once('.')
+        .map(|(_, ext)| ext == "parquet" || ext == "geoparquet")
+        .unwrap_or_default()
+    {
+        #[cfg(feature = "geoparquet")]
+        {
+            serde_json::from_value(serde_json::to_value(geoparquet::read(href)?)?)
+                .map_err(crate::Error::from)
+        }
+        #[cfg(not(feature = "geoparquet"))]
+        {
+            log::warn!("{} has a geoparquet extension, but this crate was not built with the `geoparquet` feature. Reading as JSON.", href);
+            json::read(href)
+        }
+    } else {
+        json::read(href)
+    }
+}
+
+trait Read<T: Href + DeserializeOwned> {
+    fn read(href: impl ToString) -> Result<T> {
+        let href = href.to_string();
+        let mut value: T = if let Some(url) = crate::href_to_url(&href) {
+            Self::read_from_url(url)?
+        } else {
+            Self::read_from_path(&href)?
+        };
+        value.set_href(href);
+        Ok(value)
+    }
+
+    fn read_from_path(path: impl AsRef<Path>) -> Result<T> {
+        let file = File::open(path.as_ref())?;
+        Self::read_from_file(file)
+    }
+
+    fn read_from_file(file: File) -> Result<T>;
+
+    #[cfg(feature = "reqwest")]
+    fn read_from_url(url: Url) -> Result<T> {
+        let response = reqwest::blocking::get(url.clone())?;
+        Self::from_response(response)
+    }
+
+    #[cfg(feature = "reqwest")]
+    fn from_response(response: Response) -> Result<T>;
+
+    #[cfg(not(feature = "reqwest"))]
+    fn read_from_url(_: Url) -> Result<T> {
+        Err(crate::Error::ReqwestNotEnabled)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::{Catalog, Collection, Item, ItemCollection};
+
+    macro_rules! read {
+        ($function:ident, $filename:expr, $value:ty) => {
+            #[test]
+            fn $function() {
+                use crate::Href;
+
+                let value: $value = crate::read($filename).unwrap();
+                assert!(value.href().is_some());
+            }
+        };
+    }
+
+    read!(read_item_from_path, "data/simple-item.json", Item);
+    read!(read_catalog_from_path, "data/catalog.json", Catalog);
+    read!(
+        read_collection_from_path,
+        "data/collection.json",
+        Collection
+    );
+    read!(
+        read_item_collection_from_path,
+        "examples/item-collection.json",
+        ItemCollection
+    );
+
+    #[cfg(feature = "reqwest")]
+    mod with_reqwest {
+        use crate::{Catalog, Collection, Item};
+
+        read!(
+            read_item_from_url,
+            "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json",
+            Item
+        );
+        read!(
+            read_catalog_from_url,
+            "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/catalog.json",
+            Catalog
+        );
+        read!(
+            read_collection_from_url,
+            "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/collection.json",
+            Collection
+        );
+    }
+
+    #[cfg(not(feature = "reqwest"))]
+    mod without_reqwest {
+        #[test]
+        fn read_url() {
+            assert!(matches!(
+                crate::read::<crate::Item>("http://stac-rs.test/item.json").unwrap_err(),
+                crate::Error::ReqwestNotEnabled
+            ));
+        }
+    }
+
+    #[test]
+    #[cfg(feature = "geoparquet")]
+    fn read_geoparquet() {
+        let _: ItemCollection = super::read("examples/extended-item.parquet").unwrap();
+    }
+
+    #[test]
+    #[cfg(not(feature = "geoparquet"))]
+    fn read_geoparquet() {
+        let _ = super::read::<ItemCollection>("examples/extended-item.parquet").unwrap_err();
+    }
+}

stac/src/item.rs

@@ -803,7 +803,8 @@ mod tests {
 
     #[test]
     fn deserialize_invalid_type_field() {
-        let mut item: Value = crate::io::read_json("data/simple-item.json").unwrap();
+        let mut item: Value =
+            serde_json::to_value(crate::read::<Item>("data/simple-item.json").unwrap()).unwrap();
         item["type"] = "Item".into(); // must be "Feature"
         assert!(serde_json::from_value::<Item>(item).is_err());
     }

stac/src/lib.rs

@@ -134,7 +134,7 @@ pub mod geoarrow;
 #[cfg(feature = "geoparquet")]
 pub mod geoparquet;
 mod href;
-mod io;
+pub mod io;
 pub mod item;
 mod item_collection;
 pub mod link;

stac/src/migrate.rs

@@ -221,7 +221,9 @@ mod tests {
         assert_eq!(asset.bands[2].name.as_ref().unwrap(), "b");
         assert_eq!(asset.bands[3].name.as_ref().unwrap(), "nir");
 
-        let expected: Value = crate::io::read_json("examples/bands-v1.1.0-beta.1.json").unwrap();
+        let expected: Value =
+            serde_json::to_value(crate::read::<Item>("examples/bands-v1.1.0-beta.1.json").unwrap())
+                .unwrap();
         assert_json_eq!(expected, serde_json::to_value(item).unwrap());
 
         let collection = Collection::new("an-id", "a description");