You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Adds a new repository to stac-utils, stac-cli. This repository will be a click-based Comand Line Interface (CLI), named stac, for working with STAC. The command-line interface in pystac-client will be deprecated, with the plan to remove it once stac-cli reaches an acceptable level of maturity. The command-line interface in stactools will be reworked to use a plugin interface built into stac-cli.
Motivation
Currently there are two CLIs in the Python+STAC ecosystem:
pystac-client provides stac-client, which performs searches and other queries against STAC APIs
stactools provides stac, which includes some built-in functionality for moving, copying, and otherwise modifing STAC items, as well as a plugin interface used by stactools-packages to add their own subcommands
Having two different command-line interfaces in the ecosystem is confusing for users; for example, it's reasonable to assume that you can do stac search https://my-great-stac-api.com/, but you can't; you need to use stac-client search. Additionally, in an effort to keep the dependency profile of pystac-client light, its CLI is not built with click, meaning that its implementation is more complex and less featured than a click-based implementation would be. By moving the CLI to a standalone stac-cli repository, we will make pystac-client smaller and more focused on its core task. Any by porting some stactools subcommands to stac-cli, we will provide more command-line functionality to users without requiring them to install the entire stactools dependency stack.
Guide-level explanation
stac-utils/stac-cli will be a standard Python library, with a similar layout to the existing stac-utils Python packages. It will depend on pystac, pystac-client, and click. The CLI will be accessible via stac, e.g.:
stac --help
Subcommands
The following subcommands currently exist for pystac-client and will be ported to stac-cli:
name
description
collections
Get all collections in this Catalog
search
Perform new search of items
The following subcommands currently exist for stactools:
name
description
add
Add an item to a catalog/collection.
add-asset
Add an asset to an item.
add-raster
Add raster extension to an Item.
copy
Copy a STAC Catalog
create-item
Creates an item from an asset
describe
Prints out a list of all catalogs, collections and items in this STAC.
info
Display info about a static STAC catalog.
layout
Reformat the layout of a STAC based on templating.
lint
Lint a stac object with stac-check.
merge
Merge items from one STAC into another.
move-assets
Move or copy assets in a STAC to the Item locations.
summary
Summarize a STAC collection's contents.
update-geometry
Update an item geometry from an asset footprint
validate
Validate a stac object.
version
Display version info.
Some of these stactools commands depend on heavy or complicated third-party libraries (e.g. rasterio); these will stay in stactools. Many of the simpler commands can be implemented purely via pystac and pystac-client, and these will be ported to stac-cli and removed from stactools.
Plugin interface
stactools currently has a plugin interface that allows outside packages to add subcommands to the stac CLI entrypoint. This plugin interface will be ported from stactools to stac-cli, and stactools will be reworked to provide any of its remaining subcommands via this plugin interface. This interface will be designed to be backwards compatible, so existing stactools-packages continue to work without any changes.
Drawbacks
We're increasing complexity and management effort by adding another repository to the stac-utils Python ecosystem
Users who are currently relying on the stac-client entrypoint will have to update their workflows to use stac
By decoupling pystac-client from its CLI, we increase the probability that the CLI and the pystac-client Python API will become out-of-sync, causing breakages
Rationale and alternatives
By removing command-line responsibilities from pystac-client, we make that library simpler and easier to maintain.
click is widely used within the STAC+Python ecosytem, so by reimplementing pystac-client subcommands in click, we provide a less surprising experience for users.
If we don't make this change, users will continue to be confused about whether to use stac or stac-client for command-line operations, and the maintenance burden of pystac-client will remain higher than it otherwise would be. Additionally, some functionality that could be exposed on the command line withoutstactools (e.g. stac describe) will be inaccessible.
Prior art
aws-cli is a command line interface to botocore, which is similar to how stac-cli would be a CLI to pystac
I personally have positive experiences when I decouple my command-line interfaces from my software APIs, e.g. for my stac-rs and (wip) stac-cli-rs projects
Unresolved questions
Which stactools subcommands will get ported over to stac-cli?
Will we need to rename any of the pystac-client subcommands?
In stac-cli, how strictly will we bound the dependencies on pystac and pystac-client? We want to provide some flexibility to allow external packages to use the plugin mechanism, but we also want to ensure users that run pip install stac-cli will get a working installation.
What will be the deprecation/removal timeline for the pystac-client CLI?
Future possibilities
We could enable/add async support for stac-cli, which would be extremely helpful for stac search, stac download, etc, without necessarily having to push async down into pystac and pystac-client
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
-
stac-cli
Summary
Adds a new repository to stac-utils, stac-cli. This repository will be a click-based Comand Line Interface (CLI), named
stac
, for working with STAC. The command-line interface in pystac-client will be deprecated, with the plan to remove it once stac-cli reaches an acceptable level of maturity. The command-line interface in stactools will be reworked to use a plugin interface built into stac-cli.Motivation
Currently there are two CLIs in the Python+STAC ecosystem:
stac-client
, which performs searches and other queries against STAC APIsstac
, which includes some built-in functionality for moving, copying, and otherwise modifing STAC items, as well as a plugin interface used by stactools-packages to add their own subcommandsHaving two different command-line interfaces in the ecosystem is confusing for users; for example, it's reasonable to assume that you can do
stac search https://my-great-stac-api.com/
, but you can't; you need to usestac-client search
. Additionally, in an effort to keep the dependency profile of pystac-client light, its CLI is not built with click, meaning that its implementation is more complex and less featured than a click-based implementation would be. By moving the CLI to a standalone stac-cli repository, we will make pystac-client smaller and more focused on its core task. Any by porting some stactools subcommands to stac-cli, we will provide more command-line functionality to users without requiring them to install the entire stactools dependency stack.Guide-level explanation
stac-utils/stac-cli will be a standard Python library, with a similar layout to the existing stac-utils Python packages. It will depend on pystac, pystac-client, and click. The CLI will be accessible via
stac
, e.g.:Subcommands
The following subcommands currently exist for pystac-client and will be ported to stac-cli:
The following subcommands currently exist for stactools:
Some of these stactools commands depend on heavy or complicated third-party libraries (e.g. rasterio); these will stay in stactools. Many of the simpler commands can be implemented purely via pystac and pystac-client, and these will be ported to stac-cli and removed from stactools.
Plugin interface
stactools currently has a plugin interface that allows outside packages to add subcommands to the
stac
CLI entrypoint. This plugin interface will be ported from stactools to stac-cli, and stactools will be reworked to provide any of its remaining subcommands via this plugin interface. This interface will be designed to be backwards compatible, so existing stactools-packages continue to work without any changes.Drawbacks
stac-client
entrypoint will have to update their workflows to usestac
Rationale and alternatives
stac
orstac-client
for command-line operations, and the maintenance burden of pystac-client will remain higher than it otherwise would be. Additionally, some functionality that could be exposed on the command line without stactools (e.g.stac describe
) will be inaccessible.Prior art
Unresolved questions
pip install stac-cli
will get a working installation.Future possibilities
We could enable/add
async
support for stac-cli, which would be extremely helpful forstac search
,stac download
, etc, without necessarily having to pushasync
down into pystac and pystac-clientBeta Was this translation helpful? Give feedback.
All reactions