springbootAI 1.8.0__py3-none-any.whl

spring/csv/reader.py

@@ -0,0 +1,195 @@
+"""SpringBootAI CSV 读取引擎。
+
+按 ``@CsvProperty`` / ``@CsvIgnore`` / ``@csv_file`` 注解把 CSV 文件读为实体对象列表。
+底层使用 Python 标准库 ``csv``（**无可选依赖**，开箱即用）。
+
+读取流程对齐 Excel 模块（``spring.excel.reader``）与 alibaba EasyExcel：
+    1. 读取表头行（``has_header``，默认 True）。
+    2. 表头文案 -> ``CsvColumnModel`` 映射（按 ``value`` 匹配；无注解时按列位置匹配）。
+    3. 数据行逐行按 ``converter.from_excel`` 转换，构造实体实例。
+"""
+from __future__ import annotations
+
+import csv as _csv
+import inspect
+from typing import Any, List, Optional, Type
+
+from .annotations import (
+    CsvColumnModel, CsvFile, _get_class_file_meta, has_explicit_properties,
+    parse_csv_columns,
+)
+from .converters import resolve_csv_converter
+from .exceptions import CsvReadError
+
+
+def _build_instance(cls: Type, kwargs: dict) -> Any:
+    """构造实体实例：优先 ``cls(**kwargs)``，失败则逐字段 setattr（兼容纯 ``__init__`` 模型）。
+
+    镜像 Excel ``_build_instance``。
+    """
+    try:
+        sig = inspect.signature(cls.__init__)
+        params = list(sig.parameters.values())[1:]  # 跳过 self
+        accept_kwargs = any(p.kind == inspect.Parameter.VAR_KEYWORD for p in params)
+        if accept_kwargs:
+            return cls(**kwargs)
+        allowed = {p.name for p in params if p.kind in (
+            inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY,
+        )}
+        filtered = {k: v for k, v in kwargs.items() if k in allowed}
+        return cls(**filtered)
+    except TypeError:
+        pass
+    # 回退：无参构造 + setattr
+    try:
+        obj = cls()
+    except Exception:
+        obj = object.__new__(cls)
+    for k, v in kwargs.items():
+        try:
+            setattr(obj, k, v)
+        except Exception:
+            pass
+    return obj
+
+
+def _open_for_read(source: Any, encoding: str):
+    """支持文件路径（str/Path）或类文件对象。"""
+    try:
+        if isinstance(source, (str, bytes)) or hasattr(source, "__fspath__"):
+            return open(source, "r", encoding=encoding, newline="")
+        # 类文件对象，直接使用
+        return source
+    except Exception as e:
+        raise CsvReadError(f"打开 CSV 文件失败: {e}") from e
+
+
+class CsvReader:
+    """CSV 读取器。由 ``EasyCsv.read(...)`` 构建，调用 ``doRead`` 执行。"""
+
+    def __init__(
+        self,
+        source: Any,
+        head: Optional[Type] = None,
+        has_header: Optional[bool] = None,
+        delimiter: Optional[str] = None,
+        encoding: Optional[str] = None,
+    ):
+        self.source = source
+        self.head = head
+        self._has_header = has_header
+        self._delimiter = delimiter
+        self._encoding = encoding
+
+    # ---- 流式配置 ----
+
+    def has_header(self, flag: bool) -> "CsvReader":
+        self._has_header = flag
+        return self
+
+    def delimiter(self, d: str) -> "CsvReader":
+        self._delimiter = d
+        return self
+
+    def encoding(self, enc: str) -> "CsvReader":
+        self._encoding = enc
+        return self
+
+    # ---- 执行 ----
+
+    def _resolve_meta(self) -> CsvFile:
+        meta = _get_class_file_meta(self.head) if self.head is not None else CsvFile()
+        if self._has_header is not None:
+            meta.has_header = self._has_header
+        if self._delimiter is not None:
+            meta.delimiter = self._delimiter
+        if self._encoding is not None:
+            meta.encoding = self._encoding
+        return meta
+
+    def doRead(self) -> List[Any]:
+        """读取 CSV，返回实体列表。"""
+        if self.head is None:
+            raise CsvReadError("read 需指定 head 实体类")
+        meta = self._resolve_meta()
+        columns: List[CsvColumnModel] = parse_csv_columns(self.head)
+        explicit = has_explicit_properties(self.head)
+
+        f = _open_for_read(self.source, meta.encoding)
+        owns_fh = f is not self.source
+        try:
+            reader = _csv.reader(f, delimiter=meta.delimiter, quotechar=meta.quote_char)
+            rows = list(reader)
+        finally:
+            if owns_fh:
+                try:
+                    f.close()
+                except Exception:
+                    pass
+
+        if not rows:
+            return []
+
+        # 表头
+        start_idx = 0
+        header_cells: List[str] = []
+        if meta.has_header:
+            header_cells = [str(c).strip() if c is not None else "" for c in rows[0]]
+            start_idx = 1
+
+        # 列映射：列序号(0-based) -> CsvColumnModel
+        col_mapping = self._map_columns(columns, header_cells, explicit, meta.has_header)
+
+        results: List[Any] = []
+        for row in rows[start_idx:]:
+            if not row or all((v is None or str(v).strip() == "") for v in row):
+                continue  # 跳过全空行
+            kwargs = {}
+            for col_idx, model in col_mapping.items():
+                cell_value = row[col_idx] if col_idx < len(row) else None
+                value = self._convert_from_cell(model, cell_value)
+                kwargs[model.attr_name] = value
+            results.append(_build_instance(self.head, kwargs))
+        return results
+
+    def _map_columns(
+        self,
+        columns: List[CsvColumnModel],
+        header_cells: List[str],
+        explicit: bool,
+        has_header: bool,
+    ) -> dict:
+        """表头 -> 列模型映射。返回 {列序号(0-based): CsvColumnModel}。"""
+        col_mapping: dict = {}
+        if explicit and has_header and any(c.header for c in columns):
+            # 按表头文案匹配
+            header_to_col = {}
+            for idx, h in enumerate(header_cells):
+                if h == "":
+                    continue
+                header_to_col.setdefault(h, idx)
+            for model in columns:
+                col_idx = header_to_col.get(model.header)
+                if col_idx is None:
+                    continue
+                col_mapping[col_idx] = model
+        else:
+            # 按列位置匹配（无注解或无表头）
+            for offset, model in enumerate(columns):
+                col_idx = (model.index if model.index is not None else offset)
+                col_mapping[col_idx] = model
+        return col_mapping
+
+    def _convert_from_cell(self, model: CsvColumnModel, cell_value: Any) -> Any:
+        converter = resolve_csv_converter(model.py_type, model.converter, model.date_format)
+        if converter is None:
+            return cell_value
+        try:
+            return converter.from_excel(cell_value)
+        except Exception as e:
+            raise CsvReadError(
+                f"字段 '{model.attr_name}' 转换失败 (单元格值={cell_value!r}): {e}"
+            ) from e
+
+
+__all__ = ["CsvReader"]

