xiaoe-config-manager 1.0.0__tar.gz

xiaoe_config_manager-1.0.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: xiaoe-config-manager
+Version: 1.0.0
+Summary: 多进程安全的 JSON 配置文件管理器，支持默认配置、动态重置与进程间自动同步
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/xiaoe/xiaoe-config-manager
+Project-URL: Repository, https://github.com/xiaoe/xiaoe-config-manager
+Keywords: config,configuration,json,multiprocess,thread-safe
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# xiaoe-config-manager
+
+多进程安全的 JSON 配置文件管理器，纯 Python 标准库实现，零外部依赖。
+
+## 特性
+
+- **线程安全** — 内置线程锁，单进程多线程环境下安全读写
+- **多进程安全** — 通过 `multiprocessing.Queue` 双向管道实现主进程与子进程之间的配置自动同步
+- **默认配置** — 支持静态默认字典和动态回调两种方式，配置项缺失时自动补齐
+- **配置重置** — 支持单个 key 或全部配置一键恢复默认值
+- **默认值热更新** — 当默认配置变化时，自动识别用户未修改的项并更新为新默认值
+- **纯标准库** — 无任何第三方依赖，仅使用 `json`、`threading`、`multiprocessing` 等标准库
+
+## 安装
+
+```bash
+pip install xiaoe-config-manager
+```
+
+## 快速开始
+
+### 单进程使用
+
+```python
+from config import Config
+
+# 初始化，指定配置文件名（不含扩展名）
+config = Config("app_config")
+
+# 写入配置
+config.configset("api_url", "https://api.example.com")
+config.configset("timeout", 30)
+
+# 读取配置
+print(config.configget("api_url"))  # https://api.example.com
+
+# 读取全部配置
+all_config = config.configget("all")
+print(all_config)  # {"api_url": "https://api.example.com", "timeout": 30}
+```
+
+### 带默认配置
+
+```python
+from config import Config
+
+defaults = {
+    "host": "0.0.0.0",
+    "port": 8080,
+    "debug": False,
+}
+
+config = Config("server_config", default_config=defaults)
+
+# 配置文件中已有的键保留原值，缺失的键自动用默认值补齐
+print(config.configget("host"))   # "0.0.0.0"
+print(config.configget("port"))   # 8080
+
+# 恢复单个配置项为默认值
+config.configreset("port")
+
+# 恢复全部配置为默认值
+config.configreset("all")
+```
+
+### 使用回调函数动态生成默认配置
+
+```python
+from config import Config
+
+def dynamic_defaults(current_config):
+    """根据当前配置动态生成默认值"""
+    import socket
+    return {
+        "host": "0.0.0.0",
+        "port": 8080,
+        "hostname": socket.gethostname(),
+        "worker_count": 4,
+    }
+
+config = Config(
+    "dynamic_config",
+    default_config_callback=dynamic_defaults,
+    init_use_callback=True,  # 初始化时调用回调
+)
+
+# 重置时会再次调用回调，获取最新的默认值
+config.configreset("all")
+```
+
+## 多进程使用
+
+多进程场景下，**主进程持有 `Config` 单例**，子进程通过 `ConfigInChildProcessPipe` 与主进程通信。主进程需要为每个子进程创建一个 `ConfigInMainProcessPipe` 实例。
+
+### 主进程
+
+```python
+from config import Config, ConfigInMainProcessPipe
+
+# 1. 创建配置单例
+config = Config("my_config", default_config={"workers": 4})
+
+# 2. 为子进程创建主进程端的管道
+main_pipe = ConfigInMainProcessPipe(config)
+
+# 3. 获取队列，传递给子进程
+set_queue, get_queue = main_pipe.get_queues()
+
+# 4. 启动子进程（以 multiprocessing.Process 为例）
+import multiprocessing
+
+def worker(set_q, get_q):
+    from config import ConfigInChildProcessPipe
+    # 5. 为子进程创建子进程端的管道
+    child_config = ConfigInChildProcessPipe(set_q, get_q)
+    child_config.configset("worker_status", "running")
+    child_config.close()
+
+p = multiprocessing.Process(target=worker, args=(set_queue, get_queue))
+p.start()
+p.join()
+
+# 6. 主进程可直接读写配置，修改会自动同步并广播到到子进程。
+# 同样，子进程的修改请求会提交至主进程修改，最后由主进程广播至所有子进程。
+config.configset("master_status", "ok")
+
+# 6. 清理
+main_pipe.close()
+```
+
+### 子进程
+
+```python
+from config import ConfigInChildProcessPipe
+
+def worker(set_queue, get_queue):
+    # 使用主进程传入的队列初始化
+    config = ConfigInChildProcessPipe(set_queue, get_queue)
+
+    # 读取配置（从本地缓存读取，无 I/O 开销）
+    print(config.configget("workers"))  # 4
+
+    # 修改配置（发送消息给主进程，由主进程执行实际写入）
+    config.configset("worker_status", "done")
+
+    # 主进程的修改会自动同步到本地缓存
+
+    # 使用完毕后关闭
+    config.close()
+```
+
+### 架构说明
+
+```
+子进程 configset() ──→ set_queue ──→ 主进程 _loop() ──→ Config.configset()
+                                                              │
+                                                              ▼
+                                                     config_get_queue
+                                                              │
+                                                              ▼
+                                             子进程 _update_config_loop()
+                                             更新本地 self.config 缓存
+```
+
+- 子进程的 `configset()` 和 `configreset()` 不直接写文件，而是通过队列将请求发送给主进程
+- 主进程统一处理所有写操作和文件 I/O，修改后通过广播队列通知所有子进程
+- 子进程的 `configget()` 从本地缓存读取，无跨进程开销
+- 每个子进程需要独立的管道对（一个 `ConfigInMainProcessPipe` + 一个 `ConfigInChildProcessPipe`）
+
+## API 参考
+
+### Config
+
+核心配置类，管理 JSON 文件的读写。
+
+```python
+Config(file_name="config", default_config=None, default_config_callback=None, init_use_callback=True)
+```
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `file_name` | `str` | `"config"` | 配置文件名，不含 `.json` 扩展名 |
+| `default_config` | `dict` | `None` | 默认配置字典，缺失的 key 自动补齐 |
+| `default_config_callback` | `Callable` | `None` | 默认配置回调函数，重置时动态生成默认值。接受当前 config 字典作为参数 |
+| `init_use_callback` | `bool` | `True` | 是否在初始化时调用回调来填充 `default_config` |
+
+**方法：**
+
+| 方法 | 说明 |
+|------|------|
+| `configget(key)` | 获取配置值。`key="all"` 返回全部配置 |
+| `configset(key, value)` | 设置配置值，自动保存到文件并通知子进程 |
+| `configreset(key)` | 恢复默认值。`key="all"` 恢复全部 |
+| `configupdate_config(key, last_value=None)` | 更新默认值，用于版本更新时希望修改软件的默认值。若用户未修改过该 key 则同步为新默认值。需要手动创建一项"{原配置key}_reseted"=False的配置，用于标记是否执行过更新默认值的操作。 |
+| `update_config()` | 向所有已注册的子进程广播当前配置 |
+
+### ConfigInMainProcessPipe
+
+主进程管道接口，在主进程中每个子进程对应创建一个实例。
+
+```python
+ConfigInMainProcessPipe(config: Config)
+```
+
+| 方法 | 说明 |
+|------|------|
+| `get_queues()` | 返回 `(set_queue, get_queue)` 元组，传递给子进程 |
+| `close()` | 关闭管道，停止监听线程 |
+
+### ConfigInChildProcessPipe
+
+子进程配置工具，在子进程中实例化，通过管道与主进程通信。
+
+```python
+ConfigInChildProcessPipe(config_set_queue, config_get_queue)
+```
+
+| 方法 | 说明 |
+|------|------|
+| `configget(key)` | 从本地缓存读取配置值 |
+| `configset(key, value)` | 修改配置（消息发送给主进程执行） |
+| `configreset(key)` | 恢复默认值（消息发送给主进程执行） |
+| `close()` | 关闭管道，停止同步线程 |
+
+## 注意事项
+
+1. **多进程环境下请保持 Config 单例** — 多个 Config 实例同时操作同一文件会导致数据不一致
+2. **子进程中的 ConfigInChildProcessPipe 不直接操作文件** — 所有写操作将发送请求，由主进程统一处理
+3. **使用完毕后请调用 `close()`** — 避免守护线程未正常退出
+4. **配置文件名不含 `.json` 后缀** — 传入 `"myconfig"` 对应文件 `myconfig.json`
+
+## 许可证
+
+MIT

