pop-conf 1.0.0

理解 conf.py 文件

Pop 依赖于配置文件来管理如何合并应用程序，以及如何管理和合并配置数据。该文件中的数据以 4 个 Python 字典的形式呈现，并定义了配置加载的各个方面。

这 4 个字典分别称为 CONFIG、CLI_CONFIG、SUBCOMMANDS 和 DYNE。每个字典都有其特定的用途。您可以通过它们定义如何呈现 CLI 参数、所有配置默认值、文档等。

CONFIG 字典

大部分配置将存在于 CONFIG 字典中。您所有的配置选项都定义在这里。大多数 CONFIG 字典条目都非常简单，仅公开最基本值。

CONFIG = {
    "name": {
        "default": "frank",
        "help": "Enter the name to use",
    },
}

以下简单示例展示了配置值的文档和默认值应该是什么。

垂直合并的项目可以像这样向其父 dynes 添加配置项

CONFIG = {
    "new_item": {
        "type": int,
        "default": 1,
        "dyne": "idem",
    },
}

还有更多选项可以使用，但它们将在参考文档中介绍。

CLI_CONFIG 字典

添加配置值不会使其出现在命令行上。每个应用程序都可以扩展以包含命令行选项。让我们扩展我们之前的示例，以公开“name”选项作为命令行参数。

CLI_CONFIG = {
    "name": {},
}
CONFIG = {
    "name": {
        "default": "frank",
        "help": "Enter the name to use",
    },
}

就是这样！现在，“name”选项可在命令行上使用，可以用作 –name bob。

但如果我们想将其作为位置参数呢？简单！只需将位置参数添加到 CLI_CONFIG。

CLI_CONFIG = {
    "name": {
        "positional": True,
    },
}
CONFIG = {
    "name": {
        "default": "frank",
        "help": "Enter the name to use",
    },
}

您可以从其他项目继承 CLI 参数。例如，如果您想以与 rend 相同的方式实现 –output 标志，您可以这样引用

CLI_CONFIG = {
    "output": {
        "source": "rend",
    },
}

还有更多选项存在，允许您控制用户命令行体验的各个方面。

SUBCOMMANDS 字典

有时可能希望有子命令。子命令允许您的 CLI 以类似于 git CLI 的方式工作，其中您有多个例程都可以从单个命令中调用。

让我们添加一些东西到我们的示例中，以便我们可以有子命令。

CLI_CONFIG = {
    "name": {
        "subcommands": ["test", "apply"],
    },
    "weight": {},
    "power": {
        "subcommands": ["apply"],
    },
}
CONFIG = {
    "name": {
        "default": "frank",
        "help": "Enter the name to use",
    },
    "weight": {
        "default": "150",
        "help": "Enter how heavy it should be",
    },
    "power": {
        "default": "100",
        "help": "Enter how powerful it should be",
    },
}

SUBCOMMANDS = {
    "test": {
        "help": "Used to test",
        "desc": "When running in test mode, things will be tested",
    },
    "apply": {
        "help": "Used to apply",
        "desc": "When running in apply mode, things will be applied",
    },
}

在这个例子中，我们看到选项 name 将在子命令 test 和 apply 下可用。选项 power 仅在子命令 apply 下可用，而选项 weight 是全局可用的。

DYNE 字典

DYNE 字典允许您控制您的应用程序向其他 pop 项目呈现的动态名称。此名称不仅用于 pop-conf 内部，还用于 pop 内部以确定此应用程序与哪些插件子系统合并。DYNE 系统允许 CLI 通过第三方代码扩展，使配置选项可通过外部代码提供给您的应用程序。

DYNE 系统非常强大。但由于它对于开始使用 pop-conf 不是关键的，因此它将在另一篇文档中更详细地介绍。