Skip to main content

pretty-yaml: Pretty YAML serialization

YAML is generally nice an easy format to read if it was written by humans.

Unfortunately, by default, available serializers seem to not care about that aspect, producing correct but less-readable (and format allows for json-style crap) and poorly-formatted dumps, hence this simple module.

Observe…


Let’s try default PyYAML methods first.

yaml.dump(src, sys.stdout):

destination:
  encoding:
    xz: {enabled: true, min_size: 5120, options: null, path_filter: null}
  result: {append_to_file: null, append_to_lafs_dir: null, print_to_stdout: true}
  url: http://localhost:3456/uri
filter: ["\u0414\u043B\u0438\u043D\u043D\u044B\u0439 \u0441\u0442\u0440\u0438\u043D\
    \u0433 \u043D\u0430 \u0440\u0443\u0441\u0441\u043A\u043E\u043C", "\u0415\u0449\
    \u0435 \u043E\u0434\u043D\u0430 \u0434\u043B\u0438\u043D\u043D\u0430\u044F \u0441\
    \u0442\u0440\u043E\u043A\u0430"]

Quite similar to JSON (a subset of YAML, actually).

yaml.dump(src, sys.stdout, default_flow_style=False):

destination:
  encoding:
    xz:
      enabled: true
      min_size: 5120
      options: null
      path_filter: null
  result:
    append_to_file: null
    append_to_lafs_dir: null
    print_to_stdout: true
  url: http://localhost:3456/uri
filter:
- "\u0414\u043B\u0438\u043D\u043D\u044B\u0439 \u0441\u0442\u0440\u0438\u043D\u0433\
  \ \u043D\u0430 \u0440\u0443\u0441\u0441\u043A\u043E\u043C"
- "\u0415\u0449\u0435 \u043E\u0434\u043D\u0430 \u0434\u043B\u0438\u043D\u043D\u0430\
  \u044F \u0441\u0442\u0440\u043E\u043A\u0430"

Better, but why all the “null” stuff if yaml allows to have just empty values? Why make all non-ascii strings completely unreadable like that if pretty much every parser reads utf-8 or whatever unicode-string object by default?

pyaml.dump(src, sys.stdout):

destination:
  encoding:
    xz:
      enabled: true
      min_size: 5120
      options:
      path_filter:
  result:
    append_to_file:
    append_to_lafs_dir:
    print_to_stdout: true
  url: http://localhost:3456/uri
filter:
  - 'Длинный стринг на русском'
  - 'Еще одна длинная строка'

Note, yaml.load will read that to the same thing as the above dumps, but now you can read that as well.


Another example.

Let’s say you have a parsed URL like this:

# -*- coding: utf-8 -*-
url = dict(
  path='/some/path',
  query_dump=OrderedDict([
    ('key1', 'тест1'),
    ('key2', 'тест2'),
    ('key3', 'тест3'),
    ('последний', None) ]) )

Order of keys in query matters because there might be a hundred of them and you’d like the output to be diff-friendly.

yaml.dump(url, sys.stdout):

path: !!python/unicode '/some/path'
query_dump: !!python/object/apply:collections.OrderedDict
- - [!!python/unicode 'key1', "\u0442\u0435\u0441\u04421"]
  - [!!python/unicode 'key2', "\u0442\u0435\u0441\u04422"]
  - [!!python/unicode 'key3', "\u0442\u0435\u0441\u04423"]
  - ["\u043F\u043E\u0441\u043B\u0435\u0434\u043D\u0438\u0439", null]

Ugh…

yaml.safe_dump(url, sys.stdout):

