tretool 0.2.1__py3-none-any.whl

tretool/__init__.py

@@ -0,0 +1,27 @@
+"""
+# tretool
+
+## tretool - Python多功能工具库
+
+[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/)
+
+**tretool** 是一个集成常用功能的Python工具库。
+"""
+
+from . import config
+
+from . import encoding
+
+from . import jsonlib
+
+from . import markfunc
+from . import memorizeTools
+
+from . import path
+from . import platformlib
+from . import plugin
+
+from . import timelib
+from . import transform
+
+from . import writeLog

tretool/config.py

@@ -0,0 +1,262 @@
+"""
+### 配置管理库，提供安全的键值对存储和访问机制
+
+特性:
+- 类型安全的设置和获取
+- 默认值支持
+- 批量操作支持
+- 配置项存在性检查
+- 防止意外覆盖
+- 配置文件持久化
+- 配置变更回调
+"""
+
+import json
+import os
+from typing import Any, Callable, Dict, Optional
+
+class Config:
+    """
+    配置管理类，提供安全的键值对存储和访问机制
+    
+    特性:
+    - 类型安全的设置和获取
+    - 默认值支持
+    - 批量操作支持
+    - 配置项存在性检查
+    - 防止意外覆盖
+    - 配置变更通知
+    
+    使用示例:
+    ```
+        config = Config({"theme": "dark"})
+        config.set_config("font_size", 14)
+        theme = config.get_config("theme", default="light")
+        
+        # 添加配置变更监听
+        def on_config_change(key, old_value, new_value):
+            print(f"配置变更: {key} 从 {old_value} 改为 {new_value}")
+            
+        config.add_change_listener(on_config_change)
+        
+        # 保存和加载配置
+        config.save_to_file("settings.json")
+        new_config = Config.load_from_file("settings.json")
+    ```
+    """
+    
+    def __init__(self, initial_config: Optional[Dict[str, Any]] = None):
+        """
+        初始化配置存储
+        
+        参数:
+            initial_config: 初始配置字典 (可选)
+        """
+        self.config_dict = initial_config.copy() if initial_config else {}
+        self._lock = False  # 防止意外修改的锁
+        self._change_listeners = []  # 配置变更监听器列表
+        
+    def __str__(self) -> str:
+        """返回配置的可读字符串表示"""
+        return json.dumps(self.config_dict, indent=2, ensure_ascii=False)
+    
+    def __repr__(self) -> str:
+        """返回配置的正式表示"""
+        return f"Config({self.config_dict})"
+    
+    def __contains__(self, item: str) -> bool:
+        """检查配置项是否存在"""
+        return item in self.config_dict
+    
+    def __len__(self) -> int:
+        """返回配置项的数量"""
+        return len(self.config_dict)
+    
+    def add_change_listener(self, listener: Callable[[str, Any, Any], None]):
+        """
+        添加配置变更监听器
+        
+        参数:
+            listener: 回调函数，格式为 func(key, old_value, new_value)
+        """
+        if listener not in self._change_listeners:
+            self._change_listeners.append(listener)
+    
+    def remove_change_listener(self, listener: Callable[[str, Any, Any], None]):
+        """移除配置变更监听器"""
+        if listener in self._change_listeners:
+            self._change_listeners.remove(listener)
+    
+    def _notify_change(self, key: str, old_value: Any, new_value: Any):
+        """通知所有监听器配置变更"""
+        for listener in self._change_listeners:
+            try:
+                listener(key, old_value, new_value)
+            except Exception as e:
+                print(f"配置变更通知错误: {e}")
+    
+    def get_config(self, item: str, default: Any = None) -> Any:
+        """
+        安全获取配置项
+        
+        参数:
+            item: 配置键名
+            default: 当键不存在时返回的默认值
+            
+        返回:
+            配置值或默认值
+        """
+        return self.config_dict.get(item, default)
+
+    def set_config(self, item: str, value: Any) -> bool:
+        """
+        设置配置项
+        
+        参数:
+            item: 配置键名
+            value: 配置值
+            
+        返回:
+            True 设置成功, False 设置失败
+        """
+        if self._lock:
+            print(f"警告: 配置系统已锁定，无法修改 '{item}'")
+            return False
+            
+        old_value = self.config_dict.get(item)
+        self.config_dict[item] = value
+        
+        # 通知变更
+        self._notify_change(item, old_value, value)
+        return True
+
+    def delete_config(self, item: str) -> bool:
+        """
+        删除配置项
+        
+        参数:
+            item: 要删除的配置键名
+            
+        返回:
+            True 删除成功, False 键不存在
+        """
+        if item in self.config_dict:
+            old_value = self.config_dict[item]
+            del self.config_dict[item]
+            
+            # 通知变更 (值为 None 表示删除)
+            self._notify_change(item, old_value, None)
+            return True
+        return False
+
+    def save_to_file(self, filename: str) -> bool:
+        """
+        保存配置到文件
+        
+        参数:
+            filename: 文件名
+            
+        返回:
+            True 保存成功, False 保存失败
+        """
+        try:
+            with open(filename, 'w', encoding='utf-8') as f:
+                json.dump(self.get_all_configs(), f, indent=2, ensure_ascii=False)
+            return True
+        except (IOError, TypeError) as e:
+            print(f"保存配置失败: {e}")
+            return False
+
+    @classmethod
+    def load_from_file(cls, filename: str) -> Optional['Config']:
+        """
+        从文件加载配置
+        
+        参数:
+            filename: 文件名
+            
+        返回:
+            加载成功的 Config 实例，失败返回 None
+        """
+        if not os.path.exists(filename):
+            print(f"配置文件不存在: {filename}")
+            return None
+            
+        try:
+            with open(filename, 'r', encoding='utf-8') as f:
+                config_data = json.load(f)
+                return cls(config_data)
+        except (IOError, json.JSONDecodeError) as e:
+            print(f"加载配置失败: {e}")
+            return None
+
+    def has_config(self, item: str) -> bool:
+        """检查配置项是否存在"""
+        return item in self.config_dict
+
+    def lock_config(self):
+        """锁定配置防止修改"""
+        self._lock = True
+
+    def unlock_config(self):
+        """解锁配置允许修改"""
+        self._lock = False
+
+    def is_locked(self) -> bool:
+        """检查配置是否已锁定"""
+        return self._lock
+
+    def bulk_update(self, update_dict: Dict[str, Any]) -> bool:
+        """
+        批量更新配置
+        
+        参数:
+            update_dict: 包含多个键值对的字典
+            
+        返回:
+            True 更新成功, False 更新失败
+        """
+        if self._lock:
+            print("警告: 配置系统已锁定，批量更新被拒绝")
+            return False
+            
+        # 记录变更
+        changes = {}
+        for key, value in update_dict.items():
+            old_value = self.config_dict.get(key)
+            self.config_dict[key] = value
+            changes[key] = (old_value, value)
+        
+        # 批量通知变更
+        for key, (old_value, new_value) in changes.items():
+            self._notify_change(key, old_value, new_value)
+            
+        return True
+
+    def get_all_configs(self) -> Dict[str, Any]:
+        """获取所有配置的副本"""
+        return self.config_dict.copy()
+    
+    def reset_config(self, new_config: Optional[Dict[str, Any]] = None) -> None:
+        """
+        重置所有配置
+        
+        参数:
+            new_config: 新的配置字典 (可选，默认清空)
+        """
+        if self._lock:
+            print("警告: 配置系统已锁定，无法重置")
+            return
+            
+        # 记录所有变更（删除）
+        for key in list(self.config_dict.keys()):
+            old_value = self.config_dict[key]
+            self._notify_change(key, old_value, None)
+        
+        # 重置配置
+        self.config_dict = new_config.copy() if new_config else {}
+        
+        # 通知所有新配置项
+        for key, value in self.config_dict.items():
+            self._notify_change(key, None, value)
+

