springbootAI 1.8.0__py3-none-any.whl

spring/i18n/properties.py

@@ -0,0 +1,168 @@
+"""Java 风格 ``.properties`` 文件解析器。
+
+对齐 ``java.util.Properties.load`` 的常见行为：
+- ``key=value`` / ``key:value`` / ``key value`` 三种分隔符。
+- ``#`` / ``!`` 开头为注释行。
+- 反斜杠续行：行尾 ``\\`` 与下一行拼接（去除前导空白）。
+- 转义序列：``\\n`` ``\\t`` ``\\r`` ``\\f`` ``\\\\`` ``\\:`` ``\\=`` ``\\uXXXX``。
+- 默认 UTF-8 编码（Java 9+ ``Properties`` 默认 ISO-8859-1，但 Spring
+  ``ResourceBundleMessageSource.setDefaultEncoding("UTF-8")`` 是事实标准）。
+
+不实现：
+- ``Properties.store`` 写出（本框架仅读取国际化资源）。
+- XML 属性文件（``Properties.loadFromXML``）。
+"""
+from __future__ import annotations
+
+import io
+import re
+from typing import Dict, Mapping, TextIO, Union
+
+
+# ==================== 转义序列处理 ====================
+
+_ESCAPES = {
+    "n": "\n", "t": "\t", "r": "\r", "f": "\f",
+    "\\": "\\", ":": ":", "=": "=", "#": "#", "!": "!", "\"": "\"", "'": "'",
+    "0": "\0",
+    # 单引号在 Java Properties 中并非转义，但 MessageFormat 中是；此处保守保留原样
+}
+
+_UNICODE_ESCAPE = re.compile(r"\\u([0-9a-fA-F]{4})")
+
+
+def _unescape(text: str) -> str:
+    """反转义 ``\\n``/``\\t``/``\\uXXXX`` 等序列。"""
+    # 先处理 \uXXXX（4 位十六进制 Unicode）
+    text = _UNICODE_ESCAPE.sub(lambda m: chr(int(m.group(1), 16)), text)
+    out = []
+    i = 0
+    n = len(text)
+    while i < n:
+        ch = text[i]
+        if ch == "\\" and i + 1 < n:
+            nxt = text[i + 1]
+            out.append(_ESCAPES.get(nxt, "\\" + nxt))
+            i += 2
+        else:
+            out.append(ch)
+            i += 1
+    return "".join(out)
+
+
+def _split_kv(line: str) -> "tuple[str, str]":
+    """按首个未转义的 ``=``/``:`` 或连续空白拆分 key/value。
+
+    对齐 Java ``Properties`` 的宽松分隔规则。
+    """
+    i = 0
+    n = len(line)
+    # 跳过前导空白
+    while i < n and line[i] in " \t\f":
+        i += 1
+    key_chars = []
+    # key 中允许转义分隔符（\= \:）
+    while i < n:
+        ch = line[i]
+        if ch == "\\" and i + 1 < n:
+            key_chars.append(ch)
+            key_chars.append(line[i + 1])
+            i += 2
+            continue
+        if ch in "=: \t\f":
+            break
+        key_chars.append(ch)
+        i += 1
+    # 跳过 key 后的分隔符（一个 = 或 : 或空白序列）
+    sep_seen = False
+    while i < n and line[i] in "=: \t\f":
+        if line[i] in "=:":
+            if sep_seen:
+                break
+            sep_seen = True
+            i += 1
+            # 分隔符后的空白也吞掉
+            while i < n and line[i] in " \t\f":
+                i += 1
+            break
+        else:
+            i += 1
+    value = line[i:]
+    return _unescape("".join(key_chars)).strip(), _unescape(value)
+
+
+def _read_logical_lines(stream: TextIO) -> "list[str]":
+    """读取逻辑行：合并续行（行尾 ``\\``），跳过注释与空行。
+
+    返回每条逻辑行的原始字符串（已合并续行、未拆 key/value）。
+    """
+    logical: list = []
+    buf = ""
+    in_continuation = False
+    for raw in stream:
+        # 统一换行
+        line = raw.rstrip("\r\n")
+        # 注释/空行仅在非续行状态下生效
+        if not in_continuation:
+            stripped = line.lstrip(" \t\f")
+            if not stripped or stripped[0] in "#!":
+                continue
+            buf = line
+        else:
+            # 续行：拼接，去除前导空白
+            buf += line.lstrip(" \t\f")
+        # 续行判定：行尾奇数个反斜杠表示续行
+        backslashes = 0
+        idx = len(buf) - 1
+        while idx >= 0 and buf[idx] == "\\":
+            backslashes += 1
+            idx -= 1
+        if backslashes % 2 == 1:
+            # 去掉最后一个反斜杠，进入续行
+            buf = buf[:-1]
+            in_continuation = True
+            continue
+        logical.append(buf)
+        buf = ""
+        in_continuation = False
+    # 文件末尾仍在续行（异常文件）—— 兜底加入
+    if buf:
+        logical.append(buf)
+    return logical
+
+
+def parse_properties(content: str) -> Dict[str, str]:
+    """解析 properties 文本内容，返回 ``{key: value}`` 字典。"""
+    result: Dict[str, str] = {}
+    with io.StringIO(content) as s:
+        for line in _read_logical_lines(s):
+            key, value = _split_kv(line)
+            if key:
+                result[key] = value
+    return result
+
+
+def load_properties(path: str, encoding: str = "utf-8") -> Dict[str, str]:
+    """从文件路径加载 properties，返回 ``{key: value}`` 字典。
+
+    Args:
+        path:     文件路径。
+        encoding: 文件编码，默认 UTF-8（对齐 Spring ``defaultEncoding``）。
+    """
+    with open(path, "r", encoding=encoding, newline="") as f:
+        return parse_properties(f.read())
+
+
+def merge_properties(*mappings: Mapping[str, str]) -> Dict[str, str]:
+    """合并多个 properties 映射，后者覆盖前者（用于多 basename 合并）。"""
+    merged: Dict[str, str] = {}
+    for m in mappings:
+        merged.update(m)
+    return merged
+
+
+__all__ = [
+    "parse_properties",
+    "load_properties",
+    "merge_properties",
+]

