Metadata-Version: 2.4
Name: yaml-config-loader
Version: 1.1.0
Summary: 轻量级 Python 配置加载工具包，提供类似 Spring Boot 的 @configuration_properties 注解，支持 YAML 配置绑定、单例 Bean 容器、点访问字典等功能。
Author-email: wangxz <wangxz@example.com>
License: MIT
Project-URL: Homepage, https://github.com/wangxz/yaml-config-loader
Project-URL: Repository, https://github.com/wangxz/yaml-config-loader
Project-URL: Documentation, https://github.com/wangxz/yaml-config-loader#readme
Project-URL: Issues, https://github.com/wangxz/yaml-config-loader/issues
Keywords: yaml,config,configuration,spring-boot,dataclass,ioc,properties
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Dynamic: license-file

# yaml-config-loader

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

## 功能特性

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

## 安装

```bash
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

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

server:
  port: 8080
  host: "localhost"
```

### 2. 使用 @configuration_properties 绑定配置

```python
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 自动转换

```python
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. 使用单例容器

```python
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 加载工具

```python
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 参考

### 装饰器

| 装饰器 | 说明 |
|--------|------|
| `@configuration_properties(prefix="xxx")` | 绑定 YAML 配置到类属性 |
| `@component` | 注册为单例 Bean |

### 函数

| 函数 | 说明 |
|------|------|
| `load_yaml(path=None)` | 加载 YAML 配置到全局缓存 |
| `find_yaml()` | 递归查找 application.yml 文件路径 |
| `get_yaml_config()` | 获取全局配置字典 |
| `get_loaded_yaml_path()` | 获取已加载的配置文件路径 |
| `get_bean(cls)` | 获取单例 Bean 实例 |
| `list_beans()` | 列出所有已注册的 Bean |
| `to_dot_dict(d)` | 将普通字典转为 DotDict |

### 类

| 类 | 说明 |
|----|------|
| `DotDict` | 支持点访问的字典 |

## 配置文件查找规则

`find_yaml()` 会按以下顺序递归查找：
1. 当前工作目录
2. 上级目录（最多向上查找 5 层）
3. 项目中的 `config/`、`conf/`、`resources/` 子目录

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

## 许可证

MIT License