spring/csv/writer.py

@@ -0,0 +1,155 @@
+"""SpringBootAI CSV 写入引擎。
+
+按 ``@CsvProperty`` / ``@CsvIgnore`` / ``@csv_file`` 注解把实体对象列表写入 CSV。
+底层使用 Python 标准库 ``csv``（**无可选依赖**，开箱即用）。
+
+写入流程对齐 Excel 模块（``spring.excel.writer``）与 alibaba EasyExcel：
+    1. 按列模型排序写表头行（``has_header=True`` 时）。
+    2. 逐行按 ``converter.to_excel`` 转换并写单元格；处理大数字防丢精度。
+"""
+from __future__ import annotations
+
+import csv as _csv
+from typing import Any, Iterable, List, Optional, Type
+
+from .annotations import (
+    CsvColumnModel, CsvFile, _get_class_file_meta, parse_csv_columns,
+)
+from .converters import resolve_csv_converter
+from .exceptions import CsvWriteError
+
+
+def _get_value(item: Any, attr_name: str) -> Any:
+    """从实体对象或 dict 取字段值。镜像 Excel ``_get_value``。"""
+    if isinstance(item, dict):
+        return item.get(attr_name)
+    return getattr(item, attr_name, None)
+
+
+def _is_large_int(value: Any) -> bool:
+    """是否为会丢精度的长整数（>15 位有效数字）。镜像 Excel ``_is_large_int``。"""
+    if isinstance(value, bool):
+        return False
+    if isinstance(value, int):
+        return len(str(abs(value))) > 15
+    return False
+
+
+def _open_for_write(target: Any, encoding: str):
+    """支持文件路径（str/Path）或类文件对象。"""
+    try:
+        if isinstance(target, (str, bytes)) or hasattr(target, "__fspath__"):
+            return open(target, "w", encoding=encoding, newline="")
+        return target
+    except Exception as e:
+        raise CsvWriteError(f"打开 CSV 文件失败: {e}") from e
+
+
+class CsvWriter:
+    """CSV 写入器。由 ``EasyCsv.write(...)`` 构建，调用 ``doWrite`` 执行。"""
+
+    def __init__(
+        self,
+        target: Any,
+        head: Optional[Type] = None,
+        delimiter: Optional[str] = None,
+        encoding: Optional[str] = None,
+    ):
+        self.target = target
+        self.head = head
+        self._delimiter = delimiter
+        self._encoding = encoding
+        self._has_header: Optional[bool] = None
+
+    # ---- 流式配置 ----
+
+    def delimiter(self, d: str) -> "CsvWriter":
+        self._delimiter = d
+        return self
+
+    def encoding(self, enc: str) -> "CsvWriter":
+        self._encoding = enc
+        return self
+
+    def has_header(self, flag: bool) -> "CsvWriter":
+        self._has_header = flag
+        return self
+
+    # ---- 执行 ----
+
+    def _resolve_meta(self) -> CsvFile:
+        meta = _get_class_file_meta(self.head) if self.head is not None else CsvFile()
+        if self._delimiter is not None:
+            meta.delimiter = self._delimiter
+        if self._encoding is not None:
+            meta.encoding = self._encoding
+        if self._has_header is not None:
+            meta.has_header = self._has_header
+        return meta
+
+    def doWrite(self, data: Iterable[Any]) -> Any:
+        """写入 CSV 并保存到 ``target``。返回目标路径。"""
+        if self.head is None:
+            raise CsvWriteError("write 需指定 head 实体类")
+        meta = self._resolve_meta()
+        columns: List[CsvColumnModel] = parse_csv_columns(self.head)
+
+        f = _open_for_write(self.target, meta.encoding)
+        owns_fh = f is not self.target
+        try:
+            writer = _csv.writer(
+                f,
+                delimiter=meta.delimiter,
+                quotechar=meta.quote_char,
+                lineterminator=meta.line_terminator,
+            )
+            # 1. 表头
+            if meta.has_header:
+                writer.writerow([m.header for m in columns])
+            # 2. 数据行
+            for item in data:
+                row = []
+                for model in columns:
+                    raw = _get_value(item, model.attr_name)
+                    cell_value = self._convert_to_cell(model, raw)
+                    row.append(cell_value)
+                writer.writerow(row)
+        except Exception as e:
+            raise CsvWriteError(f"写入 CSV 文件失败: {e}") from e
+        finally:
+            if owns_fh:
+                try:
+                    f.close()
+                except Exception:
+                    pass
+        return self.target
+
+    def _convert_to_cell(self, model: CsvColumnModel, raw: Any) -> str:
+        """Python 值 -> CSV 单元格字符串。"""
+        converter = resolve_csv_converter(model.py_type, model.converter, model.date_format)
+        if converter is not None:
+            try:
+                converted = converter.to_excel(raw)
+            except Exception as e:
+                raise CsvWriteError(
+                    f"字段 '{model.attr_name}' 转换失败 (值={raw!r}): {e}"
+                ) from e
+            return self._to_cell_str(converted)
+        # 无转换器：按规则处理
+        if raw is None:
+            return ""
+        if model.big_number or _is_large_int(raw):
+            return str(raw)
+        return self._to_cell_str(raw)
+
+    @staticmethod
+    def _to_cell_str(value: Any) -> str:
+        """统一转字符串：None -> ""，bool -> "True"/"False"，其余 str(value)。"""
+        if value is None:
+            return ""
+        if isinstance(value, bool):
+            return "True" if value else "False"
+        return str(value)
+
+
+__all__ = ["CsvWriter"]

