(Python之ruamel.yaml模块详解（一）)

1 ruamel.yaml简介

• ruamel.yaml是一个yaml解析器；
• ruamel.yaml是一个用于Python的yaml1.2加载器/转储程序包；
• 它是PyYAML 3.11的衍生产品；
• ruamel.yaml库继承子PyMYAL库，读写方法基本相同，目前来说可以根据自己的习惯选择使用 ruamel.yaml 还是 PyMYAL 进行yaml文件的读写操作。

2 ruamel.yaml安装

• 前提条件是：确保安装了最新版本的pip和setuptools（>=20.6.8）。

2.1 setuptools安装

pip install -U pip setuptools wheel

2.2 pip安装ruamel.yaml

• 一般情况安装到这就可以了，后续的2.3和2.4仅供参考使用。

pip install ruamel.yaml

C:\Users\Administrator>pip install ruamel.yaml
Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple
Collecting ruamel.yaml
  Downloading https://pypi.tuna.tsinghua.edu.cn/packages/9e/cb/938214ac358fbef7058343b3765c79a1b7ed0c366f7f992ce7ff38335652/ruamel.yaml-0.17.21-py3-none-any.whl (109 kB)
     --------------------------------------- 109.5/109.5 kB 2.1 MB/s eta 0:00:00

Collecting ruamel.yaml.clib>=0.2.6
  Downloading https://pypi.tuna.tsinghua.edu.cn/packages/da/f4/928e950925fe1b9eb048ddab8eef073a52e9ae01afd06f98f1daf743e355/ruamel.yaml.clib-0.2.7-cp37-cp37m-win_amd64.whl (115 kB)
     ------------------------------------- 115.9/115.9 kB 357.0 kB/s eta 0:00:00

Installing collected packages: ruamel.yaml.clib, ruamel.yaml
Successfully installed ruamel.yaml-0.17.21 ruamel.yaml.clib-0.2.7

2.3 处理jinja2/YAML模板

pip install ruamel.yaml[jinja2]

2.4 yaml命令行实用程序

pip install ruamel.yaml.cmd

3 yaml.load()和yaml.dump()解析

3.1 yaml.load()读ymal文件

from ruamel.yaml import YAML

yaml=YAML(typ='safe')   
yaml.load(doc)

• 以上typ若没有指定，默认为 'rt' (round-trip)；
• doc可以是文件指针（即具有.read（）方法、字符串或pathlib.Path（）的对象）；
• typ='safe'完成了与safe_load（）之前相同的操作：加载文档而不解析未知标记；
• pure=True以使用纯Python实现强制执行，否则将在可能/可用时使用更快的C库。
• 详细的可以参考源码：

class YAML:
    def __init__(self, *, typ=None, pure=False, output=None, plug_ins=None):  # input=None,
        # type: (Any, Optional[Text], Any, Any, Any) -> None
        """
        typ: 'rt'/None -> RoundTripLoader/RoundTripDumper,  (default)
             'safe'    -> SafeLoader/SafeDumper,
             'unsafe'  -> normal/unsafe Loader/Dumper
             'base'    -> baseloader
        pure: if True only use Python modules
        input/output: needed to work as context manager
        plug_ins: a list of plug-in files
        """

    def load(self, stream):
        # type: (Union[Path, StreamTextType]) -> Any
        """
        at this point you either have the non-pure Parser (which has its own reader and
        scanner) or you have the pure Parser.
        If the pure Parser is set, then set the Reader and Scanner, if not already set.
        If either the Scanner or Reader are set, you cannot use the non-pure Parser,
            so reset it to the pure parser and set the Reader resp. Scanner if necessary
        """
        if not hasattr(stream, 'read') and hasattr(stream, 'open'):
            # pathlib.Path() instance
            with stream.open('rb') as fp:
                return self.load(fp)
        constructor, parser = self.get_constructor_parser(stream)
        try:
            return constructor.get_single_data()
        finally:
            parser.dispose()
            try:
                self._reader.reset_reader()
            except AttributeError:
                pass
            try:
                self._scanner.reset_scanner()
            except AttributeError:
                pass

3.2 yaml.dump()写ymal文件

from ruamel.yaml import YAML

yaml=YAML()
yaml.default_flow_style = False
yaml.dump({'a': [1, 2]}, s)

• 方式和load差不多；
• s可以是文件指针（即，具有.write（）方法的对象，或pathlib.Path（）。如果要显示输出，只需sys.stdout即可；
• 如果需要转换输出的字符串表示形式，请提供一个将字符串作为输入并返回一个字符串的函数：

def tr(s):
    return s.replace('\n', '<\n')  # such output is not valid YAML!

yaml.dump(data, sys.stdout, transform=tr)

• 详细查看源码：

 def dump(self, data, stream=None, *, transform=None):
        # type: (Any, Union[Path, StreamType], Any, Any) -> Any
        if self._context_manager:
            if not self._output:
                raise TypeError('Missing output stream while dumping from context manager')
            if transform is not None:
                raise TypeError(
                    '{}.dump() in the context manager cannot have transform keyword '
                    ''.format(self.__class__.__name__)
                )
            self._context_manager.dump(data)
        else:  # old style
            if stream is None:
                raise TypeError('Need a stream argument when not dumping from context manager')
            return self.dump_all([data], stream, transform=transform)

3.3 基于C的SafeLoader

from ruamel.yaml import YAML

yaml=YAML(typ="safe")
yaml.load("""a:\n  b: 2\n  c: 3\n""")

3.4 基于Python的SafeLoader

from ruamel.yaml import YAML

yaml=YAML(typ="safe", pure=True)
yaml.load("""a:\n  b: 2\n  c: 3\n""")