Figcan - 最小化配置处理库

Figcan 是一个用于Python的最小化配置处理库。

它旨在帮助您管理来自不同来源的运行时配置，而不对配置文件格式和位置做出任何假设，同时在常用用例中保持非常简单易用。

Figcan除了Python 2.7或3.4及以上版本的Python版本外，没有其他运行时依赖。

Figcan的哲学

Figcan的设计基于几个基本假设

• 在任何但最简单的项目中，配置都是重要的
• 配置可以很容易地描述为一系列嵌套的键值对，其中值可以是几种原生标量类型（布尔值、字符串、数字）或容器类型（列表、映射）
• Python字典几乎完美地适用于配置。几乎。
• 配置键可以预先知道。您期望的配置结构几乎总是为您的项目代码所知，因此可以预先描述。
• 配置可以来自多个来源：代码中的默认值、多个配置文件、环境变量、命令行参数、数据库持久化的键值对等。
• 但现实中，从这些来源读取的对象并没有太大区别：它们几乎总是可以表示为Python对象属性或字典
• 已经有一个Python模块可以处理从这些来源读取值并将它们转换为某种原生字典或对象

考虑到这些，以下是Figcan将要做什么

• 提供包含配置的字典样式的对象
• 该对象是从指定默认配置的字典创建的
• 可以在默认配置之上“分层”额外的配置值（以Python字典或对象的形式），以覆盖值

以下是一行中Figcan不会为您做的事情——但是只需编写几行自定义代码就可以轻松实现

• 读取和解析特定格式的文件（例如INI、JSON、YAML等）
• 根据操作系统或环境查找特定位置的配置文件
• 从特定的命令行参数解析器（argparse、optparse、click等）中读取值
• 管理将配置保存到文件或任何其他位置
• 提供任何API来访问配置，超出了Python dict接口提供的功能（如果您问我们，这应该对每个人来说都足够了）

我们计划提供一些文档和示例，说明如何使用Figcan来完成这些任务。

入门指南

安装

建议您使用pip将Figcan添加到您的项目中

pip install figcan

您也应该能够直接从git获取的源树中安装

`TBD`

在项目中使用

通常，Figcan在程序开始时（例如在您的main函数中）读取所有来源的配置，并根据需要将配置对象提供给程序的其他部分。

以下是一个非常基本的（但并非不切实际的）使用示例

import os
from figcan import Configuration
from my_project.config import default_config  # A dictionary defining default configuration values

def main():
    config = Configuration(default_config)

    # Apply configuration overrides from environment variables
    config.apply_flat(os.environ, prefix='MYPROJECT')

    # Do something with the configuration:
    db_engine = sqlalchemy.create_engine(config['db']['url'])

从YAML或JSON文件应用配置

如果您的配置以可以解析为Python dict的文件格式保存，您可以让Figcan轻松地与之工作。例如

import yaml
from figcan import Configuration
from my_project.config import default_config  # A dictionary defining default configuration values

def main(config_file_path):
    config = Configuration(default_config)

    with open(config_file_path) as f:
        config.apply(yaml.safe_load(f))

    # Do something with the configuration:
    db_engine = sqlalchemy.create_engine(config['db']['url'])

请注意，如果Configuration.apply遇到不在您的default_config中存在的配置键，它将引发异常。这可以按照以下方式更改

config.apply(yaml.safe_load(f), raise_on_unknown_key=False)

如果您想允许将新的配置键合并到配置部分中，您需要在基本配置中将该部分定义为可扩展的

from figcan import Configuration, Extensible

default_config = dict({  # Base configuration keys are known ahead and static 
    'bind_port': 5656,
    'db': {  # Database settings keys are known ahead and static
        'hostname': 'db.local',
        'username': 'foobar',
        'password': 'blahblah'
    } ,
    'logging': Extensible({  # But logging settings are flexible, and new handlers / loggers can be defined
        'handlers': {
            'handler_1': '...'
        }
    })
})

config = Configuration(default_config)

# This will not raise an exception and 'handler_2' config will be available in `config`:
config.apply({"logging": {"handlers": {"handler_2": "... more config ..."}}})

从环境变量应用配置

从命令行参数应用配置

一些可供考虑的替代方案

有多个用于Python的配置处理库。其中一些可能比Figcan更适合您（我们在决定编写Figcan之前尝试过一些库）

待办事项/计划功能

基于模式类型强制转换和验证配置值

这里的想法是，初始的default_config字典也将以某种形式包含一些类型注解。这些将用于强制转换覆盖值（例如，当作为字符串从环境变量中来时）以及在配置应用时进行一些验证。

允许定义“灵活”与“非灵活”的配置映射

例如，用于logging.config.dictConfig的logging部分通常需要一个灵活的结构。但是，使一切都很灵活可能会导致无法检测到拼写错误等。

致谢

Figcan由Shoppimon团队创建，并在Shoppimon的广泛使用、关键生产代码中使用。

许可

© 2018 Shoppimon LTD，版权所有

根据Apache License，版本2.0（“许可证”）；除非遵守许可证，否则不得使用此文件。您可以在以下位置获得许可证副本：

https://apache.ac.cn/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则在许可证下分发的软件按“原样”基础分发，不提供任何明示或暗示的保证或条件。有关许可证的具体语言，请参阅许可证。