springbootAI 1.8.0__py3-none-any.whl

spring/context/registry.py

@@ -0,0 +1,58 @@
+from typing import Dict, Type, Any, Optional
+
+
+class BeanRegistry:
+    _instance: Optional['BeanRegistry'] = None
+    _initialized: bool = False
+
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        if self._initialized:
+            return
+        self._beans: Dict[str, Any] = {}
+        self._types: Dict[Type, str] = {}
+        self._initialized = True
+
+    def register(self, name: str, bean: Any) -> None:
+        self._beans[name] = bean
+        self._types[type(bean)] = name
+
+    def get(self, name: str) -> Any:
+        return self._beans.get(name)
+
+    def get_by_type(self, bean_type: Type) -> Any:
+        if bean_type in self._types:
+            return self._beans[self._types[bean_type]]
+        for bean in self._beans.values():
+            if isinstance(bean, bean_type):
+                return bean
+        return None
+
+    def contains(self, name: str) -> bool:
+        return name in self._beans
+
+    def contains_type(self, bean_type: Type) -> bool:
+        return bean_type in self._types
+
+    def unregister(self, name: str) -> None:
+        if name in self._beans:
+            bean = self._beans[name]
+            del self._types[type(bean)]
+            del self._beans[name]
+
+    def clear(self) -> None:
+        self._beans.clear()
+        self._types.clear()
+
+    def get_all(self) -> Dict[str, Any]:
+        return dict(self._beans)
+
+    def get_names(self) -> list:
+        return list(self._beans.keys())
+
+    def get_count(self) -> int:
+        return len(self._beans)

spring/context/scanner.py

@@ -0,0 +1,106 @@
+from typing import List, Type, Any
+import importlib
+import os
+import pkgutil
+from spring.annotations.core import (
+    Component,
+    Service,
+    Repository,
+    Controller,
+    RestController,
+    Configuration,
+    ControllerAdvice,
+    ConfigurationProperties,
+    get_spring_annotations,
+)
+
+
+class ComponentScanner:
+    def __init__(self, application_context: Any):
+        self.application_context = application_context
+        self._scanned_classes: set = set()
+
+    def scan(self, base_packages: List[str]) -> List[Type]:
+        components: List[Type] = []
+        for package_name in base_packages:
+            components.extend(self._scan_package(package_name))
+        return components
+
+    def scan_classes(self, base_packages: List[str]) -> List[Type]:
+        """Import packages and return all declared classes once.
+
+        Cloud integrations such as Feign are interface-like declarations and
+        deliberately are not IoC components themselves, so they need a
+        separate class scan from the component scan.
+        """
+        classes: List[Type] = []
+        for package_name in base_packages:
+            classes.extend(self._scan_package_classes(package_name))
+        return classes
+
+    def _scan_package_classes(self, package_name: str) -> List[Type]:
+        classes: List[Type] = []
+        try:
+            package = importlib.import_module(package_name)
+        except ImportError:
+            return classes
+        if hasattr(package, '__path__'):
+            for _, module_name, is_pkg in pkgutil.walk_packages(package.__path__, package_name + '.'):
+                if is_pkg:
+                    classes.extend(self._scan_package_classes(module_name))
+                else:
+                    try:
+                        module = importlib.import_module(module_name)
+                    except ImportError:
+                        continue
+                    classes.extend(
+                        obj for obj in vars(module).values()
+                        if isinstance(obj, type) and obj.__module__ == module.__name__
+                    )
+        return classes
+
+    def _scan_package(self, package_name: str) -> List[Type]:
+        components: List[Type] = []
+        try:
+            package = importlib.import_module(package_name)
+        except ImportError:
+            return components
+
+        if hasattr(package, '__path__'):
+            for _, module_name, is_pkg in pkgutil.walk_packages(package.__path__, package_name + '.'):
+                if is_pkg:
+                    components.extend(self._scan_package(module_name))
+                else:
+                    try:
+                        module = importlib.import_module(module_name)
+                        components.extend(self._find_components_in_module(module))
+                    except ImportError:
+                        continue
+        return components
+
+    def _find_components_in_module(self, module: Any) -> List[Type]:
+        components: List[Type] = []
+        for name in dir(module):
+            obj = getattr(module, name)
+            if isinstance(obj, type) and obj not in self._scanned_classes:
+                if self._is_component(obj):
+                    self._scanned_classes.add(obj)
+                    components.append(obj)
+        return components
+
+    def _is_component(self, cls: Type) -> bool:
+        annotations = get_spring_annotations(cls)
+        component_annotations = (
+            Component,
+            Service,
+            Repository,
+            Controller,
+            RestController,
+            Configuration,
+            ControllerAdvice,
+            ConfigurationProperties,
+        )
+        for annotation in annotations:
+            if isinstance(annotation, component_annotations):
+                return True
+        return False

