MetOffice / MetOffice/CMEW

Consider a best practice YAML output `flow_style`

Open
#224 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement question testing
Dominant language
Python
Stars
5
Forks
3
Avg merge
5d 6h
Merged PRs (30d)
8

Description

**Is your feature request related to a problem? Please describe.**

As explored during #18, by default PyYAML varies the chosen output form style:

> By default, PyYAML chooses the style of a collection depending on whether it has nested collections. If a collection has nested collections, it will be assigned the block style. Otherwise it will have the flow style.
>
> If you want collections to be always serialized in the block style, set the parameter default_flow_style of dump() to False. For instance,
>
>\>> print yaml.dump(yaml.load(document), default_flow_style=False)
>
> Source: [PyYaml Documentation](https://pyyaml.org/wiki/PyYAMLDocumentation)

The unpredictability of this default behaviour may make outputs harder to test.

**Describe the solution you'd like**

The working practices should be updated to recommend `yaml.dump` have `default_flow_style=False` passed. An issue could also be raised to make this uniform across the current code.

**Describe alternatives you've considered**

It's possible that `default_flow_style=True` defaults to always using a `flow` style of output. This didn't seem clear from the docs and wasn't tested thoroughly. But if the `flow` style is preferred this may be an approach. (See example of output below).

**Additional context**

YAML is written in with either the `flow` style or the `block` style.

Example: `flow` style:

```yml
{glossary: {GlossDiv: {GlossList: {GlossEntry: {Abbrev: 'ISO 8879:1986', Acronym: SGML,
GlossDef: {GlossSeeAlso: [GML, XML], para: 'A meta-markup language, used
to create markup languages such as DocBook.'}, GlossSee: markup, GlossTerm: Standard
Generalized Markup Language, ID: SGML, SortAs: SGML}}, title: S}, title: example
glossary}}
```

Example: `block` style

```yml
glossary:
GlossDiv:
GlossList:
GlossEntry:
Abbrev: ISO 8879:1986
Acronym: SGML
GlossDef:
GlossSeeAlso:
- GML
- XML
para: A meta-markup language, used to create markup languages such as DocBook.
GlossSee: markup
GlossTerm: Standard Generalized Markup Language
ID: SGML
SortAs: SGML
title: S
title: example glossary
```

Note also that the default behaviour seems to mix and match `flow` and `block` as in this section of default output:

```yml
Acronym: SGML
GlossDef:
GlossSeeAlso: [GML, XML]
para: A meta-markup language, used to create markup languages such as DocBook.
GlossSee: markup
```

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No repository file is named. Find the working-practices documentation and review issue #18 alongside the PyYAML documentation linked here; update the guidance to recommend passing default_flow_style=False to yaml.dump, with the completed guidance making the preferred YAML output style explicit.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.