代码之家 › 专栏 › 技术社区 › benjimin

如何记录配置文件?

documentation configuration python

benjimin · 技术社区 · 5 年前

对于配置文件文档,特别是python,有什么最佳实践吗?

特别是在科学计算中,通常使用配置文件作为输入来控制批处理作业(例如模拟),并期望用户为其场景定制配置的大部分内容。(配置也可能在不同的处理模块中进行选择,每个模块拥有不同的配置字段套件)。因此,用户应该知道:每个设置的含义或效果;哪些设置是未使用的(在哪些情况下);默认值是什么(以及允许的值或范围);等等。

我发现不完整的配置文件文档很常见。根本的问题似乎是,如果文档与代码分开维护,它们会变得不同步。(API文档的问题似乎没有那么大,因为标准做法涉及到同位的docstring和从函数签名/argspec自动生成)例如,如果只使用标准python configparser分析配置文件,则访问单个属性的代码(并隐式确定配置模式)可能仍然存在分布在整个代码库中(可能只在运行时可用,而不是在构建文档时)。

用用户自定义的python脚本替换配置文件(yaml或类似文件)是否是一种不好的做法(这样只需要API文档)?
是否可以维护一个模式,既可以在代码中使用(帮助解析、验证和设置默认值),也可以以某种方式生成文档?

0 回复 | 直到 5 年前

Don Kirkby 5 年前

我个人喜欢用 argparse

这是 an example 使用和环境变量:

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 任何用户都可以使用 systemctl show .

我通常让在工作站上运行的开发人员使用默认值,这样他们就可以在不更改任何配置的情况下开始开发。

另一个选项是将配置设置放入 settings.py settings_template.py

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