xiaoe_config_manager-1.0.0/README.md

@@ -0,0 +1,234 @@
+# xiaoe-config-manager
+
+多进程安全的 JSON 配置文件管理器，纯 Python 标准库实现，零外部依赖。
+
+## 特性
+
+- **线程安全** — 内置线程锁，单进程多线程环境下安全读写
+- **多进程安全** — 通过 `multiprocessing.Queue` 双向管道实现主进程与子进程之间的配置自动同步
+- **默认配置** — 支持静态默认字典和动态回调两种方式，配置项缺失时自动补齐
+- **配置重置** — 支持单个 key 或全部配置一键恢复默认值
+- **默认值热更新** — 当默认配置变化时，自动识别用户未修改的项并更新为新默认值
+- **纯标准库** — 无任何第三方依赖，仅使用 `json`、`threading`、`multiprocessing` 等标准库
+
+## 安装
+
+```bash
+pip install xiaoe-config-manager
+```
+
+## 快速开始
+
+### 单进程使用
+
+```python
+from config import Config
+
+# 初始化，指定配置文件名（不含扩展名）
+config = Config("app_config")
+
+# 写入配置
+config.configset("api_url", "https://api.example.com")
+config.configset("timeout", 30)
+
+# 读取配置
+print(config.configget("api_url"))  # https://api.example.com
+
+# 读取全部配置
+all_config = config.configget("all")
+print(all_config)  # {"api_url": "https://api.example.com", "timeout": 30}
+```
+
+### 带默认配置
+
+```python
+from config import Config
+
+defaults = {
+    "host": "0.0.0.0",
+    "port": 8080,
+    "debug": False,
+}
+
+config = Config("server_config", default_config=defaults)
+
+# 配置文件中已有的键保留原值，缺失的键自动用默认值补齐
+print(config.configget("host"))   # "0.0.0.0"
+print(config.configget("port"))   # 8080
+
+# 恢复单个配置项为默认值
+config.configreset("port")
+
+# 恢复全部配置为默认值
+config.configreset("all")
+```
+
+### 使用回调函数动态生成默认配置
+
+```python
+from config import Config
+
+def dynamic_defaults(current_config):
+    """根据当前配置动态生成默认值"""
+    import socket
+    return {
+        "host": "0.0.0.0",
+        "port": 8080,
+        "hostname": socket.gethostname(),
+        "worker_count": 4,
+    }
+
+config = Config(
+    "dynamic_config",
+    default_config_callback=dynamic_defaults,
+    init_use_callback=True,  # 初始化时调用回调
+)
+
+# 重置时会再次调用回调，获取最新的默认值
+config.configreset("all")
+```
+
+## 多进程使用
+
+多进程场景下，**主进程持有 `Config` 单例**，子进程通过 `ConfigInChildProcessPipe` 与主进程通信。主进程需要为每个子进程创建一个 `ConfigInMainProcessPipe` 实例。
+
+### 主进程
+
+```python
+from config import Config, ConfigInMainProcessPipe
+
+# 1. 创建配置单例
+config = Config("my_config", default_config={"workers": 4})
+
+# 2. 为子进程创建主进程端的管道
+main_pipe = ConfigInMainProcessPipe(config)
+
+# 3. 获取队列，传递给子进程
+set_queue, get_queue = main_pipe.get_queues()
+
+# 4. 启动子进程（以 multiprocessing.Process 为例）
+import multiprocessing
+
+def worker(set_q, get_q):
+    from config import ConfigInChildProcessPipe
+    # 5. 为子进程创建子进程端的管道
+    child_config = ConfigInChildProcessPipe(set_q, get_q)
+    child_config.configset("worker_status", "running")
+    child_config.close()
+
+p = multiprocessing.Process(target=worker, args=(set_queue, get_queue))
+p.start()
+p.join()
+
+# 6. 主进程可直接读写配置，修改会自动同步并广播到到子进程。
+# 同样，子进程的修改请求会提交至主进程修改，最后由主进程广播至所有子进程。
+config.configset("master_status", "ok")
+
+# 6. 清理
+main_pipe.close()
+```
+
+### 子进程
+
+```python
+from config import ConfigInChildProcessPipe
+
+def worker(set_queue, get_queue):
+    # 使用主进程传入的队列初始化
+    config = ConfigInChildProcessPipe(set_queue, get_queue)
+
+    # 读取配置（从本地缓存读取，无 I/O 开销）
+    print(config.configget("workers"))  # 4
+
+    # 修改配置（发送消息给主进程，由主进程执行实际写入）
+    config.configset("worker_status", "done")
+
+    # 主进程的修改会自动同步到本地缓存
+
+    # 使用完毕后关闭
+    config.close()
+```
+
+### 架构说明
+
+```
+子进程 configset() ──→ set_queue ──→ 主进程 _loop() ──→ Config.configset()
+                                                              │
+                                                              ▼
+                                                     config_get_queue
+                                                              │
+                                                              ▼
+                                             子进程 _update_config_loop()
+                                             更新本地 self.config 缓存
+```
+
+- 子进程的 `configset()` 和 `configreset()` 不直接写文件，而是通过队列将请求发送给主进程
+- 主进程统一处理所有写操作和文件 I/O，修改后通过广播队列通知所有子进程
+- 子进程的 `configget()` 从本地缓存读取，无跨进程开销
+- 每个子进程需要独立的管道对（一个 `ConfigInMainProcessPipe` + 一个 `ConfigInChildProcessPipe`）
+
+## API 参考
+
+### Config
+
+核心配置类，管理 JSON 文件的读写。
+
+```python
+Config(file_name="config", default_config=None, default_config_callback=None, init_use_callback=True)
+```
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `file_name` | `str` | `"config"` | 配置文件名，不含 `.json` 扩展名 |
+| `default_config` | `dict` | `None` | 默认配置字典，缺失的 key 自动补齐 |
+| `default_config_callback` | `Callable` | `None` | 默认配置回调函数，重置时动态生成默认值。接受当前 config 字典作为参数 |
+| `init_use_callback` | `bool` | `True` | 是否在初始化时调用回调来填充 `default_config` |
+
+**方法：**
+
+| 方法 | 说明 |
+|------|------|
+| `configget(key)` | 获取配置值。`key="all"` 返回全部配置 |
+| `configset(key, value)` | 设置配置值，自动保存到文件并通知子进程 |
+| `configreset(key)` | 恢复默认值。`key="all"` 恢复全部 |
+| `configupdate_config(key, last_value=None)` | 更新默认值，用于版本更新时希望修改软件的默认值。若用户未修改过该 key 则同步为新默认值。需要手动创建一项"{原配置key}_reseted"=False的配置，用于标记是否执行过更新默认值的操作。 |
+| `update_config()` | 向所有已注册的子进程广播当前配置 |
+
+### ConfigInMainProcessPipe
+
+主进程管道接口，在主进程中每个子进程对应创建一个实例。
+
+```python
+ConfigInMainProcessPipe(config: Config)
+```
+
+| 方法 | 说明 |
+|------|------|
+| `get_queues()` | 返回 `(set_queue, get_queue)` 元组，传递给子进程 |
+| `close()` | 关闭管道，停止监听线程 |
+
+### ConfigInChildProcessPipe
+
+子进程配置工具，在子进程中实例化，通过管道与主进程通信。
+
+```python
+ConfigInChildProcessPipe(config_set_queue, config_get_queue)
+```
+
+| 方法 | 说明 |
+|------|------|
+| `configget(key)` | 从本地缓存读取配置值 |
+| `configset(key, value)` | 修改配置（消息发送给主进程执行） |
+| `configreset(key)` | 恢复默认值（消息发送给主进程执行） |
+| `close()` | 关闭管道，停止同步线程 |
+
+## 注意事项
+
+1. **多进程环境下请保持 Config 单例** — 多个 Config 实例同时操作同一文件会导致数据不一致
+2. **子进程中的 ConfigInChildProcessPipe 不直接操作文件** — 所有写操作将发送请求，由主进程统一处理
+3. **使用完毕后请调用 `close()`** — 避免守护线程未正常退出
+4. **配置文件名不含 `.json` 后缀** — 传入 `"myconfig"` 对应文件 `myconfig.json`
+
+## 许可证
+
+MIT

