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.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.19.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for anthon from gravatar.com anthon

Credits

Author: Anthon van der Neut

License

MIT License (MIT license)

Classifiers

Report project as malware

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.17.tar.gz (227.5 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.17-cp34-none-win_amd64.whl (71.1 kB view details)

Uploaded CPython 3.4Windows x86-64

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

Uploaded CPython 3.4Windows x86

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

Uploaded CPython 3.3Windows x86-64

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

Uploaded CPython 3.3Windows x86

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

Uploaded CPython 2.7Windows x86-64

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

Uploaded CPython 2.7Windows x86

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

Uploaded CPython 2.6Windows x86-64

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

Uploaded CPython 2.6Windows x86

File details

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

File metadata

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

File hashes

Hashes for ruamel.yaml-0.10.17.tar.gz
Algorithm Hash digest
SHA256 97d5d220f105f1a5e59897ad9060e26bf2eb5baa4a39f792996bce73ef678a57
MD5 f80c67c39e9bdb7a2dae5f2d8d5a99bb
BLAKE2b-256 32db8fb4b47b64ad36aa376ccc265472f4149e67a1381d33b3fc43d478921cb2

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for ruamel.yaml-0.10.17-cp34-none-win_amd64.whl
Algorithm Hash digest
SHA256 1781a713fc93a4121e9ad28c6697beb0a4001ca385b141143d9c957d1b17eb82
MD5 1716428e97aa58ce26348e21f6670852
BLAKE2b-256 2cf207574dad504b8aad5f4327d42f51c00566a3eb06981fad4681cec8230506

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for ruamel.yaml-0.10.17-cp34-none-win32.whl
Algorithm Hash digest
SHA256 64e1ff726ebf408dfd5a5fe2c9016460af78249c39db4b4bd7892acd25d8b90a
MD5 80bc20ab3502b50ca825e7ca01fc7984
BLAKE2b-256 29e48a29bc16d3509c397c978ec78f20d07ed567ca72ac05bcfaca4ddcaefeb7

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for ruamel.yaml-0.10.17-cp33-none-win_amd64.whl
Algorithm Hash digest
SHA256 ffb8a477ac6d2830225857804c1beb05ae81e1ed4b08fcbd75bc5a1d827c31e4
MD5 447c24b28824da133a33bf99970a7c33
BLAKE2b-256 7c89d337d8c51d3237dd69a68fec83b1ec22c3a329057fcda9d03ba77c2738c9

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for ruamel.yaml-0.10.17-cp33-none-win32.whl
Algorithm Hash digest
SHA256 96ee92e8e33cc3c7e386a1eafe5e3c18a7b5ad4feb56adb9e77ab25c46fe0e80
MD5 58e46385af9afed57edc25c00f42332f
BLAKE2b-256 7a0a46a3330ce5bcc25a16d33a2d6732ef81fd186b043bdf7ee1cb0e28c14ffa

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for ruamel.yaml-0.10.17-cp27-none-win_amd64.whl
Algorithm Hash digest
SHA256 66fa5ca49d8ee11f9b66d2dfac1dbc6a23008751602f27c640c14eddff101636
MD5 88d6cffc78b64c390ebcfc17faca0692
BLAKE2b-256 b07fefb61e91eccbef38538889ab4ff19a2e29fb96b0aa15c82c9f5ed72c532b

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for ruamel.yaml-0.10.17-cp27-none-win32.whl
Algorithm Hash digest
SHA256 be377a60653f7aa9207cd23853d4c517353475ef8e2bc6592a93484c4daf5d40
MD5 8eb3f0c0fb900b3a399a92aeaa9e87fc
BLAKE2b-256 4fdc335ee3031680e68e33d8b357e4c57a54515d01bb48f68d3d80a0d0c4b907

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for ruamel.yaml-0.10.17-cp26-none-win_amd64.whl
Algorithm Hash digest
SHA256 8ae58cc88082a84607765979e152b85873b45b226af3c7412db7043a1c040029
MD5 f6fc5bfead37d99acb65accab253d156
BLAKE2b-256 05f248b730ccaf18274dbb09786076c519b0da40cd2ad96467282a7714b3941f

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for ruamel.yaml-0.10.17-cp26-none-win32.whl
Algorithm Hash digest
SHA256 52062f5555d30e7ee66f0d16d716a1727544f0e17effea0931e3b51a04236a25
MD5 3d59099a85073d34bfc30c1a37560969
BLAKE2b-256 cc7d2bbefb7aa20e8305ad92afd52f6890d8451c012ee495d02c4a530c6a8e3f

See more details on using hashes here.

Release history Release notifications | RSS feed

0.19.1

0.19.0

0.18.17

0.18.16

0.18.15

0.18.14

0.18.13

0.18.12

0.18.11

0.18.10

0.18.9

0.18.8

0.18.7

0.18.6

0.18.5

0.18.3

0.18.2

0.18.1

0.18.0

0.17.40

0.17.39

0.17.38

0.17.36

0.17.35

0.17.34

0.17.33

0.17.32

0.17.31

0.17.30

0.17.29

0.17.28

0.17.27

0.17.26

0.17.25

0.17.24

0.17.23

0.17.22

0.17.21

0.17.20

0.17.19

0.17.18

0.17.17

0.17.16

0.17.15

0.17.14

0.17.13

0.17.12

0.17.11

0.17.10

0.17.9

0.17.8

0.17.7

0.17.6

0.17.5

0.17.4

0.17.3

0.17.2

0.17.1 yanked

Reason this release was yanked:

would still install for Python 2

0.17.0 yanked

Reason this release was yanked:

would still install for Python 2

0.16.13

0.16.12

0.16.11

0.16.10

0.16.9

0.16.7

0.16.6

0.16.5

0.16.4

0.16.3

0.16.2

0.16.1

0.16.0

0.15.100

0.15.99

0.15.98

0.15.97

0.15.96

0.15.95

0.15.94

0.15.93

0.15.92

0.15.91

0.15.90

0.15.89

0.15.88

0.15.87

0.15.86

0.15.85

0.15.84

0.15.83

0.15.82

0.15.81

0.15.80

0.15.79

0.15.78

0.15.77

0.15.76

0.15.75

0.15.74

0.15.73

0.15.72

0.15.71

0.15.70

0.15.69

0.15.68

0.15.67

0.15.66

0.15.65

0.15.64

0.15.63

0.15.62

0.15.61

0.15.60

0.15.59

0.15.58

0.15.57

0.15.56

0.15.55

0.15.54

0.15.53

0.15.52

0.15.51

0.15.50

0.15.49

0.15.48

0.15.47

0.15.46

0.15.45

0.15.44

0.15.43

0.15.42

0.15.41

0.15.40

0.15.39

0.15.38

0.15.37

0.15.35

0.15.34

0.15.33

0.15.32

0.15.31

0.15.30

0.15.29

0.15.28

0.15.27

0.15.26

0.15.25

0.15.24

0.15.23

0.15.22

0.15.21

0.15.20

0.15.19

0.15.18

0.15.17

0.15.16

0.15.15

0.15.14

0.15.13

0.15.12

0.15.11

0.15.10

0.15.9

0.15.8

0.15.7

0.15.6

0.15.5

0.15.4

0.15.3

0.15.2

0.15.1

0.15.0

0.14.12

0.14.11

0.14.10

0.14.9

0.14.8

0.14.7

0.14.6

0.14.5

0.14.4

0.14.3

0.14.2

0.14.1

0.14.0

0.13.14

0.13.13

0.13.11

0.13.10

0.13.9

0.13.8

0.13.7

0.13.6

0.13.5

0.13.4

0.13.3

0.13.2

0.13.1

0.13.0

0.12.18

0.12.17

0.12.16

0.12.15

0.12.14

0.12.13

0.12.12

0.12.11

0.12.10

0.12.9

0.12.8

0.12.7

0.12.6

0.12.5

0.12.4

0.12.3

0.12.2

0.12.1

0.12.0

0.11.15

0.11.14

0.11.11

0.11.10

0.11.9

0.11.8

0.11.7

0.11.6

0.11.5

0.11.3

0.11.2

0.11.1

0.11.0

0.10.23

0.10.22

0.10.21

0.10.20

0.10.19

0.10.18

This release

0.10.17

0.10.16

0.10.15

0.10.14

0.10.13

0.10.12

0.10.11

0.10.10

0.10.9

0.10.8

0.10.7

0.10.6

0.10.5

0.10.4

0.10.2

0.10.1

0.10

0.9.8

0.9.7

0.9.6

0.9.5

0.9.4

0.9.2

0.9.1

0.8

0.7.2

0.7.1

0.7

0.6.1

0.6

0.5.1

0.5

0.4

0.3

0.2

0.1

Supported by

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