pon 0.2.5

为什么不是YAML/XML/INI-CFG/JSON

Python已经包含了PON的大部分电池组件

在Python中，您已经可以做到

config = dict(
    version = [1, 2, 3],  # Major, Minor and Micro version number
    email = "avdn@europython.org",
    score = 8.7,
    restrictions = None,
    published = True,
    install_requires=dict(   # nested structure
        any=['requests', 'beautifulsoup',],
        py26=['ordereddict']
    ),
)

这是一个有效的Python代码，嵌入要求是隐式处理的。问题是您并不总是想以代码的形式评估/包含/导入这个，因为存在安全问题。您需要能够解析它并拒绝无效或危险的构造。

（注意，您可以在上面的例子中删除包含py26=的整个行，而不会破坏任何事情，尽管您最终会在闭括号之前得到一个逗号。）

直接解析PON（几乎）

来自ast模块的literal_eval函数可以解析之前配置的更类似于JSON的变体。例如，以下文件的内容

{
  "version": [1, 2, 3],  # Major, Minor and Micro version number
  "email": "avdn@europython.org",
  "score": 8.7,
  "restrictions": None,
  "published": True,
  "install_requires": {   # nested structure
    "any": ['requests', 'beautifulsoup',],
    "py26": ['ordereddict']
  },
}

使用以下

python -c 'import ast; ast.literal_eval(open("input2.pon").read())

上述内容也可以通过在较大的（Python源代码）文件中寻找对已知变量（如 config = {）的赋值，以及对应的 }（通常位于相同的缩进级别）来相对容易地解析。

这几乎就是JSON，但要使Python能够包含JSON并解析它，你还需要做更多修改。

true = True
null = None
config = {
    "version": [1, 2, 3],
    "email": "avdn@europython.org",
    "score": 8.7,
    "restrictions": null,
    "published": true,
    "install_requires": {
        "any": ["requests", "beautifulsoup",],
        "py26": ["ordereddict"]
    }
}

你需要为Python解析器定义 null 和 true，对于大多数JSON解析器，你还需要删除注释，并始终使用双引号来表示字符串。最重要的是，你必须删除尾随逗号，这在删除JSON中字典/映射末尾的整个键值行时最容易被遗忘（除非你使用 ruamel.yaml/PyYAML 来加载你的JSON文件，否则会导致程序无法运行）。

实际上，上述内容不是有效的JSON（你看到 any 行上的尾随逗号了吗？）。这些问题并不使JSON成为一个糟糕的格式。它适用于程序之间的信息交换。JSON文件绝对不应该被编辑，甚至最好也不需要由人类读取。

literal_eval 的替代品

ast.literal_eval 不能处理 dict()，因此使用它时，你不能有不带引号的字符串键。当它接收无效字符串时，它还会抛出一个无用的通用 ValueError，这使得向（无效的）配置数据的人类编辑者提供有意义的反馈变得困难。最后，当它接收诸如浮点数之类的无意义数据时，它会愉快地尝试并失败。

ast.literal_eval 是如何围绕 ast 功能制作最小评估器的良好例子。经过少量调整后，它可以处理额外的内容，如 dict、date 和 datetime。因此，允许非引号简单键，同时禁止非字符串键用于 {}，强制使用顶层字典。代码包括针对2.6及以后版本的支持（2.6的无法处理 {} 类型集合）的调整。

import sys                                               # NOQA
import platform                                          # NOQA
import datetime                                          # NOQA
from textwrap import dedent                              # NOQA
from _ast import *                                       # NOQA

if sys.version_info < (3, ):
    string_type = basestring
else:
    string_type = str

if sys.version_info < (3, 4):
    class Bytes():
        pass

    class NameConstant:
        pass

if sys.version_info < (2, 7) or platform.python_implementation() == 'Jython':
    class Set():
        pass