spring/core/__init__.py

@@ -0,0 +1,3 @@
+from spring.core.graceful_shutdown import GracefulShutdown, shutdown_handler
+
+__all__ = ['GracefulShutdown', 'shutdown_handler']

spring/core/graceful_shutdown.py

@@ -0,0 +1,196 @@
+"""
+优雅退出处理器 (Graceful Shutdown)
+
+功能：
+- 捕获 SIGTERM/SIGINT 信号
+- 停止接收新请求（健康检查返回 NOT_READY）
+- 等待在途请求完成（可配置超时）
+- 关闭连接池、消息消费者等资源
+- 注销服务发现
+"""
+
+import signal
+import time
+import logging
+import threading
+import asyncio
+from typing import Optional, Callable, List, Dict, Any
+from enum import Enum
+
+logger = logging.getLogger("Spring.Core.Shutdown")
+
+
+class ShutdownPhase(Enum):
+    RUNNING = "RUNNING"
+    DRAINING = "DRAINING"     # 停止接收新请求
+    SHUTTING_DOWN = "SHUTTING_DOWN"  # 关闭资源
+    STOPPED = "STOPPED"
+
+
+class GracefulShutdown:
+    """
+    优雅退出管理器
+
+    Usage:
+        shutdown = GracefulShutdown()
+        shutdown.register_hook("db_pool", pool.close)
+        shutdown.register_hook("redis", redis_client.close)
+        # 信号会自动注册
+    """
+
+    def __init__(self, drain_timeout: float = 30.0, shutdown_timeout: float = 30.0):
+        self.drain_timeout = drain_timeout
+        self.shutdown_timeout = shutdown_timeout
+        self._phase = ShutdownPhase.RUNNING
+        self._phase_lock = threading.RLock()
+        self._hooks: Dict[str, Callable] = {}
+        self._hooks_order: List[str] = []
+        self._inflight_count = 0
+        self._inflight_lock = threading.RLock()
+        self._shutdown_event = threading.Event()
+        self._original_sigterm = None
+        self._original_sigint = None
+        self._signal_received = False
+        self._shutdown_start_time: Optional[float] = None
+
+    def register_signals(self):
+        """注册系统信号处理器"""
+        try:
+            self._original_sigterm = signal.getsignal(signal.SIGTERM)
+            self._original_sigint = signal.getsignal(signal.SIGINT)
+            signal.signal(signal.SIGTERM, self._signal_handler)
+            signal.signal(signal.SIGINT, self._signal_handler)
+            logger.info("Graceful shutdown signal handlers registered (SIGTERM/SIGINT)")
+        except (ValueError, OSError) as e:
+            # 在非主线程中无法注册信号，忽略
+            logger.debug(f"Cannot register signal handlers: {e}")
+
+    def _signal_handler(self, signum, frame):
+        """信号处理回调"""
+        if self._signal_received:
+            logger.warning("Second signal received, forcing immediate shutdown")
+            self._force_shutdown()
+            return
+        self._signal_received = True
+        sig_name = signal.Signals(signum).name
+        logger.info(f"Received signal {sig_name}, starting graceful shutdown...")
+        threading.Thread(target=self.initiate_shutdown, daemon=True).start()
+
+    def register_hook(self, name: str, hook: Callable, order: int = 0):
+        """
+        注册关闭钩子
+
+        Args:
+            name: 钩子名称（唯一标识）
+            hook: 无参可调用对象
+            order: 执行顺序（越小越先执行）
+        """
+        with self._phase_lock:
+            self._hooks[name] = (order, hook)
+            self._hooks_order = sorted(self._hooks.keys(), key=lambda n: self._hooks[n][0])
+        logger.debug(f"Registered shutdown hook: {name} (order={order})")
+
+    def request_started(self):
+        """请求开始时调用，跟踪在途请求数"""
+        with self._inflight_lock:
+            self._inflight_count += 1
+
+    def request_finished(self):
+        """请求结束时调用"""
+        with self._inflight_lock:
+            self._inflight_count -= 1
+
+    @property
+    def is_draining(self) -> bool:
+        """是否正在排空请求（不应接收新请求）"""
+        with self._phase_lock:
+            return self._phase in (ShutdownPhase.DRAINING, ShutdownPhase.SHUTTING_DOWN, ShutdownPhase.STOPPED)
+
+    @property
+    def is_shutting_down(self) -> bool:
+        return self._phase in (ShutdownPhase.SHUTTING_DOWN, ShutdownPhase.STOPPED)
+
+    @property
+    def phase(self) -> ShutdownPhase:
+        return self._phase
+
+    @property
+    def inflight_count(self) -> int:
+        return self._inflight_count
+
+    def initiate_shutdown(self):
+        """启动优雅关闭流程"""
+        with self._phase_lock:
+            if self._phase != ShutdownPhase.RUNNING:
+                return
+            self._phase = ShutdownPhase.DRAINING
+            self._shutdown_start_time = time.monotonic()
+
+        logger.info("Phase 1: Draining - stopping new requests, waiting for in-flight requests...")
+
+        # 等待在途请求完成
+        deadline = time.monotonic() + self.drain_timeout
+        while time.monotonic() < deadline:
+            with self._inflight_lock:
+                inflight = self._inflight_count
+            if inflight == 0:
+                break
+            logger.info(f"Waiting for {inflight} in-flight request(s)... ({deadline - time.monotonic():.1f}s remaining)")
+            time.sleep(0.5)
+
+        with self._inflight_lock:
+            remaining = self._inflight_count
+        if remaining > 0:
+            logger.warning(f"{remaining} request(s) still in-flight after drain timeout, proceeding to shutdown")
+
+        # 关闭资源
+        with self._phase_lock:
+            self._phase = ShutdownPhase.SHUTTING_DOWN
+
+        logger.info("Phase 2: Shutting down resources...")
+        self._execute_hooks()
+
+        with self._phase_lock:
+            self._phase = ShutdownPhase.STOPPED
+
+        elapsed = time.monotonic() - self._shutdown_start_time
+        logger.info(f"Graceful shutdown completed in {elapsed:.2f}s")
+        self._shutdown_event.set()
+
+    def _execute_hooks(self):
+        """执行所有关闭钩子"""
+        for name in self._hooks_order:
+            _, hook = self._hooks[name]
+            hook_start = time.monotonic()
+            try:
+                result = hook()
+                if asyncio.iscoroutine(result):
+                    # 尝试在当前事件循环中运行协程
+                    try:
+                        loop = asyncio.get_event_loop()
+                        if loop.is_running():
+                            asyncio.ensure_future(result)
+                        else:
+                            loop.run_until_complete(result)
+                    except RuntimeError:
+                        pass
+                elapsed = time.monotonic() - hook_start
+                logger.info(f"Shutdown hook '{name}' completed in {elapsed:.2f}s")
+            except Exception as e:
+                elapsed = time.monotonic() - hook_start
+                logger.error(f"Shutdown hook '{name}' failed after {elapsed:.2f}s: {e}")
+
+    def _force_shutdown(self):
+        """强制关闭"""
+        logger.critical("Force shutdown initiated")
+        with self._phase_lock:
+            self._phase = ShutdownPhase.STOPPED
+        self._shutdown_event.set()
+
+    def wait_for_shutdown(self, timeout: Optional[float] = None):
+        """等待关闭完成"""
+        self._shutdown_event.wait(timeout=timeout)
+
+
+# 全局单例
+shutdown_handler = GracefulShutdown()

