yaml-config-loader

轻量级 Python 配置加载工具包，提供类似 Spring Boot 的配置管理能力。

功能特性

• YAML 配置加载：自动递归查找 application.yml，全局缓存配置
• @configuration_properties：类似 Spring Boot 的配置属性绑定，支持嵌套 dataclass 自动转换
• @component 单例容器：轻量级 IoC 容器，自动注册和获取 Bean
• DotDict 点访问字典：支持 config.user.name 方式访问嵌套字典
• 零配置：开箱即用，无需复杂设置

安装

pip install yaml-config-loader

v1.1.0 包名变更说明：import 包名已从 config_loader 更名为 yaml_config_loader，与 PyPI 包名保持一致，这样 PyCharm 等 IDE 能自动识别并提示"安装软件包"。

旧代码 from config_loader import ... 仍然可用（兼容别名包），但推荐新代码使用 from yaml_config_loader import ...。

快速开始

1. 创建 application.yml

user:
  name: "张三"
  age: 25
  email: "zhangsan@example.com"
  address:
    city: "北京"
    street: "长安街"

server:
  port: 8080
  host: "localhost"

2. 使用 @configuration_properties 绑定配置

from dataclasses import dataclass
from typing import Optional
from yaml_config_loader import configuration_properties, component, DotDict

@component
@configuration_properties(prefix="user")
@dataclass
class UserConfig:
    name: str = None
    age: int = None
    email: str = None
    address: Optional[DotDict] = None  # 嵌套配置自动转为 DotDict

    def _after_config(self):
        """配置绑定完成后的钩子方法"""
        print(f"[UserConfig] 初始化完成: {self.name}")

    def show(self):
        print(f"姓名: {self.name}")
        print(f"年龄: {self.age}")
        print(f"邮箱: {self.email}")
        print(f"城市: {self.address.city}")  # 点访问嵌套配置

3. 嵌套 dataclass 自动转换

from dataclasses import dataclass
from typing import Optional
from yaml_config_loader import configuration_properties, component

@dataclass
class Address:
    city: str = None
    street: str = None

@component
@configuration_properties(prefix="user")
@dataclass
class UserConfig:
    name: str = None
    address: Optional[Address] = None  # 自动转为 Address 实例

user = UserConfig()
print(user.address.city)  # 北京

4. 使用单例容器

from yaml_config_loader import component, get_bean

@component
class MyService:
    def hello(self):
        return "Hello, World!"

# 获取单例实例
service = get_bean(MyService)
print(service.hello())  # Hello, World!

5. 直接使用 YAML 加载工具

from yaml_config_loader import load_yaml, get_yaml_config, find_yaml

# 自动查找并加载 application.yml
load_yaml()

# 获取全局配置
config = get_yaml_config()
print(config["user"]["name"])  # 张三

# 查找配置文件路径
path = find_yaml()
print(path)

API 参考

装饰器

函数

类

配置文件查找规则

find_yaml() 会按以下顺序递归查找：

1. 当前工作目录
2. 上级目录（最多向上查找 5 层）
3. 项目中的 config/、conf/、resources/ 子目录

支持的文件名：application.yml、application.yaml

许可证

MIT License