yaml.representer.RepresenterError: cannot represent an object: OrderedDict(...

Right… let’s try something designed to be pretty here:

>>> from pprint import pprint
>>> pprint(url)
{'path': u'/some/path',
 'query_dump': OrderedDict([(u'key1', u'\u0442\u0435\u0441\u04421'), (u'key2', u'\u0442\u0435\u0441\u04422'), (u'key3', u'\u0442\u0435\u0441\u04423'), (u'\u043f\u043e\u0441\u043b\u0435\u0434\u043d\u0438\u0439', None)])}

YUCK!

pyaml.dump(url, sys.stdout):

path: /some/path
query_dump:
  key1: тест1
  key2: тест2
  key3: тест3
  последний:

Much easier to read than… anything else! Diff-friendly.


Have a long config which will produce a wall-of-text even with indentation? No problem!

pyaml.dump(src, sys.stdout, vspacing=[2, 1]):

destination:

  encoding:
    xz:
      enabled: true
      min_size: 5120
      options:
      path_filter:
        - \.(gz|bz2|t[gb]z2?|xz|lzma|7z|zip|rar)$
        - \.(rpm|deb|iso)$
        - \.(jpe?g|gif|png|mov|avi|ogg|mkv|webm|mp[34g]|flv|flac|ape|pdf|djvu)$
        - \.(sqlite3?|fossil|fsl)$
        - \.git/objects/[0-9a-f]+/[0-9a-f]+$

  result:
    append_to_file:
    append_to_lafs_dir:
    print_to_stdout: true

  url: http://localhost:3456/uri


filter:
  - /(CVS|RCS|SCCS|_darcs|\{arch\})/$
  - /\.(git|hg|bzr|svn|cvs)(/|ignore|attributes|tags)?$
  - /=(RELEASE-ID|meta-update|update)$


http:

  ca_certs_files: /etc/ssl/certs/ca-certificates.crt

  debug_requests: false

  request_pool_options:
    cachedConnectionTimeout: 600
    maxPersistentPerHost: 10
    retryAutomatically: true


logging:

  formatters:
    basic:
      datefmt: '%Y-%m-%d %H:%M:%S'
      format: '%(asctime)s :: %(name)s :: %(levelname)s: %(message)s'

  handlers:
    console:
      class: logging.StreamHandler
      formatter: basic
      level: custom
      stream: ext://sys.stderr

  loggers:
    twisted:
      handlers:
        - console
      level: 0

  root:
    handlers:
      - console
    level: custom

Hopefully, the why should be obvious now.

Among other features - proper readable (and working) object deduplication links by the grace of unidecode module transliteration and an option (“force_embed” keyword) to disable deduplication (imagine reading through dump riddled with such “jump there” links - none of that!).

Obligatory warning

Note that prime concern for this module is to chew simple stuff gracefully, and internally there are some nasty hacks (that I’m not proud of) are used to do it, which may not work with more complex serialization cases, possibly even producing non-deserializable (but fixable) output.

Again, prime goal is not to serialize, say, gigabytes of complex document-storage db contents, but rather individual simple human-parseable documents, please keep that in mind (and of course, patches for hacks are welcome!).

Installation

It’s a regular package for Python 2.7 (not 3.X).

Using pip is the best way:

% pip install pyaml

If you don’t have it, use:

% easy_install pip
% pip install pyaml

Alternatively (see also):

% curl https://raw.github.com/pypa/pip/master/contrib/get-pip.py | python
% pip install pyaml

Or, if you absolutely must:

% easy_install pyaml

But, you really shouldn’t do that.

Current-git version can be installed like this:

% pip install 'git+https://github.com/mk-fg/pretty-yaml.git#egg=pyaml'

Module uses PyYAML for processing of the actual YAML files and should pull it in as a dependency.

Dependency on unidecode module is optional and should only be necessary if same-id objects or recursion is used within serialized data.

Metadata

Release files for pyaml 14.05.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyaml 14.05.7
File Size Uploaded Provenance Actions
pyaml-14.05.7.tar.gz 7.4 kB Without provenance Details for pyaml-14.05.7.tar.gz

Release files / pyaml-14.05.7.tar.gz

Download URL pyaml-14.05.7.tar.gz
Size 7.4 kB
Tags Source
SHA-256 checksum
How to use checksums
8c1edf635edc0658d9f6cd222f175e35aecaaef1cad432b188206b71a9cdbd30
BLAKE2b-256 checksum
How to use checksums
4c7fcf86f472b7f746b71879d8a64daa43a5f4975e84cf64c68bae695785fca7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Security for pyaml 14.05.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

14.05.7 This release

1 release file No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page