| 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).
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, 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.
* 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 simplier 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)
cert: '-----BEGIN CERTIFICATE-----
MIIH3jCCBcagAwIBAgIJAJi7AjQ4Z87OMA0GCSqGSIb3DQEBCwUAMIHBMRcwFQYD
VQQKFA52YWxlcm9uLm5vX2lzcDEeMBwGA1UECxMVQ2VydGlmaWNhdGUgQXV0aG9y
...
|