tretool/encoding.py

@@ -0,0 +1,92 @@
+import chardet
+
+from typing import Union, BinaryIO
+
+def detect_encoding(
+    input_data: Union[bytes, str, BinaryIO],
+    sample_size: int = 1024,
+    fallback_encoding: str = 'utf-8'
+) -> str:
+    """
+    自动检测文本数据的字符编码
+    
+    参数：
+        input_data: 可以是以下类型之一：
+                   - bytes: 原始字节数据
+                   - str: 字符串（将尝试重新编码检测）
+                   - BinaryIO: 文件对象（将读取前sample_size字节）
+        sample_size: 从文件/大数据中采样的字节数（默认1024）
+        fallback_encoding: 无法检测时使用的回退编码（默认'utf-8'）
+    
+    返回：
+        检测到的编码名称字符串
+    
+    示例：
+        # 检测字节数据编码
+        detect_encoding(b'\xc3\xa9chantillon')
+        
+        # 检测文件编码
+        with open('file.txt', 'rb') as f:
+            encoding = detect_encoding(f)
+    """
+    raw_data = _get_sample_data(input_data, sample_size)
+    
+    if not raw_data:
+        return fallback_encoding
+    
+    try:
+        # 使用chardet进行编码检测
+        result = chardet.detect(raw_data)
+        confidence = result['confidence']
+        encoding = result['encoding'].lower()
+        
+        # 验证检测结果
+        if confidence > 0.9:
+            return encoding
+        if confidence > 0.7 and validate_encoding(raw_data, encoding):
+            return encoding
+        
+        # 尝试常见编码验证
+        for enc in ['utf-8', 'latin-1', 'gbk', 'gb2312', 'big5']:
+            if validate_encoding(raw_data, enc):
+                return enc
+                
+    except Exception:
+        pass
+    
+    return fallback_encoding
+
+
+def _get_sample_data(
+    input_data: Union[bytes, str, BinaryIO],
+    sample_size: int
+) -> bytes:
+    """获取用于检测的样本数据"""
+    if isinstance(input_data, bytes):
+        return input_data[:sample_size]
+    
+    if isinstance(input_data, str):
+        try:
+            return input_data.encode('latin-1', errors='ignore')[:sample_size]
+        except:
+            return b''
+    
+    if hasattr(input_data, 'read'):
+        try:
+            pos = input_data.tell()
+            data = input_data.read(sample_size)
+            input_data.seek(pos)  # 重置文件指针
+            return data if isinstance(data, bytes) else b''
+        except:
+            return b''
+    
+    return b''
+
+
+def validate_encoding(data: bytes, encoding: str) -> bool:
+    """验证编码是否有效"""
+    try:
+        data.decode(encoding, errors='strict')
+        return True
+    except:
+        return False

