feat(wip): pgstac python API

Author: gadomski

.github/workflows/python.yml

@@ -17,7 +17,7 @@ jobs:
   build-wheels:
     uses: ./.github/workflows/wheels.yml
     with:
-      manifest-path: python/Cargo.toml
+      manifest-path: python/stacrs/Cargo.toml
 
   sdist:
     runs-on: ubuntu-latest
@@ -29,7 +29,7 @@ jobs:
         uses: PyO3/maturin-action@v1
         with:
           command: sdist
-          args: --out dist --manifest-path python/Cargo.toml
+          args: --out dist --manifest-path python/stacrs/Cargo.toml
       - name: Upload sdist
         uses: actions/upload-artifact@v4
         with:

.markdownlint-cli2.jsonc

@@ -1,8 +1,13 @@
 {
-    "config": {
-        "MD013": false
-    },
-    "globs": ["**/*.md"],
-    "gitignore": true,
-    "ignores": ["spec-examples/*/README.md", "crates/*/examples/README.md", "python/examples/README.md", "target/**/*.md"]
-}
+  "config": {
+    "MD013": false
+  },
+  "globs": ["**/*.md"],
+  "gitignore": true,
+  "ignores": [
+    "spec-examples/*/README.md",
+    "crates/*/examples/README.md",
+    "python/stacrs/examples/README.md",
+    "target/**/*.md"
+  ]
+}

Cargo.toml

@@ -10,7 +10,8 @@ members = [
     "crates/pgstac",
     "crates/server",
     "crates/types",
-    "python",
+    "python/stacrs",
+    "python/pgstacrs",
 ]
 default-members = [
     "crates/api",
@@ -64,7 +65,12 @@ openssl = { version = "0.10.68", features = ["vendored"] }
 openssl-src = "=300.3.1" # joinked from https://github.com/iopsystems/rpc-perf/commit/705b290d2105af6f33150da04b217422c6d68701#diff-2e9d962a08321605940b5a657135052fbcef87b5e360662bb527c96d9a615542R41 to cross-compile Python
 parquet = { version = "52.2", default-features = false }
 pgstac = { version = "0.2.2", path = "crates/pgstac" }
+postgres = "0.19.9"
 pyo3 = "0.22.3"
+pyo3-async-runtimes = { version = "0.22.0", features = [
+    "attributes",
+    "tokio-runtime",
+] }
 pythonize = "0.22.0"
 quote = "1.0"
 reqwest = "0.12.8"

README.md

@@ -35,7 +35,7 @@ stacrs.search_to("items-compressed.parquet",
 )
 ```
 
-See [the Python documentation](https://stac-utils.github.io/stac-rs/latest/python/) for more information.
+See [the Python documentation](https://stac-utils.github.io/stac-rs/latest/python/stacrs/) for more information.
 
 ## Command line interface
 

crates/pgstac/Cargo.toml

@@ -16,6 +16,7 @@ tls = ["dep:rustls", "dep:tokio-postgres-rustls", "dep:webpki-roots"]
 
 [dependencies]
 geojson.workspace = true
+postgres-types = "0.2.8"
 rustls = { workspace = true, features = ["ring", "std"], optional = true }
 serde.workspace = true
 serde_json.workspace = true

crates/pgstac/src/client.rs

@@ -212,7 +212,8 @@ impl<'a, C: GenericClient> Client<'a, C> {
         }
     }
 
-    async fn opt<T>(&self, function: &str, params: &[&(dyn ToSql + Sync)]) -> Result<Option<T>>
+    /// Return an optional, deserializable thing.
+    pub async fn opt<T>(&self, function: &str, params: &[&(dyn ToSql + Sync)]) -> Result<Option<T>>
     where
         T: DeserializeOwned,
     {
@@ -244,7 +245,8 @@ impl<'a, C: GenericClient> Client<'a, C> {
         serde_json::from_value(value).map_err(Error::from)
     }
 
-    async fn void(&self, function: &str, params: &[&(dyn ToSql + Sync)]) -> Result<()> {
+    /// Run a function and return nothing if it works.
+    pub async fn void(&self, function: &str, params: &[&(dyn ToSql + Sync)]) -> Result<()> {
         let _ = self.query_one(function, params).await?;
         Ok(())
     }

crates/pgstac/src/lib.rs

@@ -40,6 +40,7 @@
 
 mod client;
 mod page;
+pub mod query;
 #[cfg(feature = "tls")]
 mod tls;
 

crates/pgstac/src/query.rs

@@ -0,0 +1,44 @@
+//! Build queries for **pgstac**.
+use postgres_types::ToSql;
+
+/// A pgstac query.
+#[derive(Debug)]
+pub struct Query {
+    /// The query.
+    pub query: String,
+
+    /// The function that was called.
+    pub function: String,
+
+    params: Vec<Box<dyn ToSql + Sync>>,
+}
+
+/// Build the version query.
+pub fn version() -> Query {
+    Query::new("get_version", Vec::new())
+}
+
+/// Get a collection.
+pub fn get_collection(id: impl ToString) -> Query {
+    Query::new("get_collection", vec![Box::new(id.to_string())])
+}
+
+impl Query {
+    fn new(function: &str, params: Vec<Box<(dyn ToSql + Sync)>>) -> Query {
+        let param_string = (0..params.len())
+            .map(|i| format!("${}", i + 1))
+            .collect::<Vec<_>>()
+            .join(", ");
+        let query = format!("SELECT * from pgstac.{}({})", function, param_string);
+        Query {
+            query,
+            params,
+            function: function.to_string(),
+        }
+    }
+
+    /// Returns a vec of the references to the params.
+    pub fn params(&self) -> Vec<&(dyn ToSql + Sync)> {
+        self.params.iter().map(|param| param.as_ref()).collect()
+    }
+}

docs/index.md

@@ -6,7 +6,7 @@ Command Line Interface (CLI), Rust crates, and other libraries for the [SpatioTe
 
 ## Python documentation
 
-Our Python package is named **stacrs** and its documentation is available [here](./python/index.md).
+Our Python package is named **stacrs** and its documentation is available [here](./python/stacrs/index.md).
 
 ## Rust documentation on docs.rs
 

mkdocs.yml

@@ -18,16 +18,16 @@ theme:
 nav:
   - Home: index.md
   - Python:
-      - python/index.md
-      - Example notebook: python/example.ipynb
+      - python/stacrs/index.md
+      - Example notebook: python/stacrs/example.ipynb
       - API:
-          - python/api/index.md
-          - migrate: python/api/migrate.md
-          - read: python/api/read.md
-          - search: python/api/search.md
-          - validate: python/api/validate.md
-          - version: python/api/version.md
-          - write: python/api/write.md
+          - python/stacrs/api/index.md
+          - migrate: python/stacrs/api/migrate.md
+          - read: python/stacrs/api/read.md
+          - search: python/stacrs/api/search.md
+          - validate: python/stacrs/api/validate.md
+          - version: python/stacrs/api/version.md
+          - write: python/stacrs/api/write.md
   - Command-line interface:
       - cli/index.md