spring/data/__init__.py

@@ -0,0 +1,54 @@
+"""SpringBootAI Spring Data 模块（对齐 Spring Data Commons / Spring Data JPA）。
+
+提供基于实体元数据的统一数据访问抽象：分页（``Pageable``/``Page``）、排序（``Sort``）、
+动态查询（``Specification``）、CRUD 仓库基类（``PagingAndSortingRepository``）。
+
+复用现有范式：
+- 实体解析复用 ``spring.orm.ddl_auto.DdlAutoManager._parse_entity``
+- SQL 执行复用 ``OptimisticLockExecutor`` 的轻量范式（pool + cursor）
+- 无需 PyMyBatis ``SqlSession`` 即可使用
+
+用法::
+
+    from spring.data import PagingAndSortingRepository, Pageable, Sort, Specifications
+    from spring.orm import entity, Id, Column
+
+    @entity("user")
+    class User:
+        id = Id()
+        name = Column("user_name")
+        age = Column()
+        def __init__(self, id=None, name=None, age=None):
+            self.id = id; self.name = name; self.age = age
+
+    repo = PagingAndSortingRepository(pool, User, dialect="sqlite")
+    repo.save(User(name="Tom", age=18))
+    page = repo.find_all(pageable=Pageable.of(0, 10, Sort.by("age")))
+    adults = repo.find_all(specification=Specifications.greater_equal("age", 18))
+"""
+from spring.data.page import Direction, Order, Sort, Pageable, Page
+from spring.data.specification import (
+    Specification,
+    And, Or, Not,
+    Predicate, ColResolver,
+    Specifications,
+)
+from spring.data.repository import (
+    PagingAndSortingRepository,
+    DataRepository,
+    get_data_repository_entity,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # 分页/排序
+    "Direction", "Order", "Sort", "Pageable", "Page",
+    # 动态查询
+    "Specification", "And", "Or", "Not", "Predicate", "ColResolver",
+    "Specifications",
+    # 仓库
+    "PagingAndSortingRepository",
+    "DataRepository", "get_data_repository_entity",
+    "__version__",
+]