xiaoe_config_manager-1.0.0/config/__init__.py

@@ -0,0 +1,10 @@
+"""
+多进程安全配置管理模块
+
+包含：
+- Config 类：配置文件核心操作（可以单独使用，也可以配合 ConfigInMainProcessPipe 和 ConfigInChildProcessPipe 使用）
+- ConfigInMainProcessPipe 类：主进程管道接口(结束时调用close())
+- ConfigInChildProcessPipe 类：子进程操作工具(结束时调用close())
+"""
+from .config import Config
+from .config_multiprocess import ConfigInMainProcessPipe, ConfigInChildProcessPipe

xiaoe_config_manager-1.0.0/config/config.py

@@ -0,0 +1,102 @@
+import copy
+import json
+import threading
+from typing import Callable
+
+
+class Config:
+    """
+    如果多进程环境下，请保持单例模式。
+    """
+    def __init__(self,file_name='config' ,default_config: dict = None,
+                 default_config_callback: Callable =None, init_use_callback : bool =True,):
+        """
+        初始化配置
+        Args:
+            file_name: 配置文件名
+            default_config: 默认配置(如果配置项多出，则会自动添加)
+            default_config_callback: 默认配置回调函数(重置时可动态获取默认配置)
+            init_use_callback: 是否在初始化时使用回调函数获取默认配置
+        """
+        self.fname = file_name
+        self.queues = []# 当配置被修改时，向所有队列发送配置
+        self.default_config = default_config
+        self.default_config_callback = default_config_callback
+        self.config_lock = threading.Lock() # 因为单个进程保持单例，使用多线程锁即可
+        try:
+            self.config = self.configget('all')
+        except Exception:
+            self.config = {}
+        if self.default_config_callback and init_use_callback:
+            self.default_config = self.default_config_callback(self.config)
+        for k, v in copy.deepcopy(self.default_config).items():
+            self._config_add(k, v)
+
+
+
+    def update_config(self):
+        """
+        向所有进程发送更新的配置
+        """
+        for _, get_queue in self.queues:
+            get_queue.put(self.config)
+
+
+    def _json_save(self):
+        """修改设置(key,value,a)(要修改的项,值,all或1)"""
+        with open(f"{self.fname}.json", 'w', encoding='UTF-8') as f:
+            json.dump(self.config, f, indent=4, ensure_ascii=False)
+
+
+
+    def configget(self, key):
+        """获取设置 in:key out:value"""
+        if key == 'all':
+            with open(f"{self.fname}.json", 'r', encoding='UTF-8') as f:
+                self.config = json.load(f)
+            return self.config
+        return self.config[key]
+
+
+
+    def configset(self, key, value):
+        """修改设置"""
+        with self.config_lock:
+            self.config[key] = value
+            self._json_save()
+            self.update_config()
+
+
+    def configreset(self, key):
+        """恢复默认设置"""
+        with self.config_lock:
+            print(f"reset config {key}")
+            if self.default_config_callback:
+                self.default_config = self.default_config_callback(
+                    None if key == 'all' else self.config
+                )
+            default_config = copy.deepcopy(self.default_config)
+            if key == 'all':
+                self.config = default_config
+            else:
+                self.config[key] = default_config[key]
+            self._json_save()
+            self.update_config()
+
+    def configupdate_config(self, key, last_value =None):
+        """
+        更新默认值, 如果用户的配置与旧的默认值一致，则更新为新的默认值
+        Args:
+            key: 需要更新的配置项
+            last_value: 旧的默认值
+        """
+        if not self.configget(f"{key}_reseted"):
+            if last_value is None or self.configget(key) == last_value:
+                self.configreset(key)
+            self.configset(f"{key}_reseted", True)
+    def _config_add(self, key, default_value=None):
+        if key not in self.config:
+            self.config[key] = default_value
+            self._json_save()
+
+

