added register_class/yaml_object0.15.19

1 files changed, 78 insertions, 0 deletions

diff --git a/_doc/basicuse.ryd b/_doc/basicuse.ryd
new file mode 100644
index 0000000..7d3ae96
--- /dev/null
+++ b/_doc/basicuse.ryd
@@ -0,0 +1,78 @@
+---
+version: 0.1
+output: rst
+fix_inline_single_backquotes: true
+pdf: true
+--- !python-pre |
+import sys
+from io import StringIO
+from ruamel.yaml import YAML
+yaml=YAML()
+s = StringIO()
+doc = "a: 1"
+data = dict(a=1)
+--- |
+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::
+--- !python |
+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::
+--- !python |
+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::
+
+--- !python |
+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``)::
+
+--- !python |
+   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``)::
+--- !python |
+   from ruamel.yaml import YAML
+
+   yaml=YAML(typ="safe", pure=True)
+   yaml.load("""a:\n  b: 2\n  c: 3\n""")
\ No newline at end of file