yai-nexus-configuration


Nameyai-nexus-configuration JSON
Version 0.1.1 PyPI version JSON
download
home_pageNone
Summary高质量的 Python 配置管理库 - 基于 Provider 模式,支持多种配置源
upload_time2025-07-08 10:33:34
maintainerNone
docs_urlNone
authorNone
requires_python>=3.8
licenseMIT
keywords configuration config nacos apollo settings management dynamic provider pydantic
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # YAI Nexus Configuration

🚀 **高质量的 Python 配置管理库** - 基于 Provider 模式,支持多种配置源

![Python](https://img.shields.io/badge/python-3.8+-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
![Version](https://img.shields.io/badge/version-0.1.0-orange.svg)

## 🎬 快速上手 (Hello, World!)

这是体验 `yai-nexus-configuration` 核心功能的最快方式。我们将通过一个完整的、可运行的示例,展示“**定义 -> 创建 -> 注册 -> 获取**”的黄金路径。

### 1. 项目结构

首先,请像这样组织您的项目文件:

```
your-project/
├── configs/
│   └── DEFAULT_GROUP/
│       └── app_config.json
└── main.py
```

### 2. 创建配置文件

在 `configs/DEFAULT_GROUP/` 目录下创建一个名为 `app_config.json` 的文件,内容如下:

```json
{
  "database_url": "sqlite:///./test.db",
  "retries": 5,
  "api_key": "a-secret-key-from-environment"
}
```
> **提示**: 在未来的版本中,我们将支持 `${VAR}` 格式的环境变量自动替换,以增强安全性。

### 3. 编写 Python 代码 (`main.py`)

现在,创建 `main.py` 并复制以下代码。它包含了使用本库的所有核心步骤。

```python
from yai_nexus_configuration import NexusConfig, nexus_config, NexusConfigManager

# 步骤 1: 定义一个与 JSON 结构匹配的配置类
# @nexus_config 装饰器将类与配置文件关联起来
@nexus_config(data_id="app_config.json", group="DEFAULT_GROUP")
class AppConfig(NexusConfig):
    database_url: str
    retries: int = 3  # 您可以提供默认值
    api_key: str

# 步骤 2: 使用工厂方法创建管理器
# `with` 语句能确保资源被正确管理和释放
with NexusConfigManager.with_file(base_path="configs") as manager:
    # 步骤 3: 向管理器注册您的配置类
    manager.register(AppConfig)

    # 步骤 4: 从管理器中获取类型安全的配置实例
    config = manager.get_config(AppConfig)

# 步骤 5: 像使用普通对象一样使用您的配置
print(f"数据库 URL: {config.database_url}")
print(f"重试次数: {config.retries}")
print(f"API 密钥: {config.api_key}")

# 运行此脚本,您将看到从文件中加载并经过验证的配置!
```

**效果**: 这个“黄金路径”示例清晰地展示了本库的核心设计思想,能帮助您快速上手,避免常见的使用陷阱。

---

## ✨ 主要特性

- 🎯 **简洁优雅的 API** - 采用工厂模式,一行代码创建管理器
- 🔒 **线程安全** - 所有操作都是线程安全的,适用于多线程环境
- 🔄 **自动配置更新** - 实时监听配置源变更,自动更新本地配置
- 🧩 **可扩展架构** - 基于 Provider 模式,轻松支持新的配置源
- ✅ **类型安全** - 完整的类型提示支持,基于 Pydantic 数据验证
- 📦 **零依赖冲突** - 精心设计的依赖管理,避免版本冲突

## 🏗️ 架构设计

YAI Nexus Configuration 采用了经过深度思考的 **方案 E(工厂模式)** 架构:

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   用户代码      │────│  NexusConfigManager    │────│  ConfigStore    │
│                 │    │  (工厂 + 管理)    │    │  (线程安全存储)  │
└─────────────────┘    └──────────┬───────┘    └─────────────────┘
                                  │
                                  ▼
                       ┌──────────────────┐
                       │ AbstractProvider │
                       │    (抽象层)       │
                       └─────────┬────────┘
                                 │
                    ┌────────────┴────────────┐
                    ▼                         ▼
            ┌──────────────┐        ┌──────────────┐
            │ NacosProvider│        │ 未来的Provider│
            │              │        │ (Apollo等)   │
            └──────────────┘        └──────────────┘
```

### 核心优势

- **高内聚,低耦合**: Provider 抽象层完全隔离了配置源实现
- **面向接口编程**: 核心逻辑只依赖抽象接口,便于测试和扩展
- **工厂模式**: 提供简洁的创建接口,隐藏复杂的初始化逻辑
- **单一职责**: 每个组件都有明确的职责边界

## 🔧 支持的配置源

| 配置源 | 状态 | 工厂方法 | 说明 |
|--------|------|----------|------|
| **Nacos** | ✅ 已支持 | `NexusConfigManager.with_nacos()` | 阿里巴巴开源的配置中心 |
| **Apollo** | 🚧 规划中 | `NexusConfigManager.with_apollo()` | 携程开源的配置中心 |
| **Etcd** | 🚧 规划中 | `NexusConfigManager.with_etcd()` | 分布式键值存储 |
| **本地文件** | ✅ 已支持 | `NexusConfigManager.with_file()` | 本地 JSON/YAML/ENV 文件 |

## 📖 详细文档

### 文件配置使用

文件提供者可以根据文件扩展名(`.json` 或 `.yaml`)自动选择解析器。

**1. 定义多个配置类**

```python
from yai_nexus_configuration import NexusConfigManager, NexusConfig, nexus_config

# JSON 配置
@nexus_config(data_id="app.json", group="DEFAULT_GROUP")
class AppConfig(NexusConfig):
    app_name: str
    debug: bool

# YAML 配置 (需要安装 PyYAML)
@nexus_config(data_id="database.yaml", group="PROD")
class DbConfig(NexusConfig):
    host: str
    port: int
```

**2. 使用同一个管理器**

```python
# 只需要一个管理器实例
with NexusConfigManager.with_file(
    base_path="configs",        # 配置文件根目录
    watch_interval=1.0,         # 文件监听间隔(秒)
) as manager:
    
    # 你的文件结构:
    # configs/
    # ├── DEFAULT_GROUP/
    # │   └── app.json
    # └── PROD/
    #     └── database.yaml

    # 批量注册
    manager.register(AppConfig, DbConfig)
    
    # 获取配置
    app_config = manager.get_config(AppConfig)
    db_config = manager.get_config(DbConfig)
    
    print(f"应用: {app_config.app_name}, 数据库主机: {db_config.host}")
```

### Nacos 配置使用

```python
# 创建管理器(建议从环境变量获取敏感信息)
manager = NexusConfigManager.with_nacos(
    server_addresses=os.environ.get("NACOS_SERVER_ADDR"),
    namespace=os.environ.get("NACOS_NAMESPACE"),
    username=os.environ.get("NACOS_USERNAME"),
    password=os.environ.get("NACOS_PASSWORD")
)

# 查看 examples/nacos_example.py 获取最佳实践
```

### 管理器使用

```python
# 创建管理器(以 Nacos 为例)
manager = NexusConfigManager.with_nacos(
    server_addresses="localhost:8848",
    namespace="production",
    username="admin",
    password="admin123"
)

# 批量注册配置
configs = [DatabaseConfig, RedisConfig, AppConfig]
for config_class in configs:
    manager.register(config_class)

# 获取配置(类型安全)
app_config: AppConfig = manager.get_config(AppConfig)

# 检查管理器状态
info = manager.get_manager_info()
print(f"已注册 {info['registered_configs']} 个配置")

# 优雅关闭
manager.close()
```

### 上下文管理器

```python
# 推荐使用 with 语句,自动管理资源
with NexusConfigManager.with_nacos("localhost:8848") as manager:
    manager.register(AppConfig)
    
    app_config = manager.get_config(AppConfig)
    print(f"App: {app_config.app_name}")
    
# 管理器自动关闭,清理所有资源
```

### 配置实时更新

```python
# 配置更新是自动的!
manager.register(AppConfig)

# 在 Nacos 控制台修改配置后...
app_config = manager.get_config(AppConfig)  # 自动获取最新配置

# 也支持手动刷新
updated_config = manager.reload_config(AppConfig)
```

## 🧪 扩展新的配置源

YAI Nexus Configuration 的设计让添加新配置源变得非常简单:

```python
from yai_nexus_configuration.providers import AbstractProvider

class MyCustomProvider(AbstractProvider):
    def __init__(self, config_url: str):
        super().__init__("MyCustom")
        self.config_url = config_url
    
    def connect(self):
        # 实现连接逻辑
        pass
    
    def get_config(self, data_id: str, group: str) -> str:
        # 实现配置获取逻辑
        pass
    
    def watch_config(self, data_id: str, group: str, callback):
        # 实现配置监听逻辑
        pass
    
    # ... 其他必须实现的方法

# 在 NexusConfigManager 中添加工厂方法
@classmethod
def with_my_custom(cls, config_url: str) -> "NexusConfigManager":
    provider = MyCustomProvider(config_url)
    return cls(provider)
```

## 🔍 错误处理

```python
from yai_nexus_configuration import (
    ConfigNotRegisteredError,
    ConfigValidationError,
    ProviderConnectionError
)

try:
    manager = NexusConfigManager.with_nacos("localhost:8848")
    manager.register(DatabaseConfig)
    db_config = manager.get_config(DatabaseConfig)
    
except ProviderConnectionError as e:
    print(f"无法连接到配置源: {e}")
    
except ConfigValidationError as e:
    print(f"配置数据验证失败: {e}")
    
except ConfigNotRegisteredError as e:
    print(f"配置未注册: {e}")
```

## 📦 安装

### 基础安装

```bash
# 最小安装(包含文件和 YAML 支持)
pip install yai-nexus-configuration
```

### 功能扩展安装

```bash
# 安装 Nacos 支持
pip install yai-nexus-configuration[nacos]

# 安装所有功能
pip install yai-nexus-configuration[all]
```

### 开发环境安装

```bash
# 克隆项目
git clone https://github.com/yai-nexus/yai-nexus-configuration.git
cd yai-nexus-configuration

# 安装开发依赖
pip install -r requirements.txt

# 或者使用 pip 安装开发模式
pip install -e ".[dev]"
```

### 快速开始

```bash
# 运行文件配置示例(无外部依赖)
python3 examples/file_example.py

# 运行 Nacos 示例
# 1. 确保 Nacos 服务正在运行,并已按示例文件中的说明创建配置
# 2. 设置环境变量:
#    export NACOS_SERVER_ADDR="your_nacos_address:8848"
#    export NACOS_NAMESPACE="your_namespace" # (可选)
#    export NACOS_USERNAME="nacos"           # (可选)
#    export NACOS_PASSWORD="nacos"         # (可选)
# 3. 运行脚本:
python3 examples/nacos_example.py
```

## 🧑‍💻 开发

### 运行测试

```bash
# 单元测试
pytest tests/

# 覆盖率测试
pytest --cov=src/yai_nexus_configuration tests/
```

## 🎯 设计哲学

YAI Nexus Configuration 的设计遵循以下原则:

1. **简洁胜过复杂** - API 设计力求简洁直观
2. **显式胜过隐式** - 避免魔法方法,所有行为都是可预测的
3. **面向接口编程** - 通过抽象接口实现高度解耦
4. **失败快速暴露** - 配置错误在启动时就会被发现,而不是运行时
5. **类型安全第一** - 完整的类型提示,让 IDE 和工具更好地帮助开发

## 🤝 贡献

我们欢迎任何形式的贡献!

- 🐛 报告 Bug
- 💡 提出新功能建议  
- 📖 改进文档
- 🔧 提交代码改进

请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细的贡献指南。

## 📜 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

## 🙏 致谢

- [Pydantic](https://pydantic-docs.helpmanual.io/) - 提供优秀的数据验证能力
- [nacos-sdk-python](https://github.com/nacos-group/nacos-sdk-python) - Nacos Python SDK
- 所有为这个项目贡献想法和代码的开发者们

---

⭐ 如果这个项目对您有帮助,请给我们一个 Star!

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "yai-nexus-configuration",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": "YAI Team <team@yai.com>",
    "keywords": "configuration, config, nacos, apollo, settings, management, dynamic, provider, pydantic",
    "author": null,
    "author_email": "YAI Team <team@yai.com>",
    "download_url": "https://files.pythonhosted.org/packages/d0/14/9928531597735e791cd8fd32953b62edbd77ae3d79c3afbd12a5dceafc64/yai_nexus_configuration-0.1.1.tar.gz",
    "platform": null,
    "description": "# YAI Nexus Configuration\n\n\ud83d\ude80 **\u9ad8\u8d28\u91cf\u7684 Python \u914d\u7f6e\u7ba1\u7406\u5e93** - \u57fa\u4e8e Provider \u6a21\u5f0f\uff0c\u652f\u6301\u591a\u79cd\u914d\u7f6e\u6e90\n\n![Python](https://img.shields.io/badge/python-3.8+-blue.svg)\n![License](https://img.shields.io/badge/license-MIT-green.svg)\n![Version](https://img.shields.io/badge/version-0.1.0-orange.svg)\n\n## \ud83c\udfac \u5feb\u901f\u4e0a\u624b (Hello, World!)\n\n\u8fd9\u662f\u4f53\u9a8c `yai-nexus-configuration` \u6838\u5fc3\u529f\u80fd\u7684\u6700\u5feb\u65b9\u5f0f\u3002\u6211\u4eec\u5c06\u901a\u8fc7\u4e00\u4e2a\u5b8c\u6574\u7684\u3001\u53ef\u8fd0\u884c\u7684\u793a\u4f8b\uff0c\u5c55\u793a\u201c**\u5b9a\u4e49 -> \u521b\u5efa -> \u6ce8\u518c -> \u83b7\u53d6**\u201d\u7684\u9ec4\u91d1\u8def\u5f84\u3002\n\n### 1. \u9879\u76ee\u7ed3\u6784\n\n\u9996\u5148\uff0c\u8bf7\u50cf\u8fd9\u6837\u7ec4\u7ec7\u60a8\u7684\u9879\u76ee\u6587\u4ef6\uff1a\n\n```\nyour-project/\n\u251c\u2500\u2500 configs/\n\u2502   \u2514\u2500\u2500 DEFAULT_GROUP/\n\u2502       \u2514\u2500\u2500 app_config.json\n\u2514\u2500\u2500 main.py\n```\n\n### 2. \u521b\u5efa\u914d\u7f6e\u6587\u4ef6\n\n\u5728 `configs/DEFAULT_GROUP/` \u76ee\u5f55\u4e0b\u521b\u5efa\u4e00\u4e2a\u540d\u4e3a `app_config.json` \u7684\u6587\u4ef6\uff0c\u5185\u5bb9\u5982\u4e0b\uff1a\n\n```json\n{\n  \"database_url\": \"sqlite:///./test.db\",\n  \"retries\": 5,\n  \"api_key\": \"a-secret-key-from-environment\"\n}\n```\n> **\u63d0\u793a**: \u5728\u672a\u6765\u7684\u7248\u672c\u4e2d\uff0c\u6211\u4eec\u5c06\u652f\u6301 `${VAR}` \u683c\u5f0f\u7684\u73af\u5883\u53d8\u91cf\u81ea\u52a8\u66ff\u6362\uff0c\u4ee5\u589e\u5f3a\u5b89\u5168\u6027\u3002\n\n### 3. \u7f16\u5199 Python \u4ee3\u7801 (`main.py`)\n\n\u73b0\u5728\uff0c\u521b\u5efa `main.py` \u5e76\u590d\u5236\u4ee5\u4e0b\u4ee3\u7801\u3002\u5b83\u5305\u542b\u4e86\u4f7f\u7528\u672c\u5e93\u7684\u6240\u6709\u6838\u5fc3\u6b65\u9aa4\u3002\n\n```python\nfrom yai_nexus_configuration import NexusConfig, nexus_config, NexusConfigManager\n\n# \u6b65\u9aa4 1: \u5b9a\u4e49\u4e00\u4e2a\u4e0e JSON \u7ed3\u6784\u5339\u914d\u7684\u914d\u7f6e\u7c7b\n# @nexus_config \u88c5\u9970\u5668\u5c06\u7c7b\u4e0e\u914d\u7f6e\u6587\u4ef6\u5173\u8054\u8d77\u6765\n@nexus_config(data_id=\"app_config.json\", group=\"DEFAULT_GROUP\")\nclass AppConfig(NexusConfig):\n    database_url: str\n    retries: int = 3  # \u60a8\u53ef\u4ee5\u63d0\u4f9b\u9ed8\u8ba4\u503c\n    api_key: str\n\n# \u6b65\u9aa4 2: \u4f7f\u7528\u5de5\u5382\u65b9\u6cd5\u521b\u5efa\u7ba1\u7406\u5668\n# `with` \u8bed\u53e5\u80fd\u786e\u4fdd\u8d44\u6e90\u88ab\u6b63\u786e\u7ba1\u7406\u548c\u91ca\u653e\nwith NexusConfigManager.with_file(base_path=\"configs\") as manager:\n    # \u6b65\u9aa4 3: \u5411\u7ba1\u7406\u5668\u6ce8\u518c\u60a8\u7684\u914d\u7f6e\u7c7b\n    manager.register(AppConfig)\n\n    # \u6b65\u9aa4 4: \u4ece\u7ba1\u7406\u5668\u4e2d\u83b7\u53d6\u7c7b\u578b\u5b89\u5168\u7684\u914d\u7f6e\u5b9e\u4f8b\n    config = manager.get_config(AppConfig)\n\n# \u6b65\u9aa4 5: \u50cf\u4f7f\u7528\u666e\u901a\u5bf9\u8c61\u4e00\u6837\u4f7f\u7528\u60a8\u7684\u914d\u7f6e\nprint(f\"\u6570\u636e\u5e93 URL: {config.database_url}\")\nprint(f\"\u91cd\u8bd5\u6b21\u6570: {config.retries}\")\nprint(f\"API \u5bc6\u94a5: {config.api_key}\")\n\n# \u8fd0\u884c\u6b64\u811a\u672c\uff0c\u60a8\u5c06\u770b\u5230\u4ece\u6587\u4ef6\u4e2d\u52a0\u8f7d\u5e76\u7ecf\u8fc7\u9a8c\u8bc1\u7684\u914d\u7f6e\uff01\n```\n\n**\u6548\u679c**: \u8fd9\u4e2a\u201c\u9ec4\u91d1\u8def\u5f84\u201d\u793a\u4f8b\u6e05\u6670\u5730\u5c55\u793a\u4e86\u672c\u5e93\u7684\u6838\u5fc3\u8bbe\u8ba1\u601d\u60f3\uff0c\u80fd\u5e2e\u52a9\u60a8\u5feb\u901f\u4e0a\u624b\uff0c\u907f\u514d\u5e38\u89c1\u7684\u4f7f\u7528\u9677\u9631\u3002\n\n---\n\n## \u2728 \u4e3b\u8981\u7279\u6027\n\n- \ud83c\udfaf **\u7b80\u6d01\u4f18\u96c5\u7684 API** - \u91c7\u7528\u5de5\u5382\u6a21\u5f0f\uff0c\u4e00\u884c\u4ee3\u7801\u521b\u5efa\u7ba1\u7406\u5668\n- \ud83d\udd12 **\u7ebf\u7a0b\u5b89\u5168** - \u6240\u6709\u64cd\u4f5c\u90fd\u662f\u7ebf\u7a0b\u5b89\u5168\u7684\uff0c\u9002\u7528\u4e8e\u591a\u7ebf\u7a0b\u73af\u5883\n- \ud83d\udd04 **\u81ea\u52a8\u914d\u7f6e\u66f4\u65b0** - \u5b9e\u65f6\u76d1\u542c\u914d\u7f6e\u6e90\u53d8\u66f4\uff0c\u81ea\u52a8\u66f4\u65b0\u672c\u5730\u914d\u7f6e\n- \ud83e\udde9 **\u53ef\u6269\u5c55\u67b6\u6784** - \u57fa\u4e8e Provider \u6a21\u5f0f\uff0c\u8f7b\u677e\u652f\u6301\u65b0\u7684\u914d\u7f6e\u6e90\n- \u2705 **\u7c7b\u578b\u5b89\u5168** - \u5b8c\u6574\u7684\u7c7b\u578b\u63d0\u793a\u652f\u6301\uff0c\u57fa\u4e8e Pydantic \u6570\u636e\u9a8c\u8bc1\n- \ud83d\udce6 **\u96f6\u4f9d\u8d56\u51b2\u7a81** - \u7cbe\u5fc3\u8bbe\u8ba1\u7684\u4f9d\u8d56\u7ba1\u7406\uff0c\u907f\u514d\u7248\u672c\u51b2\u7a81\n\n## \ud83c\udfd7\ufe0f \u67b6\u6784\u8bbe\u8ba1\n\nYAI Nexus Configuration \u91c7\u7528\u4e86\u7ecf\u8fc7\u6df1\u5ea6\u601d\u8003\u7684 **\u65b9\u6848 E\uff08\u5de5\u5382\u6a21\u5f0f\uff09** \u67b6\u6784\uff1a\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510    \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510    \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502   \u7528\u6237\u4ee3\u7801      \u2502\u2500\u2500\u2500\u2500\u2502  NexusConfigManager    \u2502\u2500\u2500\u2500\u2500\u2502  ConfigStore    \u2502\n\u2502                 \u2502    \u2502  (\u5de5\u5382 + \u7ba1\u7406)    \u2502    \u2502  (\u7ebf\u7a0b\u5b89\u5168\u5b58\u50a8)  \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                                  \u2502\n                                  \u25bc\n                       \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n                       \u2502 AbstractProvider \u2502\n                       \u2502    (\u62bd\u8c61\u5c42)       \u2502\n                       \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                                 \u2502\n                    \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n                    \u25bc                         \u25bc\n            \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510        \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n            \u2502 NacosProvider\u2502        \u2502 \u672a\u6765\u7684Provider\u2502\n            \u2502              \u2502        \u2502 (Apollo\u7b49)   \u2502\n            \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518        \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n### \u6838\u5fc3\u4f18\u52bf\n\n- **\u9ad8\u5185\u805a\uff0c\u4f4e\u8026\u5408**: Provider \u62bd\u8c61\u5c42\u5b8c\u5168\u9694\u79bb\u4e86\u914d\u7f6e\u6e90\u5b9e\u73b0\n- **\u9762\u5411\u63a5\u53e3\u7f16\u7a0b**: \u6838\u5fc3\u903b\u8f91\u53ea\u4f9d\u8d56\u62bd\u8c61\u63a5\u53e3\uff0c\u4fbf\u4e8e\u6d4b\u8bd5\u548c\u6269\u5c55\n- **\u5de5\u5382\u6a21\u5f0f**: \u63d0\u4f9b\u7b80\u6d01\u7684\u521b\u5efa\u63a5\u53e3\uff0c\u9690\u85cf\u590d\u6742\u7684\u521d\u59cb\u5316\u903b\u8f91\n- **\u5355\u4e00\u804c\u8d23**: \u6bcf\u4e2a\u7ec4\u4ef6\u90fd\u6709\u660e\u786e\u7684\u804c\u8d23\u8fb9\u754c\n\n## \ud83d\udd27 \u652f\u6301\u7684\u914d\u7f6e\u6e90\n\n| \u914d\u7f6e\u6e90 | \u72b6\u6001 | \u5de5\u5382\u65b9\u6cd5 | \u8bf4\u660e |\n|--------|------|----------|------|\n| **Nacos** | \u2705 \u5df2\u652f\u6301 | `NexusConfigManager.with_nacos()` | \u963f\u91cc\u5df4\u5df4\u5f00\u6e90\u7684\u914d\u7f6e\u4e2d\u5fc3 |\n| **Apollo** | \ud83d\udea7 \u89c4\u5212\u4e2d | `NexusConfigManager.with_apollo()` | \u643a\u7a0b\u5f00\u6e90\u7684\u914d\u7f6e\u4e2d\u5fc3 |\n| **Etcd** | \ud83d\udea7 \u89c4\u5212\u4e2d | `NexusConfigManager.with_etcd()` | \u5206\u5e03\u5f0f\u952e\u503c\u5b58\u50a8 |\n| **\u672c\u5730\u6587\u4ef6** | \u2705 \u5df2\u652f\u6301 | `NexusConfigManager.with_file()` | \u672c\u5730 JSON/YAML/ENV \u6587\u4ef6 |\n\n## \ud83d\udcd6 \u8be6\u7ec6\u6587\u6863\n\n### \u6587\u4ef6\u914d\u7f6e\u4f7f\u7528\n\n\u6587\u4ef6\u63d0\u4f9b\u8005\u53ef\u4ee5\u6839\u636e\u6587\u4ef6\u6269\u5c55\u540d\uff08`.json` \u6216 `.yaml`\uff09\u81ea\u52a8\u9009\u62e9\u89e3\u6790\u5668\u3002\n\n**1. \u5b9a\u4e49\u591a\u4e2a\u914d\u7f6e\u7c7b**\n\n```python\nfrom yai_nexus_configuration import NexusConfigManager, NexusConfig, nexus_config\n\n# JSON \u914d\u7f6e\n@nexus_config(data_id=\"app.json\", group=\"DEFAULT_GROUP\")\nclass AppConfig(NexusConfig):\n    app_name: str\n    debug: bool\n\n# YAML \u914d\u7f6e (\u9700\u8981\u5b89\u88c5 PyYAML)\n@nexus_config(data_id=\"database.yaml\", group=\"PROD\")\nclass DbConfig(NexusConfig):\n    host: str\n    port: int\n```\n\n**2. \u4f7f\u7528\u540c\u4e00\u4e2a\u7ba1\u7406\u5668**\n\n```python\n# \u53ea\u9700\u8981\u4e00\u4e2a\u7ba1\u7406\u5668\u5b9e\u4f8b\nwith NexusConfigManager.with_file(\n    base_path=\"configs\",        # \u914d\u7f6e\u6587\u4ef6\u6839\u76ee\u5f55\n    watch_interval=1.0,         # \u6587\u4ef6\u76d1\u542c\u95f4\u9694\uff08\u79d2\uff09\n) as manager:\n    \n    # \u4f60\u7684\u6587\u4ef6\u7ed3\u6784:\n    # configs/\n    # \u251c\u2500\u2500 DEFAULT_GROUP/\n    # \u2502   \u2514\u2500\u2500 app.json\n    # \u2514\u2500\u2500 PROD/\n    #     \u2514\u2500\u2500 database.yaml\n\n    # \u6279\u91cf\u6ce8\u518c\n    manager.register(AppConfig, DbConfig)\n    \n    # \u83b7\u53d6\u914d\u7f6e\n    app_config = manager.get_config(AppConfig)\n    db_config = manager.get_config(DbConfig)\n    \n    print(f\"\u5e94\u7528: {app_config.app_name}, \u6570\u636e\u5e93\u4e3b\u673a: {db_config.host}\")\n```\n\n### Nacos \u914d\u7f6e\u4f7f\u7528\n\n```python\n# \u521b\u5efa\u7ba1\u7406\u5668\uff08\u5efa\u8bae\u4ece\u73af\u5883\u53d8\u91cf\u83b7\u53d6\u654f\u611f\u4fe1\u606f\uff09\nmanager = NexusConfigManager.with_nacos(\n    server_addresses=os.environ.get(\"NACOS_SERVER_ADDR\"),\n    namespace=os.environ.get(\"NACOS_NAMESPACE\"),\n    username=os.environ.get(\"NACOS_USERNAME\"),\n    password=os.environ.get(\"NACOS_PASSWORD\")\n)\n\n# \u67e5\u770b examples/nacos_example.py \u83b7\u53d6\u6700\u4f73\u5b9e\u8df5\n```\n\n### \u7ba1\u7406\u5668\u4f7f\u7528\n\n```python\n# \u521b\u5efa\u7ba1\u7406\u5668\uff08\u4ee5 Nacos \u4e3a\u4f8b\uff09\nmanager = NexusConfigManager.with_nacos(\n    server_addresses=\"localhost:8848\",\n    namespace=\"production\",\n    username=\"admin\",\n    password=\"admin123\"\n)\n\n# \u6279\u91cf\u6ce8\u518c\u914d\u7f6e\nconfigs = [DatabaseConfig, RedisConfig, AppConfig]\nfor config_class in configs:\n    manager.register(config_class)\n\n# \u83b7\u53d6\u914d\u7f6e\uff08\u7c7b\u578b\u5b89\u5168\uff09\napp_config: AppConfig = manager.get_config(AppConfig)\n\n# \u68c0\u67e5\u7ba1\u7406\u5668\u72b6\u6001\ninfo = manager.get_manager_info()\nprint(f\"\u5df2\u6ce8\u518c {info['registered_configs']} \u4e2a\u914d\u7f6e\")\n\n# \u4f18\u96c5\u5173\u95ed\nmanager.close()\n```\n\n### \u4e0a\u4e0b\u6587\u7ba1\u7406\u5668\n\n```python\n# \u63a8\u8350\u4f7f\u7528 with \u8bed\u53e5\uff0c\u81ea\u52a8\u7ba1\u7406\u8d44\u6e90\nwith NexusConfigManager.with_nacos(\"localhost:8848\") as manager:\n    manager.register(AppConfig)\n    \n    app_config = manager.get_config(AppConfig)\n    print(f\"App: {app_config.app_name}\")\n    \n# \u7ba1\u7406\u5668\u81ea\u52a8\u5173\u95ed\uff0c\u6e05\u7406\u6240\u6709\u8d44\u6e90\n```\n\n### \u914d\u7f6e\u5b9e\u65f6\u66f4\u65b0\n\n```python\n# \u914d\u7f6e\u66f4\u65b0\u662f\u81ea\u52a8\u7684\uff01\nmanager.register(AppConfig)\n\n# \u5728 Nacos \u63a7\u5236\u53f0\u4fee\u6539\u914d\u7f6e\u540e...\napp_config = manager.get_config(AppConfig)  # \u81ea\u52a8\u83b7\u53d6\u6700\u65b0\u914d\u7f6e\n\n# \u4e5f\u652f\u6301\u624b\u52a8\u5237\u65b0\nupdated_config = manager.reload_config(AppConfig)\n```\n\n## \ud83e\uddea \u6269\u5c55\u65b0\u7684\u914d\u7f6e\u6e90\n\nYAI Nexus Configuration \u7684\u8bbe\u8ba1\u8ba9\u6dfb\u52a0\u65b0\u914d\u7f6e\u6e90\u53d8\u5f97\u975e\u5e38\u7b80\u5355\uff1a\n\n```python\nfrom yai_nexus_configuration.providers import AbstractProvider\n\nclass MyCustomProvider(AbstractProvider):\n    def __init__(self, config_url: str):\n        super().__init__(\"MyCustom\")\n        self.config_url = config_url\n    \n    def connect(self):\n        # \u5b9e\u73b0\u8fde\u63a5\u903b\u8f91\n        pass\n    \n    def get_config(self, data_id: str, group: str) -> str:\n        # \u5b9e\u73b0\u914d\u7f6e\u83b7\u53d6\u903b\u8f91\n        pass\n    \n    def watch_config(self, data_id: str, group: str, callback):\n        # \u5b9e\u73b0\u914d\u7f6e\u76d1\u542c\u903b\u8f91\n        pass\n    \n    # ... \u5176\u4ed6\u5fc5\u987b\u5b9e\u73b0\u7684\u65b9\u6cd5\n\n# \u5728 NexusConfigManager \u4e2d\u6dfb\u52a0\u5de5\u5382\u65b9\u6cd5\n@classmethod\ndef with_my_custom(cls, config_url: str) -> \"NexusConfigManager\":\n    provider = MyCustomProvider(config_url)\n    return cls(provider)\n```\n\n## \ud83d\udd0d \u9519\u8bef\u5904\u7406\n\n```python\nfrom yai_nexus_configuration import (\n    ConfigNotRegisteredError,\n    ConfigValidationError,\n    ProviderConnectionError\n)\n\ntry:\n    manager = NexusConfigManager.with_nacos(\"localhost:8848\")\n    manager.register(DatabaseConfig)\n    db_config = manager.get_config(DatabaseConfig)\n    \nexcept ProviderConnectionError as e:\n    print(f\"\u65e0\u6cd5\u8fde\u63a5\u5230\u914d\u7f6e\u6e90: {e}\")\n    \nexcept ConfigValidationError as e:\n    print(f\"\u914d\u7f6e\u6570\u636e\u9a8c\u8bc1\u5931\u8d25: {e}\")\n    \nexcept ConfigNotRegisteredError as e:\n    print(f\"\u914d\u7f6e\u672a\u6ce8\u518c: {e}\")\n```\n\n## \ud83d\udce6 \u5b89\u88c5\n\n### \u57fa\u7840\u5b89\u88c5\n\n```bash\n# \u6700\u5c0f\u5b89\u88c5\uff08\u5305\u542b\u6587\u4ef6\u548c YAML \u652f\u6301\uff09\npip install yai-nexus-configuration\n```\n\n### \u529f\u80fd\u6269\u5c55\u5b89\u88c5\n\n```bash\n# \u5b89\u88c5 Nacos \u652f\u6301\npip install yai-nexus-configuration[nacos]\n\n# \u5b89\u88c5\u6240\u6709\u529f\u80fd\npip install yai-nexus-configuration[all]\n```\n\n### \u5f00\u53d1\u73af\u5883\u5b89\u88c5\n\n```bash\n# \u514b\u9686\u9879\u76ee\ngit clone https://github.com/yai-nexus/yai-nexus-configuration.git\ncd yai-nexus-configuration\n\n# \u5b89\u88c5\u5f00\u53d1\u4f9d\u8d56\npip install -r requirements.txt\n\n# \u6216\u8005\u4f7f\u7528 pip \u5b89\u88c5\u5f00\u53d1\u6a21\u5f0f\npip install -e \".[dev]\"\n```\n\n### \u5feb\u901f\u5f00\u59cb\n\n```bash\n# \u8fd0\u884c\u6587\u4ef6\u914d\u7f6e\u793a\u4f8b\uff08\u65e0\u5916\u90e8\u4f9d\u8d56\uff09\npython3 examples/file_example.py\n\n# \u8fd0\u884c Nacos \u793a\u4f8b\n# 1. \u786e\u4fdd Nacos \u670d\u52a1\u6b63\u5728\u8fd0\u884c\uff0c\u5e76\u5df2\u6309\u793a\u4f8b\u6587\u4ef6\u4e2d\u7684\u8bf4\u660e\u521b\u5efa\u914d\u7f6e\n# 2. \u8bbe\u7f6e\u73af\u5883\u53d8\u91cf:\n#    export NACOS_SERVER_ADDR=\"your_nacos_address:8848\"\n#    export NACOS_NAMESPACE=\"your_namespace\" # (\u53ef\u9009)\n#    export NACOS_USERNAME=\"nacos\"           # (\u53ef\u9009)\n#    export NACOS_PASSWORD=\"nacos\"         # (\u53ef\u9009)\n# 3. \u8fd0\u884c\u811a\u672c:\npython3 examples/nacos_example.py\n```\n\n## \ud83e\uddd1\u200d\ud83d\udcbb \u5f00\u53d1\n\n### \u8fd0\u884c\u6d4b\u8bd5\n\n```bash\n# \u5355\u5143\u6d4b\u8bd5\npytest tests/\n\n# \u8986\u76d6\u7387\u6d4b\u8bd5\npytest --cov=src/yai_nexus_configuration tests/\n```\n\n## \ud83c\udfaf \u8bbe\u8ba1\u54f2\u5b66\n\nYAI Nexus Configuration \u7684\u8bbe\u8ba1\u9075\u5faa\u4ee5\u4e0b\u539f\u5219\uff1a\n\n1. **\u7b80\u6d01\u80dc\u8fc7\u590d\u6742** - API \u8bbe\u8ba1\u529b\u6c42\u7b80\u6d01\u76f4\u89c2\n2. **\u663e\u5f0f\u80dc\u8fc7\u9690\u5f0f** - \u907f\u514d\u9b54\u6cd5\u65b9\u6cd5\uff0c\u6240\u6709\u884c\u4e3a\u90fd\u662f\u53ef\u9884\u6d4b\u7684\n3. **\u9762\u5411\u63a5\u53e3\u7f16\u7a0b** - \u901a\u8fc7\u62bd\u8c61\u63a5\u53e3\u5b9e\u73b0\u9ad8\u5ea6\u89e3\u8026\n4. **\u5931\u8d25\u5feb\u901f\u66b4\u9732** - \u914d\u7f6e\u9519\u8bef\u5728\u542f\u52a8\u65f6\u5c31\u4f1a\u88ab\u53d1\u73b0\uff0c\u800c\u4e0d\u662f\u8fd0\u884c\u65f6\n5. **\u7c7b\u578b\u5b89\u5168\u7b2c\u4e00** - \u5b8c\u6574\u7684\u7c7b\u578b\u63d0\u793a\uff0c\u8ba9 IDE \u548c\u5de5\u5177\u66f4\u597d\u5730\u5e2e\u52a9\u5f00\u53d1\n\n## \ud83e\udd1d \u8d21\u732e\n\n\u6211\u4eec\u6b22\u8fce\u4efb\u4f55\u5f62\u5f0f\u7684\u8d21\u732e\uff01\n\n- \ud83d\udc1b \u62a5\u544a Bug\n- \ud83d\udca1 \u63d0\u51fa\u65b0\u529f\u80fd\u5efa\u8bae  \n- \ud83d\udcd6 \u6539\u8fdb\u6587\u6863\n- \ud83d\udd27 \u63d0\u4ea4\u4ee3\u7801\u6539\u8fdb\n\n\u8bf7\u67e5\u770b [CONTRIBUTING.md](CONTRIBUTING.md) \u4e86\u89e3\u8be6\u7ec6\u7684\u8d21\u732e\u6307\u5357\u3002\n\n## \ud83d\udcdc \u8bb8\u53ef\u8bc1\n\n\u672c\u9879\u76ee\u91c7\u7528 MIT \u8bb8\u53ef\u8bc1 - \u8be6\u89c1 [LICENSE](LICENSE) \u6587\u4ef6\u3002\n\n## \ud83d\ude4f \u81f4\u8c22\n\n- [Pydantic](https://pydantic-docs.helpmanual.io/) - \u63d0\u4f9b\u4f18\u79c0\u7684\u6570\u636e\u9a8c\u8bc1\u80fd\u529b\n- [nacos-sdk-python](https://github.com/nacos-group/nacos-sdk-python) - Nacos Python SDK\n- \u6240\u6709\u4e3a\u8fd9\u4e2a\u9879\u76ee\u8d21\u732e\u60f3\u6cd5\u548c\u4ee3\u7801\u7684\u5f00\u53d1\u8005\u4eec\n\n---\n\n\u2b50 \u5982\u679c\u8fd9\u4e2a\u9879\u76ee\u5bf9\u60a8\u6709\u5e2e\u52a9\uff0c\u8bf7\u7ed9\u6211\u4eec\u4e00\u4e2a Star\uff01\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "\u9ad8\u8d28\u91cf\u7684 Python \u914d\u7f6e\u7ba1\u7406\u5e93 - \u57fa\u4e8e Provider \u6a21\u5f0f\uff0c\u652f\u6301\u591a\u79cd\u914d\u7f6e\u6e90",
    "version": "0.1.1",
    "project_urls": {
        "Bug Tracker": "https://github.com/yai-team/yai-nexus-configuration/issues",
        "Changelog": "https://github.com/yai-team/yai-nexus-configuration/blob/main/CHANGELOG.md",
        "Documentation": "https://yai-nexus-configuration.readthedocs.io/",
        "Homepage": "https://github.com/yai-team/yai-nexus-configuration",
        "Repository": "https://github.com/yai-team/yai-nexus-configuration.git"
    },
    "split_keywords": [
        "configuration",
        " config",
        " nacos",
        " apollo",
        " settings",
        " management",
        " dynamic",
        " provider",
        " pydantic"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "ebd05ee4abf2606273f7ea0032b0ddc6d265f8540308118fe17322cb787c7216",
                "md5": "9c642ab276808e3c4a831f934fe767eb",
                "sha256": "b5369c74f58deb59b50458cae121279620bc967bbe51662ee8418a89a8380267"
            },
            "downloads": -1,
            "filename": "yai_nexus_configuration-0.1.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "9c642ab276808e3c4a831f934fe767eb",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 25783,
            "upload_time": "2025-07-08T10:33:33",
            "upload_time_iso_8601": "2025-07-08T10:33:33.185287Z",
            "url": "https://files.pythonhosted.org/packages/eb/d0/5ee4abf2606273f7ea0032b0ddc6d265f8540308118fe17322cb787c7216/yai_nexus_configuration-0.1.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "d0149928531597735e791cd8fd32953b62edbd77ae3d79c3afbd12a5dceafc64",
                "md5": "1e70e17d0b5437cd3e03ed4fe6e66b5f",
                "sha256": "4231370e2a2dafcb41cede3bf9c0d2a93a4ed97d9f55776371ddfa2285e06716"
            },
            "downloads": -1,
            "filename": "yai_nexus_configuration-0.1.1.tar.gz",
            "has_sig": false,
            "md5_digest": "1e70e17d0b5437cd3e03ed4fe6e66b5f",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 24967,
            "upload_time": "2025-07-08T10:33:34",
            "upload_time_iso_8601": "2025-07-08T10:33:34.256341Z",
            "url": "https://files.pythonhosted.org/packages/d0/14/9928531597735e791cd8fd32953b62edbd77ae3d79c3afbd12a5dceafc64/yai_nexus_configuration-0.1.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-08 10:33:34",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "yai-team",
    "github_project": "yai-nexus-configuration",
    "github_not_found": true,
    "lcname": "yai-nexus-configuration"
}
        
Elapsed time: 1.57151s