When saving objects to YAML, use templates instead of yaml.dump()

During the write, if we just dump object data to files, we can’t really control how YAML is presented. It would not matter when we deserialize it back programmatically, but it would matter to a human, or for Git diff purposes.

The idea is to read objects from YAML the normal way (yaml.load()), but write YAML using a template string. (After the write, we can load back YAML as a safety check—if it throws, then it’s probably indentation somewhere in the template string.) Since we are not dealing with arbitrary objects, we know the properties of each type, this is viable.

While at that we can also format non-string keys the way we want (e.g., for readability we don’t want the default yaml.dump() behavior of including full timestamps with timezones on things like issue publication dates).

For example, here’s what happens if we update publication date on an already existing issue.

Dates are output as full timestamps with timezone
Formatting is changed (it got rid of whitespace, inline object syntax, multiline string syntax)
Interestingly, the order of keys doesn’t change (but we shouldn’t rely on this!)
That boolean yes are converted to string 'yes' is the issue at the loading stage, so we can ignore that

Previously existing (human-written) YAML loaded:

id: 1173
publication_date: 2019-06-01
cutoff_date: 2019-05-15
issn: 1564-5223

languages:
  en: yes
  ru: yes
  zh: yes

authors:
  - address: >-
      Place des Nations CH-1211
      Genève 20 (Switzerland)
    contacts:
      - { type: phone, data: "+41 22 730 5111" }
      - { type: email, data: "itumail@itu.int", recommended: yes }
  - name:
      en: Standardization Bureau (TSB)
      ru: Бюро стандартизации электросвязи (БСЭ)
      zh: 电信标准化局（TSB）
    contacts:
      - { type: phone, data: "+41 22 730 5211", recommended: yes }
      - { type: fax, data: "+41 22 730 5853", recommended: yes }
      - { type: email, data: "tsbmail@itu.int", recommended: yes }
      - { type: email, data: "tsbtson@itu.int", recommended: yes }
  - name:
      en: Radiocommunication Bureau (BR)
      ru: Бюро радиосвязи (БР)
      zh: 无线电通信局（BR）
    contacts:
      - { type: phone, data: "+41 22 730 5560", recommended: yes }
      - { type: fax, data: "+41 22 730 5785", recommended: yes }
      - { type: email, data: "brmail@itu.int", recommended: yes }

planned_issues:
  - id: 1174
    publication_date: 2019-06-15
    cutoff_date: 2019-05-31

Having altered the loaded data structure for above YAML (updating publication/cutoff date), the new YAML dumped:


id: 1173
publication_date: 2019-08-20T00:00:00.000Z
cutoff_date: 2019-08-10T00:00:00.000Z
issn: 1564-5223
languages:
  en: 'yes'
  ru: 'yes'
  zh: 'yes'
authors:
  - address: Place des Nations CH-1211 Genève 20 (Switzerland)
    contacts:
      - type: phone
        data: +41 22 730 5111
      - type: email
        data: itumail@itu.int
        recommended: 'yes'
  - name:
      en: Standardization Bureau (TSB)
      ru: Бюро стандартизации электросвязи (БСЭ)
      zh: 电信标准化局（TSB）
    contacts:
      - type: phone
        data: +41 22 730 5211
        recommended: 'yes'
      - type: fax
        data: +41 22 730 5853
        recommended: 'yes'
      - type: email
        data: tsbmail@itu.int
        recommended: 'yes'
      - type: email
        data: tsbtson@itu.int
        recommended: 'yes'
  - name:
      en: Radiocommunication Bureau (BR)
      ru: Бюро радиосвязи (БР)
      zh: 无线电通信局（BR）
    contacts:
      - type: phone
        data: +41 22 730 5560
        recommended: 'yes'
      - type: fax
        data: +41 22 730 5785
        recommended: 'yes'
      - type: email
        data: brmail@itu.int
        recommended: 'yes'
planned_issues:
  - id: 1174
    publication_date: 2019-06-15T00:00:00.000Z
    cutoff_date: 2019-05-31T00:00:00.000Z

ituob / itu-ob-editor

When saving objects to YAML, use templates instead of yaml.dump() #1