nacos-toolkit 0.1.0__tar.gz

nacos_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,278 @@
+Metadata-Version: 2.4
+Name: nacos-toolkit
+Version: 0.1.0
+Summary: Nacos configuration parsing and management tool
+Keywords: nacos,config,configuration,template,yaml
+Author: nacos-toolkit contributors
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: nacos-sdk-python>=1.0.0
+Requires-Dist: loguru>=0.7.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://pypi.org/project/nacos-toolkit/
+Description-Content-Type: text/markdown
+
+# nacos-toolkit
+
+Nacos 配置解析与管理工具。
+
+支持从 Nacos 服务端拉取配置、`${VAR}` 模板变量渲染、多配置深度合并、本地配置文件读取。
+
+## 安装
+
+```bash
+uv add nacos-toolkit
+```
+
+或使用 pip：
+
+```bash
+pip install nacos-toolkit
+```
+
+## 快速开始
+
+### 从 Nacos 获取配置
+
+```python
+import asyncio
+from nacos_toolkit import get_nacos_config
+
+async def main():
+    result = await get_nacos_config(
+        connection={
+            "server_addr": "nacos-server:8848",
+            "namespace": "production",
+            "username": "nacos",
+            "password": "nacos",
+        },
+        base_configs=[
+            {"data_id": "common.yml", "group": "DEFAULT_GROUP"},
+            {"data_id": "app.yml", "group": "DEFAULT_GROUP"},
+        ],
+    )
+    print(result["config"])
+
+asyncio.run(main())
+```
+
+**处理流程：**
+
+1. 按顺序拉取所有 `base_configs` 的内容
+2. 浅合并所有配置，作为模板变量上下文
+3. 仅处理最后一个配置文件，渲染其中的 `${VAR}` 模板
+4. 自动注入 `DEPLOY_ENV = namespace`
+
+### 带覆盖配置
+
+```python
+result = await get_nacos_config(
+    connection={...},
+    base_configs=[
+        {"data_id": "common.yml", "group": "DEFAULT_GROUP"},
+        {"data_id": "app.yml", "group": "DEFAULT_GROUP"},
+    ],
+    override_config={
+        "data_id": "app-customized.yml",
+        "group": "DEFAULT_GROUP",
+    },
+)
+```
+
+覆盖配置会与基础配置深度合并，覆盖配置的值优先。
+
+### Debug 模式
+
+```python
+result = await get_nacos_config(
+    connection={...},
+    base_configs=[...],
+    debug=True,
+)
+print(result["config"])  # 处理后的配置
+print(result["raw"])     # 合并后的原始配置（未经模板渲染）
+```
+
+## 配置处理工具
+
+### 处理 YAML/JSON 配置
+
+```python
+from nacos_toolkit import NacosConfigUtils, NacosParser
+
+# 处理 YAML 配置（默认格式）
+config = NacosConfigUtils.process_configuration(
+    """
+    server:
+      host: ${HOST}
+      port: ${PORT}
+    database:
+      url: ${DB_HOST}:3306
+    """,
+    external_vars={
+        "HOST": "localhost",
+        "PORT": "8080",
+        "DB_HOST": "mysql-server",
+    },
+)
+# config = {"server": {"host": "localhost", "port": "8080"}, "database": {"url": "mysql-server:3306"}}
+
+# 处理 JSON 配置
+config = NacosConfigUtils.process_configuration(
+    '{"name": "${APP_NAME}"}',
+    fmt=NacosParser.JSON,
+    external_vars={"APP_NAME": "my-app"},
+)
+```
+
+**模板特性：**
+
+- 支持 `${VAR}` 语法
+- 支持点号嵌套引用：`${redis.hostname}`
+- 支持嵌套模板解析：`${URL}` -> `${PROTO}://${HOST}` -> `https://example.com`
+- 最大渲染深度 5 层，防止无限循环
+- 未定义的变量保持原样 `${UNKNOWN}`
+
+### 合并自定义配置
+
+```python
+base = {"host": "localhost", "port": 3000, "cors": {"whitelist": ["http://a.com"]}}
+
+merged = NacosConfigUtils.process_and_merge_custom_config(
+    base,
+    """
+    port: 9999
+    cors:
+      whitelist:
+        - http://b.com
+        - http://c.com
+    """,
+)
+# merged = {"host": "localhost", "port": 9999, "cors": {"whitelist": ["http://b.com", "http://c.com"]}}
+```
+
+**合并规则：**
+
+- 字典深度合并
+- 数组直接替换（不做元素合并）
+- 自定义配置中可使用基础配置的变量
+
+### 逗号分隔字符串自动转数组
+
+默认会将 `cors.whitelist` 字段的逗号分隔字符串转为数组：
+
+```python
+config = NacosConfigUtils.process_configuration(
+    "cors:\n  whitelist: 'http://a.com, http://b.com'"
+)
+# config["cors"]["whitelist"] = ["http://a.com", "http://b.com"]
+
+# 自定义需要转换的字段
+config = NacosConfigUtils.process_configuration(
+    "tags: 'a, b, c'",
+    convert_array_fields=["tags"],
+)
+# config["tags"] = ["a", "b", "c"]
+```
+
+如果值是 YAML 数组格式则保持不变，不会重复处理。
+
+## 配置监听
+
+```python
+from nacos_toolkit import setup_config_listener
+
+def on_update(content: str):
+    print(f"配置已更新: {content}")
+
+setup_config_listener(
+    nacos_config={
+        "server_addr": "nacos-server:8848",
+        "namespace": "production",
+        "username": "nacos",
+        "password": "nacos",
+    },
+    listen_requests=[
+        {"data_id": "app.yml", "group": "DEFAULT_GROUP"},
+    ],
+    callback=on_update,
+)
+```
+
+不传 `callback` 时，默认自动更新缓存中的配置。
+
+## 本地配置文件
+
+```python
+from nacos_toolkit import get_local_config, find_local_config, parse_config_file
+
+# 自动查找并解析（按 .json -> .yaml -> .yml 优先级）
+config = get_local_config(file_name="app", file_path="./config")
+
+# 仅查找文件路径
+path = find_local_config(file_name="app", file_path="./config")
+# path = "/abs/path/config/app.yml" 或 None
+
+# 解析指定文件
+config = parse_config_file(file_path="/path/to/config.yml")
+```
+
+## 底层工具
+
+```python
+from nacos_toolkit import NacosConfigUtils, ConfigMerger, TemplateEngine
+
+# 深度合并
+merged = ConfigMerger.merge({"a": 1, "b": {"x": 1}}, {"b": {"y": 2}, "c": 3})
+# {"a": 1, "b": {"x": 1, "y": 2}, "c": 3}
+
+# 嵌套属性访问
+val = NacosConfigUtils.get_nested_property({"a": {"b": {"c": 42}}}, "a.b.c")
+# 42
+
+# 嵌套属性设置
+obj = {}
+NacosConfigUtils.set_nested_property(obj, "a.b.c", 42)
+# obj = {"a": {"b": {"c": 42}}}
+
+# 模板检测
+TemplateEngine.contains_template("${HOST}")  # True
+TemplateEngine.contains_template("plain")    # False
+```
+
+## 开发
+
+```bash
+# 安装依赖
+uv sync
+
+# 运行测试
+uv run pytest -v
+
+# 代码检查
+uv run ruff check .
+```
+
+## API 一览
+
+| 函数 / 类 | 说明 |
+|---|---|
+| `await get_nacos_config(...)` | 从 Nacos 拉取并处理配置 |
+| `setup_config_listener(...)` | 监听 Nacos 配置变更 |
+| `get_local_config(...)` | 读取本地配置文件 |
+| `NacosConfigUtils.process_configuration()` | 解析配置 + 渲染模板 |
+| `NacosConfigUtils.process_and_merge_custom_config()` | 处理并合并自定义配置 |
+| `NacosConfigUtils.merge_configurations()` | 深度合并两个配置 |
+| `NacosConfigUtils.contains_template()` | 检测字符串是否包含模板 |
+| `NacosConfigUtils.convert_string_fields_to_arrays()` | 逗号字符串转数组 |
+| `NacosConfigUtils.get_nested_property()` | 点号路径读取嵌套属性 |
+| `NacosConfigUtils.set_nested_property()` | 点号路径设置嵌套属性 |
+| `find_local_config(...)` | 查找本地配置文件路径 |
+| `parse_config_file(...)` | 解析 JSON/YAML 文件 |
+| `NacosParser.YAML / .JSON` | 配置格式枚举 |