spring/i18n/sources.py

@@ -0,0 +1,255 @@
+"""具体 ``MessageSource`` 实现：``StaticMessageSource`` / ``ResourceBundleMessageSource`` /
+``DelegatingMessageSource``（对齐 Spring 同名类）。
+
+- ``StaticMessageSource``：编程式注册消息，用于测试或动态消息。
+- ``ResourceBundleMessageSource``：从 ``basenames`` 加载资源文件（``messages`` →
+  ``messages.properties`` / ``messages_en.properties`` / ``messages_zh_CN.properties``），
+  支持 ``.properties``（Java 风格）与 ``.yml``/``.yaml``（复用项目 ``pyyaml`` 依赖）。
+- ``DelegatingMessageSource``：未配置父级时的占位实现，所有调用委派父级或返回默认消息。
+"""
+from __future__ import annotations
+
+import os
+from typing import Dict, Iterable, List, Optional, Tuple
+
+from .locale import Locale
+from .message_source import (
+    AbstractMessageSource,
+    MessageArgs,
+    MessageSource,
+    NoSuchMessageException,
+    _format_message,
+)
+from .properties import load_properties, parse_properties
+
+
+# ==================== StaticMessageSource ====================
+
+class StaticMessageSource(AbstractMessageSource):
+    """编程式消息源（对齐 Spring ``StaticMessageSource``）。
+
+    内部存储 ``{(code, locale_str): template}``，``locale_str`` 为空表示默认（无 locale）。
+    解析时按 ``locale`` → ``locale_country`` → ``language`` → 默认 顺序回退。
+    """
+
+    def __init__(self, parent: Optional[MessageSource] = None):
+        super().__init__(parent=parent)
+        # key: (code, locale_string) -> template
+        self._messages: Dict[Tuple[str, str], str] = {}
+
+    def add_message(self, code: str, locale: Locale, template: str) -> None:
+        """注册单条消息。"""
+        self._messages[(code, locale.to_string())] = template
+
+    def add_messages(self, messages: Dict[str, str], locale: Locale) -> None:
+        """批量注册消息。"""
+        loc_str = locale.to_string()
+        for code, template in messages.items():
+            self._messages[(code, loc_str)] = template
+
+    def resolve_code(self, code: str, locale: Locale) -> Optional[str]:
+        loc_str = locale.to_string()
+        # 1. 精确匹配
+        if (code, loc_str) in self._messages:
+            return self._messages[(code, loc_str)]
+        # 2. language_COUNTRY → language 回退
+        if locale.country:
+            lang_key = (code, locale.language)
+            if lang_key in self._messages:
+                return self._messages[lang_key]
+        # 3. 默认（无 locale）
+        default_key = (code, "")
+        if default_key in self._messages:
+            return self._messages[default_key]
+        return None
+
+
+# ==================== ResourceBundleMessageSource ====================
+
+
+def _load_yaml(path: str, encoding: str) -> Dict[str, str]:
+    """加载 YAML 资源文件；顶层必须是扁平 ``{key: value}`` 映射。"""
+    import yaml  # 项目核心依赖（pyyaml）
+    with open(path, "r", encoding=encoding, newline="") as f:
+        data = yaml.safe_load(f.read()) or {}
+    if not isinstance(data, dict):
+        return {}
+    # 值统一转字符串（消息模板必须是字符串）
+    return {str(k): "" if v is None else str(v) for k, v in data.items()}
+
+
+# 支持的文件扩展名及加载器
+_EXT_LOADERS = (
+    (".properties", lambda path, enc: load_properties(path, enc)),
+    (".yml", _load_yaml),
+    (".yaml", _load_yaml),
+)
+
+
+class ResourceBundleMessageSource(AbstractMessageSource):
+    """资源包消息源（对齐 Spring ``ResourceBundleMessageSource``）。
+
+    Args:
+        basenames:        资源基名列表，如 ``["messages", "errors"]``。
+                          解析时按 basename + locale 后缀搜索文件。
+        base_dir:         资源根目录，默认 ``"."``。搜索文件时拼接 ``base_dir/basename_locale.ext``。
+        default_encoding: 文件编码，默认 UTF-8（对齐 Spring ``defaultEncoding``）。
+        fallback_to_system_locale: 当请求 locale 找不到时，是否回退到系统 locale。
+                          默认 True（对齐 Spring 同名开关）。
+        default_locale:   默认 locale（``None`` 时用 ``Locale("")``）。
+
+    文件命名约定（与 Java ``ResourceBundle`` 一致）：
+        ``messages.properties``          — 默认
+        ``messages_en.properties``       — 英语
+        ``messages_en_US.properties``    — 英语(美国)
+        ``messages_zh_CN.properties``    — 中文(中国)
+
+    YML 等价：
+        ``messages.yml`` / ``messages_en.yml`` / ``messages_zh_CN.yml``
+
+    解析顺序：``locale`` → ``locale_country`` → ``language`` → 默认。
+    多 ``basename`` 时，前者优先（后者作为补充，不覆盖前者已命中的 code）。
+    """
+
+    def __init__(
+        self,
+        basenames: Optional[Iterable[str]] = None,
+        base_dir: str = ".",
+        default_encoding: str = "utf-8",
+        fallback_to_system_locale: bool = True,
+        default_locale: Optional[Locale] = None,
+        parent: Optional[MessageSource] = None,
+    ):
+        super().__init__(parent=parent)
+        self._basenames: List[str] = list(basenames) if basenames else ["messages"]
+        self._base_dir = base_dir
+        self._default_encoding = default_encoding
+        self._fallback_to_system_locale = fallback_to_system_locale
+        self._default_locale = default_locale or Locale("")
+        # 缓存：{(basename, locale_str): {code: template}}
+        self._cached_bundles: Dict[Tuple[str, str], Dict[str, str]] = {}
+
+    # ---- 配置 ----
+
+    def add_basename(self, basename: str) -> None:
+        self._basenames.append(basename)
+        self._cached_bundles.clear()
+
+    def set_default_encoding(self, encoding: str) -> None:
+        self._default_encoding = encoding
+        self._cached_bundles.clear()
+
+    def set_base_dir(self, base_dir: str) -> None:
+        self._base_dir = base_dir
+        self._cached_bundles.clear()
+
+    def set_default_locale(self, locale: Locale) -> None:
+        self._default_locale = locale
+        self._cached_bundles.clear()
+
+    # ---- 解析 ----
+
+    def resolve_code(self, code: str, locale: Locale) -> Optional[str]:
+        # 优先精确 locale，再 country 回退到 language，再默认
+        for loc in self._locale_fallback_chain(locale):
+            for basename in self._basenames:
+                bundle = self._get_bundle(basename, loc)
+                if bundle and code in bundle:
+                    return bundle[code]
+        return None
+
+    def resolve_code_without_args(self, code: str, locale: Locale) -> Optional[str]:
+        # 复用同一解析路径（无参数优化空间不大，保持一致性）
+        return self.resolve_code(code, locale)
+
+    # ---- 内部 ----
+
+    def _locale_fallback_chain(self, locale: Locale) -> List[Locale]:
+        """构造 locale 回退链：locale → locale(country 去掉) → language → 默认。"""
+        chain: List[Locale] = []
+        if not locale.is_empty:
+            chain.append(locale)
+            if locale.country:
+                chain.append(Locale(locale.language))
+            elif locale.variant:
+                chain.append(Locale(locale.language))
+        if self._fallback_to_system_locale and not self._default_locale.is_empty:
+            if self._default_locale not in chain:
+                chain.append(self._default_locale)
+        # 默认（空 locale）
+        if Locale("") not in chain:
+            chain.append(Locale(""))
+        return chain
+
+    def _get_bundle(self, basename: str, locale: Locale) -> Dict[str, str]:
+        """获取指定 basename + locale 的消息字典（带缓存）。"""
+        cache_key = (basename, locale.to_string())
+        if cache_key in self._cached_bundles:
+            return self._cached_bundles[cache_key]
+        bundle = self._load_bundle(basename, locale)
+        self._cached_bundles[cache_key] = bundle
+        return bundle
+
+    def _load_bundle(self, basename: str, locale: Locale) -> Dict[str, str]:
+        """在 ``base_dir`` 下查找 basename + locale 后缀的资源文件。"""
+        # locale 后缀：locale.to_string() 为空则无后缀
+        loc_str = locale.to_string()
+        suffix = f"_{loc_str}" if loc_str else ""
+        # 依次尝试 .properties / .yml / .yaml
+        for ext, loader in _EXT_LOADERS:
+            path = os.path.join(self._base_dir, f"{basename}{suffix}{ext}")
+            if os.path.isfile(path):
+                try:
+                    return loader(path, self._default_encoding)
+                except Exception:
+                    # 加载失败：跳过，回退到下一个扩展名
+                    continue
+        return {}
+
+
+# ==================== DelegatingMessageSource ====================
+
+class DelegatingMessageSource(MessageSource):
+    """委派消息源（对齐 Spring ``DelegatingMessageSource``）。
+
+    ApplicationContext 初始化前用作占位 ``MessageSource``：所有调用委派给父级；
+    父级为 None 时返回 ``default_message`` 或抛 ``NoSuchMessageException``。
+    """
+
+    def __init__(self, parent: Optional[MessageSource] = None):
+        self._parent: Optional[MessageSource] = parent
+
+    @property
+    def parent_message_source(self) -> Optional[MessageSource]:
+        return self._parent
+
+    @parent_message_source.setter
+    def parent_message_source(self, value: Optional[MessageSource]) -> None:
+        self._parent = value
+
+    def getMessage(self, code, args=None, locale=None):  # noqa: N802
+        if self._parent is not None:
+            return self._parent.getMessage(code, args, locale)
+        raise NoSuchMessageException(code, locale)
+
+    def getMessageOrDefault(self, code, args=None, default_message=None, locale=None):
+        if self._parent is not None:
+            return self._parent.getMessageOrDefault(code, args, default_message, locale)
+        return default_message
+
+    def getMessageFromResolvable(self, resolvable, locale=None):
+        if self._parent is not None:
+            return self._parent.getMessageFromResolvable(resolvable, locale)
+        default = resolvable.get_default_message()
+        if default is not None:
+            return _format_message(default, resolvable.get_arguments(), locale)
+        raise NoSuchMessageException(
+            resolvable.get_codes()[0] if resolvable.get_codes() else "", locale
+        )
+
+
+__all__ = [
+    "StaticMessageSource",
+    "ResourceBundleMessageSource",
+    "DelegatingMessageSource",
+]

