# 前言
在许多工程项目中，经常需要配置一些选项供用户或者员工自己使用。以人工智能领域为例， Paddlepaddle 、 mmdetection 等深度学习框架都需要根据需求在配置文件中配置数据、网络等相关参数。 Paddlepaddle 使用 YAML 格式存储配置信息， mmdetection 则直接使用 Python 文件来设定配置。此外， JSON 格式也是常用的数据存储格式。无论何种格式，当配置信息不断增加膨胀之后，如何组织配置的结构就成为了一件迫切需要考虑的事情。
这三种配置格式孰优孰劣，我无法评价。由于我目前接手的工作中使用的是 YAML 格式的配置文件，因此本文主要介绍最近一段时间经过调研搜索后，我决定采用的一种配置文件组织方案。
在实际阐述方案之前，有必要阐述一下 YAML 和 dataclass 这两个概念。如果读者对这二者比较熟悉，可以直接跳过相关部分。
# YAML 中的 tag
YAML 诞生于 2004 年，根据官网说法[1]，其有 7 条设计目标，其中，易读、不同编程语言间良好的兼容性、可扩展等特性使得其被广泛用于存储格式化的信息。
关于其具体的语法，可以参考官方网站或者其他教程，这里不做过多介绍，本文主要介绍其 tag 标签功能。
tag 可以标注 YAML 中数据的类型或者其归属的对象类别，其可以是 str 、 int 、 float 等基本类型，也可以是用户自己定义的任何有意义的类别名称。这些标签可以帮助我们在阅读或者解析的时候，更方便地判断数据的归属。
我们不妨来看一个例子：
name: 'linn' | |
age: 18 | |
gender: 'male' |
在上述 YAML 文件中，我们定义了三个属性，可以很清晰地看到，这三个属性描述的都是个人信息，它们在许多场景下通常会结伴出现。对于这种数据，有一个专门的称呼叫做数据泥团（Data Clumps）[2]。有时候，我们会发现某些函数包含大量的参数，而这些参数往往一起出现，很显然，在通常的编程语言中，用结构体或者类来组织这种数据，比直接使用原生类型是更好的选择。而在 YAML 中，我们也可以用 tag 来表征这一特点：
!Person | |
name: 'linn' | |
age: 18 | |
gender: 'male' |
在 YAML 中，使用 ! 来表示这一标识是一个 tag 的名称。相比于仅仅列出属性，增加一个 tag 可以使得数据的语义更加明晰。当我们的配置文件中的数据项膨胀到数十个的时候，增加一个 tag 能够帮助你更好的理解配置选项的意义。
# 解析 YAML 的 tag
当然，光在 YAML 中定义一个 tag ，并没有全部发挥出 tag 的作用。 tag 黑能配合编程语言，帮助解析 YAML 文件中的内容。
想象一下，当没有 tag 的时候，我们通常是如何解析 YAML 的？一般情况的代码大致如下（为了方便，直接在文件中用字符串表示 YAML 内容）：
import yaml | |
class Person: | |
def __init__(self, name, age, gender): | |
self.name = name | |
self.age = age | |
self.gender = gender | |
yaml_str = """ | |
name: 'linn' | |
age: 18 | |
gender: 'male' | |
""" | |
content = yaml.load(yaml_str, Loader=yaml.SafeLoader) | |
""" | |
content | |
{'name': 'linn', 'age': 18, 'gender': 'male'} | |
""" | |
person = Person(**content) |
以上代码可以分为两个部分：
- 读取
YAML文件的内容，赋值给某个对象。一般而言，读入的内容会存储在字典或者列表中； - 创建某个类的对象，利用读取的
YAML内容为其初始化。 对于结构简单的YAML文件，上述方法还可接受，但是如果YAML文件变得复杂，那么按照上述方法来解析的代码便会变得繁琐。
我们可以看下面这个例子[3]：
name: MyBusiness | |
locations: | |
- "Hawaii" | |
- "India" | |
- "Japan" | |
employees: | |
- !Employee | |
name: Matthew Burruss | |
id: 1 | |
- !Employee | |
name: John Doe | |
id: 2 |
显然，如果 employees 中的内容较多，我们甚至还需要写一个循环来初始化这些对象。而通过结合 YAML 的 tag ，我们可以自定义 constructor 来解析其内容：
import yaml | |
class Employee: | |
"""Employee class.""" | |
def __init__(self, name, id): | |
self._name, self._id = name, id | |
def employee_constructor(loader: yaml.SafeLoader, node: yaml.nodes.MappingNode) -> Employee: | |
"""Construct an employee.""" | |
return Employee(**loader.construct_mapping(node)) | |
def get_loader(): | |
"""Add constructors to PyYAML loader.""" | |
loader = yaml.SafeLoader | |
loader.add_constructor("!Employee", employee_constructor) | |
return loader | |
yaml.load(open("config.yml", "rb"), Loader=get_loader()) | |
""" | |
{ | |
'name': 'MyBusiness', | |
'locations': ['Hawaii', 'India', 'Japan'], | |
'employees': [ | |
<__main__.Employee object at 0x7f0ea2694d10>, | |
<__main__.Employee object at 0x7f0ea2694d90> | |
] | |
} | |
""" |
这样一来，我们可以直接生成对应的类的对象，省去了自己创建的过程。
# dataclass
你是否经常面临下面的情形：
class Person: | |
def __init__(self, name, age, gender, ...): | |
self.name = name | |
self.age = age | |
self.gender = gender | |
... |
当我们在 __init__ 函数的参数列表中敲击了一系列参数之后，又需要在 __init__ 函数体中，将它们一一赋值给类成员变量。一旦这些变量数量增多，这项工作就成了一项非常繁琐无趣的事情。
很多时候，我们定义类只是想将一些相关的数据组织起来，但却不得不动手编写许多重复的代码。于是乎，这里就轮到 dataclass 出场了。类比而言， dataclass 可以看成是 C/C++ 中的结构体，能够方便我们将一系列的数据组合在一起，同时给每个成员指定默认值，不用再手动为成员变量赋值。
可以看下面这个例子[4]：
from dataclasses import dataclass | |
@dataclass | |
class Lang: | |
"""a dataclass that describes a programming language""" | |
name: str = 'python' | |
strong_type: bool = True | |
static_type: bool = False | |
age: int = 28 |
这里定义了一个编程语言的类 Lang ，我们从 dataclasses 模块中引入了装饰器 dataclass 。之后，我们在类中定义了一系列成员变量。
使用上述方式定义之后，该类会自动生成一个初始化构造函数：
def __init__(self, name: str='python', | |
strong_type: bool=True, | |
static_type: bool=False, | |
age: int=28): | |
self.name = name | |
self.strong_type = strong_type | |
self.static_type = static_type | |
self.age = age |
除此之外， __repr__ 和 __eq__ 函数也会自动生成，便于打印和比较。通过以上方式，再也不用每次都自己定义一个构造函数，并且为每个变量都赋值一遍，省却了繁琐的操作。
执行效果如下：
>>> Lang() | |
Lang(name='python', strong_type=True, static_type=False, age=28) | |
>>> Lang('js', False, False, 23) | |
Lang(name='js', strong_type=False, static_type=False, age=23) | |
>>> Lang('js', False, False, 23) == Lang() | |
False | |
>>> Lang('python', True, False, 28) == Lang() | |
True |
除此之外， dataclass 可以通过 asdict 或者 astuple 生成类成员的字典或者元组。
需要注意的是，对于 mutable 类型的变量，如 list 、 map 等，推荐使用 field 来初始化：
from dataclasses import dataclass, field | |
@dataclass | |
class C: | |
mylist: List[int] = field(default_factory=list) |
其他功能的详细介绍，可以参考这篇博客或者官方网站的说明。
# 结合 dataclass 和 YAML
在介绍以上两部分内容之后，我们可以结合 dataclass 和 YAML 来方便地构建配置类，并从 YAML 文件导入，或者导出到 YAML 文件。
参考了相关资料后[3:1][5]，我编写了下面的参数类模板。
import sys | |
import yaml | |
from yaml import SafeLoader, SafeDumper | |
from yaml.nodes import MappingNode | |
from dataclasses import dataclass, asdict, field, is_dataclass | |
from typing import Type | |
from typing_extensions import Self | |
@dataclass | |
class BaseConfig(object): | |
@classmethod | |
def constructor(cls, loader: SafeLoader, node: MappingNode) -> Self: | |
"""Construct an instance.""" | |
return cls(**loader.construct_mapping(node)) | |
@classmethod | |
def loader(cls, safe_loader: SafeLoader) -> Type[SafeLoader]: | |
"""Add constructors to PyYAML loader.""" | |
safe_loader = yaml.SafeLoader | |
safe_loader.add_constructor(f"!{cls.__name__}", cls.constructor) | |
for (name, data_fields) in cls.__dataclass_fields__.items(): | |
cls_type = data_fields.type | |
if is_dataclass(cls_type): | |
safe_loader.add_constructor(f"!{cls_type.__name__}", cls_type.constructor) | |
safe_loader = cls_type.loader(SafeLoader) | |
return safe_loader | |
@classmethod | |
def representer(cls, dumper: SafeDumper, config) -> MappingNode: | |
"""Represent an instance as a YAML mapping node.""" | |
return dumper.represent_mapping(f"!{cls.__name__}", config.__dict__) | |
@classmethod | |
def dumper(cls, safe_dumper: SafeDumper) -> Type[SafeDumper]: | |
"""Add representers to a YAML seriailizer.""" | |
# safe_dumper = yaml.SafeDumper | |
safe_dumper.add_representer(cls, cls.representer) | |
for (name, data_fields) in cls.__dataclass_fields__.items(): | |
cls_type = data_fields.type | |
if is_dataclass(cls_type): | |
safe_dumper.add_representer(cls_type, cls_type.representer) | |
safe_dumper = cls_type.dumper(safe_dumper) | |
return safe_dumper | |
@dataclass | |
class DatasetConfig(BaseConfig): | |
data_root_path: str = "./data/coco" | |
train_path: str = "./data/coco/train" | |
train_ann_path: str = "./data/coco/annotations/instances_train2017.json" | |
@dataclass | |
class COCODatasetConfig(BaseConfig): | |
name: str = "COCO" | |
num_classes: int = 80 | |
dataset: DatasetConfig = field(default_factory=DatasetConfig) | |
@dataclass | |
class COCODataConfig(BaseConfig): | |
train_data: COCODatasetConfig = field(default_factory=COCODatasetConfig) | |
val_data: COCODatasetConfig = field(default_factory=COCODatasetConfig) | |
# If you want dump without tag, change the tag name of the class | |
# to 'tag:yaml.org,2002:map', this is the default map type of YAML | |
# @classmethod | |
# def representer(cls, dumper: SafeDumper, config) -> MappingNode: | |
# """Represent an instance as a YAML mapping node.""" | |
# return dumper.represent_mapping("tag:yaml.org,2002:map", config.__dict__) | |
if __name__ == "__main__": | |
# config = COCODatasetConfig() | |
# config = yaml.load(open("output.yaml", "rb"), Loader=COCODataConfig.loader(SafeLoader)) | |
config = COCODataConfig() | |
print(config) | |
print(asdict(config)) | |
# config = DatasetConfig() | |
# with open("output.yaml", "w") as stream: | |
# stream.write(yaml.dump(config, Dumper=COCODatasetConfig.dumper())) | |
# stream.write(yaml.dump(config, Dumper=COCODataConfig.dumper(SafeDumper))) | |
# yaml.dump(config, sys.stdout, Dumper=COCODatasetConfig.dumper(), sort_keys=False) | |
yaml.dump(config, sys.stdout, Dumper=COCODataConfig.dumper(SafeDumper), sort_keys=False) |
上述模板可以支持多个 dataclass 类别的嵌套，并且会保留每个类别的 tag 标签，便于将来再读取配置的内容。
如果不想输出某个 dataclass 类的 tag ，则重载其 representer 和 loader 函数，修改其中设定的 tag 名称为 tag:yaml.org,2002:map [6]。其他类型可以参看官方文档[7]。
如果某些变量依赖于其他变量的赋值，可以使用 __post_init__ 方法：
@dataclass | |
class C: | |
a: int | |
b: int | |
c: int = field(init=False) | |
def __post_init__(self): | |
self.c = self.a + self.b |
此外，如果需要额外的参数用于初始化，但是之后的程序中不需要用到它的话，可以指定一个 field 的类型注解为 dataclasses.InitVar ，那么这个 field 将只能在初始化过程中（ __init__ 和 __post_init__ ）使用，当初始化完成后访问该 field 会返回一个 dataclasses.Field 对象而不是 field 原本的值，也就是该 field 不再是一个可访问的数据对象。比如一个由数据库对象，它只需要在初始化的过程中被访问：
@dataclass | |
class C: | |
i: int | |
j: int = None | |
database: InitVar[DatabaseType] = None | |
def __post_init__(self, database): | |
if self.j is None and database is not None: | |
self.j = database.lookup('j') | |
c = C(10, database=my_database) |
database 只在初始化过程中用于初始化 i, j ，后续无法再访问，可以认为是传递了一个额外的参数用于初始化操作。
# 总结
通过以上内容，我们得到了一个用于 YAML 格式的通用模板类，用于导入或者导出相关的配置内容，帮助我们更好地管理配置文件中参数的结构，提高工作效率。减少加班
YAML Ain’t Markup Language (YAML™) revision 1.2.2 ↩︎
Data Clumps (refactoring.guru) ↩︎
来自博客 A Powerful Python Trick: Custom YAML tags & PyYAML | Matthew Burruss (matthewpburruss.com) ↩︎ ↩︎
来自博客 Python3.7 dataclass 使用指南 - apocelipes - 博客园 (cnblogs.com) ↩︎
dataclass を使った YAML 形式で保存／ロード可能な設定クラス - Qiita ↩︎
PyYAML 笔记 - 一个单板滑雪爱好者的编程笔记 (caosiyang.github.io) ↩︎
Language-Independent Types for YAML™ Version 1.1 ↩︎