def loads(node_or_string, dict_typ=dict, return_ast=False, file_name=None):
    """
    Safely evaluate an expression node or a string containing a Python
    expression.  The string or node provided may only consist of the following
    Python literal structures: strings, bytes, numbers, tuples, lists, dicts,
    sets, booleans, and None.
    """
    if sys.version_info < (3, 4):
        _safe_names = {'None': None, 'True': True, 'False': False}
    if isinstance(node_or_string, string_type):
        node_or_string = compile(
            node_or_string,
            '<string>' if file_name is None else file_name, 'eval', PyCF_ONLY_AST)
    if isinstance(node_or_string, Expression):
        node_or_string = node_or_string.body
    else:
        raise TypeError("only string or AST nodes supported")

    def _convert(node, expect_string=False):
        if isinstance(node, (Str, Bytes)):
            return node.s
        if expect_string:
            pass
        elif isinstance(node, Num):
            return node.n
        elif isinstance(node, Tuple):
            return tuple(map(_convert, node.elts))
        elif isinstance(node, List):
            return list(map(_convert, node.elts))
        elif isinstance(node, Set):
            return set(map(_convert, node.elts))
        elif isinstance(node, Dict):
            return dict_typ((_convert(k, expect_string=True), _convert(v)) for k, v
                            in zip(node.keys, node.values))
        elif isinstance(node, NameConstant):
            return node.value
        elif sys.version_info < (3, 4) and isinstance(node, Name):
            if node.id in _safe_names:
                return _safe_names[node.id]
        elif isinstance(node, UnaryOp) and \
             isinstance(node.op, (UAdd, USub)) and \
             isinstance(node.operand, (Num, UnaryOp, BinOp)):  # NOQA
            operand = _convert(node.operand)
            if isinstance(node.op, UAdd):
                return + operand
            else:
                return - operand
        elif isinstance(node, BinOp) and \
             isinstance(node.op, (Add, Sub, Mult)) and \
             isinstance(node.right, (Num, UnaryOp, BinOp)) and \
             isinstance(node.left, (Num, UnaryOp, BinOp)):  # NOQA
            left = _convert(node.left)
            right = _convert(node.right)
            if isinstance(node.op, Add):
                return left + right
            elif isinstance(node.op, Mult):
                return left * right
            else:
                return left - right
        elif isinstance(node, Call):
            func_id = getattr(node.func, 'id', None)
            if func_id == 'dict':
                return dict_typ((k.arg, _convert(k.value)) for k in node.keywords)
            elif func_id == 'set':
                return set(_convert(node.args[0]))
            elif func_id == 'date':
                return datetime.date(*[_convert(k) for k in node.args])
            elif func_id == 'datetime':
                return datetime.datetime(*[_convert(k) for k in node.args])
            elif func_id == 'dedent':
                return dedent(*[_convert(k) for k in node.args])
        elif isinstance(node, Name):
            return node.s
        err = SyntaxError('malformed node or string: ' + repr(node))
        err.filename = '<string>'
        err.lineno = node.lineno
        err.offset = node.col_offset
        err.text = repr(node)
        err.node = node
        raise err
    res = _convert(node_or_string)
    if not isinstance(res, dict_typ):
        raise SyntaxError("Top level must be dict not " + repr(type(res)))
    if return_ast:
        return res, node_or_string
    return res

上述109行Python 确实是 加载整个PON的可迭代对象的实际代码。

如果你只需要支持较新的Python版本，并且知道你的输入是受限的（没有数学，没有 set/tuples/{}，没有 datetime 等），则可以进一步减少这段代码。

error_str = u"""
dict(
    a= u"α",
    b= False,
    c= date(2015, 9, 12),
    d= 1.37,
)
"""

try:
    loads(error_str)
except SyntaxError as e:
    context = 2
    from_line = e.lineno - (context + 1)
    to_line = e.lineno + (context - 1)
    w = len(str(to_line))
    for index, line in enumerate(error_str.splitlines(True)):
        if from_line <= index <= to_line:
            print(u"{:{}}: {}".format(index, w, line), end=u'')
            if index == e.lineno - 1:
                print(u"{:{}}  {}^--- {}".format(
                    u' ', w, u' ' * e.offset, e.node))

2:    a= u"α",
3:    b= False,
4:    c= date(2015, 9, 12),
         ^--- <_ast.Call object at 0x7f1598d20950>
5:    d= 1.37,
6: )

动机

开发 literal_eval 扩展/替代品是由从包的 __init__.py 文件中清理版本和其他信息到其 setup.py 文件所激发的，从而最小化了基础目录中额外配置文件的杂乱（setup.py、dist 和 tox.ini 作为非隐藏文件/目录已经足够糟糕）。

版本号可以很容易地从 __init__.py 文件中解析出来。但是，允许更复杂和完整的配置数据可以使 setup.py 在我的所有项目中保持一致。

使用 pon 包

pon 包提供了主要的解析器 loads()、实用函数 get()、store() 和 extract() 以及 PON 类（这些实用函数是快捷方式）。

