Question

配置文件文档（尤其是python）是否有最佳实践？

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

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

进一步的想法：

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

Answer 1

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

这里的an example使用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，请查看service unit，并谨慎使用EnvironmentFile代替Environment来获取所有机密信息。任何用户都可以使用Environment查看systemctl show值。

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

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

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

如何记录配置文件？

1 个答案: