| single |
pretty-yaml (or pyaml)
======================
PyYAML_-based python module to produce a bit more pretty and human-readable
YAML-serialized data.
This module is for serialization only, see `ruamel.yaml`_ module for
literate
YAML parsing (keeping track of comments, spacing, line/column numbers of
values, etc).
(side-note: to dump stuff parsed by ruamel.yaml with this module, use only
``YAML(typ='safe')`` there)
It's a small module, and for projects that only need part of its
functionality,
I'd recommend copy-pasting that in, instead of adding janky dependency.
.. _PyYAML: http://pyyaml.org/
.. _ruamel.yaml: https://bitbucket.org/ruamel/yaml/
.. contents::
:backlinks: none
Repository URLs:
- https://github.com/mk-fg/pretty-yaml
- https://codeberg.org/mk-fg/pretty-yaml
- https://fraggod.net/code/git/pretty-yaml
Warning
-------
Prime goal of this module is to produce human-readable output that can be
easily diff'ed, manipulated and re-used, but maybe with occasional issues.
So please do not rely on the thing to produce output that can always be
deserialized exactly to what was exported, at least - use PyYAML directly
for that (but maybe with options from the next section).
Output also isn't guaranteed to be stable between module versions,
as new representation tweaks get added occasionally, but these can usually
be disabled via module parameters, to get output stability over
improvements.
What this module does and why
-----------------------------
YAML is generally nice and easy format to read *if* it was written by
humans.
PyYAML can a do fairly decent job of making stuff readable, and the best
combination of parameters for such output that I've seen so far is probably
this one::
>>> m = [123, 45.67, {1: None, 2: False}, 'some text']
>>> data = dict(a='asldnsa\nasldpáknsa\n', b='whatever text', ma=m,
mb=m)
>>> yaml.safe_dump( data, sys.stdout,
width=100, allow_unicode=True, default_flow_style=False )
a: 'asldnsa
asldpáknsa
'
b: whatever text
ma: &id001
- 123
- 45.67
- 1: null
2: false
- some text
mb: *id001
pyaml (this module) tries to improve on that a bit, with the following
tweaks:
* Most human-friendly representation options in PyYAML (that I know of)
are used as defaults - unicode, flow-style, width=100 (old default is
80).
* Dump "null" values as empty values, if possible, which have the same
meaning
but reduce visual clutter and are easier to edit.
* Dicts, sets, OrderedDicts, defaultdicts, namedtuples, enums, dataclasses,
etc
are represented as their safe YAML-compatible base (like int, list or
mapping),
with mappings key-sorted by default for more diff-friendly output.
* Use shorter and simpler yes/no for booleans.
* List items get indented, as they should be.
* Attempt is made to pick more readable string representation styles,
depending
on the value, e.g.::
>>> yaml.safe_dump(cert, sys.stdout)
|