spring/data/page.py

@@ -0,0 +1,181 @@
+"""Spring Data 风格的分页/排序值对象（对齐 ``org.springframework.data.domain``）。
+
+提供 ``Pageable`` / ``Page`` / ``Sort`` / ``Order``，供 ``PagingAndSortingRepository``
+与上层服务使用。纯值对象，无 IO 依赖，便于单测。
+
+与 Java 差异：
+- ``Pageable`` 为可实例化的值对象（Python 无接口），``.offset`` 直接计算为 ``(page_number) * page_size``。
+- ``Sort.Order`` 的 ``direction`` 用枚举 ``Direction.ASC/DESC``。
+- 页码从 0 起（与 Spring Data 一致），``page_number=0`` 为第一页。
+"""
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Generic, List, Optional, TypeVar
+
+T = TypeVar("T")
+
+
+class Direction(Enum):
+    ASC = "ASC"
+    DESC = "DESC"
+
+
+@dataclass(frozen=True)
+class Order:
+    """单字段排序指令。"""
+    property: str
+    direction: Direction = Direction.ASC
+
+    @staticmethod
+    def asc(property: str) -> "Order":
+        return Order(property=property, direction=Direction.ASC)
+
+    @staticmethod
+    def desc(property: str) -> "Order":
+        return Order(property=property, direction=Direction.DESC)
+
+    def to_sql(self, col_resolver=None) -> str:
+        """转 SQL 片段 ``"col" ASC``。
+
+        Args:
+            col_resolver: 可选 ``property_name -> sql_column_name`` 映射函数，
+                          用于把 Python 属性名翻译为真实列名（对齐 ``Column(name=...)``）。
+        """
+        col = col_resolver(self.property) if col_resolver else self.property
+        return f"{col} {self.direction.value}"
+
+
+class Sort:
+    """多字段排序（对齐 ``Sort``）。空 ``orders`` 表示不排序。
+
+    不可变值对象：构造后 ``orders`` 为 tuple。
+    """
+
+    __slots__ = ("orders",)
+
+    def __init__(self, *orders):
+        object.__setattr__(self, "orders", tuple(orders))
+
+    def __setattr__(self, name, value):
+        raise AttributeError("Sort 是不可变值对象")
+
+    def __delattr__(self, name):
+        raise AttributeError("Sort 是不可变值对象")
+
+    def __eq__(self, other):
+        return isinstance(other, Sort) and self.orders == other.orders
+
+    def __repr__(self):
+        return f"Sort({', '.join(repr(o) for o in self.orders)})"
+
+    @staticmethod
+    def by(*properties: str) -> "Sort":
+        return Sort(*[Order(p) for p in properties])
+
+    @staticmethod
+    def unsorted() -> "Sort":
+        return Sort()
+
+    @property
+    def is_sorted(self) -> bool:
+        return bool(self.orders)
+
+    def to_sql(self, col_resolver=None) -> str:
+        if not self.orders:
+            return ""
+        return ", ".join(o.to_sql(col_resolver) for o in self.orders)
+
+
+@dataclass(frozen=True)
+class Pageable:
+    """分页请求（页码从 0 起）。"""
+    page_number: int = 0
+    page_size: int = 20
+    sort: Sort = field(default_factory=Sort.unsorted)
+
+    def __post_init__(self):
+        if self.page_number < 0:
+            raise ValueError(f"page_number 不能为负: {self.page_number}")
+        if self.page_size <= 0:
+            raise ValueError(f"page_size 必须为正: {self.page_size}")
+
+    @property
+    def offset(self) -> int:
+        return self.page_number * self.page_size
+
+    @property
+    def limit(self) -> int:
+        return self.page_size
+
+    def next(self) -> "Pageable":
+        return Pageable(self.page_number + 1, self.page_size, self.sort)
+
+    def previous_or_first(self) -> "Pageable":
+        return Pageable(max(0, self.page_number - 1), self.page_size, self.sort)
+
+    def first(self) -> "Pageable":
+        return Pageable(0, self.page_size, self.sort)
+
+    @staticmethod
+    def of(page_number: int = 0, page_size: int = 20, sort: Optional[Sort] = None) -> "Pageable":
+        return Pageable(page_number, page_size, sort or Sort.unsorted())
+
+
+@dataclass
+class Page(Generic[T]):
+    """分页结果（对齐 ``Page<T>``）。"""
+    content: List[T]
+    pageable: Pageable
+    total: int
+
+    @property
+    def number(self) -> int:
+        return self.pageable.page_number
+
+    @property
+    def size(self) -> int:
+        return self.pageable.page_size
+
+    @property
+    def total_pages(self) -> int:
+        if self.size == 0:
+            return 0
+        return (self.total + self.size - 1) // self.size
+
+    @property
+    def number_of_elements(self) -> int:
+        return len(self.content)
+
+    @property
+    def has_content(self) -> bool:
+        return bool(self.content)
+
+    @property
+    def has_next(self) -> bool:
+        return self.number + 1 < self.total_pages
+
+    @property
+    def has_previous(self) -> bool:
+        return self.number > 0
+
+    @property
+    def is_first(self) -> bool:
+        return self.number == 0
+
+    @property
+    def is_last(self) -> bool:
+        return not self.has_next
+
+    @property
+    def is_empty(self) -> bool:
+        return not self.has_content
+
+    def next_pageable(self) -> Optional[Pageable]:
+        return self.pageable.next() if self.has_next else None
+
+    def previous_pageable(self) -> Optional[Pageable]:
+        return self.pageable.previous_or_first() if self.has_previous else None
+
+    @staticmethod
+    def empty(pageable: Pageable) -> "Page":
+        return Page([], pageable, 0)