mdbq 4.0.23__py3-none-any.whl → 4.0.24__py3-none-any.whl

mdbq/myconf/{myconf2.py → myconf_bak.py}

@@ -22,7 +22,14 @@ T = TypeVar('T')  # 类型变量
 
 
 class ConfigError(Exception):
-    """配置相关的基础异常类"""
+    """配置相关的基础异常类
+    
+    Attributes:
+        message: 错误消息
+        file_path: 配置文件路径
+        section: 配置节名称
+        key: 配置键名称
+    """
     def __init__(self, message: str, file_path: Optional[Union[str, Path]] = None, 
                  section: Optional[str] = None, key: Optional[str] = None):
         self.message = message
@@ -44,13 +51,17 @@ class ConfigError(Exception):
 
 
 class ConfigFileNotFoundError(ConfigError):
-    """配置文件不存在异常"""
+    """当指定的配置文件不存在时抛出的异常"""
     def __init__(self, file_path: Union[str, Path]):
         super().__init__("配置文件不存在", file_path=file_path)
 
 
 class ConfigReadError(ConfigError):
-    """读取配置文件失败异常"""
+    """当读取配置文件失败时抛出的异常
+    
+    Attributes:
+        original_error: 原始错误对象
+    """
     def __init__(self, file_path: Union[str, Path], original_error: Exception):
         super().__init__(
             f"读取配置文件失败: {str(original_error)}",
@@ -60,7 +71,11 @@ class ConfigReadError(ConfigError):
 
 
 class ConfigWriteError(ConfigError):
-    """写入配置文件失败异常"""
+    """当写入配置文件失败时抛出的异常
+    
+    Attributes:
+        original_error: 原始错误对象
+    """
     def __init__(self, file_path: Union[str, Path], original_error: Exception):
         super().__init__(
             f"写入配置文件失败: {str(original_error)}",
@@ -70,14 +85,14 @@ class ConfigWriteError(ConfigError):
 
 
 class ConfigValueError(ConfigError):
-    """配置值无效异常"""
+    """当配置值无效时抛出的异常"""
     def __init__(self, message: str, file_path: Union[str, Path], 
                  section: Optional[str] = None, key: Optional[str] = None):
         super().__init__(message, file_path=file_path, section=section, key=key)
 
 
 class ConfigSectionNotFoundError(ConfigError):
-    """配置节不存在异常"""
+    """当指定的配置节不存在时抛出的异常"""
     def __init__(self, file_path: Union[str, Path], section: str):
         super().__init__(
             f"配置节不存在",
@@ -87,7 +102,7 @@ class ConfigSectionNotFoundError(ConfigError):
 
 
 class ConfigKeyNotFoundError(ConfigError):
-    """配置键不存在异常"""
+    """当指定的配置键不存在时抛出的异常"""
     def __init__(self, file_path: Union[str, Path], section: str, key: str):
         super().__init__(
             f"配置键不存在",
@@ -106,7 +121,21 @@ class CommentStyle(Enum):
 
 @dataclass
 class ConfigOptions:
-    """配置解析器选项"""
+    """配置解析器的选项类
+    
+    Attributes:
+        comment_styles: 支持的注释风格列表
+        encoding: 文件编码
+        auto_create: 是否自动创建不存在的配置文件
+        strip_values: 是否去除配置值的首尾空白
+        preserve_comments: 是否保留注释
+        default_section: 默认配置节名称
+        separators: 支持的分隔符列表
+        cache_ttl: 缓存过期时间（秒）
+        validate_keys: 是否验证键名
+        key_pattern: 键名正则表达式模式
+        case_sensitive: 是否区分大小写
+    """
     comment_styles: List[CommentStyle] = field(default_factory=lambda: [CommentStyle.HASH, CommentStyle.DOUBLE_SLASH])
     encoding: str = 'utf-8'
     auto_create: bool = False
@@ -121,26 +150,57 @@ class ConfigOptions:
 
 
 class ConfigParser:
-    """配置文件解析器"""
+    """配置文件解析器，用于读取和写入配置文件
+    
+    Attributes:
+        options: 解析器配置选项
+        _config_cache: 配置缓存，用于存储已读取的配置
+        _cache_timestamps: 缓存时间戳，用于管理缓存过期
+        _comments_cache: 注释缓存，用于存储每个配置节的注释
+        _section_map: 用于存储大小写映射
+        _current_file: 当前正在处理的文件路径
+    """
     
     def __init__(self, options: Optional[ConfigOptions] = None):
         self.options = options or ConfigOptions()
         self._config_cache: Dict[str, Dict[str, Any]] = {}
         self._cache_timestamps: Dict[str, float] = {}
         self._comments_cache: Dict[str, Dict[str, List[str]]] = {}
-        self._section_map: Dict[str, Dict[str, str]] = {}
-        self._current_file: Optional[Path] = None
+        self._section_map: Dict[str, Dict[str, str]] = {}  # 用于存储大小写映射
+        self._current_file: Optional[Path] = None  # 当前正在处理的文件路径
     
     def __enter__(self) -> 'ConfigParser':
+        """进入上下文管理器
+        
+        Returns:
+            ConfigParser: 返回当前实例
+        """
         return self
 
     def __exit__(self, exc_type: Optional[Type[BaseException]], 
                  exc_val: Optional[BaseException], 
                  exc_tb: Optional[Any]) -> None:
+        """退出上下文管理器
+        
+        Args:
+            exc_type: 异常类型
+            exc_val: 异常值
+            exc_tb: 异常追踪信息
+        """
         self._current_file = None
 
     def open(self, file_path: Union[str, Path]) -> 'ConfigParser':
-        """打开配置文件"""
+        """打开配置文件
+        
+        Args:
+            file_path: 配置文件路径
+            
+        Returns:
+            ConfigParser: 返回当前实例，支持链式调用
+            
+        Raises:
+            ConfigFileNotFoundError: 当配置文件不存在且未启用自动创建时
+        """
         file_path = Path(file_path)
         if not file_path.exists() and not self.options.auto_create:
             raise ConfigFileNotFoundError(file_path)
@@ -148,17 +208,25 @@ class ConfigParser:
         return self
 
     def _ensure_file_open(self) -> None:
-        """确保文件已打开"""
+        """确保文件已打开
+        
+        Raises:
+            ConfigError: 当文件未打开时
+        """
         if self._current_file is None:
             raise ConfigError("未打开任何配置文件，请先调用 open() 方法")
 
     def _is_comment_line(self, line: str) -> bool:
-        """判断是否为注释行"""
+        """判断一行是否为注释行"""
         stripped = line.strip()
         return any(stripped.startswith(style.value) for style in self.options.comment_styles)
     
     def _extract_comment(self, line: str) -> Tuple[str, str]:
-        """从行中提取注释"""
+        """从行中提取注释
+        
+        Returns:
+            Tuple[str, str]: (去除注释后的行内容, 注释内容)
+        """
         for style in self.options.comment_styles:
             comment_match = re.search(fr'\s+{re.escape(style.value)}.*$', line)
             if comment_match:
@@ -166,7 +234,14 @@ class ConfigParser:
         return line.strip(), ''
     
     def _split_key_value(self, line: str) -> Optional[Tuple[str, str]]:
-        """分割配置行为键值对"""
+        """分割配置行为键值对
+        
+        Args:
+            line: 要分割的配置行
+            
+        Returns:
+            Optional[Tuple[str, str]]: 键值对元组，如果无法分割则返回None
+        """
         for sep in self.options.separators:
             if sep in line:
                 key_part, value_part = line.split(sep, 1)
@@ -188,8 +263,11 @@ class ConfigParser:
         return bool(re.match(self.options.key_pattern, key))
     
     def _get_cached_config(self, file_path: str) -> Optional[Dict[str, Any]]:
-        """获取缓存的配置"""
-        if file_path not in self._config_cache or file_path not in self._cache_timestamps:
+        """获取缓存的配置，如果过期则返回None"""
+        if file_path not in self._config_cache:
+            return None
+        
+        if file_path not in self._cache_timestamps:
             return None
         
         if time.time() - self._cache_timestamps[file_path] > self.options.cache_ttl:
@@ -203,8 +281,10 @@ class ConfigParser:
         self._cache_timestamps[file_path] = time.time()
     
     def _normalize_section(self, section: str) -> str:
-        """标准化节名称"""
-        return section if self.options.case_sensitive else section.lower()
+        """标准化节名称（处理大小写）"""
+        if self.options.case_sensitive:
+            return section
+        return section.lower()
     
     def _get_original_section(self, file_path: str, normalized_section: str) -> Optional[str]:
         """获取原始节名称"""
@@ -233,50 +313,73 @@ class ConfigParser:
             self._comments_cache.clear()
             self._section_map.clear()
     
-    def _convert_value(self, value: str, target_type: Type[T], file_path: Optional[Union[str, Path]] = None, key: Optional[str] = None) -> T:
-        """转换配置值到指定类型"""
+    def _convert_value(self, value: str, target_type: Type[T]) -> T:
+        """转换配置值到指定类型
+        
+        Args:
+            value: 要转换的值
+            target_type: 目标类型
+            
+        Returns:
+            T: 转换后的值
+            
+        Raises:
+            ConfigValueError: 当值无法转换为指定类型时
+        """
         try:
             if target_type == bool:
                 return bool(value.lower() in ('true', 'yes', '1', 'on'))
             elif target_type == list:
+                # 支持多种分隔符的列表
                 if not value.strip():
                     return []
+                # 尝试不同的分隔符
                 for sep in [',', ';', '|', ' ']:
                     if sep in value:
                         return [item.strip() for item in value.split(sep) if item.strip()]
+                # 如果没有分隔符，则作为单个元素返回
                 return [value.strip()]
             elif target_type == tuple:
+                # 支持元组类型
                 if not value.strip():
                     return ()
+                # 尝试不同的分隔符
                 for sep in [',', ';', '|', ' ']:
                     if sep in value:
                         return tuple(item.strip() for item in value.split(sep) if item.strip())
+                # 如果没有分隔符，则作为单个元素返回
                 return (value.strip(),)
-            elif target_type == set or target_type == frozenset:
+            elif target_type == set:
+                # 支持集合类型
                 if not value.strip():
-                    return set() if target_type == set else frozenset()
+                    return set()
+                # 尝试不同的分隔符
                 for sep in [',', ';', '|', ' ']:
                     if sep in value:
-                        items = [item.strip() for item in value.split(sep) if item.strip()]
-                        return set(items) if target_type == set else frozenset(items)
-                return set([value.strip()]) if target_type == set else frozenset([value.strip()])
+                        return {item.strip() for item in value.split(sep) if item.strip()}
+                # 如果没有分隔符，则作为单个元素返回
+                return {value.strip()}
             elif target_type == dict:
+                # 支持字典类型，格式：key1=value1,key2=value2
                 if not value.strip():
                     return {}
                 result = {}
+                # 尝试不同的分隔符
                 for sep in [',', ';', '|']:
                     if sep in value:
                         pairs = [pair.strip() for pair in value.split(sep) if pair.strip()]
                         for pair in pairs:
                             if '=' in pair:
-                                key_, val = pair.split('=', 1)
-                                result[key_.strip()] = val.strip()
+                                key, val = pair.split('=', 1)
+                                result[key.strip()] = val.strip()
                         return result
+                # 如果没有分隔符，尝试单个键值对
                 if '=' in value:
-                    key_, val = value.split('=', 1)
-                    return {key_.strip(): val.strip()}
+                    key, val = value.split('=', 1)
+                    return {key.strip(): val.strip()}
                 return {}
             elif target_type == int:
+                # 支持十六进制、八进制、二进制
                 value = value.strip().lower()
                 if value.startswith('0x'):
                     return int(value, 16)
@@ -293,7 +396,12 @@ class ConfigParser:
                 return value.encode('utf-8')
             elif target_type == bytearray:
                 return bytearray(value.encode('utf-8'))
+            elif target_type == set:
+                return set(value.split(','))
+            elif target_type == frozenset:
+                return frozenset(value.split(','))
             elif target_type == range:
+                # 支持 range 类型，格式：start:stop:step 或 start:stop
                 parts = value.split(':')
                 if len(parts) == 2:
                     return range(int(parts[0]), int(parts[1]))
@@ -304,41 +412,79 @@ class ConfigParser:
         except (ValueError, TypeError) as e:
             raise ConfigValueError(
                 f"无法将值 '{value}' 转换为类型 {target_type.__name__}",
-                file_path=file_path,
-                key=key
+                file_path=None,
+                key=None
             )
     
     def get_value(self, file_path: Optional[Union[str, Path]] = None, key: str = None, 
                  section: Optional[str] = None, default: Any = None,
                  value_type: Optional[Type[T]] = None) -> T:
-        """获取指定配置项的值"""
+        """获取指定配置项的值
+        
+        Args:
+            file_path: 配置文件路径，如果为None则使用当前打开的文件
+            key: 配置键
+            section: 配置节名称，如果为None则使用默认节
+            default: 当配置项不存在时返回的默认值
+            value_type: 期望的值的类型
+            
+        Returns:
+            T: 配置值
+            
+        Raises:
+            ConfigSectionNotFoundError: 当指定的节不存在且未提供默认值时
+            ConfigKeyNotFoundError: 当指定的键不存在且未提供默认值时
+            ConfigValueError: 当值无法转换为指定类型时
+        """
         if file_path is None:
             self._ensure_file_open()
             file_path = self._current_file
         if not self._validate_key(key):
             raise ConfigValueError(f"无效的键名: {key}", file_path=file_path, key=key)
+            
         config = self.read(file_path)
         section = section or self.options.default_section
         normalized_section = self._normalize_section(section)
+        
+        # 获取原始节名称
         original_section = self._get_original_section(str(file_path), normalized_section)
         if original_section is None:
             if default is not None:
                 return default
             raise ConfigSectionNotFoundError(file_path, section)
+            
         if key not in config[original_section]:
             if default is not None:
                 return default
             raise ConfigKeyNotFoundError(file_path, original_section, key)
+            
         value = config[original_section][key]
+        
         if value_type is not None:
-            return self._convert_value(value, value_type, file_path=file_path, key=key)
+            return self._convert_value(value, value_type)
+            
         return value
     
     def get_values(self, keys: List[Tuple[str, str]], 
                   file_path: Optional[Union[str, Path]] = None,
                   defaults: Optional[Dict[str, Any]] = None,
                   value_types: Optional[Dict[str, Type]] = None) -> Dict[str, Any]:
-        """批量获取多个配置项的值"""
+        """批量获取多个配置项的值
+        
+        Args:
+            keys: 配置项列表，每个元素为 (section, key) 元组
+            file_path: 配置文件路径，如果为None则使用当前打开的文件
+            defaults: 默认值字典，格式为 {key: default_value}
+            value_types: 值类型字典，格式为 {key: type}
+            
+        Returns:
+            Dict[str, Any]: 配置值字典，格式为 {key: value}
+            
+        Raises:
+            ConfigSectionNotFoundError: 当指定的节不存在且未提供默认值时
+            ConfigKeyNotFoundError: 当指定的键不存在且未提供默认值时
+            ConfigValueError: 当值无法转换为指定类型时
+        """
         if file_path is None:
             self._ensure_file_open()
             file_path = self._current_file
@@ -369,7 +515,23 @@ class ConfigParser:
                           file_path: Optional[Union[str, Path]] = None,
                           defaults: Optional[Dict[str, Any]] = None,
                           value_types: Optional[Dict[str, Type]] = None) -> Tuple[Any, ...]:
-        """获取指定节点下多个键的值元组"""
+        """获取指定节点下多个键的值元组
+        
+        Args:
+            keys: 要获取的键列表
+            section: 配置节名称，默认为 DEFAULT
+            file_path: 配置文件路径，如果为None则使用当前打开的文件
+            defaults: 默认值字典，格式为 {key: default_value}
+            value_types: 值类型字典，格式为 {key: type}
+            
+        Returns:
+            Tuple[Any, ...]: 按键列表顺序返回的值元组
+            
+        Raises:
+            ConfigSectionNotFoundError: 当指定的节不存在且未提供默认值时
+            ConfigKeyNotFoundError: 当指定的键不存在且未提供默认值时
+            ConfigValueError: 当值无法转换为指定类型时
+        """
         if file_path is None:
             self._ensure_file_open()
             file_path = self._current_file
@@ -399,20 +561,37 @@ class ConfigParser:
                  section: Optional[str] = None,
                  file_path: Optional[Union[str, Path]] = None,
                  value_type: Optional[Type] = None) -> None:
-        """设置指定配置项的值"""
+        """设置指定配置项的值，保持原始文件的格式和注释
+        
+        Args:
+            key: 配置键
+            value: 要设置的值
+            section: 配置节名称，如果为None则使用默认节
+            file_path: 配置文件路径，如果为None则使用当前打开的文件
+            value_type: 值的类型，用于验证和转换
+            
+        Raises:
+            ConfigValueError: 当值无法转换为指定类型时
+            ConfigError: 当其他配置错误发生时
+        """
         if file_path is None:
             self._ensure_file_open()
             file_path = self._current_file
         if not self._validate_key(key):
             raise ConfigValueError(f"无效的键名: {key}", file_path=file_path, key=key)
-        section = section or self.options.default_section
+            
+        # 读取原始文件內容
         original_lines = []
         if file_path.exists():
             with open(file_path, 'r', encoding=self.options.encoding) as file:
                 original_lines = file.readlines()
+        
+        # 读取当前配置
         config = self.read(file_path)
+        
         if section not in config:
             config[section] = {}
+            
         if value_type is not None:
             try:
                 if value_type == bool:
@@ -429,63 +608,96 @@ class ConfigParser:
                     section=section,
                     key=key
                 )
+        
         if isinstance(value, bool):
             value = str(value).lower()
         else:
             value = str(value)
+            
+        # 更新配置
         config[section][key] = value
+        
+        # 写入文件，保持原始格式
         try:
             file_path.parent.mkdir(parents=True, exist_ok=True)
+            
             with open(file_path, 'w', encoding=self.options.encoding) as file:
                 current_section = self.options.default_section
-                section_separators = {}
+                section_separators = {}  # 用于存储每个section使用的分隔符
+                
+                # 解析原始文件，提取格式信息
                 for line in original_lines:
                     stripped_line = line.strip()
+                    
                     if not stripped_line:
-                        file.write(line)
+                        file.write(line)  # 保持空行
                         continue
+                        
                     if stripped_line.startswith('[') and stripped_line.endswith(']'):
                         current_section = stripped_line[1:-1]
-                        file.write(line)
+                        file.write(line)  # 保持节标记的原始格式
                         continue
+                        
                     if self._is_comment_line(stripped_line):
-                        file.write(line)
+                        file.write(line)  # 保持注释的原始格式
                         continue
+                        
                     key_value = self._split_key_value(stripped_line)
                     if key_value:
                         orig_key, orig_value = key_value
+                        # 检测使用的分隔符
                         for sep in self.options.separators:
                             if sep in line:
                                 section_separators.setdefault(current_section, {})[orig_key] = sep
                                 break
+                        
+                        # 如果是当前要修改的键，则写入新值
                         if current_section == section and orig_key == key:
                             separator = section_separators.get(current_section, {}).get(orig_key, self.options.separators[0])
+                            # 提取行尾注释
                             comment = ''
                             for style in self.options.comment_styles:
                                 comment_match = re.search(fr'\s+{re.escape(style.value)}.*$', line)
                                 if comment_match:
                                     comment = comment_match.group(0)
                                     break
+                            # 写入新值并保留注释
                             file.write(f'{key}{separator}{value}{comment}\n')
                         else:
-                            file.write(line)
+                            file.write(line)  # 保持其他行的原始格式
                     else:
-                        file.write(line)
+                        file.write(line)  # 保持无法解析的行的原始格式
+                
+                # 如果section不存在，则添加新的section
                 if section not in [line.strip()[1:-1] for line in original_lines if line.strip().startswith('[') and line.strip().endswith(']')]:
                     file.write(f'\n[{section}]\n')
                     file.write(f'{key}={value}\n')
+            
             self._clear_cache(str(file_path))
+            
         except Exception as e:
             raise ConfigWriteError(file_path, e)
     
     def read(self, file_path: Optional[Union[str, Path]] = None) -> Dict[str, Any]:
-        """读取配置文件内容"""
+        """读取配置文件内容
+        
+        Args:
+            file_path: 配置文件路径，如果为None则使用当前打开的文件
+            
+        Returns:
+            Dict[str, Any]: 配置字典，格式为 {section: {key: value}}
+            
+        Raises:
+            ConfigFileNotFoundError: 当配置文件不存在且未启用自动创建时
+            ConfigReadError: 当读取配置文件失败时
+        """
         if file_path is None:
             self._ensure_file_open()
             file_path = self._current_file
         else:
-            file_path = Path(file_path)
+            file_path = Path(file_path)  # 确保 file_path 是 Path 对象
         
+        # 检查缓存
         cached_config = self._get_cached_config(str(file_path))
         if cached_config is not None:
             return cached_config
@@ -555,39 +767,49 @@ class ConfigParser:
                 
         except Exception as e:
             raise ConfigReadError(file_path, e)
-
+    
 
 def main() -> None:
-    """示例用法"""
+    # 使用示例
     config_file = Path('/Users/xigua/spd.txt')
-    try:
-        # 方式1：使用上下文管理器
-        with ConfigParser() as parser:
-            parser.open(config_file)
-            host, port, username, password = parser.get_section_values(
-                keys=['host', 'port', 'username', 'password'],
-                section='mysql'
-            )
-            print("方式1结果:", host, port, username, password)
-            parser.set_value('username', 'root', section='mysql')
-            parser.set_value('port', 3306, section='mysql')
-        # 方式2：链式调用
-        parser = ConfigParser()
-        host, port, username, password = parser.open(config_file).get_section_values(
+    
+    # 方式1：使用上下文管理器
+    with ConfigParser() as parser:
+        parser.open(config_file)
+        host, port, username, password = parser.get_section_values(
             keys=['host', 'port', 'username', 'password'],
             section='mysql'
         )
-        print("\n方式2结果:", host, port, username, password)
-        # 方式3：传统方式
-        parser = ConfigParser()
-        host, port, username, password = parser.get_section_values(
-            file_path=config_file,
-            section='mysql',
-            keys=['host', 'port', 'username', 'password']
-        )
-        print("\n方式3结果:", host, port, username, password)
-    except Exception as e:
-        print(f"配置文件操作异常: {e}")
+        print("方式1结果:", host, port, username, password)
+        
+        # 修改配置
+        parser.set_value('host', 'localhost', section='mysql')
+        parser.set_value('port', 3306, section='mysql')
+        
+        # # 读取整个配置
+        # config = parser.read()
+        # print("\n当前配置:")
+        # for section, items in config.items():
+        #     print(f"\n[{section}]")
+        #     for key, value in items.items():
+        #         print(f"{key} = {value}")
+    
+    # 方式2：链式调用
+    parser = ConfigParser()
+    host, port, username, password = parser.open(config_file).get_section_values(
+        keys=['host', 'port', 'username', 'password'],
+        section='mysql'
+    )
+    print("\n方式2结果:", host, port, username, password)
+    
+    # 方式3：传统方式
+    parser = ConfigParser()
+    host, port, username, password = parser.get_section_values(
+        file_path=config_file,
+        section='mysql',
+        keys=['host', 'port', 'username', 'password']
+    )
+    print("\n方式3结果:", host, port, username, password)
 
 
 if __name__ == '__main__':

{mdbq-4.0.23.dist-info → mdbq-4.0.24.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: mdbq
-Version: 4.0.23
+Version: 4.0.24
 Home-page: https://pypi.org/project/mdbq
 Author: xigua, 
 Author-email: 2587125111@qq.com