feat(python): add read, write, and more docs

python/CHANGELOG.md

@@ -8,6 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - `migrate_href` ([#334](https://github.com/stac-utils/stac-rs/pull/334))
 - `search` and `search_to` ([#387](https://github.com/stac-utils/stac-rs/pull/387))
+- `read`, `write`, and `pystac` ([#418](https://github.com/stac-utils/stac-rs/pull/418))
 
 ## [0.0.3] - 2024-08-29
 

python/Cargo.toml

@@ -13,7 +13,9 @@ name = "stacrs"
 crate-type = ["cdylib"]
 
 [features]
-geoparquet = ["stac/geoparquet-compression"]
+geoparquet = [
+    "stac/geoparquet-compression",
+] # need to be able to disable geoparquet so this builds on readthedocs
 
 [dependencies]
 geojson = "0.24"

python/README.md

@@ -6,7 +6,7 @@
 ![PyPI - License](https://img.shields.io/pypi/l/stacrs?style=for-the-badge)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg?style=for-the-badge)](./CODE_OF_CONDUCT)
 
-A Python package for working with [STAC](https://stacspec.org/), using Rust under the hood.
+A no-dependency Python package for [STAC](https://stacspec.org/), using Rust under the hood.
 
 ## Usage
 
@@ -21,21 +21,61 @@ Then:
 ```python
 import stacrs
 
-# Searches a STAC API
+# Search a STAC API
 items = stacrs.search(
     "https://landsatlook.usgs.gov/stac-server",
     collections="landsat-c2l2-sr",
     intersects={"type": "Point", "coordinates": [-105.119, 40.173]},
     sortby="-properties.datetime",
-    max_items=1,
+    max_items=100,
 )
 
-# Validates a href using json-schema
-stacrs.validate_href("https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0/examples/simple-item.json")
+# Write items to a stac-geoparquet file
+stacrs.write("items.parquet", items)
+
+# Read items from a stac-geoparquet file as an item collection
+item_collection = stacrs.read("items.parquet")
+
+# Use `search_to` for better performance if you know you'll be writing the items
+# to a file
+stacrs.search_to(
+    "items.parquet",
+    "https://landsatlook.usgs.gov/stac-server",
+    collections="landsat-c2l2-sr",
+    intersects={"type": "Point", "coordinates": [-105.119, 40.173]},
+    sortby="-properties.datetime",
+    max_items=100,
+)
+```
+
+### pystac
+
+If [pystac](https://pystac.readthedocs.io) is present, `stacrs.pystac` provides functions that take **pystac** objects as their inputs and outputs:
+
+```python
+import pystac
+import stacrs.pystac
+
+item = pystac.read_file("item.json")
+stacrs.pystac.validate(item)
+
+items = list(stacrs.pystac.search(...))
+```
+
+You can install **pystac** with **stacrs** via an optional dependency:
+
+```shell
+pip install 'stacrs[pystac]'
 ```
 
-See [the documentation](https://stacrs.readthedocs.io/) for more information.
+## Comparisons
+
+This package (intentionally) has limited functionality, as it is _not_ intended to be a replacement for existing Python STAC packages.
+[pystac](https://pystac.readthedocs.io) is a mature Python library with a significantly richer API for working with STAC objects.
+For querying STAC APIs, [pystac-client](https://pystac-client.readthedocs.io) is more feature-rich than our simplistic `stacrs.search`.
+
+That being said, it is hoped that **stacrs** will be a nice complement to the existing Python STAC ecosystem by providing a no-dependency package with unique capabilities, such as searching directly into a stac-geoparquet file.
 
 ## Other info
 
-This crate is part of the [stac-rs](https://github.com/stac-utils/stac-rs) monorepo, see its README for contributing and license information.
+This package is part of the [stac-rs](https://github.com/stac-utils/stac-rs) monorepo, see its README for contributing and license information.

python/docs/api/index.md

@@ -0,0 +1,9 @@
+# API
+
+API documentation for **stacrs**.
+
+- [migrate](./migrate.md)
+- [search](./search.md)
+- [validate](./validate.md)
+- [write](./write.md)
+- [pystac](./pystac.md)

python/docs/api/migrate.md

@@ -0,0 +1,4 @@
+# Migration
+
+::: stacrs.migrate
+::: stacrs.migrate_href

python/docs/api/pystac.md

@@ -0,0 +1,14 @@
+# pystac
+
+These functions are only available if [pystac](https://pystac.readthedocs.io/) is available on your system.
+To install **pystac** and **stacrs**:
+
+```shell
+pip install 'stacrs[pystac]'
+```
+
+::: stacrs.pystac.migrate
+::: stacrs.pystac.read
+::: stacrs.pystac.search
+::: stacrs.pystac.validate
+::: stacrs.pystac.write

python/docs/api/read.md

@@ -0,0 +1,3 @@
+# Read
+
+::: stacrs.read

python/docs/api/search.md

@@ -0,0 +1,4 @@
+# Search
+
+::: stacrs.search
+::: stacrs.search_to

python/docs/api/validate.md

@@ -0,0 +1,4 @@
+# Validate
+
+::: stacrs.validate
+::: stacrs.validate_href

python/docs/api/write.md

@@ -0,0 +1,3 @@
+# Write
+
+::: stacrs.write

python/mkdocs.yml

@@ -5,9 +5,18 @@ theme:
   name: material
   icon:
     repo: fontawesome/brands/github
+  features:
+    - navigation.indexes
 nav:
   - Home: index.md
-  - API: api.md
+  - API:
+      - api/index.md
+      - migrate: api/migrate.md
+      - read: api/read.md
+      - search: api/search.md
+      - validate: api/validate.md
+      - write: api/write.md
+      - pystac: api/pystac.md
 plugins:
   - search
   - mkdocstrings:

python/pyproject.toml

@@ -22,13 +22,17 @@ classifiers = [
 keywords = ["stac", "geospatial"]
 dynamic = ["version"]
 
+[project.optional-dependencies]
+pystac = ["pystac>=1"]
+
 [project.urls]
 Repository = "https://github.com/stac-utils/stac-rs"
 Documentation = "https://stacrs.readthedocs.io/"
 Issues = "https://github.com/stac-utils/stac-rs/issues"
 
 [tool.maturin]
 features = ["pyo3/extension-module"]
+python-source = "python"
 
 [[tool.mypy.overrides]]
 module = "pyarrow.*"

python/python/stacrs/__init__.py

@@ -0,0 +1,30 @@
+from . import stacrs
+from .stacrs import (
+    migrate,
+    migrate_href,
+    read,
+    search,
+    search_to,
+    validate,
+    validate_href,
+    write,
+)
+
+__doc__ = stacrs.__doc__
+__all__ = [
+    "migrate",
+    "migrate_href",
+    "read",
+    "search",
+    "search_to",
+    "validate",
+    "validate_href",
+    "write",
+]
+
+import importlib.util
+
+if importlib.util.find_spec("pystac") is not None:
+    from . import pystac as pystac
+
+    __all__.append("pystac")