diff options
Diffstat (limited to '_doc/api.rst')
| -rw-r--r-- | _doc/api.rst | 76 |
1 files changed, 38 insertions, 38 deletions
diff --git a/_doc/api.rst b/_doc/api.rst index f6ff28c..7f34c93 100644 --- a/_doc/api.rst +++ b/_doc/api.rst @@ -1,5 +1,3 @@ - - Departure from previous API --------------------------- @@ -35,23 +33,24 @@ of ``YAML`` before calling ``load()`` or ``dump()`` Before 0.15.0:: - from pathlib import Path - from ruamel import yaml - - data = yaml.safe_load("abc: 1") - out = path('/tmp/out.yaml') - with out.open('w') as fp: - yaml.safe_dump(data, fp, default_flow_style=False) + from pathlib import Path + from ruamel import yaml + + data = yaml.safe_load("abc: 1") + out = Path('/tmp/out.yaml') + with out.open('w') as fp: + yaml.safe_dump(data, fp, default_flow_style=False) after:: - from ruamel.yaml import YAML - - yaml = YAML(typ='safe') - yaml.default_flow_style = False - data = yaml.load("abc: 1") - out = path('/tmp/out.yaml') - yaml.dump(data, out) + from pathlib import Path + from ruamel.yaml import YAML + + yaml = YAML(typ='safe') + yaml.default_flow_style = False + data = yaml.load("abc: 1") + out = Path('/tmp/out.yaml') + yaml.dump(data, out) If you previously used an keyword argument ``explicit_start=True`` you now do ``yaml.explicit_start = True`` before calling ``dump()``. The @@ -63,6 +62,12 @@ is possible by setting the attributes ``.Parser``, ``.Constructor``, ``.Emitter``, etc., to the class of the type to create for that stage (typically a subclass of an existing class implementing that). +The default loader (`rt`) is a direct derivative of the safe loader, without the +methods to construct arbitrary Python objects that make the ``unsafe`` loader +unsafe, but with the changes needed for round-trip preservation of comments, +etc.. For trusted Python classes a constructor can of course be added to the round-trip +or safe-loader, but this has to be done explicitly (``add_constructor``). + All data is dumped (not just for round-trip-mode) with ``.allow_unicode = True`` @@ -76,7 +81,6 @@ all functionality of the old interface will be available via Loading ------- - Duplicate keys ++++++++++++++ @@ -127,55 +131,53 @@ for reading resp. writing. Loading and dumping using the ``SafeLoader``:: - if yaml.version_info < (0, 15): + if ruamel.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 + yml = ruamel.yaml.YAML(typ='safe', pure=True) # 'safe' load and dump data = yml.load(istream) - yml.dump(ostream) - + yml.dump(data, ostream) Loading with the ``CSafeLoader``, dumping with ``RoundTripLoader``. You need two ``YAML`` instances, but each of them -can be re-used :: +can be re-used:: - if yaml.version_info < (0, 15): + if ruamel.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') + yml = ruamel.yaml.YAML(typ='safe') data = yml.load(istream) - ymlo = yaml.YAML() # or yaml.YAML(typ='rt') + ymlo = ruamel.yaml.YAML() # or yaml.YAML(typ='rt') ymlo.width = 1000 ymlo.explicit_start = True - ymlo.dump(ostream) - + ymlo.dump(data, ostream) Loading and dumping from ``pathlib.Path`` instances using the round-trip-loader:: # in myyaml.py - if yaml.version_info < (0, 15): + if ruamel.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 - + # in your code try: from myyaml import MyYAML - except ImportError: - if yaml.version_info >= (0, 15): + except (ModuleNotFoundError, ImportError): + if ruamel.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): + + if ruamel.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: @@ -184,10 +186,7 @@ round-trip-loader:: yml = MyYAML() # no need for with statement when using pathlib.Path instances data = yml.load(inf) - yml.dump(outf) - - - + yml.dump(data, outf) Reason for API change --------------------- @@ -242,3 +241,4 @@ information via that instance. Representers, etc., are added to a reusable instance and different YAML instances can co-exists. This change eases development and helps prevent regressions. + |