xiaoe_config_manager-1.0.0/config/config_multiprocess.py

@@ -0,0 +1,127 @@
+# 多进程配置模块
+# 主进程中实例化ConfigProcess，子进程中实例化ConfigProcessTools。
+# 通过双向管道实现子进程对主进程配置文件的读写。
+import multiprocessing
+import threading
+import traceback
+
+from .config import Config
+
+
+class ConfigInMainProcessPipe:
+    """
+    config多进程的主进程管道口。
+    每个进程都需要在主进程实例化一个。
+    """
+    def __init__(self, config: Config):
+        """
+        初始化
+        Args:
+            config: 主进程中的配置单例
+        """
+        self.config = config
+        self.config_set_queue = multiprocessing.Queue()# 子进程-》主进程
+        self.config_get_queue = multiprocessing.Queue()# 主进程-》子进程
+        # 注册队列
+        #   当config被修改时，通过这个队列向所有进程发送新配置
+        self.config.queues.append((
+            self.config_set_queue,
+            self.config_get_queue
+        ))
+
+        self._loop_thread = threading.Thread(target=self._loop, daemon=True)
+        self._loop_thread.start()
+
+    def get_queues(self):
+        """将这两个对象传递给子进程"""
+        return self.config_set_queue, self.config_get_queue
+
+    def _loop(self):
+        while True:
+            msg = self.config_set_queue.get()
+            if msg is None:
+                break
+            args = msg.get("args", [])
+            if msg['call'] == 'configset':
+                self.config.configset(*args)
+            # if msg['call'] == 'configget':
+            #     self.config_get_queue.put(self.config.configget(*args))
+            if msg['call'] == 'configreset':
+                self.config.configreset(*args)
+            if msg['call'] == 'configgetall':
+                self.config_get_queue.put(self.config.config)
+            # 当有进程修改了配置，通知所有进程更新配置
+
+    def close(self):
+        try:
+            self.config_set_queue.put(None)
+            self._loop_thread.join()
+        except Exception:
+            traceback.print_exc()
+
+
+class ConfigInChildProcessPipe:
+    """
+    在子进程中实例化，与主进程中的ConfigProcess通信。
+    通过传入双向管道实现子进程对配置文件的读写。
+    """
+    def __init__(
+            self,
+            config_set_queue: multiprocessing.Queue,
+            config_get_queue: multiprocessing.Queue,
+    ):
+        """
+        初始化
+        Args:
+            config_set_queue: 主进程-》子进程(当config被修改时，接收修改消息)
+            config_get_queue: 子进程-》主进程
+        """
+
+        self.config_set_queue = config_set_queue
+        self.config_get_queue = config_get_queue
+        self.config = {}
+        self._init_config()
+        print('success init config process tools')
+        self._update_config_loop_thread = threading.Thread(target=self._update_config_loop, daemon=True)
+        self._update_config_loop_thread.start()
+
+    def configget(self, key):
+        """获取设置 in:key out:value"""
+        result = self.config.get(key)
+        return result
+
+    def configset(self, key, value):
+        """修改设置"""
+        self.config[key] = value
+        self.config_set_queue.put({
+            'call': 'configset',
+            'args': [key, value],
+        })
+
+    def configreset(self, key):
+        """恢复默认设置"""
+        self.config_set_queue.put({
+            'call': 'configreset',
+            'args': [key],
+        })
+
+    def _init_config(self):
+        self.config_set_queue.put({
+            'call': 'configgetall',
+        })
+        self.config = self.config_get_queue.get()
+
+    def _update_config_loop(self):
+        """收到更新配置的消息，更新本地配置"""
+        while True:
+            config = self.config_get_queue.get()
+            if config is None:
+                break
+            self.config = config
+
+    def close(self):
+        try:
+            self.config_get_queue.put(None)
+            self._update_config_loop_thread.join()
+        except Exception:
+            traceback.print_exc()

