Skip to main content

ruamel.yaml

Starting with 0.10.7 the package has been reorganised and the command line utility is in its own package ruamel.yaml.cmd (so installing ruamel.yaml doesn’t pull in possibly irrelevant modules only used in the command line utility)

ruamel.yaml is a YAML package for Python. It is a derivative of Kirill Simonov’s PyYAML 3.11 which supports YAML1.1

Major differences with PyYAML 3.11:

  • integrated Python 2 and 3 sources, running on Python 2.6, 2.7 (CPython, PyPy), 3.3 and 3.4.

  • round trip mode that includes comments (block mode, key ordering kept)

  • support for simple lists as mapping keys by transforming these to tuples

  • !!omap generates ordereddict (C) on Python 2, collections.OrderedDict on Python 3, and !!omap is generated for these types.

  • some YAML 1.2 enhancements (0o octal prefix, \/ escape)

  • pep8 compliance

  • tox and py.test based testing

  • Tests whether the C yaml library is installed as well as the header files. That library doesn’t generate CommentTokens, so it cannot be used to do round trip editing on comments. It can be used to speed up normal processing (so you don’t need to install ruamel.yaml and PyYaml). See the section Optional requirements.

  • Basic support for multiline strings with preserved newlines and chomping ( ‘|’, ‘|+’, ‘|-’ ). As this subclasses the string type the information is lost on reassignment. (This might be changed in the future so that the preservation/folding/chomping is part of the parent container, like comments).

  • RoundTrip preservation of flow style sequences ( ‘a: b, c, d’) (based on request and test by Anthony Sottile)

  • anchors names that are hand-crafted (not of the form``idNNN``) are preserved

  • merges in dictionaries are preserved

  • adding/replacing comments on block-style sequences and mappings with smart column positioning

  • collection objects (when read in via RoundTripParser) have an lc property that contains line and column info lc.line and lc.col. Individual positions for mappings and sequences can also be retrieved (lc.key('a'), lc.value('a') resp. lc.item(3))

  • preservation of whitelines after block scalars. Contributed by Sam Thursfield.

Round trip including comments

The major motivation for this fork is the round-trip capability for comments. The integration of the sources was just an initial step to make this easier.

adding/replacing comments

Starting with version 0.8, you can add/replace comments on block style collections (mappings/sequences resuting in Python dict/list). The basic for for this is:

from __future__ import print_function

import ruamel.yaml

inp = """\
abc:
  - a     # comment 1
xyz:
  a: 1    # comment 2
  b: 2
  c: 3
  d: 4
  e: 5
  f: 6 # comment 3
"""

data = ruamel.yaml.load(inp, ruamel.yaml.RoundTripLoader)
data['abc'].append('b')
data['abc'].yaml_add_eol_comment('comment 4', 1)  # takes column of comment 1
data['xyz'].yaml_add_eol_comment('comment 5', 'c')  # takes column of comment 2
data['xyz'].yaml_add_eol_comment('comment 6', 'e')  # takes column of comment 3
data['xyz'].yaml_add_eol_comment('comment 7', 'd', column=20)

print(ruamel.yaml.dump(data, Dumper=ruamel.yaml.RoundTripDumper), end='')

Resulting in:

abc:
- a       # comment 1
- b       # comment 4
xyz:
  a: 1    # comment 2
  b: 2
  c: 3    # comment 5
  d: 4              # comment 7
  e: 5 # comment 6
  f: 6 # comment 3

If the comment doesn’t start with ‘#’, this will be added. The key is the element index for list, the actual key for dictionaries. As can be seen from the example, the column to choose for a comment is derived from the previous, next or preceding comment column (picking the first one found).

Config file formats

There are only a few configuration file formats that are easily readable and editable: JSON, INI/ConfigParser, YAML (XML is to cluttered to be called easily readable).

Unfortunately JSON doesn’t support comments, and although there are some solutions with pre-processed filtering of comments, there are no libraries that support round trip updating of such commented files.

INI files support comments, and the excellent ConfigObj library by Foord and Larosa even supports round trip editing with comment preservation, nesting of sections and limited lists (within a value). Retrieval of particular value format is explicit (and extensible).

YAML has basic mapping and sequence structures as well as support for ordered mappings and sets. It supports scalars various types including dates and datetimes (missing in JSON). YAML has comments, but these are normally thrown away.

Block structured YAML is a clean and very human readable format. By extending the Python YAML parser to support round trip preservation of comments, it makes YAML a very good choice for configuration files that are human readable and editable while at the same time interpretable and modifiable by a program.

Extending

There are normally six files involved when extending the roundtrip capabilities: the reader, parser, composer and constructor to go from YAML to Python and the resolver, representer, serializer and emitter to go the other way.

Extending involves keeping extra data around for the next process step, eventuallly resulting in a different Python object (subclass or alternative), that should behave like the original, but on the way from Python to YAML generates the original (or at least something much closer).

Smartening

When you use round-tripping, then the complex data you get are already subclasses of the built-in types. So you can patch in extra methods or override existing ones. Some methods are already included and you can do:

