proceed.model.StepResult

class proceed.model.StepResult(name=None, image_id=None, exit_code=None, log_file=None, timing=None, files_done=<factory>, files_in=<factory>, files_out=<factory>, files_summary=<factory>, skipped=False)

Records what happened when a Step ran.

Parameters:

  • name (str)

  • image_id (str)

  • exit_code (int)

  • log_file (str)

  • timing (Timing)

  • files_done (dict[str, dict[str, str]])

  • files_in (dict[str, dict[str, str]])

  • files_out (dict[str, dict[str, str]])

  • files_summary (dict[str, dict[str, str]])

  • skipped (bool)

name: str = None

The name of the Step that ran.

image_id: str = None

The unique id of the Step.image that was used.

This image_id is always a unique id (like the IMAGE ID output of docker images), even if the step’s Step.image was given as a human-readable tag. This avoids ambiguitiy from mutable tags like :latest.

exit_code: int = None

The exit code / status code of the step’s container process.

Exit code 0 is interpreted as success, nonzero as failure.

log_file: str = None

The host path to the log file with step console output (stdout and stderr).

timing: Timing = None

Start datetime, finish datetime, and duration for the step’s container process.

files_done: dict[str, dict[str, str]]

Files that matched the Step.match_done pattern.

This is a key-value mapping from host Step.volumes paths to matched files. The keys are strings (host volume paths). The values are nested key-value mappings, where the keys are matched file paths within a volume and the values are content hash digests of the matched files.

step_results:
  - name: files done example
    files_done:
      /host/volume: {done_file.txt: 'sha256:5f386141...'}
    skipped: true

When files_done is nonempty the Step is considered to be already complete before running, and skipped should be True.

files_in: dict[str, dict[str, str]]

Files that matched the Step.match_in pattern.

This is a key-value mapping from host Step.volumes paths to matched files. The keys are strings (host volume paths). The values are nested key-value mappings, where the keys are matched file paths within a volume and the values are content hash digests of the matched files.

step_results:
  - name: files in example
    files_in:
      /host/volume/a: {first_match.txt: 'sha256:93d4e5c7...', second_match.txt: 'sha256:d1b54ec5...'}
      /host/volume/b: {third_match.txt: 'sha256:a4619a89...'}

Unlike files_done, files_in does not affect step execution. files_in is intended to support auditing for reproducibility and comparisons to files used in other steps or pipeline executions.

files_out: dict[str, dict[str, str]]

Files that matched the Step.match_out pattern.

This is a key-value mapping from host Step.volumes paths to matched files. The keys are strings (host volume paths). The values are nested key-value mappings, where the keys are matched file paths within a volume and the values are content hash digests of the matched files.

step_results:
  - name: files out example
    files_out:
      /host/volume/a: {first_match.txt: 'sha256:93d4e5c7...', second_match.txt: 'sha256:d1b54ec5...'}
      /host/volume/b: {third_match.txt: 'sha256:a4619a89...'}

Unlike files_done, files_out does not affect step execution. files_out is intended to support auditing for reproducibility and comparisons to files used in other steps or pipeline executions.

files_summary: dict[str, dict[str, str]]

Files that matched the Step.match_summary pattern, to include when summarizing results.

This is a key-value mapping from host Step.volumes paths to matched files. The keys are strings (host volume paths). The values are nested key-value mappings, where the keys are matched file paths within a volume and the values are content hash digests of the matched files.

step_results:
  - name: files summary example
    files_summary:
      /host/volume/a: {first_match.txt: 'sha256:93d4e5c7...', second_match.txt: 'sha256:d1b54ec5...'}
      /host/volume/b: {third_match.txt: 'sha256:a4619a89...'}

Unlike files_done, files_summary does not affect step execution. files_summary is intended to enrich pipeline execution summaries with custom columns.

When creating a pipeline execution summary (as with proceed summarize ...) each file from files_summary will be parsed for one or more key-value pairs. Any keys found will be added as columns to the summery document. Values found will be added in corresponding columns and rows for the the same step. The parsing works as follows:

YAML Matching YAML files will be parsed for top-level key-value mappings. Keys and values will be taken from within the YAML document.

Other Other matching files will be teated as plaintext. The file name will be taken as one key, and the file text content be taken as the corresponding value.

skipped: bool = False

Whether a step was skipped (True) or actually executed (False).

step_results:
  - name: step skipped example
    skipped: true
    files_done:
      /host/volume: {done_file.txt: 'sha256:5f386141...'}

When files_done is nonempty the Step is considered to be already complete before running, and skipped should be True.