From bbc2e7adedb8427a6aaee83e5a1b652a257d7bfb Mon Sep 17 00:00:00 2001
From: Kyle Barron <kyle@developmentseed.org>
Date: Tue, 12 Nov 2024 12:47:16 -0500
Subject: [PATCH] Add read_shapefile to python io docs

---
 python/docs/api/io/shapefile.md               |  5 ++
 .../python/geoarrow/rust/io/_io.pyi           |  9 ++++
 python/geoarrow-io/src/io/postgis.rs          | 54 ++++++++-----------
 python/mkdocs.yml                             |  5 +-
 4 files changed, 38 insertions(+), 35 deletions(-)
 create mode 100644 python/docs/api/io/shapefile.md

diff --git a/python/docs/api/io/shapefile.md b/python/docs/api/io/shapefile.md
new file mode 100644
index 000000000..bc95cb5ba
--- /dev/null
+++ b/python/docs/api/io/shapefile.md
@@ -0,0 +1,5 @@
+# Shapefile
+
+Read Shapefile files.
+
+::: geoarrow.rust.io.read_shapefile
diff --git a/python/geoarrow-io/python/geoarrow/rust/io/_io.pyi b/python/geoarrow-io/python/geoarrow/rust/io/_io.pyi
index acd8668a9..e9a389696 100644
--- a/python/geoarrow-io/python/geoarrow/rust/io/_io.pyi
+++ b/python/geoarrow-io/python/geoarrow/rust/io/_io.pyi
@@ -528,6 +528,15 @@ def read_shapefile(
 ) -> Table:
     """
     Read a Shapefile into an Arrow Table.
+
+    The returned Arrow table will have geometry information in native GeoArrow encoding.
+
+    !!! note
+        Coordinate Reference System information is not currently read from the Shapefile.
+
+    Args:
+        shp_file: the path to the `.shp` file or the `.shp` file as a Python file object in binary read mode.
+        dbf_file: the path to the `.dbf` file or the `.dbf` file as a Python file object in binary read mode.
     """
 
 def write_csv(table: ArrowStreamExportable, file: str | Path | BinaryIO) -> None:
diff --git a/python/geoarrow-io/src/io/postgis.rs b/python/geoarrow-io/src/io/postgis.rs
index d0574220d..9c896adf0 100644
--- a/python/geoarrow-io/src/io/postgis.rs
+++ b/python/geoarrow-io/src/io/postgis.rs
@@ -1,36 +1,23 @@
-use crate::error::{PyGeoArrowError, PyGeoArrowResult};
+use crate::error::PyGeoArrowError;
 use crate::util::table_to_pytable;
 use geoarrow::error::GeoArrowError;
 use geoarrow::io::postgis::read_postgis as _read_postgis;
 use pyo3::prelude::*;
+use pyo3_arrow::PyTable;
 use pyo3_async_runtimes::tokio::future_into_py;
 use sqlx::postgres::PgPoolOptions;
 
 #[pyfunction]
-pub fn read_postgis(
-    py: Python,
-    connection_url: String,
-    sql: String,
-) -> PyGeoArrowResult<Option<PyObject>> {
+pub fn read_postgis(py: Python, connection_url: String, sql: String) -> PyResult<Option<PyObject>> {
     // https://tokio.rs/tokio/topics/bridging#what-tokiomain-expands-to
-    tokio::runtime::Builder::new_multi_thread()
+    let runtime = tokio::runtime::Builder::new_multi_thread()
         .enable_all()
         .build()
-        .unwrap()
-        .block_on(async move {
-            let pool = PgPoolOptions::new()
-                .connect(&connection_url)
-                .await
-                .map_err(|err| PyGeoArrowError::GeoArrowError(GeoArrowError::SqlxError(err)))?;
+        .unwrap();
 
-            let table = _read_postgis(&pool, &sql)
-                .await
-                .map_err(PyGeoArrowError::GeoArrowError)?;
-
-            Ok(table
-                .map(|table| table_to_pytable(table).to_arro3(py))
-                .transpose()?)
-        })
+    // TODO: py.allow_threads
+    let out = runtime.block_on(read_postgis_inner(connection_url, sql))?;
+    out.map(|table| table.to_arro3(py)).transpose()
 }
 
 #[pyfunction]
@@ -38,18 +25,19 @@ pub fn read_postgis_async(
     py: Python,
     connection_url: String,
     sql: String,
-) -> PyGeoArrowResult<PyObject> {
-    let fut = future_into_py(py, async move {
-        let pool = PgPoolOptions::new()
-            .connect(&connection_url)
-            .await
-            .map_err(|err| PyGeoArrowError::GeoArrowError(GeoArrowError::SqlxError(err)))?;
+) -> PyResult<Bound<PyAny>> {
+    future_into_py(py, read_postgis_inner(connection_url, sql))
+}
+
+async fn read_postgis_inner(connection_url: String, sql: String) -> PyResult<Option<PyTable>> {
+    let pool = PgPoolOptions::new()
+        .connect(&connection_url)
+        .await
+        .map_err(|err| PyGeoArrowError::GeoArrowError(GeoArrowError::SqlxError(err)))?;
 
-        let table = _read_postgis(&pool, &sql)
-            .await
-            .map_err(PyGeoArrowError::GeoArrowError)?;
+    let table = _read_postgis(&pool, &sql)
+        .await
+        .map_err(PyGeoArrowError::GeoArrowError)?;
 
-        Ok(table.map(table_to_pytable))
-    })?;
-    Ok(fut.into())
+    Ok(table.map(table_to_pytable))
 }
diff --git a/python/mkdocs.yml b/python/mkdocs.yml
index d22d43703..ef98c65e7 100644
--- a/python/mkdocs.yml
+++ b/python/mkdocs.yml
@@ -36,13 +36,14 @@ nav:
           - api/compute/enums.md
           - api/compute/types.md
       - geoarrow.rust.io:
+          - api/io/arrow_ipc.md
           - api/io/csv.md
           - api/io/flatgeobuf.md
+          - api/io/gdal.md
           - api/io/geojson.md
           - api/io/geoparquet.md
           - api/io/postgis.md
-          - api/io/arrow_ipc.md
-          - api/io/gdal.md
+          - api/io/shapefile.md
   - Ecosystem:
       - ecosystem/geopandas.md
       - ecosystem/lonboard.md