1. pypyr
  2. docs
  3. steps
  4. fetchtoml

pypyr.steps.fetchtoml permalink

load & parse toml permalink

Parse a toml fie and load it into the pypyr context.

This step requires the following key in the pypyr context:

- name: pypyr.steps.fetchtoml
  comment: fetch toml from path and store result in key.
  in:
    fetchToml:
      path: ./path.toml # required. path to file on disk. can be relative.
      key: destinationKey # optional. write toml to this context key.

If you do not specify key, the toml structure writes directly to context root.

If you do not want to specify a key, you can instead use the streamlined input format to save yourself some typing:

- name: pypyr.steps.fetchtoml
  comment: simplified input with only path
  in:
    fetchToml: ./path.toml # required. path to file on disk. can be relative.

All inputs support substitutions.

You can set variables from pyproject.toml directly, without needing to use the fetchtoml step to import it manually.

example permalink

Given a toml file like this, saved as ./sample-files/sample.toml:

#this is a toml example
echoMe = "this is a value from a toml file"
key1 = "value1"
key2 = "value2"
keyBool = true
keyInt = 123

[mytable]
mytablekey = "{key1} and {key2} and {key3}"

And given a pipeline like this, arbitrarily saved as ./fetch-toml.yaml:

# ./fetch-toml.yaml
steps:
  - name: pypyr.steps.fetchtoml
    comment: fetch toml from path
    in:
      fetchToml:
        path: ./testfiles/sample.toml

  # echoMe is set in the toml input file
  - pypyr.steps.echo

  - name: pypyr.steps.set
    comment: use the int from toml as a strongly typed int
    in:
      set:
        intResult: !py keyInt * 2
        key3: value3
  
  - name: pypyr.steps.echo
    comment: print out result of int calculation
    in:
      echoMe: "strongly typed happens automatically: {intResult}"

  - name: pypyr.steps.echo
    comment: access a key in a table
             formatting expressions in toml string will work
    in:
      echoMe: "{mytable[mytablekey]}"
    
  - name: pypyr.steps.echo
    comment: only run if input bool is true
    run: '{keyBool}'
    in:
      echoMe: you'll only see me if the bool was true

You can run this pipeline as follows:

term
$ pypyr fetch-toml
this is a value from a toml file
strongly typed happens automatically: 246
value1 and value2 and value3
you'll only see me if the bool was true

Notice that mytable.mytablekey uses pypyr {substitution} expressions where key1 and key2 are set in the toml file itself, and key3 is set in the pypyr pipeline with pypyr.steps.set.

If you change the keyBool bool to false in the toml input file, the last step won’t run anymore because the run condition is False.

term
$ pypyr fetch-toml
this is a value from a toml file
value3 and value1 and value2
strongly typed happens automatically: 246

substitutions permalink

You can use substitutions on all the step’s inputs:

- name: pypyr.steps.set
  comment: use set to set arbitrary values for path & key referenced
           by the fetch toml step. 
  in:
    set:
      filename: 'sample'
      keyname: 'savemehere'

- name: pypyr.steps.fetchtoml
  description: fetch toml into key with path substitutions
  in:
    fetchToml:
      path: ./testfiles/{filename}.toml
      key: '{keyname}'

toml structure merging permalink

pypyr will merge the toml parsed from the file into the pypyr context. This will overwrite existing values if the same keys already exist in context.

I.e if file toml has

eggs = "boiled"

And in context the following already exists:

{
  "eggs": "raw"
}

After fetchtoml the value of key ’eggs’ will be ‘boiled’.

encoding permalink

A TOML file must always be in utf-8, per the TOML Spec.

see also

last updated on .