Command line interface

This document describes the command-line interface (CLI) as a development reference and to track implementation status.

We use symbols to indicate the status of implementation (see table below). For planned or in-progress work, we might include signatures, docstrings, and pseudocode to clarify the design. Once the interface is implemented, these are replaced by links to the reference documentation.

A table showing the symbols used to indicate the status of interface components, along with their descriptions.
Status	Description
	Interface that has been implemented.
	Interface that is currently being worked on.
	Interface that is planned, but isn’t being worked on currently.

`seedcase-sprout`

seedcase-sprout has the following signature:

Terminal

seedcase-sprout <COMMAND> [PARAMETERS]

When used on its own, seedcase-sprout shows the help message as a shorthand for --help:

Terminal

seedcase-sprout

Note

As a convenience, we provide the command sprout as a shorthand for seedcase-sprout. It can be used in place of seedcase-sprout in all instances.

seedcase-sprout has several commands: extract-metadata, init-metadata, build-resources, build-metadata, and build that runs the other build-* commands. These commands are described below.

`extract-metadata`

The extract-metadata command extracts metadata from a Parquet file and outputs a Python script with the ResourceProperties() dataclass filled in with the extracted metadata. It is meant to be used with Parquet files in the staging/ directory that have the same schema (columns and data types) as the final resource. It has the signature:

Terminal

seedcase-sprout extract-metadata [PARQUET-PATH] --output/-o [OUTPUT-PATH]

flowchart LR
    parquet[/"Parquet path<br>[PARQUET-PATH]"/]
    output_opt[/"Output path<br>[--output]"/]
    extract["extract-metadata"]
    output[/"Python script<br>[File]"/]

    parquet --> extract
    output_opt --> extract
    extract --> output

Figure 1: The flow of input and output through the CLI extract-metadata command.

`init-metadata`

The init-metadata command creates a Python script with metadata fields that haven’t been filled in yet. It creates a Python script with empty *Properties() dataclasses. It has the signature:

Terminal

seedcase-sprout init-metadata [OUTPUT-PATH] --type [TYPE]

The output-path is the path to the file that will be created (e.g. package_properties.py or resource1_properties.py) so that there is full flexibility and control about where and what name the file will have. The --type determines whether to make a file with metadata for the package overall (top-level metadata) or for a resource file. The default is the package overall.

Unlike extract-metadata when --type is resource, the output is a Python script with a ResourceProperties() class listing all fields but nothing filled in yet (all commented out). For resource metadata, the script will have be manually imported into the package metadata file (since the PackageProperties() contains a field for the ResourceProperties()).

flowchart LR
    output_path[/"Path<br>[OUTPUT-PATH]"/]
    type[/"Metadata type<br>[TYPE]"/]
    init["init-metadata"]
    output[/"Python script<br>[File]"/]

    output_path --> init
    type --> init
    init --> output

Figure 2: The flow of input and output through the CLI init-metadata command.