diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-14 20:19:53 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-14 20:19:53 +0000 |
commit | e7ee850d46d54789979bf0c5244bae1825fb7149 (patch) | |
tree | 6e94ed55df9ec749682a3c792ce752d07892b968 /_doc/basicuse.rst | |
parent | Initial commit. (diff) | |
download | python-ruyaml-e7ee850d46d54789979bf0c5244bae1825fb7149.tar.xz python-ruyaml-e7ee850d46d54789979bf0c5244bae1825fb7149.zip |
Adding upstream version 0.91.0.upstream/0.91.0upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '_doc/basicuse.rst')
-rw-r--r-- | _doc/basicuse.rst | 55 |
1 files changed, 55 insertions, 0 deletions
diff --git a/_doc/basicuse.rst b/_doc/basicuse.rst new file mode 100644 index 0000000..5b4f9a8 --- /dev/null +++ b/_doc/basicuse.rst @@ -0,0 +1,55 @@ +*********** +Basic Usage +*********** + +You load a YAML document using:: + + from ruyaml import YAML + + yaml=YAML(typ='safe') # default, if not specfied, is 'rt' (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 unknown tags. Provide ``pure=True`` to +enforce using the pure Python implementation, otherwise the faster C libraries will be used +when possible/available but these behave slightly different (and sometimes more like a YAML 1.1 loader). + +Dumping works in the same way:: + + from ruyaml 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 ruyaml 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 ruyaml import YAML + + yaml=YAML(typ="safe", pure=True) + yaml.load("""a:\n b: 2\n c: 3\n""") |