便捷地读取插件配置文件

使用此方法优雅方便地读取用户的插件配置文件！

如果你的插件想便捷的读取用户的插件配置文件和检测配置文件的完整性和合法性， 你可以使用 tooldelta.cfg 内置配置文件库的 Cfg 类中的一些方法。

from tooldelta import Config
# Config 就是 Cfg 类

获取插件配置文件

def get_plugin_config_and_version(
    plugin_name: str,
    standard_type: Any,
    default: dict,
    default_vers: VERSION,
) -> tuple[dict[str, Any], VERSION]

获取配置文件内容与版本， 同时检测配置文件合法性。

• 参数：
  • pluginName (str)： 插件名字, 配置文件的名称会以此名作为文件名
  • standardType (Any)： 作为模板的标准样式, 下面会进行详细讲解。 若填{}则不会对插件配置文件做任何检查。
  • default (Any)： 默认配置文件内容。通常为 dict。
  • default_vers (tuple[int, int, int])： 默认配置文件的默认版本，像这样：(0, 0, 1)
• 返回：
  • 配置文件内容 (Any), 配置文件版本 (tuple[int, int, int])
• 引发异常：
  • 配置文件合法性检测失败(值的类型和模板类型不同引发)： Config.ConfigError
  • 提示： 若是在类式插件的插件主类初始化时（即__init__方法） 时使用， 则不需要处理异常， 系统会自动向用户提示配置文件不正确和其详细内容。
• 示例：

  config, version = Config.get_plugin_config_and_version(
      "趣味钓鱼",
      {
          "宝藏概率": float,
          "可以开出物品的ID": Config.JsonList(str),
      },
      {
          "宝藏概率": 0.05,
          "可以开出物品的ID": ["diamond", "emerald", "gold_ingot"]
      },
      (0, 0, 1)
  )

更新插件配置文件

def upgrade_plugin_config(
    plugin_name: str,
    configs: dict,
    version: VERSION,
)

更新插件配置文件。

• 参数：
  • plugin_name (str): 插件名
  • configs (dict): 配置内容
  • default_vers (tuple[int, int, int]): 版本
• 示例：

  if version < (0, 0, 2):
      # 升级配置, 添加一个配置项
      config["大保底次数"] = 90
      Config.upgrade_plugin_config(
          "趣味钓鱼",
          config,
          (0, 0, 2)
      )

模版匹配性检测

def check_auto(
    standard: Any,
    val: Any,
    fromkey: str = "?",
)

检查 dict 内的内容是否和模版标准样式相同。

• 参数:
  • standard (Any)： 作为模板的标准样式, 下面会进行详细讲解。
  • val (Any)： 传入待检测的值。
  • fromkey (str)： 内部使用， 表示其父级键值对的键名，不需要填写
• 引发异常：
  • 合法性检测失败（值的类型和模板类型不同引发）： Config.ConfigError
• 示例：

  std = {"姓名": str, "年龄": Config.PInt}
  Config.check_auto(std, {"姓名": "Stelle", "年龄": 1})
  # 无报错
  Config.check_auto(std, {"姓名": "Caelus", "年龄": -1})
  # 报错: 键 年龄 只能为正整数
  Config.check_auto(std, {"姓名": 100, "年龄": 2})
  # 报错: 键 姓名 只能为字符串

配置文件模版标准样式

配置文件的模版标准样式就是键值对的值部分改成了类型， 以便检测键值结构相同的配置文件， 例如这样， 这是一个示范配置文件的 Python dict 形式（它是能通过检测的）：

config = {
    "name": "Stelle",
    "age": 1,
    "is_human": True
}

这是这个配置文件的模版样式：

config_std = {
    "name": str,
    "age": Cfg.PInt,
    "is_human": bool
}

我们通过 config_std 来指定了配置文件中 "name" 值只能是字符串，"age" 值则只能是正整数(Cfg.PInt, tooldelta.cfg 里内置的一种模版类型)，"is_human" 值则只能是布尔值。 除了示例里的 Config.PInt, 还有如下几种模版检测类型：

• int： 整数
• str: 字符串
• bool: 布尔值
• None: null 值
• dict: 字典，就是json对象。可以多层嵌套
• (type1, type2, dict, ...): 元组内的类型里的任意一种类型或者 json 对象
• Config.PInt: 正整数
• Config.NNInt: 非负整数
• Config.PFloat: 正浮点小数
• Config.NNFloat: 非负浮点小数
• Config.Number: 任何数
• Config.PNumber: 正数(包括整数和浮点数)
• Config.NNNumber: 非负数
• Config.JsonList(types, len_limit = -1): 表示一个列表。types指定了列表各项的类型，lem_limit指定了列表的固定长度，-1为不限制长度。
• Config.AnyKeyValue(val_type): 表示一个键名可以是任意名称的 json 对象, val_type指定了其值的类型。

综合使用示例：

default_cfg = {
    "多类型": "Hi!",
    "只能是正数": 2.345,
    "只能是非负整数": 0,
    "列表": [
        1, 2, 3
    ],
    "多类型列表": [
        1, 2, 3,
        "Hi", "World"
    ],
    "混合列表": [
        4, 5,
        {"Hi", "World"}
    ],
    "嵌套json": {
        "任意键测试": {
            "apple": 2,
            "banana": 1.5,
            "cherries": 4
        },
        "正常值": "Hi China"
    }
}
std_cfg_model = {
    "多类型": (str, int)
    "只能是正数": Config.PInt,
    "只能是非负整数": Config.NNNumber,
    "列表": Config.JsonList(int),
    "多类型列表": Config.JsonList((int, str)),
    "混合列表": Config.JsonList((int, {"Hi": str})),
    "嵌套json": {
        "任意键测试": Config.AnyKeyValue(Config.PNumber),
        "正常值": str
    }
}

Config.check_auto(std_cfg_model, default_cfg)
# 有报错 (Cfg.ConfigError) 会在此方法内引发, 通常是通俗易懂的中文提示
# 以上的示例模板检测不会产生问题。

如果你实在懒得写配置文件标准模版检查样式， 使用 std_cfg_model = Config.auto_to_std(default_cfg) 也可以，但是智能应用于简单的配置文件类型（不支持任意键名、非必要键值对等）