yaml_str = """\
a:
- b:
  c: 42
- d:
    f: 196
  e:
    g: 3.14
"""


data = yaml.load(yaml_str, Loader=yaml.RoundTripLoader)

assert data.mlget(['a', 1, 'd', 'f'], list_ok=True) == 196

Examples

Basic round trip of parsing YAML to Python objects, modifying and generating YAML:

from __future__ import print_function

import ruamel.yaml

inp = """\
# example
name:
  # details
  family: Smith   # very common
  given: Alice    # one of the siblings
"""

code = ruamel.yaml.load(inp, ruamel.yaml.RoundTripLoader)
code['name']['given'] = 'Bob'

print(ruamel.yaml.dump(code, Dumper=ruamel.yaml.RoundTripDumper), end='')

Resulting in

# example
name:
  # details
  family: Smith   # very common
  given: Bob      # one of the siblings

YAML handcrafted anchors and references as well as key merging is preserved. The merged keys can transparently be accessed using [] and .get():

import ruamel.yaml

inp = """\
- &CENTER {x: 1, y: 2}
- &LEFT {x: 0, y: 2}
- &BIG {r: 10}
- &SMALL {r: 1}
# All the following maps are equal:
# Explicit keys
- x: 1
  y: 2
  r: 10
  label: center/big
# Merge one map
- <<: *CENTER
  r: 10
  label: center/big
# Merge multiple maps
- <<: [*CENTER, *BIG]
  label: center/big
# Override
- <<: [*BIG, *LEFT, *SMALL]
  x: 1
  label: center/big
"""

data = ruamel.yaml.load(inp, ruamel.yaml.RoundTripLoader)
assert data[7]['y'] == 2

Optional requirements

If you have the C yaml library and headers installed, as well as the header files for your Python executables then you can use the non-roundtrip but faster C loader and emitter.

On Debian systems you should use:

sudo apt-get install libyaml-dev python-dev python3-dev

you can leave out python3-dev if you don’t use python3

For CentOS (7) based systems you should do:

sudo yum install libyaml-devel python-devel

Testing

