Skip to content

Commit 3dc9bbc

Browse files
gadomskigadomski
committed
docs(python): move to stub file
1 parent 60e218e commit 3dc9bbc

File tree

6 files changed

+231
-208
lines changed

6 files changed

+231
-208
lines changed

‎python/src/migrate.rs‎

Lines changed: 0 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -2,30 +2,6 @@ use crate::Error;
22
use pyo3::{prelude::*, types::PyDict};
33
use stac::{Migrate, Value};
44

5-
/// Migrates a STAC dictionary to another version.
6-
///
7-
/// Migration can be as simple as updating the `stac_version` attribute, but
8-
/// sometimes can be more complicated. For example, when migrating to v1.1.0,
9-
/// [eo:bands and raster:bands should be consolidated to the new bands
10-
/// structure](https://github.com/radiantearth/stac-spec/releases/tag/v1.1.0-beta.1).
11-
///
12-
/// See [the stac-rs
13-
/// documentation](https://docs.rs/stac/latest/stac/enum.Version.html) for
14-
/// supported versions.
15-
///
16-
/// Args:
17-
/// value (dict[str, Any]): The STAC value to migrate
18-
/// version (str | None): The version to migrate to. If not provided, the
19-
/// value will be migrated to the latest stable version.
20-
///
21-
/// Returns:
22-
/// dict[str, Any]: The migrated dictionary
23-
///
24-
/// Examples:
25-
/// >>> with open("examples/simple-item.json") as f:
26-
/// >>> item = json.load(f)
27-
/// >>> item = stacrs.migrate(item, "1.1.0-beta.1")
28-
/// >>> assert item["stac_version"] == "1.1.0-beta.1"
295
#[pyfunction]
306
#[pyo3(signature = (value, version=None))]
317
pub fn migrate<'py>(
@@ -44,25 +20,6 @@ pub fn migrate<'py>(
4420
value.downcast_into().map_err(PyErr::from)
4521
}
4622

47-
/// Migrates a STAC dictionary at the given href to another version.
48-
///
49-
/// Migration can be as simple as updating the `stac_version` attribute, but
50-
/// sometimes can be more complicated. For example, when migrating to v1.1.0,
51-
/// [eo:bands and raster:bands should be consolidated to the new bands
52-
/// structure](https://github.com/radiantearth/stac-spec/releases/tag/v1.1.0-beta.1).
53-
///
54-
/// See [the stac-rs
55-
/// documentation](https://docs.rs/stac/latest/stac/enum.Version.html) for
56-
/// supported versions.
57-
///
58-
/// Args:
59-
/// href (str): The href to read the STAC object from
60-
/// version (str | None): The version to migrate to. If not provided, the
61-
/// value will be migrated to the latest stable version.
62-
///
63-
/// Examples:
64-
/// >>> item = stacrs.migrate_href("examples/simple-item.json", "1.1.0-beta.1")
65-
/// >>> assert item["stac_version"] == "1.1.0-beta.1"
6623
#[pyfunction]
6724
#[pyo3(signature = (href, version=None))]
6825
pub fn migrate_href<'py>(

‎python/src/read.rs‎

