confull 0.0.1__tar.gz

confull-0.0.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

confull-0.0.1/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.3
+Name: confull
+Version: 0.0.1
+Summary: 一个简单的配置管理工具(A simple dictionary configuration management tool),dict <-> config file [json, toml, yaml, ini, xml]
+Author: zisul
+Author-email: zisull@qq.com
+Requires-Python: >=3.6,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+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
+Requires-Dist: configparser (>=7.1.0,<8.0.0)
+Requires-Dist: orjson (>=3.10.11,<4.0.0)
+Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
+Requires-Dist: toml (>=0.10.2,<0.11.0)
+Description-Content-Type: text/markdown
+
+# confull 多格式配置管理器说明文档
+
+[Zh](https://github.com/zisull/confull/blob/main/README.md)  / [En](https://github.com/zisull/confull/blob/main/doc/README-en.md)
+
+## 一、概述
+
+```cmd
+pip install confull
+```
+
+## 一、概述
+
+本配置管理器是一个多格式的配置管理工具，支持 `dict` 与 `ini`、`xml`、`json`、`toml`、`yaml` 等格式的读写与自动保存。它提供了便捷的接口来管理配置数据，并且可以根据需要切换配置文件和格式。
+
+
+
+## 二、类和方法说明
+
+### 1. `Config` 类
+
+该类是配置管理器的核心类，负责管理配置数据的读写、保存等操作。
+
+#### 初始化方法 `__init__`
+
+```python
+def __init__(self, data: dict = None, file: str = "config", way: str = "toml", replace: bool = False,
+             auto_save: bool = True, backup: bool = False):
+```
+
+- 参数说明
+  - `data`：初始配置数据，类型为 `dict`，默认为 `None`。
+  - `file`：配置文件名（可无扩展名），默认为 `"config"`。
+  - `way`：配置文件格式，支持 `json`、`toml`、`yaml`、`ini`、`xml`，默认为 `"toml"`。
+  - `replace`：是否覆盖已有配置文件，布尔值，默认为 `False`。
+  - `auto_save`：是否自动保存，布尔值，默认为 `True`。
+  - `backup`：是否备份原配置文件，布尔值，默认为 `False`。
+
+#### 属性
+
+- `json`：以 json 字符串格式返回配置数据。
+- `dict`：以 `dict` 格式返回配置数据，也可用于批量设置配置数据。
+- `auto_save`：是否自动保存，可读写属性。
+- `backup`：是否备份原配置文件，可读写属性。
+- `str`：以字符串格式返回配置数据。
+- `file_path`：配置文件路径。
+- `file_path_abs`：配置文件绝对路径。
+
+#### 方法
+
+- `read(key: str, default=None)`：读取配置项，支持点号路径，如 `a.b.c`。若配置项不存在，返回默认值。
+- `write(key: str, value, overwrite_mode: bool = False)`：写入配置项，支持点号路径。若 `overwrite_mode` 为 `True`，路径冲突时会覆盖。写入后若 `auto_save` 为 `True`，则自动保存。
+- `del_clean()`：清空所有配置并删除配置文件。
+- `update(data: dict)`：批量更新配置项，支持点号路径。更新后若 `auto_save` 为 `True`，则自动保存。
+- `set_data(data: dict)`：用 `dict` 完全替换配置数据。替换后若 `auto_save` 为 `True`，则自动保存。
+- `del_key(key: str)`：删除指定配置项，支持点号路径。删除后若 `auto_save` 为 `True`，则自动保存。
+- `_load()`：从文件加载配置，内部方法。
+- `load(file: str = None, way: str = None)`：切换配置文件或格式（不自动加载内容）。
+- `mark_dirty()`：标记配置已更改。
+- `save()`：保存配置到文件。
+- `save_to_file(file: str = None, way: str = None)`：另存为指定文件和格式。
+- `_ensure_file_exists()`：确保配置文件存在，内部方法。
+- `_backup_file()`：备份原配置文件，内部方法。
+- `_recursive_update(original, new_data)`：递归更新配置，支持点号路径，内部方法。
+- `validate_format(_way)`：校验并返回合法格式名，静态方法。
+- `ensure_extension(file)`：确保文件名有正确扩展名。
+
+## 三、使用示例
+
+### 1. 初始化配置管理器
+
+```python
+from confull import Config
+
+# 使用默认参数初始化
+config = Config()
+
+# 使用自定义参数初始化
+data = {'a': {'b': 'c'}}
+config = Config(data=data, file='custom_config', way='json')
+```
+
+### 2. 读取和写入配置项
+
+```python
+# 写入配置项
+config.write('a.b', 'new_value')  # 也可以写为 : config.a.b = 'new_value'
+# 读取配置项
+value = config.read('a.b')  # value = config.a.b
+print(value)  # 输出: new_value
+```
+
+### 3. 批量更新配置项
+
+```python
+new_data = {'a': {'b': 'updated_value'}, 'd': 'e'}
+config.update(new_data)
+```
+
+### 4. 保存和另存配置文件
+
+```python
+# 保存配置文件
+config.save()
+
+# 另存为指定文件和格式
+config.save_to_file(file='backup_config', way='yaml')
+```
+
+### 5. 删除配置项和清空配置
+
+```python
+# 删除配置项
+config.del_key('a.b')
+
+# 清空配置并删除文件
+config.del_clean()
+```
+
+### 6.# 读写方法示例
+
+```
+# 读写方法示例
+from confull import Config
+
+cc = Config()
+cc.write('学校名称', '大学')
+cc.学校.日期 = "2021-01-01"
+print(cc.read('学校.日期'))
+print(cc['学校名称'])
+print(cc.学校.日期)
+print(cc)
+cc.pop('学校名称')
+print(cc)
+cc.clear()  # 字典方式清空配置data
+print(cc)
+cc.del_clean()
+
+# 字典方式设置值示例
+cc = Config()
+cc.dict = {'地点': '北京', '图书': {'数量': 100, '价格': 10.5}, '学生': {'数量': 1000, '年龄': 20}}
+print(cc)
+cc.del_clean()
+
+# 强制覆写示例
+dic_ = {'学校': 'pass'}
+cc = Config(data=dic_)
+cc.write('学校.大学', '大学', overwrite_mode=True)  # overwrite_mode=True 强制覆写，但会导致原路径被删除
+print(cc)
+cc.del_clean()
+```
+
+
+
+## 四、注意事项
+
+- 当使用 `write`、`update`、`set_data`、`del_key` 等方法修改配置数据时，若 `auto_save` 为 `True`，会自动保存配置文件。
+- 若配置文件格式不支持，会抛出 `ValueError` 异常。
+- 在使用 `INIConfigHandler` 保存配置时，若数据不是嵌套字典，会将其包装在一个默认的 `'默认'` 节中。
+
+## 尾语
+
+作者水平有限，尽可能简化配置文件的读写流程，让使用者可以用一种更加直观、便捷的方式去操作配置信息。
+
+2024 年 11 月 19 日   zisull@qq.com
+

confull-0.0.1/README.md

@@ -0,0 +1,164 @@
+# confull 多格式配置管理器说明文档
+
+[Zh](https://github.com/zisull/confull/blob/main/README.md)  / [En](https://github.com/zisull/confull/blob/main/doc/README-en.md)
+
+## 一、概述
+
+```cmd
+pip install confull
+```
+
+## 一、概述
+
+本配置管理器是一个多格式的配置管理工具，支持 `dict` 与 `ini`、`xml`、`json`、`toml`、`yaml` 等格式的读写与自动保存。它提供了便捷的接口来管理配置数据，并且可以根据需要切换配置文件和格式。
+
+
+
+## 二、类和方法说明
+
+### 1. `Config` 类
+
+该类是配置管理器的核心类，负责管理配置数据的读写、保存等操作。
+
+#### 初始化方法 `__init__`
+
+```python
+def __init__(self, data: dict = None, file: str = "config", way: str = "toml", replace: bool = False,
+             auto_save: bool = True, backup: bool = False):
+```
+
+- 参数说明
+  - `data`：初始配置数据，类型为 `dict`，默认为 `None`。
+  - `file`：配置文件名（可无扩展名），默认为 `"config"`。
+  - `way`：配置文件格式，支持 `json`、`toml`、`yaml`、`ini`、`xml`，默认为 `"toml"`。
+  - `replace`：是否覆盖已有配置文件，布尔值，默认为 `False`。
+  - `auto_save`：是否自动保存，布尔值，默认为 `True`。
+  - `backup`：是否备份原配置文件，布尔值，默认为 `False`。
+
+#### 属性
+
+- `json`：以 json 字符串格式返回配置数据。
+- `dict`：以 `dict` 格式返回配置数据，也可用于批量设置配置数据。
+- `auto_save`：是否自动保存，可读写属性。
+- `backup`：是否备份原配置文件，可读写属性。
+- `str`：以字符串格式返回配置数据。
+- `file_path`：配置文件路径。
+- `file_path_abs`：配置文件绝对路径。
+
+#### 方法
+
+- `read(key: str, default=None)`：读取配置项，支持点号路径，如 `a.b.c`。若配置项不存在，返回默认值。
+- `write(key: str, value, overwrite_mode: bool = False)`：写入配置项，支持点号路径。若 `overwrite_mode` 为 `True`，路径冲突时会覆盖。写入后若 `auto_save` 为 `True`，则自动保存。
+- `del_clean()`：清空所有配置并删除配置文件。
+- `update(data: dict)`：批量更新配置项，支持点号路径。更新后若 `auto_save` 为 `True`，则自动保存。
+- `set_data(data: dict)`：用 `dict` 完全替换配置数据。替换后若 `auto_save` 为 `True`，则自动保存。
+- `del_key(key: str)`：删除指定配置项，支持点号路径。删除后若 `auto_save` 为 `True`，则自动保存。
+- `_load()`：从文件加载配置，内部方法。
+- `load(file: str = None, way: str = None)`：切换配置文件或格式（不自动加载内容）。
+- `mark_dirty()`：标记配置已更改。
+- `save()`：保存配置到文件。
+- `save_to_file(file: str = None, way: str = None)`：另存为指定文件和格式。
+- `_ensure_file_exists()`：确保配置文件存在，内部方法。
+- `_backup_file()`：备份原配置文件，内部方法。
+- `_recursive_update(original, new_data)`：递归更新配置，支持点号路径，内部方法。
+- `validate_format(_way)`：校验并返回合法格式名，静态方法。
+- `ensure_extension(file)`：确保文件名有正确扩展名。
+
+## 三、使用示例
+
+### 1. 初始化配置管理器
+
+```python
+from confull import Config
+
+# 使用默认参数初始化
+config = Config()
+
+# 使用自定义参数初始化
+data = {'a': {'b': 'c'}}
+config = Config(data=data, file='custom_config', way='json')
+```
+
+### 2. 读取和写入配置项
+
+```python
+# 写入配置项
+config.write('a.b', 'new_value')  # 也可以写为 : config.a.b = 'new_value'
+# 读取配置项
+value = config.read('a.b')  # value = config.a.b
+print(value)  # 输出: new_value
+```
+
+### 3. 批量更新配置项
+
+```python
+new_data = {'a': {'b': 'updated_value'}, 'd': 'e'}
+config.update(new_data)
+```
+
+### 4. 保存和另存配置文件
+
+```python
+# 保存配置文件
+config.save()
+
+# 另存为指定文件和格式
+config.save_to_file(file='backup_config', way='yaml')
+```
+
+### 5. 删除配置项和清空配置
+
+```python
+# 删除配置项
+config.del_key('a.b')
+
+# 清空配置并删除文件
+config.del_clean()
+```
+
+### 6.# 读写方法示例
+
+```
+# 读写方法示例
+from confull import Config
+
+cc = Config()
+cc.write('学校名称', '大学')
+cc.学校.日期 = "2021-01-01"
+print(cc.read('学校.日期'))
+print(cc['学校名称'])
+print(cc.学校.日期)
+print(cc)
+cc.pop('学校名称')
+print(cc)
+cc.clear()  # 字典方式清空配置data
+print(cc)
+cc.del_clean()
+
+# 字典方式设置值示例
+cc = Config()
+cc.dict = {'地点': '北京', '图书': {'数量': 100, '价格': 10.5}, '学生': {'数量': 1000, '年龄': 20}}
+print(cc)
+cc.del_clean()
+
+# 强制覆写示例
+dic_ = {'学校': 'pass'}
+cc = Config(data=dic_)
+cc.write('学校.大学', '大学', overwrite_mode=True)  # overwrite_mode=True 强制覆写，但会导致原路径被删除
+print(cc)
+cc.del_clean()
+```
+
+
+
+## 四、注意事项
+
+- 当使用 `write`、`update`、`set_data`、`del_key` 等方法修改配置数据时，若 `auto_save` 为 `True`，会自动保存配置文件。
+- 若配置文件格式不支持，会抛出 `ValueError` 异常。
+- 在使用 `INIConfigHandler` 保存配置时，若数据不是嵌套字典，会将其包装在一个默认的 `'默认'` 节中。
+
+## 尾语
+
+作者水平有限，尽可能简化配置文件的读写流程，让使用者可以用一种更加直观、便捷的方式去操作配置信息。
+
+2024 年 11 月 19 日   zisull@qq.com

confull-0.0.1/confull/__init__.py

@@ -0,0 +1,4 @@
+from .config import Config
+
+if __name__ == '__main__':
+    pass

confull-0.0.1/confull/config.py

@@ -0,0 +1,619 @@
+# -*- coding: utf-8 -*-
+# @author: zisull@qq.com
+# @date: 2024年11月19日
+
+import configparser
+import os
+import xml.etree.ElementTree as ElementTree
+from collections.abc import MutableMapping
+from threading import Lock
+
+import orjson
+import toml
+import yaml
+
+
+class Config:
+    """
+    多格式配置管理器，支持 dict <=> [ini, xml, json, toml, yaml] 的读写与自动保存。
+    """
+
+    def __init__(self, data: dict = None, file: str = "config", way: str = "toml", replace: bool = False,
+                 auto_save: bool = True, backup: bool = False):
+        """
+        初始化配置管理器。
+        :param data: 初始配置数据（dict）
+        :param file: 配置文件名（可无扩展名）
+        :param way: 配置文件格式（json/toml/yaml/ini/xml）
+        :param replace: 是否覆盖已有配置文件
+        :param auto_save: 是否自动保存
+        :param backup: 是否备份原配置文件
+        """
+        self._file = file
+        self._way = self.validate_format(way)
+        self._file = self.ensure_extension(file)
+        self._auto_save = auto_save
+        self._data = ConfigNode(data if data is not None else {}, manager=self)
+        self._dirty = False if data is not None else True
+        self._backup = backup
+        self._lock = Lock()
+        self._handler = ConfigHandlerFactory.get_handler(self._way)
+
+        if os.path.exists(self._file) and not replace:
+            self._load()
+        else:
+            # 当文件不存在时，无论replace参数如何都使用data初始化
+            if data is not None:
+                self._data = ConfigNode(data, manager=self)
+                self._dirty = True  # 强制标记需要保存
+            self.save()  # 确保立即保存初始数据
+
+    @property
+    def json(self) -> str:
+        """以 JSON 字符串格式返回配置数据。"""
+        return orjson.dumps(self.dict, option=orjson.OPT_INDENT_2).decode('utf-8')
+
+    @property
+    def dict(self) -> dict:
+        """以 dict 格式返回配置数据。"""
+        return self._data.to_dict()
+
+    @dict.setter
+    def dict(self, value: dict):
+        """用 dict 批量设置配置数据。"""
+        self.set_data(value)
+
+    @property
+    def auto_save(self) -> bool:
+        """是否自动保存。"""
+        return self._auto_save
+
+    @auto_save.setter
+    def auto_save(self, value: bool):
+        """设置自动保存。"""
+        self._auto_save = value
+
+    @property
+    def backup(self) -> bool:
+        """是否备份原配置文件。"""
+        return self._backup
+
+    @backup.setter
+    def backup(self, value: bool):
+        """设置是否备份原配置文件。"""
+        self._backup = value
+
+    @property
+    def str(self) -> str:
+        """以字符串格式返回配置数据。"""
+        return str(self.dict)
+
+    @property
+    def file_path(self) -> str:
+        """配置文件路径。"""
+        return self._file
+
+    @property
+    def file_path_abs(self) -> str:
+        """配置文件绝对路径。"""
+        return os.path.abspath(self._file)
+
+    def read(self, key: str, default=None):
+        """
+        读取配置项，支持点号路径。
+        :param key: 配置项路径（如 a.b.c）
+        :param default: 默认值
+        """
+        keys = key.split('.')
+        node = self._data
+        for k in keys:
+            if isinstance(node, ConfigNode):
+                node = node.data.get(k, None)
+                if isinstance(node, dict):
+                    node = ConfigNode(node, manager=self)
+                elif node is None:
+                    return default
+            else:
+                return default
+        return node
+
+    def write(self, key: str, value, overwrite_mode: bool = False):
+        """
+        写入配置项，支持点号路径。
+        :param key: 配置项路径
+        :param value: 配置值
+        :param overwrite_mode: 路径冲突时是否覆盖
+        """
+        self.mark_dirty()
+        keys = key.split('.')
+        node = self._data
+
+        for k in keys[:-1]:
+            if overwrite_mode:
+                if isinstance(node, ConfigNode):
+                    if k not in node.data or not isinstance(node.data[k], dict):
+                        node.data[k] = {}
+                else:
+                    node.data = {k: {}}
+                node = node[k]
+            else:
+                node = getattr(node, k)
+
+        setattr(node, keys[-1], value)
+
+        if self.auto_save:
+            self.save()
+
+    def del_clean(self):
+        """清空所有配置并删除配置文件。"""
+        self.mark_dirty()
+        with self._lock:
+            if os.path.exists(self._file):
+                try:
+                    os.remove(self._file)
+                    self._data = ConfigNode({}, manager=self)
+                    return True
+                except OSError as e:
+                    print(f"清除配置文件 {self._file} 失败：{e}")
+            else:
+                print(f"配置文件 {self._file} 不存在，无法清除")
+            return False
+
+    def update(self, data: dict):
+        """
+        批量更新配置项。
+        :param data: dict，支持点号路径
+        """
+        self.mark_dirty()
+        self._recursive_update(self._data.data, data)
+        if self.auto_save:
+            self.save()
+
+    def set_data(self, data: dict):
+        """
+        用 dict 完全替换配置数据。
+        :param data: 新配置 dict
+        """
+        self.mark_dirty()
+        self._data = ConfigNode(data, manager=self)
+        if self.auto_save:
+            self.save()
+
+    def del_key(self, key: str):
+        """
+        删除指定配置项，支持点号路径。
+        :param key: 配置项路径
+        """
+        self.mark_dirty()
+        keys = key.split('.')
+        if not keys:
+            return
+        node = self._data
+        parent_nodes = []
+        for k in keys[:-1]:
+            parent_nodes.append((node, k))
+            node = getattr(node, k, None)
+            if node is None:
+                return
+        final_key = keys[-1]
+        if final_key in node.data:
+            del node.data[final_key]
+            while parent_nodes:
+                parent, key_in_parent = parent_nodes.pop()
+                if not parent[key_in_parent].data:
+                    del parent[key_in_parent]
+                else:
+                    break
+            if self.auto_save:
+                self.save()
+
+    def _load(self):
+        """从文件加载配置。"""
+        with self._lock:
+            try:
+                with open(self._file, 'rb' if self._way == "json" else 'r',
+                          encoding=None if self._way == "json" else 'utf-8') as f:
+                    raw_data = self._handler.load(f)
+                    self._data = ConfigNode(raw_data, manager=self)
+            except Exception as e:
+                print(f"加载配置文件 {self._file} 失败：{e}")
+
+    def load(self, file: str = None, way: str = None):
+        """
+        切换配置文件或格式（不自动加载内容）。
+        :param file: 新文件名
+        :param way: 新格式
+        """
+        if file:
+            self._file = file
+        if way:
+            self._way = way.lower()
+            self._handler = ConfigHandlerFactory.get_handler(self._way)
+
+    def mark_dirty(self):
+        """标记配置已更改。"""
+        self._dirty = True
+
+    def save(self):
+        """保存配置到文件。"""
+        with self._lock:
+            if not self._dirty:
+                return
+            try:
+                self._backup_file()
+                self._ensure_file_exists()
+                # 修复：为 XML 格式添加二进制写入模式
+                with open(self._file, 'wb' if self._way in ["json", "xml"] else 'w',
+                          encoding=None if self._way in ["json", "xml"] else 'utf-8') as f:
+                    self._handler.save(self._data.to_dict(), f)
+                self._dirty = False
+            except Exception as e:
+                print(f"保存配置文件失败 {self._file}: {e}")
+
+    def save_to_file(self, file: str = None, way: str = None):
+        """
+        另存为指定文件和格式。
+        :param file: 目标文件
+        :param way: 目标格式
+        """
+        with self._lock:
+            try:
+                # 使用局部变量来存储文件路径和格式
+                target_file = self.ensure_extension(file) if file else self._file
+                target_way = self.validate_format(way) if way else self._way
+                target_handler = ConfigHandlerFactory.get_handler(target_way)
+
+                # 确保文件存在
+                self._ensure_file_exists()
+
+                # 打开文件并保存数据
+                with open(target_file, 'wb' if target_way == "json" else 'w',
+                          encoding=None if target_way == "json" else 'utf-8') as f:
+                    target_handler.save(self._data.to_dict(), f)
+
+                print(f"配置已成功另存到 {target_file}")
+            except Exception as e:
+                print(f"另存配置文件失败 {target_file}: {e}")
+
+    def _ensure_file_exists(self):
+        """确保配置文件存在。"""
+        if not os.path.exists(self._file):
+            with open(self._file, 'w'):
+                pass  # 创建一个空文件
+
+    def _backup_file(self):
+        """备份原配置文件。"""
+        if os.path.exists(self._file) and self.backup:
+            backup_file = self._file + '.bak'
+            try:
+                os.replace(self._file, backup_file)
+            except Exception as e:
+                print(f"备份文件失败: {e}")
+
+    def _recursive_update(self, original, new_data):
+        """
+        递归更新配置，支持点号路径。
+        :param original: 原始 dict
+        :param new_data: 新数据 dict
+        """
+        for key, value in new_data.items():
+            if '.' in key:
+                keys = key.split('.')
+                current = original
+                for k in keys[:-1]:
+                    current = current.setdefault(k, {})
+                current[keys[-1]] = value
+            elif isinstance(value, dict) and isinstance(original.get(key, None), dict):
+                self._recursive_update(original[key], value)
+            else:
+                if original.get(key) != value:
+                    original[key] = value
+                    self.mark_dirty()
+
+    @staticmethod
+    def validate_format(_way):
+        """
+        校验并返回合法格式名。
+        :param _way: 格式名
+        """
+        _way = _way.lower()
+        way_list = ['json', 'toml', 'yaml', 'ini', 'xml']  # 修复：将 way_list 定义为局部变量
+        if _way not in way_list:
+            raise ValueError(f"Unsupported format: {_way}. Supported formats are: {', '.join(way_list)}")
+        return _way
+
+    def ensure_extension(self, file):
+        """
+        确保文件名有正确扩展名。
+        :param file: 文件名
+        """
+        if not os.path.splitext(file)[1]:
+            file += f".{self._way}"
+        return file
+
+    def __str__(self):
+        """str(self)"""
+        return str(self.dict)
+
+    def __repr__(self):
+        """repr(self)"""
+        return repr(self.dict)
+
+    def __getattr__(self, item: str):
+        """属性访问代理到配置数据。"""
+        return getattr(self._data, item)
+
+    def __getitem__(self, item: str):
+        """dict 方式访问配置数据。"""
+        return self._data[item]
+
+    def __call__(self, key: str, value=None):
+        """cc(key) 等价于 cc.read(key, value)"""
+        return self.read(key, value)
+
+    def __len__(self):
+        """配置项数量。"""
+        return len(self._data)
+
+    def __iter__(self):
+        """遍历配置项。"""
+        return iter(self._data)
+
+    def __contains__(self, item):
+        """判断配置项是否存在。"""
+        return item in self._data
+
+    def __bool__(self):
+        """配置是否非空。"""
+        return bool(self._data)
+
+    def __enter__(self):
+        """上下文管理器 enter。"""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """上下文管理器 exit，自动保存。"""
+        self.save()
+
+    def __setattr__(self, key, value):
+        """属性赋值代理到配置数据，内部属性用 _ 前缀。"""
+        if key.startswith('_'):
+            super().__setattr__(key, value)
+        else:
+            setattr(self._data, key, value)
+
+
+class ConfigHandler:
+    """
+    配置文件处理器基类。
+    """
+    def load(self, file):
+        """加载配置文件。"""
+        raise NotImplementedError
+
+    def save(self, data, file):
+        """保存配置文件。"""
+        raise NotImplementedError
+
+
+class JSONConfigHandler(ConfigHandler):
+    """
+    JSON 配置文件处理器。
+    """
+    def load(self, file):
+        """加载 JSON 配置。"""
+        return orjson.loads(file.read())
+
+    def save(self, data, file):
+        """保存 JSON 配置。"""
+        file.write(orjson.dumps(data, option=orjson.OPT_INDENT_2))
+
+
+class TOMLConfigHandler(ConfigHandler):
+    """
+    TOML 配置文件处理器。
+    """
+    def load(self, file):
+        """加载 TOML 配置。"""
+        return toml.load(file)
+
+    def save(self, data, file):
+        """保存 TOML 配置。"""
+        file.write(toml.dumps(data))
+
+
+class YAMLConfigHandler(ConfigHandler):
+    """
+    YAML 配置文件处理器。
+    """
+    def load(self, file):
+        """加载 YAML 配置。"""
+        return yaml.safe_load(file)
+
+    def save(self, data, file):
+        """保存 YAML 配置。"""
+        yaml.dump(data, file, allow_unicode=True)
+
+
+class INIConfigHandler(ConfigHandler):
+    """
+    INI 配置文件处理器。
+    """
+    def load(self, file):
+        """加载 INI 配置。"""
+        config = configparser.ConfigParser()
+        config.read_file(file)
+        return {s: dict(config.items(s)) for s in config.sections()}
+
+    def save(self, data, file):
+        """保存 INI 配置。"""
+        config = configparser.ConfigParser()
+        # 如果 data 不是嵌套字典，包装在一个默认的 section 中
+        if not all(isinstance(v, dict) for v in data.values()):
+            data = {'默认': data}
+        config.read_dict(data)
+        config.write(file)
+
+
+class XMLConfigHandler(ConfigHandler):
+    """
+    XML 配置文件处理器。
+    """
+    def load(self, file):
+        """加载 XML 配置。"""
+        tree = ElementTree.parse(file)
+        root = tree.getroot()
+        return self._element_to_dict(root)
+
+    def save(self, data, file):
+        """保存 XML 配置。"""
+        root = self._dict_to_element('config', data)
+        tree = ElementTree.ElementTree(root)
+        tree.write(file, encoding='utf-8', xml_declaration=True)
+
+    def _element_to_dict(self, element):
+        """递归解析 XML 元素为 dict。"""
+        data = {}
+        for child in element:
+            if len(child):
+                data[child.tag] = self._element_to_dict(child)
+            else:
+                data[child.tag] = child.text
+        return data
+
+    def _dict_to_element(self, tag, data):
+        """递归将 dict 转为 XML 元素。"""
+        element = ElementTree.Element(tag)
+        for key, value in data.items():
+            if isinstance(value, dict):
+                child = self._dict_to_element(key, value)
+            else:
+                child = ElementTree.Element(key)
+                child.text = str(value)
+            element.append(child)
+        return element
+
+
+class ConfigHandlerFactory:
+    handlers = {
+        'json': JSONConfigHandler(),
+        'toml': TOMLConfigHandler(),
+        'yaml': YAMLConfigHandler(),
+        'ini': INIConfigHandler(),
+        'xml': XMLConfigHandler(),  # Added XML handler
+    }
+
+    @staticmethod
+    def get_handler(_format):
+        handler = ConfigHandlerFactory.handlers.get(_format)
+        if not handler:
+            raise ValueError(f"Unsupported format: {_format}")
+        return handler
+
+
+class ConfigNode(MutableMapping):
+    """
+    配置节点，支持嵌套字典结构与自动保存。
+    """
+
+    def __init__(self, data=None, manager=None, parent=None, key_in_parent=None):
+        """
+        初始化配置节点。
+        :param data: 节点数据（dict）
+        :param manager: 顶层 Config 实例
+        :param parent: 父节点
+        :param key_in_parent: 在父节点中的键名
+        """
+        self._data = data if data is not None else {}
+        self._manager = manager
+        self._parent = parent
+        self._key_in_parent = key_in_parent
+
+    @property
+    def data(self):
+        """节点数据（dict）。"""
+        return self._data
+
+    @data.setter
+    def data(self, value):
+        """设置节点数据并自动保存。"""
+        self._data = value
+        self._trigger_save()
+
+    def _trigger_save(self):
+        """触发自动保存。"""
+        if self._manager:
+            self._manager.mark_dirty()
+            if self._manager.auto_save:
+                self._manager.save()
+
+    def __getitem__(self, key):
+        """获取子项或子节点。"""
+        value = self._data.get(key)
+        if isinstance(value, dict):
+            return ConfigNode(value, manager=self._manager, parent=self, key_in_parent=key)
+        elif value is not None:
+            return value
+        else:
+            raise KeyError(f"Key '{key}' not found.")
+
+    def __setitem__(self, key, value):
+        """设置子项并自动保存。"""
+        self._data[key] = value
+        self._trigger_save()
+
+    def __delitem__(self, key):
+        """删除子项并自动保存。"""
+        if key in self._data:
+            del self._data[key]
+            self._trigger_save()
+        else:
+            raise KeyError(f"Key '{key}' not found.")
+
+    def __iter__(self):
+        """遍历所有子项。"""
+        return iter(self._data)
+
+    def __len__(self):
+        """子项数量。"""
+        return len(self._data)
+
+    def __getattr__(self, key):
+        """属性方式访问子项。"""
+        if key in self._data:
+            value = self._data[key]
+            if isinstance(value, dict):
+                return ConfigNode(value, manager=self._manager, parent=self, key_in_parent=key)
+            else:
+                return value
+        else:
+            self._data[key] = {}
+            return ConfigNode(self._data[key], manager=self._manager, key_in_parent=key)
+
+    def __setattr__(self, key, value):
+        """属性方式设置子项，内部变量用 _ 前缀。"""
+        if key.startswith('_'):
+            super().__setattr__(key, value)
+        else:
+            self._data[key] = value
+            # 递归找到最顶层的 manager 并触发保存
+            node = self
+            while hasattr(node, '_parent') and node._parent is not None:
+                node = node._parent
+            if hasattr(node, '_manager') and node._manager is not None:
+                node._manager.mark_dirty()
+                if node._manager.auto_save:
+                    node._manager.save()
+
+    def to_dict(self):
+        """递归转为 dict。"""
+        return {key: (value.to_dict() if isinstance(value, ConfigNode) else value)
+                for key, value in self._data.items()}
+
+    def __repr__(self):
+        """repr(self)"""
+        return repr(self.to_dict())
+
+
+if __name__ == "__main__":
+    pass

confull-0.0.1/pyproject.toml

@@ -0,0 +1,19 @@
+[tool.poetry]
+name = "confull"
+version = "0.0.1"
+description = "一个简单的配置管理工具(A simple dictionary configuration management tool),dict <-> config file [json, toml, yaml, ini, xml]"
+authors = ["zisul <zisull@qq.com>"]
+readme = "README.md"
+packages = [{ include = "confull" }]
+
+[tool.poetry.dependencies]
+python = "^3.6"
+orjson = "^3.10.11"
+toml = "^0.10.2"
+pyyaml = "^6.0.2"
+configparser = "^7.1.0"
+
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"