xiaoe_config_manager-1.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xiaoe-config-manager"
+version = "1.0.0"
+description = "多进程安全的 JSON 配置文件管理器，支持默认配置、动态重置与进程间自动同步"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+keywords = ["config", "configuration", "json", "multiprocess", "thread-safe"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/xiaoe/xiaoe-config-manager"
+Repository = "https://github.com/xiaoe/xiaoe-config-manager"
+
+[tool.setuptools]
+packages = ["config"]

xiaoe_config_manager-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xiaoe_config_manager-1.0.0/xiaoe_config_manager.egg-info/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: xiaoe-config-manager
+Version: 1.0.0
+Summary: 多进程安全的 JSON 配置文件管理器，支持默认配置、动态重置与进程间自动同步
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/xiaoe/xiaoe-config-manager
+Project-URL: Repository, https://github.com/xiaoe/xiaoe-config-manager
+Keywords: config,configuration,json,multiprocess,thread-safe
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# xiaoe-config-manager
+
+多进程安全的 JSON 配置文件管理器，纯 Python 标准库实现，零外部依赖。
+
+## 特性
+
+- **线程安全** — 内置线程锁，单进程多线程环境下安全读写
+- **多进程安全** — 通过 `multiprocessing.Queue` 双向管道实现主进程与子进程之间的配置自动同步
+- **默认配置** — 支持静态默认字典和动态回调两种方式，配置项缺失时自动补齐
+- **配置重置** — 支持单个 key 或全部配置一键恢复默认值
+- **默认值热更新** — 当默认配置变化时，自动识别用户未修改的项并更新为新默认值
+- **纯标准库** — 无任何第三方依赖，仅使用 `json`、`threading`、`multiprocessing` 等标准库
+
+## 安装
+
+```bash
+pip install xiaoe-config-manager
+```
+
+## 快速开始
+
+### 单进程使用
+
+```python
+from config import Config
+
+# 初始化，指定配置文件名（不含扩展名）
+config = Config("app_config")
+
+# 写入配置
+config.configset("api_url", "https://api.example.com")
+config.configset("timeout", 30)
+
+# 读取配置
+print(config.configget("api_url"))  # https://api.example.com
+
+# 读取全部配置
+all_config = config.configget("all")
+print(all_config)  # {"api_url": "https://api.example.com", "timeout": 30}
+```
+
+### 带默认配置
+
+```python
+from config import Config
+
+defaults = {
+    "host": "0.0.0.0",
+    "port": 8080,
+    "debug": False,
+}
+
+config = Config("server_config", default_config=defaults)
+
+# 配置文件中已有的键保留原值，缺失的键自动用默认值补齐
+print(config.configget("host"))   # "0.0.0.0"
+print(config.configget("port"))   # 8080
+
+# 恢复单个配置项为默认值
+config.configreset("port")
+
+# 恢复全部配置为默认值
+config.configreset("all")
+```
+
+### 使用回调函数动态生成默认配置
+
+```python
+from config import Config
+
+def dynamic_defaults(current_config):
+    """根据当前配置动态生成默认值"""
+    import socket
+    return {
+        "host": "0.0.0.0",
+        "port": 8080,
+        "hostname": socket.gethostname(),
+        "worker_count": 4,
+    }
+
+config = Config(
+    "dynamic_config",
+    default_config_callback=dynamic_defaults,
+    init_use_callback=True,  # 初始化时调用回调
+)
+
+# 重置时会再次调用回调，获取最新的默认值
+config.configreset("all")
+```
+
+## 多进程使用
+
+多进程场景下，**主进程持有 `Config` 单例**，子进程通过 `ConfigInChildProcessPipe` 与主进程通信。主进程需要为每个子进程创建一个 `ConfigInMainProcessPipe` 实例。
+
+### 主进程
+
+```python
+from config import Config, ConfigInMainProcessPipe
+
+# 1. 创建配置单例
+config = Config("my_config", default_config={"workers": 4})
+
+# 2. 为子进程创建主进程端的管道
+main_pipe = ConfigInMainProcessPipe(config)
+
+# 3. 获取队列，传递给子进程
+set_queue, get_queue = main_pipe.get_queues()
+
+# 4. 启动子进程（以 multiprocessing.Process 为例）
+import multiprocessing
+
+def worker(set_q, get_q):
+    from config import ConfigInChildProcessPipe
+    # 5. 为子进程创建子进程端的管道
+    child_config = ConfigInChildProcessPipe(set_q, get_q)
+    child_config.configset("worker_status", "running")
+    child_config.close()
+
+p = multiprocessing.Process(target=worker, args=(set_queue, get_queue))
+p.start()
+p.join()
+
+# 6. 主进程可直接读写配置，修改会自动同步并广播到到子进程。
+# 同样，子进程的修改请求会提交至主进程修改，最后由主进程广播至所有子进程。
+config.configset("master_status", "ok")
+
+# 6. 清理
+main_pipe.close()
+```
+
+### 子进程
+
+```python
+from config import ConfigInChildProcessPipe
+
+def worker(set_queue, get_queue):
+    # 使用主进程传入的队列初始化
+    config = ConfigInChildProcessPipe(set_queue, get_queue)
+
+    # 读取配置（从本地缓存读取，无 I/O 开销）
+    print(config.configget("workers"))  # 4
+
+    # 修改配置（发送消息给主进程，由主进程执行实际写入）
+    config.configset("worker_status", "done")
+
+    # 主进程的修改会自动同步到本地缓存
+
+    # 使用完毕后关闭
+    config.close()
+```
+
+### 架构说明
+
+```
+子进程 configset() ──→ set_queue ──→ 主进程 _loop() ──→ Config.configset()
+                                                              │
+                                                              ▼
+                                                     config_get_queue
+                                                              │
+                                                              ▼
+                                             子进程 _update_config_loop()
+                                             更新本地 self.config 缓存
+```
+
+- 子进程的 `configset()` 和 `configreset()` 不直接写文件，而是通过队列将请求发送给主进程
+- 主进程统一处理所有写操作和文件 I/O，修改后通过广播队列通知所有子进程
+- 子进程的 `configget()` 从本地缓存读取，无跨进程开销
+- 每个子进程需要独立的管道对（一个 `ConfigInMainProcessPipe` + 一个 `ConfigInChildProcessPipe`）
+
+## API 参考
+
+### Config
+
+核心配置类，管理 JSON 文件的读写。
+
+```python
+Config(file_name="config", default_config=None, default_config_callback=None, init_use_callback=True)
+```
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `file_name` | `str` | `"config"` | 配置文件名，不含 `.json` 扩展名 |
+| `default_config` | `dict` | `None` | 默认配置字典，缺失的 key 自动补齐 |
+| `default_config_callback` | `Callable` | `None` | 默认配置回调函数，重置时动态生成默认值。接受当前 config 字典作为参数 |
+| `init_use_callback` | `bool` | `True` | 是否在初始化时调用回调来填充 `default_config` |
+
+**方法：**
+
+| 方法 | 说明 |
+|------|------|
+| `configget(key)` | 获取配置值。`key="all"` 返回全部配置 |
+| `configset(key, value)` | 设置配置值，自动保存到文件并通知子进程 |
+| `configreset(key)` | 恢复默认值。`key="all"` 恢复全部 |
+| `configupdate_config(key, last_value=None)` | 更新默认值，用于版本更新时希望修改软件的默认值。若用户未修改过该 key 则同步为新默认值。需要手动创建一项"{原配置key}_reseted"=False的配置，用于标记是否执行过更新默认值的操作。 |
+| `update_config()` | 向所有已注册的子进程广播当前配置 |
+
+### ConfigInMainProcessPipe
+
+主进程管道接口，在主进程中每个子进程对应创建一个实例。
+
+```python
+ConfigInMainProcessPipe(config: Config)
+```
+
+| 方法 | 说明 |
+|------|------|
+| `get_queues()` | 返回 `(set_queue, get_queue)` 元组，传递给子进程 |
+| `close()` | 关闭管道，停止监听线程 |
+
+### ConfigInChildProcessPipe
+
+子进程配置工具，在子进程中实例化，通过管道与主进程通信。
+
+```python
+ConfigInChildProcessPipe(config_set_queue, config_get_queue)
+```
+
+| 方法 | 说明 |
+|------|------|
+| `configget(key)` | 从本地缓存读取配置值 |
+| `configset(key, value)` | 修改配置（消息发送给主进程执行） |
+| `configreset(key)` | 恢复默认值（消息发送给主进程执行） |
+| `close()` | 关闭管道，停止同步线程 |
+
+## 注意事项
+
+1. **多进程环境下请保持 Config 单例** — 多个 Config 实例同时操作同一文件会导致数据不一致
+2. **子进程中的 ConfigInChildProcessPipe 不直接操作文件** — 所有写操作将发送请求，由主进程统一处理
+3. **使用完毕后请调用 `close()`** — 避免守护线程未正常退出
+4. **配置文件名不含 `.json` 后缀** — 传入 `"myconfig"` 对应文件 `myconfig.json`
+
+## 许可证
+
+MIT

xiaoe_config_manager-1.0.0/xiaoe_config_manager.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+config/__init__.py
+config/config.py
+config/config_multiprocess.py
+xiaoe_config_manager.egg-info/PKG-INFO
+xiaoe_config_manager.egg-info/SOURCES.txt
+xiaoe_config_manager.egg-info/dependency_links.txt
+xiaoe_config_manager.egg-info/top_level.txt

xiaoe_config_manager-1.0.0/xiaoe_config_manager.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

xiaoe_config_manager-1.0.0/xiaoe_config_manager.egg-info/top_level.txt

@@ -0,0 +1 @@
+config