Lines changed: 0 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -7,20 +7,6 @@ use pyo3::{
77
use stac::{Format, Value};
88
use tokio::runtime::Builder;
99

10-
/// Reads STAC from a href.
11-
///
12-
/// Args:
13-
/// href (str): The href to write to
14-
/// format (str | None): The output format to write. If not provided, will be
15-
/// inferred from the href's extension.
16-
/// options (list[tuple[str, str]] | None): Options for configuring an
17-
/// object store, e.g. your AWS credentials.
18-
///
19-
/// Returns:
20-
/// dict[str, Any]: The STAC value
21-
///
22-
/// Examples:
23-
/// >>> item = stacrs.read("item.json")
2410
#[pyfunction]
2511
#[pyo3(signature = (href, *, format=None, options=None))]
2612
pub fn read<'py>(

‎python/src/search.rs‎

Lines changed: 0 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -10,52 +10,6 @@ use stac_duckdb::Client;
1010
use std::str::FromStr;
1111
use tokio::runtime::Builder;
1212

13-
/// Searches a STAC API server.
14-
///
15-
/// Args:
16-
/// href (str): The STAC API to search.
17-
/// intersects (str | dict[str, Any] | GeoInterface | None): Searches items
18-
/// by performing intersection between their geometry and provided GeoJSON
19-
/// geometry.
20-
/// ids (list[str] | None): Array of Item ids to return.
21-
/// collections (list[str] | None): Array of one or more Collection IDs that
22-
/// each matching Item must be in.
23-
/// max_items (int | None): The maximum number of items to iterate through.
24-
/// limit (int | None): The page size returned from the server. Use
25-
/// `max_items` to actually limit the number of items returned from this
26-
/// function.
27-
/// bbox (list[float] | None): Requested bounding box.
28-
/// datetime (str | None): Single date+time, or a range (‘/’ separator),
29-
/// formatted to RFC 3339, section 5.6. Use double dots .. for open
30-
/// date ranges.
31-
/// include (list[str]] | None): fields to include in the response (see [the
32-
/// extension
33-
/// docs](https://github.com/stac-api-extensions/fields?tab=readme-ov-file#includeexclude-semantics))
34-
/// for more on the semantics).
35-
/// exclude (list[str]] | None): fields to exclude from the response (see [the
36-
/// extension
37-
/// docs](https://github.com/stac-api-extensions/fields?tab=readme-ov-file#includeexclude-semantics))
38-
/// for more on the semantics).
39-
/// sortby (list[str] | None): Fields by which to sort results (use `-field` to sort descending).
40-
/// filter (str | dict[str, Any] | none): CQL2 filter expression. Strings
41-
/// will be interpreted as cql2-text, dictionaries as cql2-json.
42-
/// query (dict[str, Any] | None): Additional filtering based on properties.
43-
/// It is recommended to use filter instead, if possible.
44-
/// use_duckdb (bool | None): Query with DuckDB. If None and the href has a
45-
/// 'parquet' or 'geoparquet' extension, will be set to True. Defaults
46-
/// to None.
47-
///
48-
/// Returns:
49-
/// list[dict[str, Any]]: A list of the returned STAC items.
50-
///
51-
/// Examples:
52-
/// >>> items = stacrs.search(
53-
/// ... "https://landsatlook.usgs.gov/stac-server",
54-
/// ... collections=["landsat-c2l2-sr"],
55-
/// ... intersects={"type": "Point", "coordinates": [-105.119, 40.173]},
56-
/// ... sortby="-properties.datetime",
57-
/// ... max_items=1,
58-
/// ... )
5913
#[pyfunction]
6014
#[pyo3(signature = (href, *, intersects=None, ids=None, collections=None, max_items=None, limit=None, bbox=None, datetime=None, include=None, exclude=None, sortby=None, filter=None, query=None, use_duckdb=None))]
6115
pub fn search<'py>(
@@ -96,57 +50,6 @@ pub fn search<'py>(
9650
.and_then(|v| v.extract())
9751
}
9852