spring/core/typing_utils.py

@@ -0,0 +1,50 @@
+"""共享类型工具 —— 规范化类型注解，消除 Python 版本差异。
+
+背景：``typing.get_type_hints`` 在 Python 3.10 上会把带 ``None`` 默认值的参数注解
+自动包装为 ``Optional[X]``（即 ``Union[X, None]``）；自 Python 3.11 起该自动包装
+行为被移除，注解原样返回。这导致同一份代码在 3.10 与 3.11/3.12 上得到不同的
+``py_type``，进而影响 SQL 类型映射、CSV 转换器选择等下游推断。
+
+本模块统一把 ``Optional[X]`` / ``Union[X, None]`` 解包为 ``X``，使下游类型推断与
+Python 版本无关。对齐 Spring ``org.springframework.core.ResolvableType`` 的职责
+（提供统一的类型解析语义），仅做最小必要的可空解包。
+"""
+import typing
+
+# NoneType 的单例，用于在 Union 参数中识别并剔除 ``None``
+_NONE_TYPE = type(None)
+
+
+def unwrap_optional_type(tp):
+    """把 ``Optional[X]`` / ``Union[X, None]`` 解包为 ``X``；其他类型原样返回。
+
+    用于从 ``get_type_hints`` 得到的类型中取出“承载类型”，供 SQL 类型映射、
+    转换器选择等只关心实际承载类型、忽略可空性的场景。可空性由 ``nullable``
+    等列元数据单独表达，不应混入类型映射。
+
+    - ``Optional[int]`` / ``Union[int, None]`` -> ``int``
+    - ``int`` -> ``int``（原样返回）
+    - ``Union[int, str, None]`` -> 原样返回（多元素 Union 无单一承载类型，不解包）
+    - ``None`` -> ``None``
+
+    Examples:
+        >>> import typing
+        >>> unwrap_optional_type(typing.Optional[int]) is int
+        True
+        >>> unwrap_optional_type(int) is int
+        True
+        >>> unwrap_optional_type(None) is None
+        True
+    """
+    if tp is None:
+        return tp
+    # Optional[X] 在运行期等价于 Union[X, None]，其 origin 为 typing.Union
+    if typing.get_origin(tp) is typing.Union:
+        args = [a for a in typing.get_args(tp) if a is not _NONE_TYPE]
+        # 仅当剔除 None 后剩单一承载类型时才解包；多元素 Union 保持原样
+        if len(args) == 1:
+            return args[0]
+    return tp
+
+
+__all__ = ["unwrap_optional_type"]