nacos_toolkit-0.1.0/README.md

@@ -0,0 +1,258 @@
+# nacos-toolkit
+
+Nacos 配置解析与管理工具。
+
+支持从 Nacos 服务端拉取配置、`${VAR}` 模板变量渲染、多配置深度合并、本地配置文件读取。
+
+## 安装
+
+```bash
+uv add nacos-toolkit
+```
+
+或使用 pip：
+
+```bash
+pip install nacos-toolkit
+```
+
+## 快速开始
+
+### 从 Nacos 获取配置
+
+```python
+import asyncio
+from nacos_toolkit import get_nacos_config
+
+async def main():
+    result = await get_nacos_config(
+        connection={
+            "server_addr": "nacos-server:8848",
+            "namespace": "production",
+            "username": "nacos",
+            "password": "nacos",
+        },
+        base_configs=[
+            {"data_id": "common.yml", "group": "DEFAULT_GROUP"},
+            {"data_id": "app.yml", "group": "DEFAULT_GROUP"},
+        ],
+    )
+    print(result["config"])
+
+asyncio.run(main())
+```
+
+**处理流程：**
+
+1. 按顺序拉取所有 `base_configs` 的内容
+2. 浅合并所有配置，作为模板变量上下文
+3. 仅处理最后一个配置文件，渲染其中的 `${VAR}` 模板
+4. 自动注入 `DEPLOY_ENV = namespace`
+
+### 带覆盖配置
+
+```python
+result = await get_nacos_config(
+    connection={...},
+    base_configs=[
+        {"data_id": "common.yml", "group": "DEFAULT_GROUP"},
+        {"data_id": "app.yml", "group": "DEFAULT_GROUP"},
+    ],
+    override_config={
+        "data_id": "app-customized.yml",
+        "group": "DEFAULT_GROUP",
+    },
+)
+```
+
+覆盖配置会与基础配置深度合并，覆盖配置的值优先。
+
+### Debug 模式
+
+```python
+result = await get_nacos_config(
+    connection={...},
+    base_configs=[...],
+    debug=True,
+)
+print(result["config"])  # 处理后的配置
+print(result["raw"])     # 合并后的原始配置（未经模板渲染）
+```
+
+## 配置处理工具
+
+### 处理 YAML/JSON 配置
+
+```python
+from nacos_toolkit import NacosConfigUtils, NacosParser
+
+# 处理 YAML 配置（默认格式）
+config = NacosConfigUtils.process_configuration(
+    """
+    server:
+      host: ${HOST}
+      port: ${PORT}
+    database:
+      url: ${DB_HOST}:3306
+    """,
+    external_vars={
+        "HOST": "localhost",
+        "PORT": "8080",
+        "DB_HOST": "mysql-server",
+    },
+)
+# config = {"server": {"host": "localhost", "port": "8080"}, "database": {"url": "mysql-server:3306"}}
+
+# 处理 JSON 配置
+config = NacosConfigUtils.process_configuration(
+    '{"name": "${APP_NAME}"}',
+    fmt=NacosParser.JSON,
+    external_vars={"APP_NAME": "my-app"},
+)
+```
+
+**模板特性：**
+
+- 支持 `${VAR}` 语法
+- 支持点号嵌套引用：`${redis.hostname}`
+- 支持嵌套模板解析：`${URL}` -> `${PROTO}://${HOST}` -> `https://example.com`
+- 最大渲染深度 5 层，防止无限循环
+- 未定义的变量保持原样 `${UNKNOWN}`
+
+### 合并自定义配置
+
+```python
+base = {"host": "localhost", "port": 3000, "cors": {"whitelist": ["http://a.com"]}}
+
+merged = NacosConfigUtils.process_and_merge_custom_config(
+    base,
+    """
+    port: 9999
+    cors:
+      whitelist:
+        - http://b.com
+        - http://c.com
+    """,
+)
+# merged = {"host": "localhost", "port": 9999, "cors": {"whitelist": ["http://b.com", "http://c.com"]}}
+```
+
+**合并规则：**
+
+- 字典深度合并
+- 数组直接替换（不做元素合并）
+- 自定义配置中可使用基础配置的变量
+
+### 逗号分隔字符串自动转数组
+
+默认会将 `cors.whitelist` 字段的逗号分隔字符串转为数组：
+
+```python
+config = NacosConfigUtils.process_configuration(
+    "cors:\n  whitelist: 'http://a.com, http://b.com'"
+)
+# config["cors"]["whitelist"] = ["http://a.com", "http://b.com"]
+
+# 自定义需要转换的字段
+config = NacosConfigUtils.process_configuration(
+    "tags: 'a, b, c'",
+    convert_array_fields=["tags"],
+)
+# config["tags"] = ["a", "b", "c"]
+```
+
+如果值是 YAML 数组格式则保持不变，不会重复处理。
+
+## 配置监听
+
+```python
+from nacos_toolkit import setup_config_listener
+
+def on_update(content: str):
+    print(f"配置已更新: {content}")
+
+setup_config_listener(
+    nacos_config={
+        "server_addr": "nacos-server:8848",
+        "namespace": "production",
+        "username": "nacos",
+        "password": "nacos",
+    },
+    listen_requests=[
+        {"data_id": "app.yml", "group": "DEFAULT_GROUP"},
+    ],
+    callback=on_update,
+)
+```
+
+不传 `callback` 时，默认自动更新缓存中的配置。
+
+## 本地配置文件
+
+```python
+from nacos_toolkit import get_local_config, find_local_config, parse_config_file
+
+# 自动查找并解析（按 .json -> .yaml -> .yml 优先级）
+config = get_local_config(file_name="app", file_path="./config")
+
+# 仅查找文件路径
+path = find_local_config(file_name="app", file_path="./config")
+# path = "/abs/path/config/app.yml" 或 None
+
+# 解析指定文件
+config = parse_config_file(file_path="/path/to/config.yml")
+```
+
+## 底层工具
+
+```python
+from nacos_toolkit import NacosConfigUtils, ConfigMerger, TemplateEngine
+
+# 深度合并
+merged = ConfigMerger.merge({"a": 1, "b": {"x": 1}}, {"b": {"y": 2}, "c": 3})
+# {"a": 1, "b": {"x": 1, "y": 2}, "c": 3}
+
+# 嵌套属性访问
+val = NacosConfigUtils.get_nested_property({"a": {"b": {"c": 42}}}, "a.b.c")
+# 42
+
+# 嵌套属性设置
+obj = {}
+NacosConfigUtils.set_nested_property(obj, "a.b.c", 42)
+# obj = {"a": {"b": {"c": 42}}}
+
+# 模板检测
+TemplateEngine.contains_template("${HOST}")  # True
+TemplateEngine.contains_template("plain")    # False
+```
+
+## 开发
+
+```bash
+# 安装依赖
+uv sync
+
+# 运行测试
+uv run pytest -v
+
+# 代码检查
+uv run ruff check .
+```
+
+## API 一览
+
+| 函数 / 类 | 说明 |
+|---|---|
+| `await get_nacos_config(...)` | 从 Nacos 拉取并处理配置 |
+| `setup_config_listener(...)` | 监听 Nacos 配置变更 |
+| `get_local_config(...)` | 读取本地配置文件 |
+| `NacosConfigUtils.process_configuration()` | 解析配置 + 渲染模板 |
+| `NacosConfigUtils.process_and_merge_custom_config()` | 处理并合并自定义配置 |
+| `NacosConfigUtils.merge_configurations()` | 深度合并两个配置 |
+| `NacosConfigUtils.contains_template()` | 检测字符串是否包含模板 |
+| `NacosConfigUtils.convert_string_fields_to_arrays()` | 逗号字符串转数组 |
+| `NacosConfigUtils.get_nested_property()` | 点号路径读取嵌套属性 |
+| `NacosConfigUtils.set_nested_property()` | 点号路径设置嵌套属性 |
+| `find_local_config(...)` | 查找本地配置文件路径 |
+| `parse_config_file(...)` | 解析 JSON/YAML 文件 |
+| `NacosParser.YAML / .JSON` | 配置格式枚举 |

