Consider a best practice YAML output `flow_style`
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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