spring/csv/__init__.py

@@ -0,0 +1,52 @@
+"""SpringBootAI CSV 模块 —— 注解驱动的 CSV 读写（对齐 alibaba EasyExcel / commons-csv）。
+
+模块组成（镜像 ``spring.excel`` 架构）：
+- annotations:  ``@CsvProperty`` / ``@CsvIgnore`` / ``@csv_file`` 字段+类级注解
+                 （复用 ORM ``Column``/``@entity`` 与 Excel ``ExcelProperty`` 元数据描述符范式）
+- converters:   复用 ``spring.excel.converters`` 的 ``Converter`` 接口与内置转换器（DRY）
+- reader:       ``CsvReader`` 读取引擎（表头映射/类型转换/位置回退）
+- writer:       ``CsvWriter`` 写入引擎（表头/顺序/大数字防丢精度）
+- easy_csv:     ``EasyCsv`` 流式构建入口（对齐 ``EasyExcel`` API）
+- exceptions:   ``CsvError`` 异常族
+
+与 Excel 模块的核心区别：
+- **无可选依赖**：CSV 使用 Python 标准库 ``csv``，``pip install springbootAI`` 即可用，
+  无需 ``springbootAI[excel]`` 等额外 extras。
+- 转换器复用 Excel 模块（``spring.excel.converters`` 不依赖 openpyxl，可安全导入）。
+- 无单元格样式/数字格式（CSV 格式本身不支持）。
+
+设计原则：**复用项目既有范式，不重复造轮子**。注解描述符、反射解析、流式 API 全部对齐
+既有 Excel/ORM 实现，未引入任何第三方库。
+"""
+from .exceptions import CsvError, CsvPropertyError, CsvReadError, CsvWriteError
+from .annotations import (
+    CsvProperty, CsvIgnore, CsvFile, csv_file,
+    CsvColumnModel, parse_csv_columns,
+)
+from .converters import (
+    Converter, CsvConverter,
+    StringConverter, IntegerConverter, FloatConverter,
+    BooleanConverter, DateStringConverter, BigDecimalConverter,
+    resolve_converter, resolve_csv_converter,
+)
+from .reader import CsvReader
+from .writer import CsvWriter
+from .easy_csv import EasyCsv, read_csv, write_csv
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # 异常
+    "CsvError", "CsvPropertyError", "CsvReadError", "CsvWriteError",
+    # 注解
+    "CsvProperty", "CsvIgnore", "CsvFile", "csv_file",
+    "CsvColumnModel", "parse_csv_columns",
+    # 转换器
+    "Converter", "CsvConverter",
+    "StringConverter", "IntegerConverter", "FloatConverter",
+    "BooleanConverter", "DateStringConverter", "BigDecimalConverter",
+    "resolve_converter", "resolve_csv_converter",
+    # 引擎
+    "CsvReader", "CsvWriter", "EasyCsv", "read_csv", "write_csv",
+    "__version__",
+]