API Change: update `tools import` to match input/output naming convention
thermokarst opened this issue · 0 comments
thermokarst commented
Part of the changes introduced in #189 were some breaking changes w.r.t. the naming convention used for the parm flags in tools export
.
Old:
qiime tools export --help
Usage: qiime tools export [OPTIONS] PATH
Export data from a QIIME 2 Artifact or Visualization. Exporting extracts
the data stored in an Artifact or Visualization and will support exporting
to multiple formats in the future. For now, the data is exported in the
format it is stored within the Artifact or Visualization. Use 'qiime tools
extract' to extract the Artifact or Visualization's entire archive.
Options:
--output-dir DIRECTORY Directory where data should be exported to
[required]
--help Show this message and exit.
New:
qiime tools export --help master 517edc7
Usage: qiime tools export [OPTIONS]
Exporting extracts (and optionally transforms) datastored inside an
Artifact or Visualization. Note thatVisualizations cannot be transformed
with --output-format
Options:
--input-path PATH [required]
--output-path PATH Directory where data should be exported to [required]
--output-format TEXT Format which the data should be exported as. --output-
format cannot be used with Visualizations
--help Show this message and exit.
Note the changes in PATH
as a positional param vs --input-path
as a flag, as well as the renaming of --output-dir
to --output-path
.
Regarding tools import
, we would like to see similar changes implemented there, so that there is symmetry between the two commands.
Current:
qiime tools import --help
Usage: qiime tools import [OPTIONS]
Import data to create a new QIIME 2 Artifact. See https://docs.qiime2.org/
for usage examples and details on the file types and associated semantic
types that can be imported.
Options:
--type TEXT The semantic type of the artifact that will be
created upon importing. Use --show-importable-
types to see what importable semantic types are
available in the current deployment. [required]
--input-path PATH Path to file or directory that should be
imported. [required]
--output-path PATH Path where output artifact should be written.
[required]
--source-format TEXT The format of the data to be imported. If not
provided, data must be in the format expected by
the semantic type provided via --type.
--show-importable-types Show the semantic types that can be supplied to
--type to import data into an artifact.
--show-importable-formats Show formats that can be supplied to --source-
format to import data into an artifact.
--help Show this message and exit.
Proposed:
qiime tools import --help
Usage: qiime tools import [OPTIONS]
Import data to create a new QIIME 2 Artifact. See https://docs.qiime2.org/
for usage examples and details on the file types and associated semantic
types that can be imported.
Options:
--type TEXT The semantic type of the artifact that will be
created upon importing. Use --show-importable-
types to see what importable semantic types are
available in the current deployment. [required]
--input-path PATH Path to file or directory that should be
imported. [required]
--output-path PATH Path where output artifact should be written.
[required]
--input-format TEXT The format of the data to be imported. If not
provided, data must be in the format expected by
the semantic type provided via --type.
--show-importable-types Show the semantic types that can be supplied to
--type to import data into an artifact.
--show-importable-formats Show formats that can be supplied to --source-
format to import data into an artifact.
--help Show this message and exit.
Note that change from --source-format
to --input-format
.
This change will likely impact the user docs (we will open another issue there if needed).
This discussion recently came up here: #189 (comment).