update doc examples

2 files changed, 80 insertions, 2 deletions

diff --git a/__init__.py b/__init__.py
index 14cf4e2..64f9a9f 100644
--- a/__init__.py
+++ b/__init__.py
@@ -11,8 +11,8 @@ if False:  # MYPY
 
 _package_data = dict(
     full_package_name='ruamel.yaml',
-    version_info=(0, 15, 0),
-    __version__='0.15.0',
+    version_info=(0, 15, 1, 'dev'),
+    __version__='0.15.1.dev',
     author='Anthon van der Neut',
     author_email='a.van.der.neut@ruamel.eu',
     description='ruamel.yaml is a YAML parser/emitter that supports roundtrip preservation of comments, seq/map flow style, and map key order',  # NOQA
diff --git a/_doc/api.rst b/_doc/api.rst
index 61d74a1..1d4a1ec 100644
--- a/_doc/api.rst
+++ b/_doc/api.rst
@@ -72,6 +72,84 @@ Initially only the typical operations are supported, but in principle
 all functionality of the old interface will be available via
 ``YAML`` instances (if you are using something that isn't let me know).
 
+Transparent usage of new and old API
+------------------------------------
+
+If you have multiple packages depending on ``ruamel.yaml``, or install
+your utility together with other packages not under your control, then
+fixing your ``install_requires`` might not be so easy.
+
+Depending on your usage you might be able to "version" your usage to
+be compatible with both the old and the new. The following are some
+examples all assuming `from ruamel import yaml`` somewhere at the top
+of your file and some ``istream`` and ``ostream`` apropriately opened
+for reading resp.  writing.
+
+
+Loading and dumping using the ``SafeLoader``::
+
+  if yaml.version_info < (0, 15):
+      data = yaml.safe_load(istream)
+      yaml.safe_dump(data, ostream)
+  else:
+      yml = yaml.YAML(typ='safe', pure=True)  # 'safe' load and dump
+      data = yml.load(istream)
+      yml.dump(ostream)
+
+
+Loading with the ``CSafeLoader``, dumping with
+``RoundTripLoader``. You need two ``YAML`` instances, but each of them
+can be re-used ::
+
+  if yaml.version_info < (0, 15):
+      data = yaml.load(istream, Loader=yaml.CSafeLoader)
+      yaml.round_trip_dump(data, ostream, width=1000, explicit_start=True)
+  else:
+      yml = yaml.YAML(typ='safe')
+      data = yml.load(istream)
+      ymlo = yaml.YAML()   # or yaml.YAML(typ='rt')
+      ymlo.width = 1000
+      ymlo.explicit_start = True
+      ymlo.dump(ostream)
+
+
+Loading and dumping from  ``pathlib.Path`` instances using the
+round-trip-loader::
+
+  # in myyaml.py
+  if yaml.version_info < (0, 15):
+      class MyYAML(yaml.YAML):
+          def __init__(self):
+              yaml.YAML.__init__(self)
+              self.preserve_quotes = True
+              self.indent = 4
+              self.block_seq_indent = 2
+
+  try:
+      from myyaml import MyYAML
+  except ImportError:
+      if yaml.version_info >= (0, 15):
+          raise
+
+  # some pathlib.Path
+  from pathlib import Path
+  inf = Path('/tmp/in.yaml')
+  outf = Path('/tmp/out.yaml')
+
+  if yaml.version_info < (0, 15):
+      with inf.open() as ifp:
+           data = yaml.round_trip_load(ifp, preserve_quotes=True)
+      with outf.open('w') as ofp:
+           yaml.round_trip_dump(data, ofp, indent=4, block_seq_indent=2)
+  else:
+      yml = MyYAML()
+      # no need for with statement when using pathlib.Path instances
+      data = yml.load(inf)
+      yml.dump(outf)
+
+
+
+
 Reason for API change
 ---------------------