tree-config 1.0.2

基本属性

此示例有一个包含两个可配置面板的应用程序类。 _config_props_ 列出了类的可配置属性，而 _config_children_ 构造了可配置对象的树。

class App:

    _config_props_ = ('size', 'name')

    _config_children_ = {'app panel': 'panel1', 'home panel': 'panel2'}

    def __init__(self):
        self.size = 12
        self.name = 'Desk'

        self.panel1 = AppPanel()
        self.panel2 = HomePanel()


class AppPanel:

    _config_props_ = ('color', )

    color = 'A4FF67'


class HomePanel:

    _config_props_ = ('shape', )

    shape = 'circle'

然后，运行

from tree_config import dump_config, read_config_from_object
app = App()
dump_config('basic_example.yaml', read_config_from_object(app))
print(f'Shape is: {app.panel2.shape}')

创建一个 basic_example.yaml 文件，内容如下

app panel: {color: A4FF67}
home panel: {shape: circle}
name: Desk
size: 12

并打印 Shape is: circle。如果我们想加载一个之前包含形状为 "square" 的yaml文件并将其应用到实例上，我们执行以下操作

from tree_config import load_config, apply_config
app = App()
apply_config(app, load_config(app, 'basic_example.yaml'))
print(f'Shape is: {app.panel2.shape}')

这会打印出 Shape is: square。

钩子属性发现

`_config_props_` 和 `_config_children_` 是在类上定义的，而不是在实例上定义的。当 `tree-config` 使用它们时，它会遍历整个类层次结构，并从所有超类中累积它们的值，因为子类不会覆盖它们，而是向它们添加。

如果 `_config_props` 和/或 `_config_children` 在类或实例上定义，`tree-config` 将直接使用该值，而不是分别遍历 `_config_props_` 和/或 `_config_children_`。

例如，以下代码

from tree_config import dump_config, read_config_from_object


class App:

    _config_children_ = {'app panel': 'panel1', 'home panel': 'panel2'}

    def __init__(self):
        self.panel1 = AppPanel()
        self.panel2 = HomePanel()


class RootPanel:

    _config_props_ = ('size', 'name')

    size = 12

    name = 'Desk'


class AppPanel(RootPanel):

    _config_props_ = ('color', )

    color = 'A4FF67'


class HomePanel(AppPanel):

    _config_props_ = ('shape', )

    shape = 'circle'

    group = 'window'

    _config_props = ('group', 'size')

运行时

app = App()
# now get and save config to yaml file
dump_config('hook_properties.yaml', read_config_from_object(app))

将生成以下 yaml 文件

app panel:
  color: A4FF67
  name: Desk
  size: 12
home panel:
  group: window
  size: 12

注意，`app panel` 包含了 `RootPanel` 和 `AppPanel` 的属性，而 `home panel` 只包含在 `_config_props` 中列出的属性。《_config_children_》的行为类似。

自定义值钩子

我们可能希望将属性获取/设置过程挂钩以更改值，在它保存之前或再次应用之前。

例如，假设我们有一个存储命名元组的属性，我们需要将其导出为列表（因为 yaml 不理解命名元组），并在恢复时再次创建命名元组。《get_config_property` 和 《apply_config_property` 是所需的钩子方法，如果类中存在，将自动使用它们

from collections import namedtuple
from tree_config import dump_config, load_config, apply_config, \
    read_config_from_object

Point = namedtuple('Point', ['x', 'y'])


class App:

    _config_props_ = ('point', 'name')

    point = Point(11, 34)

    name = ''

    def get_config_property(self, name):
        if name == 'point':
            return tuple(self.point)
        return getattr(self, name)

    def apply_config_property(self, name, value):
        if name == 'point':
            self.point = Point(*value)
        else:
            setattr(self, name, value)

然后，运行

from tree_config import dump_config, read_config_from_object
app = App()
dump_config('custom_value_example.yaml', read_config_from_object(app))
print(f'point is: {app.point}')

