如何记录配置文件？

Question

有没有关于配置文件文档的最佳实践，尤其是对于python？

---

特别是在科学计算中，通常使用配置文件作为输入来控制批处理作业（例如模拟），并期望用户针对其场景自定义配置的很大一部分。 （配置还可能在不同的处理模块中进行选择，每个处理模块都具有不同的配置字段套件。）因此，用户应该知道：每个设置的含义或作用； 哪些设置未使用（在哪种情况下）； 什么是默认值（以及允许的值或范围）； 等等

我发现配置文件文档不完整很常见。 根本的问题似乎是，如果将文档与代码分开维护，则它们会不同步。 （由于标准做法涉及并置docstring和从函数签名/ argspec自动生成，因此API文档似乎没有什么问题。）例如，如果标准python configparser一次用于解析配置文件，则用于访问各个属性的代码（并隐式确定配置方案）仍然可以分布在整个代码库中（并且可能仅在运行时可用，而不是在构建文档时可用）。

---

进一步的想法：

• 将配置文件（yaml或类似文件）替换为用户自定义的python脚本（以便仅需要API文档）是否是不好的做法？
• 分发了一个备受好评的示例配置文件（也在自动测试中使用）：如果不同的方案重复了较大的部分但需要一些完全不同的字段，该如何维护？
• 是否可以维护单个模式，以便在代码中使用（以帮助解析，验证和设置默认值）并以某种方式生成文档？
• 是否存在人类可读/可写的方式来（反）序列化表示新批处理的某些（子）实例实例的状态（以便使配置包含在现有文档中）？

Answer 1

我个人喜欢使用argparse模块进行配置，并从环境变量中读取每个设置的默认值。 这样就可以将设置和文档集中在一个地方，并且允许用户在命令行上调整设置，或者在环境变量中设置并忘记它们。 但是，请注意在命令行上放置密码，因为其他用户可能会在进程列表中看到您的命令行参数。

这是一个使用argparse和环境变量的示例 ：

def parse_args(argv=None):
    parser = ArgumentParser(description='Watch the raw data folder for new runs.',
                            formatter_class=ArgumentDefaultsHelpFormatter)
    parser.add_argument(
        '--kive_server',
        default=os.environ.get('MICALL_KIVE_SERVER', 'http://localhost:8000'),
        help='server to send runs to')
    parser.add_argument(
        '--kive_user',
        default=os.environ.get('MICALL_KIVE_USER', 'kive'),
        help='user name for Kive server')
    parser.add_argument(
        '--kive_password',
        default=SUPPRESS,
        help='password for Kive server (default not shown)')

    args = parser.parse_args(argv)
    if not hasattr(args, 'kive_password'):
        args.kive_password = os.environ.get('MICALL_KIVE_PASSWORD', 'kive')
    return args

设置这些环境变量可能会有些混乱，尤其是对于系统服务而言。 如果您使用的是systemd，请查看服务单元 ，并小心使用EnvironmentFile而不是Environment来获取任何机密信息。 任何使用systemctl show用户都可以查看Environment值。

我通常使默认值对在其工作站上运行的开发人员有用，因此他们可以在不更改任何配置的情况下开始开发。

另一个选择是将配置设置放在settings.py文件中，请注意不要将该文件提交给源代码管理。 我经常提交用户可以复制的settings_template.py文件。

如果您的设置非常复杂/灵活，以至于环境变量或设置文件变得混乱，那么我将使用API​​将项目转换为库。 用户然后不用编写设置，而是编写一个调用您的API的脚本。 您也不必费力在PyPI上托管您的库。 pip可以例如从GitHub存储库安装。