Testing is done using tox, which uses virtualenv and pytest.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ruamel.yaml-0.10.20.tar.gz (228.2 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

ruamel.yaml-0.10.20-cp35-none-win_amd64.whl (71.1 kB view details)

Uploaded CPython 3.5Windows x86-64

ruamel.yaml-0.10.20-cp35-none-win32.whl (71.1 kB view details)

Uploaded CPython 3.5Windows x86

ruamel.yaml-0.10.20-cp34-none-win_amd64.whl (71.1 kB view details)

Uploaded CPython 3.4Windows x86-64

ruamel.yaml-0.10.20-cp34-none-win32.whl (71.1 kB view details)

Uploaded CPython 3.4Windows x86

ruamel.yaml-0.10.20-cp33-none-win_amd64.whl (71.1 kB view details)

Uploaded CPython 3.3Windows x86-64

ruamel.yaml-0.10.20-cp33-none-win32.whl (71.1 kB view details)

Uploaded CPython 3.3Windows x86

ruamel.yaml-0.10.20-cp27-none-win_amd64.whl (71.2 kB view details)

Uploaded CPython 2.7Windows x86-64

ruamel.yaml-0.10.20-cp27-none-win32.whl (71.2 kB view details)

Uploaded CPython 2.7Windows x86

ruamel.yaml-0.10.20-cp26-none-win_amd64.whl (71.2 kB view details)

Uploaded CPython 2.6Windows x86-64

ruamel.yaml-0.10.20-cp26-none-win32.whl (71.2 kB view details)

Uploaded CPython 2.6Windows x86

File details

Details for the file ruamel.yaml-0.10.20.tar.gz.

File metadata

  • Download URL: ruamel.yaml-0.10.20.tar.gz
  • Upload date:
  • Size: 228.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for ruamel.yaml-0.10.20.tar.gz
Algorithm Hash digest
SHA256 d14990b19ffebec3f05a26d9c1fdc9bfb427175a6c7042b11b7ffc13dfecb2a1
MD5 d6e8599348b7c54aa64868b5403076e5
BLAKE2b-256 1ad1e745c09b1a800ba455bf057553ae389f7139c4d182da30654bb5feb1b303

See more details on using hashes here.

File details

Details for the file ruamel.yaml-0.10.20-cp35-none-win_amd64.whl.

File metadata

File hashes

Hashes for ruamel.yaml-0.10.20-cp35-none-win_amd64.whl
Algorithm Hash digest
SHA256 2caefd52aa11306aafdb1fa75db6d3c84aedbdb7ab7d0e5e585967cb057e9ef8
MD5 88f2f6b517d4178cba75698fccea1e64
BLAKE2b-256 e1707edd6af5819f513d2d7577852f71ecc568f26a0fd646623a3b2abdd1e7b4

See more details on using hashes here.

File details

Details for the file ruamel.yaml-0.10.20-cp35-none-win32.whl.

File metadata

File hashes

Hashes for ruamel.yaml-0.10.20-cp35-none-win32.whl
Algorithm Hash digest
SHA256 1a14aa35111180189b4310ec47a59bd94b935345349b22e9775a5a80d7a32c90
MD5 d5b1f5c90c4be748348e802c20c3e56b
BLAKE2b-256 f20da4173ff72c6db08aa92d6afcb02d15be47d77f003b82ba19cadb138d2b59

See more details on using hashes here.

File details

Details for the file ruamel.yaml-0.10.20-cp34-none-win_amd64.whl.

File metadata

File hashes

Hashes for ruamel.yaml-0.10.20-cp34-none-win_amd64.whl
Algorithm Hash digest
SHA256 8998b188d3bbe7492f739c5b83efafbc3b54370b7af5c3390f5741c240830c87
MD5 dde1ffc1bcf287297f3509c7c324bcf1
BLAKE2b-256 1a43234c03f85eb1081d3f60e30db9cdb2aebbcbf9fe3233ad8971c4f99ee927

See more details on using hashes here.

File details

Details for the file ruamel.yaml-0.10.20-cp34-none-win32.whl.

File metadata

File hashes

Hashes for ruamel.yaml-0.10.20-cp34-none-win32.whl
Algorithm Hash digest
SHA256 6768105f24be349a93007f57a3f3eec7c58cc98faa886d34dd2bcf2078f99d24
MD5 d23ad338ff208ad2fb5e25bf11e5331f
BLAKE2b-256 bd411eda7829f8a58e0095f5a9ea47fc42e7a2351bda4841ee191aff003bb136

See more details on using hashes here.

File details

Details for the file ruamel.yaml-0.10.20-cp33-none-win_amd64.whl.

File metadata

File hashes

Hashes for ruamel.yaml-0.10.20-cp33-none-win_amd64.whl
Algorithm Hash digest
SHA256 c9198479b06be32711595b876d763542b53212098b217ec42d35793885719aca
MD5 7dcf0180bd8388e148ff50f5855bf1b1
BLAKE2b-256 a18dfccd8baa1e2ec27f3dd00b19a76434a634c30f283e37e24527db8bb91c4d

See more details on using hashes here.

File details

Details for the file ruamel.yaml-0.10.20-cp33-none-win32.whl.

File metadata

File hashes

Hashes for ruamel.yaml-0.10.20-cp33-none-win32.whl
Algorithm Hash digest
SHA256 c9a9e84e95c3d83f2e316c221ef7dbce7e290b08729f158af335779890227982
MD5 4b4db60c2d4dc6ebf4a1b4bbfa183160
BLAKE2b-256 caf2b0b374cf325b7c62b351bec45bd21c6bf5c28faccea16cc7fcb73e0c36b3

See more details on using hashes here.

File details

Details for the file ruamel.yaml-0.10.20-cp27-none-win_amd64.whl.

File metadata

File hashes

Hashes for ruamel.yaml-0.10.20-cp27-none-win_amd64.whl
Algorithm Hash digest
SHA256 b9fc38259f44b8854bdec996fda5a4aaf278b52cf4d910dfb115096351feb685
MD5 1b65d4db43bbd3bb0520fdd4e453b758
BLAKE2b-256 dc561f5c6ffd1f9602b3c85a703e94ef23768f55003e3113ca68bdea50404d8b

See more details on using hashes here.

File details

Details for the file ruamel.yaml-0.10.20-cp27-none-win32.whl.

File metadata

File hashes

Hashes for ruamel.yaml-0.10.20-cp27-none-win32.whl
Algorithm Hash digest
SHA256 234a4fe1d54c7eb32d2a914f59ece3d73e51668651fe2db237a1b96ee799479f
MD5 35b1ce9e4de2e1d5cbe740ec87184b87
BLAKE2b-256 4064eee2e63c40c20ccb19fe5d993fbc26e02121d0bb488fc8cf9b174960c638

See more details on using hashes here.

File details

Details for the file ruamel.yaml-0.10.20-cp26-none-win_amd64.whl.

File metadata

File hashes

Hashes for ruamel.yaml-0.10.20-cp26-none-win_amd64.whl
Algorithm Hash digest
SHA256 4ea23c57591a0be9d1bf05d019772b78698807e531daeeecd60681a19d59ac78
MD5 8755f58edfee3bdf57a9db4934fa8b25
BLAKE2b-256 0f9bd3c96bf6f8d51f25c879357bd6f1afbb60704530eefbc572cdb565fd9ffc

See more details on using hashes here.

File details

Details for the file ruamel.yaml-0.10.20-cp26-none-win32.whl.

File metadata

File hashes

Hashes for ruamel.yaml-0.10.20-cp26-none-win32.whl
Algorithm Hash digest
SHA256 026a1067404ca0bb76338345da59b3fbde53003c497d03b47ef7286cecd0395a
MD5 b382221462b6338d3420e3151d010931
BLAKE2b-256 753a9114fa434e4cab49af035d8d8cb0b6a8c8f4579d4c065925cd6aa784a135

See more details on using hashes here.

Release history Release notifications | RSS feed

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page