nacos_toolkit-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "nacos-toolkit"
+version = "0.1.0"
+description = "Nacos configuration parsing and management tool"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "nacos-toolkit contributors" }
+]
+requires-python = ">=3.12"
+keywords = ["nacos", "config", "configuration", "template", "yaml"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "pyyaml>=6.0",
+    "nacos-sdk-python>=1.0.0",
+    "loguru>=0.7.0",
+]
+
+[project.urls]
+Homepage = "https://pypi.org/project/nacos-toolkit/"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=1.3.0",
+    "ruff>=0.9.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.3,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

nacos_toolkit-0.1.0/src/nacos_toolkit/__init__.py

@@ -0,0 +1,20 @@
+from nacos_toolkit.local_config import find_local_config, get_local_config, parse_config_file
+from nacos_toolkit.manager import NacosConfigManager, get_nacos_config, setup_config_listener
+from nacos_toolkit.merger import ConfigMerger
+from nacos_toolkit.parser import ConfigParser, NacosParser
+from nacos_toolkit.template import TemplateEngine
+from nacos_toolkit.utils import NacosConfigUtils
+
+__all__ = [
+    "ConfigMerger",
+    "ConfigParser",
+    "NacosConfigManager",
+    "NacosConfigUtils",
+    "NacosParser",
+    "TemplateEngine",
+    "find_local_config",
+    "get_local_config",
+    "get_nacos_config",
+    "parse_config_file",
+    "setup_config_listener",
+]