spring/logging/__init__.py

@@ -0,0 +1 @@
+"""Application logging integrations."""

spring/logging/loguru_logger.py

@@ -0,0 +1,228 @@
+"""
+Loguru结构化日志模块
+提供企业级日志功能
+"""
+import logging
+import sys
+import os
+from datetime import datetime
+from typing import Optional
+
+# 尝试导入loguru，失败则使用标准logging
+try:
+    from loguru import logger as loguru_logger
+    _loguru_available = True
+except ImportError:
+    _loguru_available = False
+    loguru_logger = None
+
+
+class SpringLogger:
+    """Spring日志管理器"""
+    
+    _instance = None
+    _lock = __import__('threading').Lock()
+    
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+        return cls._instance
+    
+    def __init__(self, level: str = "INFO", log_format: str = None, 
+                 log_dir: str = "logs", retention: str = "30 days", 
+                 rotation: str = "100 MB"):
+        if hasattr(self, '_initialized'):
+            return
+        self.level = level.upper()
+        self.log_dir = log_dir
+        self.retention = retention
+        self.rotation = rotation
+        self._initialized = True
+        self._use_loguru = _loguru_available
+        self.log_format = log_format or self._default_format()
+        
+        # 初始化日志配置
+        if self._use_loguru:
+            self._setup_loguru()
+        else:
+            self._setup_std_logging()
+    
+    def _default_format(self) -> str:
+        """默认日志格式"""
+        if self._use_loguru:
+            return (
+                "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | "
+                "<level>{level: <8}</level> | "
+                "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> | "
+                "<level>{message}</level>"
+            )
+        return "%(asctime)s | %(levelname)-8s | %(name)s:%(funcName)s:%(lineno)d | %(message)s"
+    
+    def _setup_loguru(self):
+        """配置Loguru"""
+        # 清除默认处理器
+        loguru_logger.remove()
+        
+        # 添加控制台输出
+        loguru_logger.add(
+            sys.stdout,
+            format=self.log_format,
+            level=self.level,
+            colorize=True,
+        )
+        
+        # 创建日志目录
+        if not os.path.exists(self.log_dir):
+            os.makedirs(self.log_dir)
+        
+        # 添加文件输出（按日期轮转）
+        loguru_logger.add(
+            os.path.join(self.log_dir, "application_{time:YYYY-MM-DD}.log"),
+            format=self.log_format,
+            level=self.level,
+            rotation=self.rotation,
+            retention=self.retention,
+            compression="zip",
+            encoding="utf-8",
+        )
+        
+        # 添加错误日志单独输出
+        loguru_logger.add(
+            os.path.join(self.log_dir, "error_{time:YYYY-MM-DD}.log"),
+            format=self.log_format,
+            level="ERROR",
+            rotation=self.rotation,
+            retention=self.retention,
+            compression="zip",
+            encoding="utf-8",
+        )
+    
+    def _setup_std_logging(self):
+        """配置标准logging（fallback）"""
+        self._logger = logging.getLogger("Spring")
+        self._logger.setLevel(getattr(logging, self.level))
+        
+        # 创建日志目录
+        if not os.path.exists(self.log_dir):
+            os.makedirs(self.log_dir)
+        
+        # 添加控制台输出
+        console_handler = logging.StreamHandler(sys.stdout)
+        console_handler.setFormatter(logging.Formatter(self.log_format))
+        self._logger.addHandler(console_handler)
+        
+        # 添加文件输出
+        file_handler = logging.FileHandler(
+            os.path.join(self.log_dir, "application.log"),
+            encoding="utf-8"
+        )
+        file_handler.setFormatter(logging.Formatter(self.log_format))
+        self._logger.addHandler(file_handler)
+    
+    def get_logger(self):
+        """获取日志实例"""
+        if self._use_loguru:
+            return loguru_logger
+        return self._logger
+    
+    def info(self, message: str, **kwargs):
+        """记录INFO级别日志"""
+        if self._use_loguru:
+            loguru_logger.info(message, **kwargs)
+        else:
+            self._logger.info(message)
+    
+    def debug(self, message: str, **kwargs):
+        """记录DEBUG级别日志"""
+        if self._use_loguru:
+            loguru_logger.debug(message, **kwargs)
+        else:
+            self._logger.debug(message)
+    
+    def warning(self, message: str, **kwargs):
+        """记录WARNING级别日志"""
+        if self._use_loguru:
+            loguru_logger.warning(message, **kwargs)
+        else:
+            self._logger.warning(message)
+    
+    def error(self, message: str, **kwargs):
+        """记录ERROR级别日志"""
+        if self._use_loguru:
+            loguru_logger.error(message, **kwargs)
+        else:
+            self._logger.error(message)
+    
+    def critical(self, message: str, **kwargs):
+        """记录CRITICAL级别日志"""
+        if self._use_loguru:
+            loguru_logger.critical(message, **kwargs)
+        else:
+            self._logger.critical(message)
+    
+    def exception(self, message: str, **kwargs):
+        """记录异常日志"""
+        if self._use_loguru:
+            loguru_logger.exception(message, **kwargs)
+        else:
+            self._logger.exception(message)
+    
+    def log(self, level: str, message: str, **kwargs):
+        """记录指定级别日志"""
+        if self._use_loguru:
+            loguru_logger.log(level.upper(), message, **kwargs)
+        else:
+            self._logger.log(getattr(logging, level.upper()), message)
+    
+    def bind(self, **extra):
+        """绑定额外字段到日志上下文"""
+        if self._use_loguru:
+            return loguru_logger.bind(**extra)
+        return self._logger
+    
+    def patch(self, function):
+        """添加额外字段到日志消息"""
+        if self._use_loguru:
+            return loguru_logger.patch(function)
+        return self._logger
+
+
+# 创建全局日志管理器实例
+spring_logger = SpringLogger()
+
+
+def init_logging(config: dict) -> None:
+    """
+    初始化日志配置
+    
+    Args:
+        config: 配置字典，包含level, log_dir, retention, rotation等
+    """
+    global spring_logger
+    spring_logger = SpringLogger(
+        level=config.get('level', 'INFO'),
+        log_format=config.get('log_format'),
+        log_dir=config.get('log_dir', 'logs'),
+        retention=config.get('retention', '30 days'),
+        rotation=config.get('rotation', '100 MB'),
+    )
+
+
+# 兼容标准logging模块
+if _loguru_available:
+    class LoguruHandler(logging.Handler):
+        """Loguru处理器，用于将标准logging日志转发到Loguru"""
+        
+        def emit(self, record: logging.LogRecord):
+            """处理日志记录"""
+            try:
+                level = loguru_logger.level(record.levelname).name
+                message = self.format(record)
+                loguru_logger.log(level, message)
+            except Exception:
+                self.handleError(record)
+    
+    # 将标准logging日志转发到Loguru
+    logging.basicConfig(handlers=[LoguruHandler()], level=logging.INFO)