Write and run a procedure

A procedure is a folder that holds one step of your work: reading a file your team uses, fetching data from a system, or turning one kind of data into another. The folder has two parts:

• procedure.json says what the step is called, what it reads, what it makes and which settings it takes, in words a colleague can read.
• Python code, with one function marked @procedure, does the work.

In this release you write, check and run procedures on your own computer. Nothing is published, and no server or account is needed. Sending data to another system and checking data against a reference are described in the same way and are checked already, but running them comes with a later release.

Start a procedure

ophiolite procedures new depth-shift --step process --label "Shift tops by a fixed depth"

This writes depth-shift/procedure.json and depth-shift/procedure.py. The steps are read (a file you have), source (a system you connect to), process (data you already have, into new data), send and check.

Edit procedure.json to name what the step reads and makes, and the settings a person chooses. Every label is words, such as “Depth shift”, not a code name such as depth_shift. Edit procedure.py: the marked function receives the inputs and the settings, and returns each output by name, made with a writer from ophiolite.writers (for example write_tops or write_location).

The SDK ships a complete example. To copy it next to your own:

cp -r "$(python -c 'import ophiolite, pathlib; print(pathlib.Path(ophiolite.__file__).parent / "contracts/procedures/v1/fixtures/bundles/depth-shift")')" example-depth-shift

Check it

ophiolite procedures validate depth-shift

A procedure that follows the rules says, for example, “Valid: Shift tops by a fixed depth, version 1. It reads Well tops (CSV) and makes Well tops (CSV).” One that does not says what to change, for example “Not valid: setting 1 needs a readable label, for example “Depth shift”.” The same rules, in the same words, apply wherever a procedure is checked. Add --json to see the field the sentence refers to and the procedure’s fingerprint (its digest), which changes when any of its files change. Checking never runs or imports your code.

Run it on your computer

ophiolite procedures run depth-shift --output shifted \
  --input tops=tops.csv --kind tops=well-tops-csv/1 --declared tops=tops.declared.json \
  --setting shift=2.5

• --input names the file for each input. Give --kind (the type of data) and --declared (a JSON file with what you know about it, such as the depth unit) for a file of your own. An output of an earlier run already carries both, so --input tops=shifted/shifted.csv is enough.
• --setting gives a setting as name=value. Numbers, whole numbers, true or false and choices are checked against the procedure’s description; a setting you do not give takes its default.
• --system names a local file with a source’s connection settings. They are passed to your code and never written into anything the run keeps.

The run uses a fresh copy of exactly the files that were checked, runs your function in a separate process, and writes a new folder: one file per output, log.txt with anything your code printed, and run.json, which records the procedure’s fingerprint, the settings, each input’s fingerprint and what each output is. The output folder must not exist yet. If anything goes wrong, no output folder is written and the command says what to change; the details are under --json.