nacos_toolkit-0.1.0/src/nacos_toolkit/local_config.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+from loguru import logger
+
+_CONFIG_EXTENSIONS = [".json", ".yaml", ".yml"]
+
+
+def find_local_config(*, file_name: str, file_path: str) -> str | None:
+    dir_path = Path(file_path).resolve()
+    for ext in _CONFIG_EXTENSIONS:
+        config_path = dir_path / f"{file_name}{ext}"
+        if config_path.exists():
+            return str(config_path)
+    return None
+
+
+def parse_config_file(*, file_path: str) -> dict[str, Any]:
+    p = Path(file_path)
+    ext = p.suffix.lower()
+    content = p.read_text(encoding="utf-8")
+
+    if ext == ".json":
+        return json.loads(content)
+    if ext in (".yaml", ".yml"):
+        return yaml.safe_load(content)
+    raise ValueError(f"Unsupported file format: {ext}")
+
+
+def get_local_config(*, file_name: str, file_path: str) -> dict[str, Any] | None:
+    if not file_name:
+        return None
+
+    local_path = find_local_config(file_name=file_name, file_path=file_path)
+    if not local_path:
+        logger.warning(f"No local configuration found for {file_name}")
+        return None
+
+    return parse_config_file(file_path=local_path)

nacos_toolkit-0.1.0/src/nacos_toolkit/manager.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+from loguru import logger
+
+from nacos_toolkit.parser import NacosParser
+from nacos_toolkit.utils import NacosConfigUtils
+
+
+class NacosConfigManager:
+    _instance: NacosConfigManager | None = None
+
+    def __init__(self) -> None:
+        self._client: Any = None
+        self._config_cache: dict[str, Any] | None = None
+        self._raw_config: dict[str, Any] | None = None
+
+    @classmethod
+    def get_instance(cls) -> NacosConfigManager:
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    def _create_client(self, config: dict[str, str]) -> Any:
+        import nacos
+
+        return nacos.NacosClient(
+            server_addresses=config["server_addr"],
+            namespace=config["namespace"],
+            username=config["username"],
+            password=config["password"],
+        )
+
+    def _init_client(self, config: dict[str, str]) -> Any:
+        if self._client is None:
+            self._client = self._create_client(config)
+        return self._client
+
+    async def get_config(
+        self,
+        connection: dict[str, str],
+        base_configs: list[dict[str, str]],
+        override_config: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        if self._config_cache is not None:
+            return self._config_cache
+
+        client = self._init_client(connection)
+
+        try:
+            config_contents: list[str] = []
+            for cfg in base_configs:
+                content = await client.get_config(cfg["data_id"], cfg["group"])
+                config_contents.append(content)
+
+            all_data: dict[str, Any] = {}
+            for content in config_contents:
+                parsed = yaml.safe_load(content)
+                if isinstance(parsed, dict):
+                    all_data.update(parsed)
+
+            last_content = config_contents[-1]
+            last_config = yaml.safe_load(last_content)
+            if not isinstance(last_config, dict):
+                last_config = {}
+
+            self._raw_config = all_data
+
+            self._config_cache = NacosConfigUtils.process_configuration(
+                last_config,
+                fmt=NacosParser.JSON,
+                external_vars={**all_data, "DEPLOY_ENV": connection["namespace"]},
+            )
+
+            if override_config and override_config.get("data_id"):
+                custom_content = await client.get_config(override_config["data_id"], override_config["group"])
+                fmt = _determine_format(override_config["data_id"])
+                self._config_cache = NacosConfigUtils.process_and_merge_custom_config(
+                    self._config_cache,
+                    custom_content,
+                    fmt=fmt,
+                    external_vars={**all_data, "DEPLOY_ENV": connection["namespace"]},
+                )
+
+            return self._config_cache
+
+        except Exception as e:
+            logger.error(f"Failed to fetch Nacos config: {e}")
+            raise
+
+    def clear_cache(self) -> None:
+        self._config_cache = None
+        self._raw_config = None
+
+    def get_raw_config(self) -> dict[str, Any] | None:
+        return self._raw_config
+
+
+async def get_nacos_config(
+    *,
+    connection: dict[str, str],
+    base_configs: list[dict[str, str]],
+    override_config: dict[str, str] | None = None,
+    debug: bool = False,
+) -> dict[str, Any]:
+    mgr = NacosConfigManager.get_instance()
+    config = await mgr.get_config(connection, base_configs, override_config)
+    result: dict[str, Any] = {"config": config}
+    if debug:
+        result["raw"] = mgr.get_raw_config()
+    return result
+
+
+def setup_config_listener(
+    *,
+    nacos_config: dict[str, str],
+    listen_requests: list[dict[str, str]],
+    callback: Any = None,
+) -> None:
+    mgr = NacosConfigManager.get_instance()
+    client = mgr._init_client(nacos_config)
+
+    for req in listen_requests:
+        data_id = req["data_id"]
+        group = req["group"]
+
+        def _on_change(content: str, _data_id: str = data_id) -> None:
+            logger.info(f"[Nacos] Config updated: {_data_id}")
+            if callback:
+                callback(content)
+            else:
+                parsed = yaml.safe_load(content)
+                if isinstance(parsed, dict) and mgr._config_cache is not None:
+                    mgr._config_cache.update(parsed)
+
+        client.subscribe(data_id, group, _on_change)
+
+
+def _determine_format(data_id: str) -> NacosParser:
+    if data_id.endswith(".json"):
+        return NacosParser.JSON
+    return NacosParser.YAML

nacos_toolkit-0.1.0/src/nacos_toolkit/merger.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+
+class ConfigMerger:
+    @staticmethod
+    def merge(base: dict[str, Any], custom: dict[str, Any] | None) -> dict[str, Any]:
+        if custom is None:
+            custom = {}
+        return _deep_merge(copy.deepcopy(base), custom)
+
+
+def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    for key, value in override.items():
+        if key in base and isinstance(base[key], dict) and isinstance(value, dict):
+            base[key] = _deep_merge(base[key], value)
+        else:
+            base[key] = copy.deepcopy(value)
+    return base

nacos_toolkit-0.1.0/src/nacos_toolkit/parser.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import json
+from enum import StrEnum
+from typing import Any
+
+import yaml
+from loguru import logger
+
+
+class NacosParser(StrEnum):
+    YAML = ".yml"
+    JSON = ".json"
+
+
+class ConfigParser:
+    @staticmethod
+    def parse(raw: str | dict, fmt: NacosParser) -> dict[str, Any]:
+        try:
+            if fmt == NacosParser.JSON:
+                if isinstance(raw, str):
+                    return json.loads(raw)
+                return dict(raw)
+            result = yaml.safe_load(raw)
+            if not isinstance(result, dict):
+                return {}
+            return result
+        except Exception:
+            logger.warning("Failed to parse config, returning empty dict")
+            return {}

nacos_toolkit-0.1.0/src/nacos_toolkit/template.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import re
+from collections import deque
+from typing import Any
+
+_TEMPLATE_PATTERN = re.compile(r"\$\{([^}]+)\}")
+
+MAX_RENDER_DEPTH = 5
+
+
+def _get_nested_property(obj: Any, path: str) -> Any:
+    keys = path.split(".")
+    result = obj
+    for key in keys:
+        if result is None:
+            return None
+        if isinstance(result, dict):
+            result = result.get(key)
+        else:
+            return None
+    return result
+
+
+def _set_nested_property(obj: dict, path: str, value: Any) -> None:
+    keys = path.split(".")
+    current = obj
+    for key in keys[:-1]:
+        if key not in current or not isinstance(current[key], dict):
+            current[key] = {}
+        current = current[key]
+    current[keys[-1]] = value
+
+
+class TemplateEngine:
+    @staticmethod
+    def contains_template(text: str) -> bool:
+        return bool(_TEMPLATE_PATTERN.search(text))
+
+    @staticmethod
+    def is_text_only(value: Any) -> bool:
+        if not isinstance(value, str):
+            return True
+        return not _TEMPLATE_PATTERN.search(value)
+
+    @staticmethod
+    def render_text(text: str, context: dict[str, Any]) -> str:
+        current = text
+        for _ in range(MAX_RENDER_DEPTH):
+            previous = current
+
+            def _replace(m: re.Match) -> str:
+                key = m.group(1)
+                val = _get_nested_property(context, key)
+                if val is None:
+                    return m.group(0)
+                return str(val)
+
+            current = _TEMPLATE_PATTERN.sub(_replace, current)
+            if current == previous:
+                break
+        return current
+
+    @staticmethod
+    def render(config: dict[str, Any], context: dict[str, Any]) -> dict[str, Any]:
+        # Extract all template params first
+        params = _extract_template_params(config)
+        enriched_context = {**context}
+
+        # Resolve each param in context
+        for param in params:
+            val = _get_nested_property(context, param)
+            while isinstance(val, str) and not TemplateEngine.is_text_only(val):
+                new_val = TemplateEngine.render_text(val, context)
+                if new_val == val:
+                    break
+                val = new_val
+            _set_nested_property(enriched_context, param, val)
+
+        # BFS traversal to render all string values
+        root: dict[str, Any] = {**config}
+        seen: set[int] = set()
+        queue: deque[tuple[dict, str, Any]] = deque()
+        queue.append((root, "", root))
+
+        while queue:
+            parent, key, value = queue.popleft()
+
+            if isinstance(value, str):
+                rendered = TemplateEngine.render_text(value, enriched_context)
+                if key:
+                    parent[key] = rendered
+            elif isinstance(value, list):
+                new_array = []
+                for item in value:
+                    if isinstance(item, str):
+                        new_array.append(TemplateEngine.render_text(item, enriched_context))
+                    elif isinstance(item, dict):
+                        copy = {**item}
+                        queue.append((copy, "", copy))
+                        new_array.append(copy)
+                    else:
+                        new_array.append(item)
+                if key:
+                    parent[key] = new_array
+            elif isinstance(value, dict):
+                obj_id = id(value)
+                if obj_id in seen:
+                    continue
+                seen.add(obj_id)
+                for k, v in value.items():
+                    queue.append((value, k, v))
+
+        return root
+
+
+def _extract_template_params(config: Any) -> set[str]:
+    params: set[str] = set()
+
+    def _traverse(obj: Any) -> None:
+        if isinstance(obj, str):
+            for m in _TEMPLATE_PATTERN.finditer(obj):
+                params.add(m.group(1))
+        elif isinstance(obj, list):
+            for item in obj:
+                _traverse(item)
+        elif isinstance(obj, dict):
+            for v in obj.values():
+                _traverse(v)
+
+    _traverse(config)
+    return params

nacos_toolkit-0.1.0/src/nacos_toolkit/utils.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from typing import Any
+
+from nacos_toolkit.merger import ConfigMerger
+from nacos_toolkit.parser import ConfigParser, NacosParser
+from nacos_toolkit.template import TemplateEngine
+
+
+class NacosConfigUtils:
+    @staticmethod
+    def process_configuration(
+        raw_config: str | dict,
+        *,
+        fmt: NacosParser = NacosParser.YAML,
+        external_vars: dict[str, Any] | None = None,
+        convert_array_fields: list[str] | None = None,
+    ) -> dict[str, Any]:
+        if external_vars is None:
+            external_vars = {}
+        if convert_array_fields is None:
+            convert_array_fields = ["cors.whitelist"]
+
+        parsed = ConfigParser.parse(raw_config, fmt)
+        context = {**external_vars, **parsed}
+        result = TemplateEngine.render(parsed, context)
+        return NacosConfigUtils.convert_string_fields_to_arrays(result, convert_array_fields)
+
+    @staticmethod
+    def process_and_merge_custom_config(
+        base_config: dict[str, Any],
+        custom_config: str | dict,
+        *,
+        fmt: NacosParser = NacosParser.YAML,
+        external_vars: dict[str, Any] | None = None,
+        convert_array_fields: list[str] | None = None,
+    ) -> dict[str, Any]:
+        processed_base = {**base_config}
+        merged_vars = {**(external_vars or {}), **processed_base}
+
+        processed_custom = NacosConfigUtils.process_configuration(
+            custom_config,
+            fmt=fmt,
+            external_vars=merged_vars,
+            convert_array_fields=convert_array_fields,
+        )
+        return ConfigMerger.merge(processed_base, processed_custom)
+
+    @staticmethod
+    def merge_configurations(base: dict[str, Any], custom: dict[str, Any] | None) -> dict[str, Any]:
+        return ConfigMerger.merge(base, custom)
+
+    @staticmethod
+    def contains_template(text: str) -> bool:
+        return TemplateEngine.contains_template(text)
+
+    @staticmethod
+    def convert_string_fields_to_arrays(config: dict[str, Any], field_paths: list[str]) -> dict[str, Any]:
+        result = {**config}
+        for path in field_paths:
+            value = NacosConfigUtils.get_nested_property(result, path)
+            if isinstance(value, str) and "," in value:
+                NacosConfigUtils.set_nested_property(result, path, [item.strip() for item in value.split(",")])
+        return result
+
+    @staticmethod
+    def get_nested_property(obj: Any, path: str) -> Any:
+        keys = path.split(".")
+        result = obj
+        for key in keys:
+            if result is None:
+                return None
+            if isinstance(result, dict):
+                result = result.get(key)
+            else:
+                return None
+        return result
+
+    @staticmethod
+    def set_nested_property(obj: dict, path: str, value: Any) -> None:
+        keys = path.split(".")
+        current = obj
+        for key in keys[:-1]:
+            if key not in current or not isinstance(current[key], dict):
+                current[key] = {}
+            current = current[key]
+        current[keys[-1]] = value