dict(
    a = dict(
        b = 24,
        c = [1, 3.14, {'d': 'klm'}],
}

val = get(config, 'some.path', expand=config)

import pon

config = pon.loads("""\
dict(
    a = dict(
        image = "http://{domain}/images",
        alt = "europython.eu",
        dd = (2011, 10, 2)  # this is a tuple
    ),
    domain = 'python.{tld.organisations}',
    datestr = 'date{a.dd}',
    tld = {"organisations": "org", "commmercian": "com"}
)
""")

for key in ['a.image', 'datestr']:
    print(key, '->', pon.get(config, key, expand=True))

a.image -> https://pythonlang.cn/images
datestr -> date(2011, 10, 2)

PON 的往返操作

在有些限制下，可以在保持注释的情况下对 PON 进行往返操作，就像 ruamel.yaml 可以对 YAML 做的那样

• 你不会在第一次往返操作中丢失任何数据

• 第一次往返操作可能改变格式

• 第二次往返操作将产生与第一次往返操作相同的结果

为了方便往返操作，需要保留一些额外的信息，这些信息在将你的 PON 数据结构加载到 Python 的常规字典中时是不可用的。这种额外的处理可以在前端完成，之后原始配置数据就不再以文本形式必要，但如果往返操作永远不会需要，这会浪费加载时间。这些信息可以按需提取，但在那种情况下，需要提供原始的文本数据。这种时间和存储的权衡目前是在加载时进行的，并且仅当使用 PON 类（而不是使用实用函数 loads()）时。

如果你使用 PON(input) 从 input（一个文件、一个字符串或字符串的列表）创建一个 PON 对象，生成的对象将有关字典键和列表元素的信息以及与这些键关联的注释信息。

往返操作的主要目的是更新配置中的现有信息：更新“version”键的元组值，为 py26 添加依赖包。如果需要生成包括注释在内的整个新的配置文件，通常使用（或从）文本模板开始比尝试程序性地构建结构要容易得多。

# this is the configuration driving setup
# initials comments going before the configuration information
dict(   # the top level dict can also have an end-of-line comment
    # full comment associated with the key version
    # this doesn't explain its usage that much, also associates with version
    version=(1, 2, 3)    # end-of-line comment for version
    alt = dict(   # this is end-of-line for alt
        # associated with place
        place=u"Düsseldorf",
        taste="awful",
        # the next key is klm, this comment  will move down on round-trip.
    ),  # this is assocated with klm as well, even though not a end-of-line
    "klm" = [ 3, 5, 6 ],  # although list elements, belongs to klm
    "xyz" = [   # belong to xyz
        42,     # the answer (associated with 42)
        196,
    ],
    # trailing comment, special
)
# still more to say, special as well

try:
    from cStringIO import StringIO as _StringIO
except ImportError:
    from io import StringIO as _StringIO

from pon import PON

input = """
dict(
    pckgs = dict(
        any=['package1', 'package2'],
        py26=['another package', 'and one with a long name',
        'and on a new line']   # where do you go?
    ),
)
"""

out1 = _StringIO()
p1 = PON(input)
p1.dump(out1)
print(out1.getvalue())

out2 = _StringIO()
p2 = PON(out1.getvalue())
p2.dump(out2)


print('roundtrip 1: {0}, roundtrip 2: {1}'.format(
    input == out1.getvalue(),
    out1.getvalue() == out2.getvalue()))

dict(
    pckgs=dict(
        any=['package1', 'package2'],
        py26=['another package', 'and one with a long name',
            'and on a new line',   # where do you go?
        ],
    ),
)

roundtrip 1: False, roundtrip 2: True

展示

以下程序包含大多数（如果不是所有）的功能和往返操作

from io import StringIO as _StringIO
from pon import PON

configs = u'''\
# example config
# should contain all types and facilities
dict(
    s='abc',  # single line string
    # multiline string
    mls="""one
    two
    three""",
    mls_dedent=dedent("""
        abc
        def
    """),
    ghi={'A': 1, 'B': 2},
    klm=['Airbus 370', 'Fokker 100'],
    opq=set([2, 3, 5, 7, 9]),
    rst=(0, 1, 1, 2, 3, 5, 8, 13),   # Fibonacci
    m={u'π': 3.14},
    anniversary=date(2011, 10, 2),
    dts=datetime(1919, 12, 1, 13, 45, 4),
    milisec=datetime(1922, 10, 19, 17, 55, 23, 321),
    six=2 + 4,
    secs_per_day=24 * 60 * 60,
    two=-2 - -4,
    # if you want to extend, do it here
)  # and it's over
'''

out = _StringIO()
p = PON(configs)
p.dump(out)
conf_adjust_for_calc = configs
# calculations are not preserved, they don't round trip, so adjust here
for x, y in (('2 + 4', '6'),
             ('24 * 60 * 60', "{}".format(24 * 60 * 60)),
             ('-2 - -4', '2')):
    conf_adjust_for_calc = conf_adjust_for_calc.replace(x, y)
outl = out.getvalue().splitlines(True)
orgl = conf_adjust_for_calc.splitlines(True)
if outl == orgl:
   print('roundtrip 1: equal')
else:
    import difflib
    diff = difflib.unified_diff(orgl, outl, 'input', 'output')
    for line in diff:
        print(line, end='')

输出

--- input
+++ output
@@ -3,9 +3,7 @@
 dict(
     s='abc',  # single line string
     # multiline string
-    mls="""one
-    two
-    three""",
+    mls='one\n    two\n    three',
     mls_dedent=dedent("""
         abc
         def