feat(python): add cli to python package

Author: gadomski

python/Cargo.toml

@@ -13,7 +13,10 @@ name = "stacrs"
 crate-type = ["cdylib"]
 
 [dependencies]
+clap = "4"
 pyo3 = "0.22"
 pythonize = "0.22"
 stac = { path = "../core", features = ["reqwest"] }
+stac-cli = { path = "../cli", default-features = false }
 stac-validate = { path = "../validate" }
+tokio = { version = "1", features = ["rt-multi-thread"] }

python/docs/index.md

@@ -1,6 +1,6 @@
 # stacrs
 
-A small, no-dependency Python library for working with [STAC](https://stacspec.org), using [Rust](https://github.com/stac-utils/stac-rs) under the hood.
+A small, no-dependency Python library and command-line interface (CLI) for working with [STAC](https://stacspec.org), using [Rust](https://github.com/stac-utils/stac-rs) under the hood.
 
 ## Installation
 
@@ -10,10 +10,55 @@ pip install stacrs
 
 ## Usage
 
+### API
+
 ```python
 import stacrs
 
 stacrs.validate_href("https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json")
 ```
 
 See [the API documentation](./api.md) for more.
+
+### CLI
+
+```shell
+$ stacrs --help
+Command line interface for stac-rs
+
+Usage: stacrs [OPTIONS] <COMMAND>
+
+Commands:
+  item       Creates a STAC Item
+  migrate    Migrates a STAC value from one version to another
+  search     Searches a STAC API
+  serve      Serves a STAC API
+  sort       Sorts the fields of STAC object
+  translate  Translates STAC values between formats
+  validate   Validates a STAC object or API endpoint using json-schema validation
+  help       Print this message or the help of the given subcommand(s)
+
+Options:
+  -c, --compact
+          Use a compact representation of the output, if possible
+
+  -i, --input-format <INPUT_FORMAT>
+          The input format. If not provided, the format will be detected from the input file extension when possible
+
+          Possible values:
+          - parquet: stac-geoparquet
+          - json:    JSON (the default)
+
+  -o, --output-format <OUTPUT_FORMAT>
+          The output format. If not provided, the format will be detected from the output file extension when possible
+
+          Possible values:
+          - parquet: stac-geoparquet
+          - json:    JSON (the default)
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+  -V, --version
+          Print version
+```

python/pyproject.toml

@@ -27,5 +27,8 @@ Repository = "https://github.com/stac-utils/stac-rs"
 Documentation = "https://stacrs.readthedocs.io/"
 Issues = "https://github.com/stac-utils/stac-rs/issues"
 
+[project.scripts]
+stacrs = "stacrs:main"
+
 [tool.maturin]
 features = ["pyo3/extension-module"]

python/src/lib.rs

@@ -1,9 +1,36 @@
+use clap::Parser;
 use pyo3::{create_exception, exceptions::PyException, prelude::*, types::PyDict};
 use stac::{Migrate, Value};
+use stac_cli::Args;
 use stac_validate::Validate;
 
 create_exception!(stacrs, StacrsError, PyException, "An error in stacrs");
 
+/// Runs the command-line interface.
+///
+/// Returns:
+///     int: The exit code
+#[pyfunction]
+fn main() -> PyResult<i64> {
+    std::process::exit(
+        tokio::runtime::Builder::new_multi_thread()
+            .enable_all()
+            .build()
+            .unwrap()
+            .block_on(async {
+                // We skip one because the first argument is going to be the python interpreter.
+                let args = Args::parse_from(std::env::args_os().skip(1));
+                match stac_cli::run(args).await {
+                    Ok(()) => 0,
+                    Err(err) => {
+                        eprintln!("ERROR: {}", err);
+                        err.code()
+                    }
+                }
+            }),
+    )
+}
+
 /// Migrates a STAC dictionary to another version.
 ///
 /// Migration can be as simple as updating the `stac_version` attribute, but
@@ -20,6 +47,9 @@ create_exception!(stacrs, StacrsError, PyException, "An error in stacrs");
 ///     version (str | None): The version to migrate to. If not provided, the
 ///         value will be migrated to the latest stable version.
 ///
+/// Returns:
+///     dict[str, Any]: The migrated dictionary
+///
 /// Examples:
 ///     >>> with open("examples/simple-item.json") as f:
 ///     >>>     item = json.load(f)
@@ -102,6 +132,7 @@ fn validate_value(value: Value) -> PyResult<()> {
 /// A collection of functions for working with STAC, using Rust under the hood.
 #[pymodule]
 fn stacrs(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add_function(wrap_pyfunction!(main, m)?)?;
     m.add_function(wrap_pyfunction!(migrate, m)?)?;
     m.add_function(wrap_pyfunction!(validate_href, m)?)?;
     m.add_function(wrap_pyfunction!(validate, m)?)?;

python/stacrs.pyi

@@ -2,6 +2,7 @@ from typing import Any, Optional
 
 class StacrsError(Exception): ...
 
+def main() -> int: ...
 def migrate(value: dict[str, Any], version: Optional[str] = None) -> dict[str, Any]: ...
 def validate_href(href: str) -> None: ...
 def validate(value: dict[str, Any]) -> None: ...