Update Python docs (#755)

geoarrow · Sep 3, 2024 · f9df320 · f9df320
1 parent eed1379
commit f9df320
Show file tree

Hide file tree

Showing 34 changed files with 264 additions and 716 deletions.
diff --git a/python/docs/DEVELOP.md → python/DEVELOP.md b/python/docs/DEVELOP.md → python/DEVELOP.md
diff --git a/python/docs/CHANGELOG.md b/python/docs/CHANGELOG.md
@@ -0,0 +1 @@
+../CHANGELOG.md
diff --git a/python/docs/source/api/core/enums.md → python/docs/api/core/enums.md b/python/docs/source/api/core/enums.md → python/docs/api/core/enums.md
diff --git a/python/docs/source/api/core/functions.md → python/docs/api/core/functions.md b/python/docs/source/api/core/functions.md → python/docs/api/core/functions.md
@@ -22,9 +22,13 @@
         - line_interpolate_point
         - line_locate_point
         - polylabel
+        - rotate
+        - scale
         - signed_area
         - simplify
+        - skew
         - total_bounds
+        - translate
 
 ## Table functions
 
@@ -34,3 +38,4 @@
         - "!^_"
       members:
         - explode
+        - geometry_col
diff --git a/python/docs/api/core/geometry/array.md b/python/docs/api/core/geometry/array.md
@@ -0,0 +1,13 @@
+# GeometryArray
+
+::: geoarrow.rust.core
+    options:
+      filters:
+        - "!^_"
+        - "^__arrow"
+        - "^__geo"
+        - "^__eq"
+        - "^__getitem"
+        - "^__repr"
+      members:
+        - GeometryArray
diff --git a/python/docs/api/core/geometry/chunked.md b/python/docs/api/core/geometry/chunked.md
@@ -0,0 +1,13 @@
+# ChunkedGeometryArray
+
+::: geoarrow.rust.core
+    options:
+      filters:
+        - "!^_"
+        - "^__arrow"
+        - "^__geo"
+        - "^__eq"
+        - "^__getitem"
+        - "^__repr"
+      members:
+        - ChunkedGeometryArray
diff --git a/python/docs/api/core/geometry/scalar.md b/python/docs/api/core/geometry/scalar.md
@@ -0,0 +1,10 @@
+# Geometry
+
+::: geoarrow.rust.core
+    options:
+      filters:
+        - "!^_"
+        - "^__arrow"
+        - "^__geo"
+      members:
+        - Geometry
diff --git a/python/docs/source/api/core/index.md → python/docs/api/core/index.md b/python/docs/source/api/core/index.md → python/docs/api/core/index.md
diff --git a/python/docs/source/api/core/interop.md → python/docs/api/core/interop.md b/python/docs/source/api/core/interop.md → python/docs/api/core/interop.md
@@ -7,6 +7,7 @@ Interoperability with other in-memory Python
       filters:
         - "!^_"
       members:
+        - read_pyogrio
         - from_ewkb
         - from_geopandas
         - from_shapely

diff --git a/python/docs/source/api/core/types.md → python/docs/api/core/types.md b/python/docs/source/api/core/types.md → python/docs/api/core/types.md
diff --git a/python/docs/api/io/enums.md b/python/docs/api/io/enums.md
@@ -0,0 +1,3 @@
+# Enums
+
+::: geoarrow.rust.io.enums
diff --git a/python/docs/source/api/core/io.md → python/docs/api/io/io.md b/python/docs/source/api/core/io.md → python/docs/api/io/io.md
@@ -1,8 +1,8 @@
 # I/O
 
-Read and write to files on disk and databases like PostGIS.
+Read and write to and from geospatial file formats.
 
-::: geoarrow.rust.core
+::: geoarrow.rust.io
     options:
       filters:
         - "!^_"
@@ -12,8 +12,6 @@ Read and write to files on disk and databases like PostGIS.
         - read_flatgeobuf_async
         - read_geojson
         - read_geojson_lines
-        - read_ipc
-        - read_ipc_stream
         - read_parquet
         - read_parquet_async
         - read_postgis
@@ -23,9 +21,9 @@ Read and write to files on disk and databases like PostGIS.
         - write_flatgeobuf
         - write_geojson
         - write_geojson_lines
-        - write_ipc
-        - write_ipc_stream
         - write_parquet
         - ObjectStore
         - ParquetDataset
         - ParquetFile
+        - ParquetWriter
+
diff --git a/python/docs/api/io/types.md b/python/docs/api/io/types.md
@@ -0,0 +1,3 @@
+# Types
+
+::: geoarrow.rust.io.types
diff --git a/python/docs/source/ecosystem/geopandas.md → python/docs/ecosystem/geopandas.md b/python/docs/source/ecosystem/geopandas.md → python/docs/ecosystem/geopandas.md
@@ -1,6 +1,6 @@
 # GeoPandas
 
-Use the [`from_geopandas`](../api/core/interop.md#geoarrow.rust.core.from_geopandas) and [`to_geopandas`](../api/core/interop.md#geoarrow.rust.core.to_geopandas) functions to convert a GeoTable from and to GeoPandas.
+Use the [`from_geopandas`](../api/core/interop.md#geoarrow.rust.core.from_geopandas) and [`to_geopandas`](../api/core/interop.md#geoarrow.rust.core.to_geopandas) functions to convert to and from GeoPandas.
 
 ```py
 import geopandas as gpd

diff --git a/python/docs/source/ecosystem/lonboard.md → python/docs/ecosystem/lonboard.md b/python/docs/source/ecosystem/lonboard.md → python/docs/ecosystem/lonboard.md
diff --git a/python/docs/source/ecosystem/pyogrio.md → python/docs/ecosystem/pyogrio.md b/python/docs/source/ecosystem/pyogrio.md → python/docs/ecosystem/pyogrio.md
@@ -5,10 +5,10 @@ Use the [`read_pyogrio`](../api/core/io.md#geoarrow.rust.core.read_pyogrio) func
 This requires the optional `pyogrio` and `pyarrow` dependencies.
 
 ```py
-from geoarrow.rust.core import read_pyogrio
+from geoarrow.rust.core import read_pyogrio, geometry_col
 
 path = "path/to/file.shp"
 table = read_pyogrio(path)
-table.geometry
+geometry = geometry_col(table)
 # <geoarrow.rust.core._rust.ChunkedMultiLineStringArray at 0x13fb61e70>
 ```
diff --git a/python/docs/ecosystem/shapely.md b/python/docs/ecosystem/shapely.md
@@ -0,0 +1,15 @@
+# Shapely
+
+For interoperability with [Shapely](https://shapely.readthedocs.io/en/stable/index.html), use the top-level [`to_shapely`](../api/core/interop.md#geoarrow.rust.core.to_shapely) and [`from_shapely`](../api/core/interop.md#geoarrow.rust.core.from_shapely) functions.
+
+Shapely interoperability requires `shapely` to be installed, and requires Shapely version 2.0 or higher.
+
+## Examples
+
+```py
+from geoarrow.rust.core import from_shapely, to_shapely
+import shapely
+
+shapely_geoms = to_shapely(geoarrow_array)
+geoarrow_array = from_shapely(shapely_geoms)
+```
diff --git a/python/docs/source/index.md → python/docs/index.md b/python/docs/source/index.md → python/docs/index.md
@@ -13,9 +13,8 @@ A Python library implementing the [GeoArrow](https://geoarrow.org/) specificatio
 
 More specifically, it contains:
 
-- Classes to represent GeoArrow arrays: `PointArray`, `LineStringArray`, etc.
-- Classes to represent _chunked_ GeoArrow arrays: `ChunkedPointArray`, `ChunkedLineStringArray`, etc.
-- A spatial table representation, `GeoTable`, where one column is a geospatial type and [Apache Arrow](https://arrow.apache.org/) is used to represent attribute columns. This enables future support for table-based operations like geospatial joins.
+- `GeometryArray`, which represents contiguous GeoArrow arrays
+- `ChunkedGeometryArray`, which represents a collection of GeoArrow arrays
 - Rust-based algorithms for computations on GeoArrow memory.
 - Rust-based parsers for various geospatial file formats.
 
@@ -26,7 +25,7 @@ Refer to the documentation at [geoarrow.github.io/geoarrow-rs/python](https://ge
 ## Installation
 
 ```
-pip install geoarrow-rust-core
+pip install geoarrow-rust-core geoarrow-rust-io
 ```
 
 `geoarrow-rust` is distributed with [namespace packaging](https://packaging.python.org/en/latest/guides/packaging-namespace-packages/), meaning that each python package `geoarrow-rust-[submodule-name]` (imported as `geoarrow.rust.[submodule-name]`) can be published to PyPI independently. The benefit of this approach is that _core library_ — which contains only pure-Rust code — can be precompiled for many platforms very easily. Then other submodules with C dependencies, like a future `geoarrow-rust-geos`, which will bind to GEOS for spatial operations, can be built and packaged independently.

diff --git a/...docs/source/performance/multithreading.md → python/docs/performance/multithreading.md b/...docs/source/performance/multithreading.md → python/docs/performance/multithreading.md
diff --git a/python/docs/source/CHANGELOG.md b/python/docs/source/CHANGELOG.md
diff --git a/python/docs/source/api/core/geometry/array.md b/python/docs/source/api/core/geometry/array.md
diff --git a/python/docs/source/api/core/geometry/chunked.md b/python/docs/source/api/core/geometry/chunked.md
diff --git a/python/docs/source/api/core/geometry/scalar.md b/python/docs/source/api/core/geometry/scalar.md
diff --git a/python/docs/source/ecosystem/polars.md b/python/docs/source/ecosystem/polars.md
diff --git a/python/docs/source/ecosystem/shapely.md b/python/docs/source/ecosystem/shapely.md
diff --git a/python/docs/source/stylesheets/extra.css → python/docs/stylesheets/extra.css b/python/docs/source/stylesheets/extra.css → python/docs/stylesheets/extra.css
diff --git a/python/geoarrow-core/python/geoarrow/rust/core/_rust.pyi b/python/geoarrow-core/python/geoarrow/rust/core/_rust.pyi
@@ -45,14 +45,35 @@ from .types import (
 )
 
 class Geometry:
+    """
+    An immutable geometry scalar using GeoArrow's in-memory representation.
+
+    **Note**: for best performance, do as many operations as possible on arrays or chunked
+    arrays instead of scalars.
+    """
     def __arrow_c_array__(
         self, requested_schema: object | None = None
-    ) -> Tuple[object, object]: ...
+    ) -> Tuple[object, object]:
+        """
+        An implementation of the [Arrow PyCapsule
+        Interface](https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html).
+        This dunder method should not be called directly, but enables zero-copy data
+        transfer to other Python libraries that understand Arrow memory.
+
+        For example, you can call [`pyarrow.array()`][pyarrow.array] to convert this
+        array into a pyarrow array, without copying memory.
+        """
     def __eq__(self, other: object) -> bool: ...
     @property
-    def __geo_interface__(self) -> dict: ...
-    def __repr__(self) -> str: ...
-    def _repr_svg_(self) -> str: ...
+    def __geo_interface__(self) -> dict:
+        """Implements the "geo interface protocol".
+
+        See <https://gist.github.com/sgillies/2217756>
+        """
+    def __repr__(self) -> str:
+        """Text representation."""
+    def _repr_svg_(self) -> str:
+        """Render as SVG in IPython/Jupyter."""
 
 class GeometryArray:
     """An immutable array of geometries using GeoArrow's in-memory representation."""
@@ -94,16 +115,34 @@ class GeometryArray:
         """
 
 class ChunkedGeometryArray:
-    def __arrow_c_stream__(self, requested_schema: object | None = None) -> object: ...
+    """
+    An immutable chunked array of geometries using GeoArrow's in-memory representation.
+    """
+    def __arrow_c_stream__(self, requested_schema: object | None = None) -> object:
+        """
+        An implementation of the [Arrow PyCapsule
+        Interface](https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html).
+        This dunder method should not be called directly, but enables zero-copy data
+        transfer to other Python libraries that understand Arrow memory.
+
+        For example, you can call [`pyarrow.chunked_array()`][pyarrow.chunked_array] to
+        convert this array into a pyarrow array, without copying memory.
+        """
     def __eq__(self, other: object) -> bool: ...
-    def __getitem__(self, key: int) -> Geometry: ...
-    def __len__(self) -> int: ...
-    def __repr__(self) -> str: ...
-    def chunk(self, i: int) -> GeometryArray: ...
-    def chunks(self) -> List[GeometryArray]: ...
+    def __getitem__(self, key: int) -> Geometry:
+        """Access the item at a given index."""
+    def __len__(self) -> int:
+        """The number of rows."""
+    def __repr__(self) -> str:
+        """Text representation."""
+    def chunk(self, i: int) -> GeometryArray:
+        """Access a single underlying chunk."""
+    def chunks(self) -> List[GeometryArray]:
+        """Convert to a list of single-chunked arrays."""
     @classmethod
     def from_arrow_arrays(cls, input: Sequence[ArrowArrayExportable]) -> Self: ...
-    def num_chunks(self) -> int: ...
+    def num_chunks(self) -> int:
+        """Number of underlying chunks."""
 
 # Top-level array/chunked array functions