pyrosm.recipes.run

pyrosm.recipes.run(path, out_dir=None, force=False)

Run a recipe and write its outputs and provenance record; returns their paths.

The outputs are written into out_dir (default: the recipe’s folder) under the names the recipe gives them. They are made in a staging folder and moved into place only when every stage has succeeded, so a failed stage leaves the previous outputs and record as they were; a run interrupted while moving them leaves no record. A lock file .<record name>.lock keeps two runs of a recipe from writing at once, and a run is refused when an input file changes while it runs, or when an input or the extract differs from a sha256 or snapshot pin of the recipe.

A stage whose recipe section, reader keywords, output names, inputs and package versions are those of the previous run, and whose outputs are in place unchanged, is not run again: its outputs and its part of the record are kept. An extract stage with update: true always runs.

The provenance record (JSON) holds the package versions, the resolved recipe, the SHA-256 of each input and output, where the extract came from, how the run was invoked and when.

Parameters:

• path (str | pathlib.Path) – The recipe YAML file.

• out_dir (str | pathlib.Path, optional) – The output folder, created when missing.

• force (bool) – Run every stage, whether or not it changed, and download the extract again.

Returns:

The paths of the outputs, written or reused, in the recipe’s order, and the provenance record last.

Return type:

list of pathlib.Path