diff options
Diffstat (limited to '_doc/basicuse.rst')
-rw-r--r-- | _doc/basicuse.rst | 56 |
1 files changed, 56 insertions, 0 deletions
diff --git a/_doc/basicuse.rst b/_doc/basicuse.rst new file mode 100644 index 0000000..935e83a --- /dev/null +++ b/_doc/basicuse.rst @@ -0,0 +1,56 @@ +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. + +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, a ``pathlib.Path()`` or ``None`` (the default, which causes the +YAML documented to be returned as a string. + +*If you have `yaml.dump()` +return the YAML doc as string, do not just ``print`` that returned +value*. In that case use `yaml.dump(data, sys.stdout)`, which is more +efficient (and shows that you know what you are doing). + +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""") |