summaryrefslogtreecommitdiff
path: root/_doc/basicuse.rst
blob: 56a28d620ab90c6bcbe7331b845ee4f26114b677 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
Basic Usage
===========

*This is the new (0.15+) interface for ``ruamel.yaml``, it is still in
the process of being fleshed out*. Please pin your dependency to
``ruamel.yaml<0.15`` for production software.

------

You load a YAML document using::

   from ruamel.yaml import YAML

   yaml=YAML(typ='safe')   # default if not specfied is round-trip

   yaml.load(doc)

in this ``doc`` can be a file pointer (i.e. an object that has the
`.read()` method, a string or a ``pathlib.Path()``. `typ='safe'`
accomplishes the same as what ``safe_load()`` did before: loading of a
document without resolving unknow tags. Provide  `pure=True` to
enforce using the pure Python implementation (faster C libraries will be used
when possible/available)

Dumping works in the same way::

   from ruamel.yaml import YAML

   yaml=YAML()
   yaml.default_flow_style = False
   yaml.dump({a: [1, 2]}, s)

in this ``s`` can be a file pointer (i.e. an object that has the
`.write()` method, or a ``pathlib.Path()``. If you want to display
your output, just stream to `sys.stdout`.

If you need to transform a string representation of the output provide
a function that takes a string as input and returns one::

   def tr(s):
       return s.replace('\n', '<\n')  # such output is not valid YAML!

   yaml.dump(data, sys.stdout, transform=tr)


More examples
-------------

Using the C based SafeLoader (at this time is inherited from
libyaml/PyYAML and e.g. loads ``0o52`` as well as ``052`` load as integer ``42``)::

   from ruamel.yaml import YAML

   yaml=YAML(typ="safe")
   yaml.load("""a:\n  b: 2\n  c: 3\n""")

Using the Python based SafeLoader (YAML 1.2 support, ``052`` loads as ``52``)::

   from ruamel.yaml import YAML

   yaml=YAML(typ="safe", pure=True)
   yaml.load("""a:\n  b: 2\n  c: 3\n""")