99-
/// Searches a STAC API server and saves the result to an output file.
100-
///
101-
/// Args:
102-
/// outfile (str): The output href. This can be a local file path, or any
103-
/// url scheme supported by [stac::object_store::write].
104-
/// href (str): The STAC API to search.
105-
/// intersects (str | dict[str, Any] | GeoInterface | None): Searches items
106-
/// by performing intersection between their geometry and provided GeoJSON
107-
/// geometry.
108-
/// ids (list[str] | None): Array of Item ids to return.
109-
/// collections (list[str] | None): Array of one or more Collection IDs that
110-
/// each matching Item must be in.
111-
/// max_items (int | None): The maximum number of items to iterate through.
112-
/// limit (int | None): The page size returned from the server. Use
113-
/// `max_items` to actually limit the number of items returned from this
114-
/// function.
115-
/// bbox (list[float] | None): Requested bounding box.
116-
/// datetime (str | None): Single date+time, or a range (‘/’ separator),
117-
/// formatted to RFC 3339, section 5.6. Use double dots .. for open
118-
/// date ranges.
119-
/// include (list[str]] | None): fields to include in the response (see [the
120-
/// extension
121-
/// docs](https://github.com/stac-api-extensions/fields?tab=readme-ov-file#includeexclude-semantics))
122-
/// for more on the semantics).
123-
/// exclude (list[str]] | None): fields to exclude from the response (see [the
124-
/// extension
125-
/// docs](https://github.com/stac-api-extensions/fields?tab=readme-ov-file#includeexclude-semantics))
126-
/// for more on the semantics).
127-
/// sortby (list[str] | None): Fields by which to sort results (use `-field` to sort descending).
128-
/// filter (str | dict[str, Any] | none): CQL2 filter expression. Strings
129-
/// will be interpreted as cql2-text, dictionaries as cql2-json.
130-
/// query (dict[str, Any] | None): Additional filtering based on properties.
131-
/// It is recommended to use filter instead, if possible.
132-
/// format (str | None): The output format. If none, will be inferred from
133-
/// the outfile extension, and if that fails will fall back to compact JSON.
134-
/// options (list[tuple[str, str]] | None): Configuration values to pass to the object store backend.
135-
/// use_duckdb (bool | None): Query with DuckDB. If None and the href has a
136-
/// 'parquet' or 'geoparquet' extension, will be set to True. Defaults
137-
/// to None.
138-
///
139-
/// Returns:
140-
/// list[dict[str, Any]]: A list of the returned STAC items.
141-
///
142-
/// Examples:
143-
/// >>> items = stacrs.search_to("out.parquet",
144-
/// ... "https://landsatlook.usgs.gov/stac-server",
145-
/// ... collections=["landsat-c2l2-sr"],
146-
/// ... intersects={"type": "Point", "coordinates": [-105.119, 40.173]},
147-
/// ... sortby="-properties.datetime",
148-
/// ... max_items=1,
149-
/// ... )
15053
#[pyfunction]
15154
#[pyo3(signature = (outfile, href, *, intersects=None, ids=None, collections=None, max_items=None, limit=None, bbox=None, datetime=None, include=None, exclude=None, sortby=None, filter=None, query=None, format=None, options=None, use_duckdb=None))]
15255
pub fn search_to(

‎python/src/validate.rs‎

Lines changed: 0 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -2,38 +2,12 @@ use crate::{Error, Result};
22
use pyo3::{prelude::*, types::PyDict};
33
use stac::{ValidateBlocking, Value};
44

5-
/// Validates a single href with json-schema.
6-
///
7-
/// Args:
8-
/// href (str): The href of the STAC value to validate
9-
///
10-
/// Raises:
11-
/// Exception: On any input/output error, or on a validation error
12-
///
13-
/// Examples:
14-
/// >>> stacrs.validate_href("examples/simple-item.json")
15-
/// >>> stacrs.validate_href("data/invalid-item.json")
16-
/// Traceback (most recent call last):
17-
/// File "<stdin>", line 1, in <module>
18-
/// Exception: Validation errors: "collection" is a required property
195
#[pyfunction]
206
pub fn validate_href(href: &str) -> Result<()> {
217
let value: Value = stac::read(href)?;
228
validate_value(value)
239
}
2410

25-
/// Validates a STAC dictionary with json-schema.
26-
///
27-
/// Args:
28-
/// value (dict[str, Any]): The STAC value to validate
29-
///
30-
/// Raises:
31-
/// Exception: On a validation error
32-
///
33-
/// Examples:
34-
/// >>> with open("examples/simple-item.json") as f:
35-
/// >>> data = json.load(f)
36-
/// >>> stacrs.validate(data)
3711
#[pyfunction]
3812
pub fn validate(value: &Bound<'_, PyDict>) -> PyResult<()> {
3913
let value: Value = pythonize::depythonize(value)?;

‎python/src/write.rs‎

Lines changed: 0 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -8,26 +8,6 @@ use serde_json::Value;
88
use stac::{Format, Item, ItemCollection};
99
use tokio::runtime::Builder;
1010

11-
/// Writes STAC to a href.
12-
///
13-
/// Args:
14-
/// href (str): The href to write to
15-
/// value (dict[str, Any] | list[dict[str, Any]]): The value to write. This
16-
/// can be a STAC dictionary or a list of items.
17-
/// format (str | None): The output format to write. If not provided, will be
18-
/// inferred from the href's extension.
19-
/// options (list[tuple[str, str]] | None): Options for configuring an
20-
/// object store, e.g. your AWS credentials.
21-
///
22-
/// Returns:
23-
/// dict[str, str] | None: The result of putting data into an object store,
24-
/// e.g. the e_tag and the version. None is returned if the file was written
25-
/// locally.
26-
///
27-
/// Examples:
28-
/// >>> with open("items.json") as f:
29-
/// ... items = json.load(f)
30-
/// >>> stacrs.write("items.parquet", items)
3111
#[pyfunction]
3212
#[pyo3(signature = (href, value, *, format=None, options=None))]
3313
pub fn write<'py>(

0 commit comments

Comments
 (0)