创建一个包含以下内容的 《custom_value_example.yaml` 文件

name: ''
point: [11, 34]

并打印 `point is: Point(x=11, y=34)`。如果我们想再次加载并应用 yaml 文件，我们做

from tree_config import load_config, apply_config
app = App()
apply_config(app, load_config(app, 'custom_value_example.yaml'))
print(f'point is: {app.point}')

这反过来会再次打印 `point is: Point(x=11, y=34)`。

有关类似挂钩应用子对象的应用，请参阅 `apply_config_child`。默认情况下，如果没有提供，则使用 `apply_config`，因此如果覆盖，这也应该用于基本案例。

from collections import namedtuple
from tree_config import dump_config, load_config, apply_config, \
    read_config_from_object
from ruamel.yaml import BaseConstructor, BaseRepresenter

Point = namedtuple('Point', ['x', 'y'])

yaml_tag = '!tree_config_example_point'

# encoder
def _represent_point(representer: BaseRepresenter, val):
    return representer.represent_sequence(yaml_tag, tuple(val))

# decoder
def _construct_point(constructor: BaseConstructor, tag, node):
    return Point(*constructor.construct_sequence(node))

# tell yaml how to represent a Point
def register_point_yaml_support() -> None:
    BaseRepresenter.add_multi_representer(Point, _represent_point)
    BaseConstructor.add_multi_constructor(yaml_tag, _construct_point)


class App:

    _config_props_ = ('point', 'name')

    point = Point(11, 34)

    name = ''

register_point_yaml_support()

name: ''
point: !tree_config_example_point [11, 34]

应用后分派

在将配置应用于对象及其子对象之后，如果存在，tree-config 将调用对象的 《post_config_applied` 方法。例如。

from tree_config import dump_config, load_config, apply_config, \
    read_config_from_object


class App:

    _config_props_ = ('size', 'name')

    _config_children_ = {'app panel': 'panel'}

    size = 12

    name = 'Desk'

    def __init__(self):
        self.panel = Panel()

    def apply_config_property(self, name, value):
        print('applying', name)
        setattr(self, name, value)

    def post_config_applied(self):
        print('done applying app')


class Panel:

    _config_props_ = ('color', )

    color = 'A4FF67'

    def apply_config_property(self, name, value):
        print('applying', name)
        setattr(self, name, value)

    def post_config_applied(self):
        print('done applying panel')

然后，使用

# create app and set properties
app = App()

# now get and save config to yaml file
dump_config('post_apply_dispatch.yaml', read_config_from_object(app))
# load config and apply it
apply_config(app, load_config(app, 'post_apply_dispatch.yaml'))

保存并再次应用 yaml，打印以下内容

applying color
done applying panel
applying name
applying size
done applying app

可配置类

上述示例使用了 duck typing 方法来处理这些特殊的配置/钩子方法，并且所有这些方法都是可选的。tree-config 还提供了一个 《Configurable` 超类，它定义了所有这些方法并具有适当的默认值。

从 《Configurable` 继承没有好处，但它确实提供了一个包含所有特殊配置方法的基类。此外，它为每个类缓存属性/配置子对象的列表，因此一旦检索到，就不需要遍历树，这与 duck typing 方法不同，该方法在每次保存/应用时都会重新计算。

home panel

shape:

默认值

''

家的形状。

app panel

color:

默认值

''

应用程序的颜色。

类与实例

上述配置示例从 App 实例 中保存配置。也可以使用 App 类 来转储 yaml。主要区别在于，对于实例方法（如 apply_config_child、get_config_property、apply_config_property 和 post_config_applied），这些方法是实例方法，将被跳过且不被使用。

此外，与实例不同，如果 _config_children_ 列表中的子属性值为 None，则会失败，对于类，如果定义了属性的类型提示，则将回退到类型提示。

使用 App 类而不是 App() 实例，在文档构建期间非常有帮助，此时可能无法实例化完整的 App（参见上面使用带有类型提示的类实例的文档示例）。

重用其他项目文档

由于我们依赖于 autodoc 来生成 config_prop_docs.yaml，tree-config 提供了一种机制来重用我们依赖的其他项目的文档字符串。

例如，假设我们依赖于定义可配置类的remote1和remote2项目，我们的项目通过继承和扩展它们，进一步增加了可配置属性。此外，假设这些远程项目像示例中那样将它们的可配置docstrings输出到config_prop_docs.yaml，并在它们sphinx生成的文档根目录中提供，例如在github-pages上。

然后，tree-config提供了工具将这些docstrings合并到我们的文档中，从而能够从它们创建config.rst，如下所示

echo $'Config\n===========' > source/config.rst
python -m tree_config.doc_gen download \
    -u "https://user.github.io/remote1/config_prop_docs.yaml" -o config_prop_docs.yaml
python -m tree_config.doc_gen download -f config_prop_docs.yaml \
    -u "https://matham.github.io/remote2/config_prop_docs.yaml" -o config_prop_docs.yaml
make html
make html

这将从我们的依赖项下载并合并yaml文件，将其添加到我们的文档中，并生成config.rst。