docs(pyo3-geoarrow): Improve docs (#1377)

Author: kylebarron

python/geoarrow-core/src/lib.rs

@@ -3,8 +3,6 @@
 mod constructors;
 mod interop;
 mod operations;
-// pub mod ffi;
-// pub mod table;
 
 use pyo3::exceptions::PyRuntimeWarning;
 use pyo3::intern;

rust/pyo3-geoarrow/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [Unreleased]
+
+- docs(pyo3-geoarrow): Improve docs #1377

rust/pyo3-geoarrow/README.md

@@ -0,0 +1,64 @@
+# pyo3-geoarrow
+
+[PyO3](https://pyo3.rs/) bindings for GeoArrow types, enabling seamless integration between Rust's GeoArrow implementation and Python.
+
+This crate provides Python-compatible wrappers around GeoArrow data structures, allowing Python code to efficiently work with and share geospatial data in the GeoArrow format through the [Arrow C Data Interface][arrow-c-data-interface] (using the [Arrow PyCapsule Interface][arrow-pycapsule-interface]) without data copies.
+
+[arrow-c-data-interface]: https://arrow.apache.org/docs/format/CDataInterface.html
+[arrow-pycapsule-interface]: https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html
+
+## Features
+
+- **Zero-copy data exchange**: Use Arrow's [C Data Interface][arrow-c-data-interface] for efficient memory sharing between Rust and Python.
+- **GeoArrow types**: Python bindings for GeoArrow geometry arrays, scalars, and metadata.
+- **Type safety**: Strongly-typed wrappers that preserve GeoArrow's type system in Python.
+- **FFI support**: Import and export GeoArrow data to/from Python using the [Arrow PyCapsule Interface][arrow-pycapsule-interface].
+
+## Core Types
+
+- [`PyGeoArray`]: Python wrapper for GeoArrow geometry arrays
+- [`PyGeoChunkedArray`]: Python wrapper for chunked GeoArrow geometry arrays
+- [`PyGeoArrayReader`]: Python wrapper for streaming array readers
+- [`PyGeoScalar`]: Python wrapper for GeoArrow scalar geometries
+- [`PyGeoType`]: Python wrapper for GeoArrow data types
+- [`PyCrs`]: Python wrapper for coordinate reference system representation
+
+## Usage
+
+This crate is primarily intended for use by Python binding developers who need to interoperate with GeoArrow data in Python. It is also used internally by the `geoarrow-rust-*` Python packages.
+
+```rust
+use std::sync::Arc;
+
+use pyo3::prelude::*;
+use pyo3_geoarrow::PyGeoArray;
+use geoarrow_array::GeoArrowArray;
+
+#[pyfunction]
+fn process_geometry(py: Python, array: PyGeoArray) -> PyResult<PyGeoArray> {
+    // Access the underlying GeoArrow array
+    let inner: Arc<dyn GeoArrowArray> = array.into_inner();
+
+    // Perform operations...
+
+    Ok(PyGeoArray::new(inner))
+}
+```
+
+## Integration with Arrow
+
+This crate implements the [Arrow PyCapsule Interface](https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html), allowing GeoArrow objects to be exchanged with any Python library that supports Arrow, including:
+
+- PyArrow
+- Polars (once they support extension types)
+- GeoPandas (via PyArrow)
+- DuckDB
+
+## Dependencies
+
+This crate builds on:
+
+- [`pyo3`](https://docs.rs/pyo3): Python bindings for Rust
+- [`pyo3-arrow`](https://docs.rs/pyo3-arrow): Arrow integration for PyO3
+- [`geoarrow-array`](https://docs.rs/geoarrow-array): Core GeoArrow array types
+- [`geoarrow-schema`](https://docs.rs/geoarrow-schema): GeoArrow type system and metadata

rust/pyo3-geoarrow/src/array.rs

@@ -20,10 +20,15 @@ use crate::error::{PyGeoArrowError, PyGeoArrowResult};
 use crate::scalar::PyGeoScalar;
 use crate::utils::text_repr::text_repr;
 
+/// Python wrapper for a GeoArrow geometry array.
+///
+/// This type wraps a Rust GeoArrow array and exposes it to Python through the Arrow C Data
+/// Interface. It supports zero-copy data exchange with Arrow-compatible Python libraries.
 #[pyclass(module = "geoarrow.rust.core", name = "GeoArray", subclass, frozen)]
 pub struct PyGeoArray(Arc<dyn GeoArrowArray>);
 
 impl PyGeoArray {
+    /// Create a new [`PyGeoArray`] from a GeoArrow array.
     pub fn new(array: Arc<dyn GeoArrowArray>) -> Self {
         Self(array)
     }
@@ -36,10 +41,12 @@ impl PyGeoArray {
         PyArray::from_arrow_pycapsule(schema_capsule, array_capsule)?.try_into()
     }
 
+    /// Access the underlying GeoArrow array.
     pub fn inner(&self) -> &Arc<dyn GeoArrowArray> {
         &self.0
     }
 
+    /// Consume this wrapper and return the underlying GeoArrow array.
     pub fn into_inner(self) -> Arc<dyn GeoArrowArray> {
         self.0
     }

rust/pyo3-geoarrow/src/array_reader.rs

@@ -16,9 +16,15 @@ use crate::data_type::PyGeoType;
 use crate::utils::text_repr::text_repr;
 use crate::{PyGeoArray, PyGeoArrowError, PyGeoArrowResult, PyGeoChunkedArray};
 
-/// A Python-facing GeoArrow array reader.
+/// Python wrapper for a GeoArrow array reader (stream).
 ///
-/// This is a wrapper around a [PyArrayReader].
+/// This type represents a stream of GeoArrow arrays that can be read incrementally. It implements
+/// the Arrow C Stream Interface, allowing zero-copy data exchange with Arrow-compatible Python
+/// libraries.
+///
+/// The reader can be iterated over to yield individual [`PyGeoArray`] chunks, or materialized
+/// into a [`PyGeoChunkedArray`] using the [`into_chunked_array()`][Self::into_chunked_array]
+/// method. For stream processing, prefer [`into_reader()`][Self::into_reader].
 #[pyclass(
     module = "geoarrow.rust.core",
     name = "GeoArrayReader",
@@ -31,6 +37,7 @@ pub struct PyGeoArrayReader {
 }
 
 impl PyGeoArrayReader {
+    /// Create a new [`PyGeoArrayReader`] from a GeoArrow array reader.
     pub fn new(reader: Box<dyn GeoArrowArrayReader + Send>) -> Self {
         let data_type = reader.data_type();
         Self {
@@ -51,6 +58,7 @@ impl PyGeoArrayReader {
     //     (self.iter, self.data_type)
     // }
 
+    /// Get the GeoArrow data type of arrays in this stream.
     pub fn data_type(&self) -> &GeoArrowType {
         &self.data_type
     }

rust/pyo3-geoarrow/src/chunked_array.rs

@@ -22,6 +22,9 @@ use crate::scalar::PyGeoScalar;
 use crate::utils::text_repr::text_repr;
 use crate::{PyCoordType, PyGeoArray};
 
+/// Python wrapper for a chunked GeoArrow geometry array.
+///
+/// A chunked array is a collection of contiguous arrays of the same type.
 #[pyclass(
     module = "geoarrow.rust.core",
     name = "GeoChunkedArray",
@@ -82,6 +85,7 @@ impl PyGeoChunkedArray {
         Ok(Self::try_new(chunks, data_type)?)
     }
 
+    /// Consume this wrapper and return the underlying chunks and data type.
     pub fn into_inner(self) -> (Vec<Arc<dyn GeoArrowArray>>, GeoArrowType) {
         (self.chunks, self.data_type)
     }
@@ -155,7 +159,7 @@ impl PyGeoChunkedArray {
     }
 
     #[classmethod]
-    pub fn from_arrow(_cls: &Bound<PyType>, data: Self) -> Self {
+    fn from_arrow(_cls: &Bound<PyType>, data: Self) -> Self {
         data
     }
 

rust/pyo3-geoarrow/src/coord_buffer.rs

@@ -11,9 +11,15 @@ use pyo3_arrow::PyArray;
 
 use crate::PyGeoArrowError;
 
+/// Python wrapper for a GeoArrow coordinate buffer.
+///
+/// Coordinate buffers store the raw coordinate data for geometries. They can be in either
+/// separated format (separate arrays for x, y, z, m) or interleaved format (single array
+/// with coordinates interleaved).
 pub struct PyCoordBuffer(CoordBuffer);
 
 impl PyCoordBuffer {
+    /// Consume this wrapper and return the underlying coordinate buffer.
     pub fn into_inner(self) -> CoordBuffer {
         self.0
     }

rust/pyo3-geoarrow/src/coord_type.rs

@@ -3,9 +3,15 @@ use pyo3::exceptions::PyValueError;
 use pyo3::intern;
 use pyo3::prelude::*;
 
+/// Python wrapper for GeoArrow coordinate type.
+///
+/// Specifies whether coordinates are stored in an interleaved (XYZXYZ...) or
+/// separated (XXX..., YYY..., ZZZ...) layout in memory.
 #[derive(Debug, Default, Clone, Copy)]
 pub enum PyCoordType {
+    /// Interleaved coordinate layout (XYZXYZ...).
     Interleaved,
+    /// Separated coordinate layout (XXX..., YYY..., ZZZ...).
     #[default]
     Separated,
 }

rust/pyo3-geoarrow/src/crs.rs

@@ -11,7 +11,11 @@ use serde_json::Value;
 use crate::PyGeoArrowError;
 use crate::error::PyGeoArrowResult;
 
-/// A wrapper around [`Crs`] to integrate with `pyproj` Python APIs.
+/// Python wrapper for a coordinate reference system (CRS).
+///
+/// This type integrates with the `pyproj` Python library, allowing CRS definitions to be
+/// passed between Rust and Python. It can accept any input that `pyproj.CRS.from_user_input`
+/// accepts, including EPSG codes, WKT strings, PROJ strings, and `pyproj.CRS` objects.
 #[derive(Clone, Debug, Default)]
 // TODO: should this be under an Arc?
 pub struct PyCrs(Crs);
@@ -41,6 +45,7 @@ impl<'py> FromPyObject<'py> for PyCrs {
 }
 
 impl PyCrs {
+    /// Create a [`PyCrs`] from a PROJJSON value.
     pub fn from_projjson(value: Value) -> Self {
         Self(Crs::from_projjson(value))
     }
@@ -103,6 +108,7 @@ impl PyCrs {
         Ok(crs_obj.into())
     }
 
+    /// Convert the CRS to a PROJJSON value.
     pub fn to_projjson(&self, py: Python) -> PyResult<Option<Value>> {
         let pyproj_crs = self.to_pyproj(py)?;
         if pyproj_crs.is_none(py) {
@@ -118,6 +124,7 @@ impl PyCrs {
         }
     }
 
+    /// Convert the CRS to a WKT string.
     pub fn to_wkt(&self, py: Python) -> PyResult<Option<String>> {
         let pyproj_crs = self.to_pyproj(py)?;
         if pyproj_crs.is_none(py) {
@@ -155,11 +162,15 @@ impl<'py> IntoPyObject<'py> for PyCrs {
     }
 }
 
-/// An implementation of [CrsTransform] using pyproj.
+/// An implementation of [`CrsTransform`] using pyproj.
+///
+/// This type enables CRS transformations by delegating to the pyproj Python library,
+/// allowing conversion between different CRS representations (PROJJSON, WKT, etc.).
 #[derive(Debug)]
 pub struct PyprojCRSTransform {}
 
 impl PyprojCRSTransform {
+    /// Create a new [`PyprojCRSTransform`].
     pub fn new() -> Self {
         Self {}
     }

rust/pyo3-geoarrow/src/data_type.rs

@@ -1,3 +1,13 @@
+//! GeoArrow data type definitions and constructors.
+//!
+//! This module provides Python bindings for GeoArrow geometry types, including:
+//! - Native geometry types (Point, LineString, Polygon, MultiPoint, etc.)
+//! - Well-Known Binary (WKB) and Well-Known Text (WKT) types
+//! - Type metadata (CRS, coordinate type, dimensions, edges)
+
+// TODO: remove when we move type constructors to geoarrow-rust-core
+#![allow(missing_docs)]
+
 use std::sync::Arc;
 
 use geoarrow_schema::{
@@ -14,10 +24,15 @@ use crate::error::{PyGeoArrowError, PyGeoArrowResult};
 use crate::utils::text_repr::text_repr;
 use crate::{PyCoordType, PyCrs, PyDimension, PyEdges};
 
+/// Python wrapper for a GeoArrow data type.
+///
+/// This type represents the schema of a GeoArrow geometry array, including the geometry type,
+/// coordinate type, dimensions, coordinate reference system, and edge interpolation.
 #[pyclass(module = "geoarrow.rust.core", name = "GeoType", subclass, frozen)]
 pub struct PyGeoType(pub(crate) GeoArrowType);
 
 impl PyGeoType {
+    /// Create a new [`PyGeoType`] from a GeoArrow data type.
     pub fn new(data_type: GeoArrowType) -> Self {
         Self(data_type)
     }
@@ -27,6 +42,7 @@ impl PyGeoType {
         PyField::from_arrow_pycapsule(capsule)?.try_into()
     }
 
+    /// Consume this wrapper and return the underlying GeoArrow data type.
     pub fn into_inner(self) -> GeoArrowType {
         self.0
     }
@@ -154,6 +170,7 @@ impl_from_geoarrow_type!(BoxType, Rect);
 
 macro_rules! impl_native_type_constructor {
     ($fn_name:ident, $geoarrow_type:ty) => {
+        #[allow(missing_docs)]
         #[pyfunction]
         #[pyo3(
             signature = (dimension, *, coord_type = PyCoordType::Separated, crs=None, edges=None),
@@ -205,6 +222,7 @@ pub fn geometry(coord_type: PyCoordType, crs: Option<PyCrs>, edges: Option<PyEdg
 
 macro_rules! impl_wkb_wkt {
     ($method_name:ident, $type_constructor:ty, $variant:expr) => {
+        #[allow(missing_docs)]
         #[pyfunction]
         #[pyo3(signature = (*, crs=None, edges=None))]
         pub fn $method_name(crs: Option<PyCrs>, edges: Option<PyEdges>) -> PyGeoType {