evm-cli 2.4.0__py3-none-any.whl

evm/_schema.py

@@ -0,0 +1,265 @@
+#!/usr/bin/env python3
+"""
+EVM Schema Mixin
+
+变量 schema 定义和校验功能。
+支持格式：url, email, port, integer, boolean, path, ipv4, ipv6
+"""
+
+import ipaddress
+import json
+import os
+import re
+import warnings
+from pathlib import Path
+from typing import Optional
+
+from ._typing import EnvironmentManagerProtocol
+from .exceptions import SchemaError
+
+# 内置格式校验正则
+FORMAT_PATTERNS = {
+    'url': re.compile(
+        r'^https?://[^\s/$.?#].[^\s]*$', re.IGNORECASE
+    ),
+    'email': re.compile(
+        r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
+    ),
+    'port': re.compile(r'^[0-9]{1,5}$'),
+    'integer': re.compile(r'^-?[0-9]+$'),
+    'boolean': re.compile(r'^(true|false|yes|no|1|0)$', re.IGNORECASE),
+    'path': re.compile(r'^[/~.].*|^[a-zA-Z]:\\.*'),
+    'ipv4': re.compile(
+        r'^(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}'
+        r'(?:25[0-5]|2[0-4]\d|[01]?\d\d?)$'
+    ),
+}
+
+# 环境变量 key 名校验正则
+VALID_KEY_PATTERN = re.compile(r'^[A-Za-z_][A-Za-z0-9_]*(?::[A-Za-z_][A-Za-z0-9_]*)*$')
+
+
+def validate_ipv6(value: str) -> bool:
+    """#7: 使用标准库 ipaddress 校验 IPv6 地址"""
+    try:
+        ipaddress.IPv6Address(value)
+        return True
+    except (ipaddress.AddressValueError, ValueError):
+        return False
+
+
+class SchemaMixin(EnvironmentManagerProtocol):
+    """Schema mixin — 变量格式定义和校验"""
+
+    def _get_schema_file(self) -> Path:
+        """获取 schema 文件路径"""
+        return self.env_file.parent / 'schema.json'
+
+    def _load_schema(self) -> dict:
+        """加载 schema 定义
+
+        损坏时使用 warnings.warn() 通知调用者，而非直接 print()，
+        保持 mixin 不做 I/O 的设计原则。
+        """
+        schema_file = self._get_schema_file()
+        if not schema_file.exists():
+            return {}
+        try:
+            with open(schema_file, encoding='utf-8') as f:
+                return json.load(f)  # type: ignore[no-any-return]
+        except json.JSONDecodeError as e:
+            warnings.warn(
+                f"Schema file is corrupted ({e}). "
+                f"All schema definitions will be ignored until fixed.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+            return {}
+        except OSError as e:
+            warnings.warn(
+                f"Cannot read schema file ({e}). "
+                f"All schema definitions will be ignored.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+            return {}
+
+    def _save_schema(self, schema: dict) -> None:
+        """保存 schema 定义"""
+        schema_file = self._get_schema_file()
+        try:
+            with open(schema_file, 'w', encoding='utf-8') as f:
+                json.dump(schema, f, indent=2, ensure_ascii=False)
+            os.chmod(str(schema_file), 0o600)
+        except OSError as e:
+            raise SchemaError(f"Failed to save schema: {e}")
+
+    def set_schema(
+        self,
+        key: str,
+        format: Optional[str] = None,
+        required: Optional[bool] = None,
+        pattern: Optional[str] = None,
+        description: Optional[str] = None,
+    ) -> str:
+        """为变量设置 schema 定义
+
+        Args:
+            key: 变量名
+            format: 内置格式 (url/email/port/integer/boolean/path/ipv4/ipv6)
+            required: 是否必填
+            pattern: 自定义正则
+            description: 描述
+
+        Returns:
+            确认消息
+        """
+        available_formats = list(FORMAT_PATTERNS.keys()) + ['ipv6']
+        if format and format not in available_formats:
+            raise SchemaError(
+                f"Unknown format '{format}'. "
+                f"Available: {', '.join(sorted(available_formats))}",
+                key,
+            )
+
+        schema = self._load_schema()
+        entry = schema.get(key, {})
+
+        if format is not None:
+            entry['format'] = format
+        if required is not None:
+            entry['required'] = required
+        if pattern is not None:
+            # 验证正则是否合法
+            try:
+                re.compile(pattern)
+            except re.error as e:
+                raise SchemaError(f"Invalid regex pattern: {e}", key)
+            entry['pattern'] = pattern
+        if description is not None:
+            entry['description'] = description
+
+        if not entry:
+            raise SchemaError("No schema properties specified", key)
+
+        schema[key] = entry
+        self._save_schema(schema)
+        return f"Schema set for '{key}': {json.dumps(entry, ensure_ascii=False)}"
+
+    def get_schema(self, key: Optional[str] = None) -> dict:
+        """获取 schema 定义
+
+        Args:
+            key: 指定变量名（None 返回全部）
+        """
+        schema = self._load_schema()
+        if key is not None:
+            if key not in schema:
+                raise SchemaError(f"No schema defined for '{key}'", key)
+            return {key: schema[key]}
+        return schema
+
+    def delete_schema(self, key: str) -> str:
+        """删除变量的 schema 定义"""
+        schema = self._load_schema()
+        if key not in schema:
+            raise SchemaError(f"No schema defined for '{key}'", key)
+        del schema[key]
+        self._save_schema(schema)
+        return f"Schema removed for '{key}'"
+
+    def validate(
+        self, key: str, value: Optional[str] = None
+    ) -> dict:
+        """校验变量值是否符合 schema
+
+        Args:
+            key: 变量名
+            value: 待校验值（None 则使用当前存储的值）
+
+        Returns:
+            {'valid': bool, 'errors': [...], 'warnings': [...]}
+        """
+        schema = self._load_schema()
+        if key not in schema:
+            raise SchemaError(f"No schema defined for '{key}'", key)
+
+        if value is None:
+            if key not in self._env_vars:
+                entry = schema[key]
+                if entry.get('required', False):
+                    return {
+                        'valid': False,
+                        'errors': [f"Required variable '{key}' is not set"],
+                        'warnings': [],
+                    }
+                return {
+                    'valid': True, 'errors': [],
+                    'warnings': ['Variable not set (not required)'],
+                }
+            value = self._env_vars[key]
+
+        return self._validate_value(key, str(value), schema[key])
+
+    def validate_all(self) -> dict[str, dict]:
+        """校验所有有 schema 定义的变量"""
+        schema = self._load_schema()
+        results = {}
+
+        for key, entry in schema.items():
+            if key in self._env_vars:
+                results[key] = self._validate_value(
+                    key, str(self._env_vars[key]), entry
+                )
+            elif entry.get('required', False):
+                results[key] = {
+                    'valid': False,
+                    'errors': [f"Required variable '{key}' is not set"],
+                    'warnings': [],
+                }
+            else:
+                results[key] = {
+                    'valid': True,
+                    'errors': [],
+                    'warnings': ['Variable not set (not required)'],
+                }
+
+        return results
+
+    def _validate_value(
+        self, key: str, value: str, entry: dict
+    ) -> dict:
+        """内部：校验单个值"""
+        errors: list[str] = []
+        warnings: list[str] = []
+
+        # 格式校验
+        fmt = entry.get('format')
+        if fmt == 'ipv6':
+            # #7: 使用 ipaddress 标准库校验
+            if not validate_ipv6(value):
+                errors.append(
+                    f"Value '{value}' does not match format 'ipv6'"
+                )
+        elif fmt and fmt in FORMAT_PATTERNS:
+            if not FORMAT_PATTERNS[fmt].match(value):
+                errors.append(
+                    f"Value '{value}' does not match format '{fmt}'"
+                )
+
+        # 自定义正则校验
+        pattern = entry.get('pattern')
+        if pattern:
+            try:
+                if not re.match(pattern, value):
+                    errors.append(
+                        f"Value '{value}' does not match pattern '{pattern}'"
+                    )
+            except re.error:
+                errors.append(f"Invalid schema regex: '{pattern}'")
+
+        return {
+            'valid': len(errors) == 0,
+            'errors': errors,
+            'warnings': warnings,
+        }

evm/_typing.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""
+EVM 类型定义
+
+定义 Mixin 类期望的接口协议。
+Mixin 继承此协议后可消除 type: ignore[attr-defined] 注释，
+并让 mypy 正确校验跨 mixin 的属性访问。
+"""
+
+from pathlib import Path
+from typing import Protocol
+
+
+class EnvironmentManagerProtocol(Protocol):
+    """EnvironmentManager 的协议定义，供 Mixin 类使用。
+
+    所有 mixin（IOMixin、GroupMixin、HistoryMixin、SchemaMixin）
+    在运行时期望宿主类提供以下属性和方法。
+    """
+
+    env_file: Path
+    _env_vars: dict[str, str]
+    lock_timeout: float
+
+    def _save_env_vars(self, dry_run: bool = False) -> None:
+        """保存环境变量到存储文件"""
+        ...
+
+    def log_operation(
+        self,
+        operation: str,
+        key: str = '',
+        details: str = '',
+        status: str = 'success',
+    ) -> None:
+        """记录操作日志"""
+        ...
+
+
+__all__ = ['EnvironmentManagerProtocol']