tretool/jsonlib.py

@@ -0,0 +1,299 @@
+import chardet
+from typing import Any, Union, Dict, List, BinaryIO
+
+class JSONEncodeError(Exception):
+    """JSON 编码异常"""
+    pass
+
+class JSONDecodeError(Exception):
+    """JSON 解码异常"""
+    pass
+
+def dump_to_str(obj: Any, indent: Union[int, None] = None) -> str:
+    """
+    将 Python 对象转换为 JSON 字符串
+    
+    参数：
+        obj: 要序列化的 Python 对象
+        indent: 缩进空格数（None 表示紧凑格式）
+    
+    返回：
+        JSON 格式字符串
+    
+    异常：
+        JSONEncodeError: 当遇到不可序列化的对象时
+    """
+    if indent is not None and not isinstance(indent, int):
+        raise TypeError("indent must be int or None")
+    
+    return _Encoder(indent).encode(obj)
+
+def load_from_str(json_str: str) -> Any:
+    """
+    将 JSON 字符串解析为 Python 对象
+    
+    参数：
+        json_str: JSON 格式字符串
+    
+    返回：
+        对应的 Python 对象
+    
+    异常：
+        JSONDecodeError: 当 JSON 格式无效时
+    """
+    parser = _Parser(json_str)
+    return parser.parse()
+
+class _Encoder:
+    """JSON 编码器实现"""
+    
+    def __init__(self, indent: Union[int, None] = None):
+        self.indent = indent
+        self._current_indent = 0
+    
+    def encode(self, obj: Any) -> str:
+        if obj is None:
+            return "null"
+        elif isinstance(obj, bool):
+            return "true" if obj else "false"
+        elif isinstance(obj, (int, float)):
+            return self._encode_number(obj)
+        elif isinstance(obj, str):
+            return self._encode_string(obj)
+        elif isinstance(obj, (list, tuple)):
+            return self._encode_array(obj)
+        elif isinstance(obj, dict):
+            return self._encode_object(obj)
+        else:
+            raise JSONEncodeError(f"Object of type {type(obj)} is not JSON serializable")
+    
+    def _encode_number(self, num: Union[int, float]) -> str:
+        if isinstance(num, int):
+            return str(num)
+        elif num.is_integer():
+            return str(int(num))
+        else:
+            return str(num)
+    
+    def _encode_string(self, s: str) -> str:
+        escape_map = {
+            '\"': '\\"',
+            '\\': '\\\\',
+            '\b': '\\b',
+            '\f': '\\f',
+            '\n': '\\n',
+            '\r': '\\r',
+            '\t': '\\t',
+        }
+        
+        result = []
+        for char in s:
+            if char in escape_map:
+                result.append(escape_map[char])
+            elif ord(char) < 0x20:
+                result.append(f"\\u{ord(char):04x}")
+            else:
+                result.append(char)
+        
+        return f'"{"".join(result)}"'
+    
+    def _encode_array(self, array: List[Any]) -> str:
+        if not array:
+            return "[]"
+        
+        if self.indent is None:
+            items = [self.encode(item) for item in array]
+            return f"[{','.join(items)}]"
+        else:
+            self._current_indent += self.indent
+            indent_str = "\n" + " " * self._current_indent
+            items = [f"{indent_str}{self.encode(item)}" for item in array]
+            self._current_indent -= self.indent
+            return f"[{','.join(items)}\n{' ' * self._current_indent}]"
+    
+    def _encode_object(self, obj: Dict[str, Any]) -> str:
+        if not obj:
+            return "{}"
+        
+        if self.indent is None:
+            items = [f"{self.encode(k)}:{self.encode(v)}" for k, v in obj.items()]
+            return f"{{{','.join(items)}}}"
+        else:
+            self._current_indent += self.indent
+            indent_str = "\n" + " " * self._current_indent
+            items = []
+            for k, v in obj.items():
+                key_str = self.encode(k)
+                value_str = self.encode(v)
+                items.append(f"{indent_str}{key_str}: {value_str}")
+            self._current_indent -= self.indent
+            return f"{{{','.join(items)}\n{' ' * self._current_indent}}}"
+
+class _Parser:
+    """JSON 解析器实现"""
+    
+    def __init__(self, json_str: str):
+        self.json_str = json_str.strip()
+        self.idx = 0
+        self.len = len(json_str)
+    
+    def parse(self) -> Any:
+        char = self._peek()
+        
+        if char == '{':
+            return self._parse_object()
+        elif char == '[':
+            return self._parse_array()
+        elif char == '"':
+            return self._parse_string()
+        elif char == 'n' and self._peek_next(4) == 'null':
+            self.idx += 4
+            return None
+        elif char == 't' and self._peek_next(4) == 'true':
+            self.idx += 4
+            return True
+        elif char == 'f' and self._peek_next(5) == 'false':
+            self.idx += 5
+            return False
+        elif char == '-' or char.isdigit():
+            return self._parse_number()
+        else:
+            raise JSONDecodeError(f"Unexpected character at position {self.idx}: {char}")
+    
+    def _parse_object(self) -> Dict[str, Any]:
+        obj = {}
+        self._consume('{')
+        
+        while self._peek() != '}':
+            # 解析键
+            key = self._parse_string()
+            self._consume(':')
+            
+            # 解析值
+            value = self.parse()
+            obj[key] = value
+            
+            # 处理逗号或结束
+            if self._peek() == ',':
+                self._consume(',')
+            elif self._peek() != '}':
+                raise JSONDecodeError("Expected ',' or '}' after object pair")
+        
+        self._consume('}')
+        return obj
+    
+    def _parse_array(self) -> List[Any]:
+        arr = []
+        self._consume('[')
+        
+        while self._peek() != ']':
+            # 解析元素
+            arr.append(self.parse())
+            
+            # 处理逗号或结束
+            if self._peek() == ',':
+                self._consume(',')
+            elif self._peek() != ']':
+                raise JSONDecodeError("Expected ',' or ']' after array element")
+        
+        self._consume(']')
+        return arr
+    
+    def _parse_string(self) -> str:
+        self._consume('"')
+        chars = []
+        
+        while self._peek() != '"':
+            char = self._peek()
+            
+            if char == '\\':
+                self._consume('\\')
+                esc_char = self._peek()
+                if esc_char == 'u':
+                    # Unicode 转义
+                    self._consume('u')
+                    hex_str = self.json_str[self.idx:self.idx+4]
+                    if len(hex_str) != 4:
+                        raise JSONDecodeError("Invalid Unicode escape sequence")
+                    self.idx += 4
+                    chars.append(chr(int(hex_str, 16)))
+                else:
+                    # 简单转义字符
+                    escape_map = {
+                        '"': '"',
+                        '\\': '\\',
+                        '/': '/',
+                        'b': '\b',
+                        'f': '\f',
+                        'n': '\n',
+                        'r': '\r',
+                        't': '\t',
+                    }
+                    chars.append(escape_map.get(esc_char, esc_char))
+                    self._consume(esc_char)
+            else:
+                chars.append(char)
+                self._consume(char)
+        
+        self._consume('"')
+        return ''.join(chars)
+    
+    def _parse_number(self) -> Union[int, float]:
+        start_idx = self.idx
+        is_float = False
+        
+        # 处理符号
+        if self._peek() == '-':
+            self._consume('-')
+        
+        # 整数部分
+        while self._peek().isdigit():
+            self._consume()
+        
+        # 小数部分
+        if self._peek() == '.':
+            is_float = True
+            self._consume('.')
+            while self._peek().isdigit():
+                self._consume()
+        
+        # 指数部分
+        if self._peek().lower() == 'e':
+            is_float = True
+            self._consume()
+            if self._peek() in ('+', '-'):
+                self._consume()
+            while self._peek().isdigit():
+                self._consume()
+        
+        num_str = self.json_str[start_idx:self.idx]
+        try:
+            return float(num_str) if is_float else int(num_str)
+        except ValueError:
+            raise JSONDecodeError(f"Invalid number literal: {num_str}")
+    
+    def _peek(self) -> str:
+        if self.idx >= self.len:
+            raise JSONDecodeError("Unexpected end of JSON input")
+        return self.json_str[self.idx]
+    
+    def _peek_next(self, n: int) -> str:
+        if self.idx + n > self.len:
+            raise JSONDecodeError("Unexpected end of JSON input")
+        return self.json_str[self.idx:self.idx+n]
+    
+    def _consume(self, expected: str = None):
+        if expected is not None and self._peek() != expected:
+            raise JSONDecodeError(f"Expected '{expected}' at position {self.idx}")
+        self.idx += 1
+
+# 简化版接口
+def dump_to_file(obj: Any, filepath: str, indent: Union[int, None] = 4, encoding:str='utf-8'):
+    """将 Python 对象序列化为 JSON 格式并写入文件"""
+    with open(filepath, 'w', encoding=encoding) as file:
+        file.write(dump_to_str(obj, indent))
+
+def load_from_file(filepath:str, encoding:str='utf-8'):
+    """从文件读取 JSON 数据并解析为 Python 对象"""
+    with open(filepath, 'r', encoding=encoding) as file:
+        return load_from_str(file.read())