yimo-kit 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. yimo/__init__.py +26 -0
  2. yimo/kit/__init__.py +98 -0
  3. yimo/kit/ai/__init__.py +110 -0
  4. yimo/kit/ai/_internal/__init__.py +27 -0
  5. yimo/kit/ai/_internal/failover.py +535 -0
  6. yimo/kit/ai/_internal/pool.py +526 -0
  7. yimo/kit/ai/_internal/rerank_transport.py +137 -0
  8. yimo/kit/ai/_internal/retry_after.py +51 -0
  9. yimo/kit/ai/_internal/sdk_client.py +463 -0
  10. yimo/kit/ai/_internal/service_base.py +115 -0
  11. yimo/kit/ai/_internal/types.py +28 -0
  12. yimo/kit/ai/agent/__init__.py +127 -0
  13. yimo/kit/ai/agent/approval.py +66 -0
  14. yimo/kit/ai/agent/errors.py +128 -0
  15. yimo/kit/ai/agent/loop.py +643 -0
  16. yimo/kit/ai/agent/mcp.py +278 -0
  17. yimo/kit/ai/agent/registry.py +203 -0
  18. yimo/kit/ai/agent/session.py +150 -0
  19. yimo/kit/ai/agent/skill.py +370 -0
  20. yimo/kit/ai/agent/types.py +161 -0
  21. yimo/kit/ai/chat_service.py +724 -0
  22. yimo/kit/ai/decision/__init__.py +57 -0
  23. yimo/kit/ai/decision/decima.py +853 -0
  24. yimo/kit/ai/decision/laya.py +552 -0
  25. yimo/kit/ai/embedding_service.py +198 -0
  26. yimo/kit/ai/exceptions.py +109 -0
  27. yimo/kit/ai/image_service.py +84 -0
  28. yimo/kit/ai/messages.py +105 -0
  29. yimo/kit/ai/model_builder.py +121 -0
  30. yimo/kit/ai/model_client.py +62 -0
  31. yimo/kit/ai/profiles.py +577 -0
  32. yimo/kit/ai/rerank_service.py +136 -0
  33. yimo/kit/ai/runner.py +1127 -0
  34. yimo/kit/common_kit.py +221 -0
  35. yimo/kit/config/__init__.py +44 -0
  36. yimo/kit/config/kit_config.py +210 -0
  37. yimo/kit/config/log_config.py +171 -0
  38. yimo/kit/crawl/__init__.py +71 -0
  39. yimo/kit/crawl/article_io.py +325 -0
  40. yimo/kit/crawl/article_models.py +172 -0
  41. yimo/kit/crawl/deepseek_kit.py +673 -0
  42. yimo/kit/crawl/web_article_kit.py +638 -0
  43. yimo/kit/crawl/wx_article_kit.py +692 -0
  44. yimo/kit/db/__init__.py +101 -0
  45. yimo/kit/db/audit.py +625 -0
  46. yimo/kit/db/base_db_kit.py +1265 -0
  47. yimo/kit/db/crud.py +423 -0
  48. yimo/kit/db/engine.py +235 -0
  49. yimo/kit/db/exceptions.py +45 -0
  50. yimo/kit/db/models/__init__.py +33 -0
  51. yimo/kit/db/models/base.py +56 -0
  52. yimo/kit/db/mysql_kit.py +348 -0
  53. yimo/kit/db/pg_kit.py +442 -0
  54. yimo/kit/db/query.py +338 -0
  55. yimo/kit/db/session.py +85 -0
  56. yimo/kit/db/sqlite_kit.py +462 -0
  57. yimo/kit/db/transaction.py +109 -0
  58. yimo/kit/docs/__init__.py +34 -0
  59. yimo/kit/docs/anydoc_kit.py +490 -0
  60. yimo/kit/docs/docx_kit.py +895 -0
  61. yimo/kit/docs/md2doc_kit.py +1801 -0
  62. yimo/kit/docs/mineru_kit.py +1497 -0
  63. yimo/kit/docs/rc_docparser_kit.py +654 -0
  64. yimo/kit/file_kit.py +518 -0
  65. yimo/kit/license_kit.py +533 -0
  66. yimo/kit/redis_kit.py +392 -0
  67. yimo_kit-0.1.0.dist-info/METADATA +1673 -0
  68. yimo_kit-0.1.0.dist-info/RECORD +70 -0
  69. yimo_kit-0.1.0.dist-info/WHEEL +4 -0
  70. yimo_kit-0.1.0.dist-info/licenses/LICENSE +201 -0
yimo/kit/db/crud.py ADDED
@@ -0,0 +1,423 @@
1
+ """
2
+ Copyright (c) 2021-2026 溢墨修心(Yimo). All Rights Reserved.
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+
16
+ Project: yimo
17
+ Author: 溢墨修心(Yimo)
18
+ """
19
+
20
+ # date: 2026-08-23
21
+ """通用 CRUD 操作基类
22
+
23
+ 核心设计原则:CRUD 方法内部不调用 commit/rollback,仅执行 add/flush 或
24
+ Core DML(update/delete)。事务的提交/回滚交给外层 session_scope 或
25
+ @transactional 装饰器统一管理。这保证了多个 CRUD 操作可以在同一事务中安全组合。
26
+
27
+ 性能要点:
28
+ - upsert 使用各数据库原生 ``INSERT ... ON CONFLICT``(原子,单语句)。
29
+ - update_multi / delete_multi 使用单条批量 SQL,不再逐对象载入修改。
30
+ - exists 只查主键列,不载入整对象。
31
+ """
32
+
33
+ from typing import Any, cast
34
+
35
+ from sqlalchemy import Column, Table, delete, func, update
36
+ from sqlalchemy.dialects import mysql as mysql_dialect
37
+ from sqlalchemy.dialects import postgresql as pg_dialect
38
+ from sqlalchemy.dialects import sqlite as sqlite_dialect
39
+ from sqlalchemy.types import TypeEngine
40
+ from sqlmodel import Session, SQLModel, select
41
+ from sqlmodel.sql._expression_select_cls import SelectOfScalar
42
+
43
+ from yimo.kit.config.log_config import get_default_logger
44
+ from yimo.kit.db.audit import (
45
+ DELETED,
46
+ AuditConfig,
47
+ fill_insert,
48
+ fill_update,
49
+ insert_only_columns,
50
+ normal_value,
51
+ )
52
+ from yimo.kit.db.exceptions import DBError, NotFoundError
53
+
54
+ logger = get_default_logger(__name__)
55
+
56
+
57
+ class CRUDBase[
58
+ ModelType: SQLModel,
59
+ CreateSchemaType: SQLModel,
60
+ UpdateSchemaType: SQLModel,
61
+ ]:
62
+ """通用 CRUD 操作基类(不在内部提交事务)
63
+
64
+ 所有写操作(create/update/delete)仅执行 session.add() + flush() 或 Core DML,
65
+ 不调用 session.commit(),由外层 session_scope 统一管理事务边界。
66
+
67
+ 用法::
68
+
69
+ user_crud = CRUDBase(User)
70
+
71
+ with session_scope() as session:
72
+ user = user_crud.create(session, UserCreate(name="test"))
73
+ # 退出 with 时统一提交
74
+ """
75
+
76
+ def __init__(self, model: type[ModelType]):
77
+ self.model = model
78
+
79
+ def _select_all(self, *, include_deleted: bool = False) -> SelectOfScalar[ModelType]:
80
+ """返回 sqlmodel.select 的标量查询(SQLModel 类型桥接)
81
+
82
+ Args:
83
+ include_deleted: 是否跳过软删除过滤(默认 False;仅过滤开关开启时有效)
84
+ """
85
+ statement = cast(SelectOfScalar[ModelType], select(self.model))
86
+ condition = self._deleted_condition(include_deleted=include_deleted)
87
+ return statement.where(condition) if condition is not None else statement
88
+
89
+ def _deleted_condition(self, *, include_deleted: bool = False) -> Any:
90
+ """软删除过滤条件(过滤关闭 / 模型无 deleted 列时返回 None)
91
+
92
+ 严格等值:``deleted = 正常值``(整数列 ``0``、字符串列 ``"0"``)。
93
+ ``NULL`` 不视为未删除——本工具类只做底层约定,不为业务历史数据兜底。
94
+ """
95
+ if include_deleted or not AuditConfig.filter_deleted():
96
+ return None
97
+ column = getattr(self.model, AuditConfig.fields()[DELETED], None)
98
+ if column is None:
99
+ return None
100
+ return column == normal_value(column.type)
101
+
102
+ def _is_visible(self, obj: ModelType) -> bool:
103
+ """对象是否未被软删除(过滤关闭 / 模型无该字段时恒为 True)"""
104
+ if not AuditConfig.filter_deleted():
105
+ return True
106
+ column = getattr(self.model, AuditConfig.fields()[DELETED], None)
107
+ if column is None:
108
+ return True
109
+ return getattr(obj, column.key, None) == normal_value(column.type)
110
+
111
+ def _id_col(self) -> Column[Any]:
112
+ """约定的主键列(避免 SQLModel 泛型无 id 字段的类型缺陷)"""
113
+ return cast(Column[Any], getattr(self.model, "id"))
114
+
115
+ def _table(self) -> Table:
116
+ """模型对应的 Table(避免 SQLModel 泛型无 __table__ 的类型缺陷)"""
117
+ return cast(Table, getattr(self.model, "__table__"))
118
+
119
+ def _column_names(self) -> dict[str, TypeEngine[Any]]:
120
+ """模型映射表的「列名 → SQLAlchemy 类型对象」(读元数据,零 DB 查询)
121
+
122
+ 供审计字段自动填充判断「表中是否存在该列」,以及 ``deleted`` 的取值类型。
123
+ """
124
+ return {column.name: column.type for column in self._table().columns}
125
+
126
+ # ==================== 查询方法 ====================
127
+
128
+ def get(self, session: Session, id: Any) -> ModelType | None:
129
+ """根据主键获取单条记录(开启软删除过滤时隐藏已删除记录)"""
130
+ obj = session.get(self.model, id)
131
+ if obj is not None and not self._is_visible(obj):
132
+ logger.info(f"🔍 查询 {self.model.__name__} id={id} → 已软删除(过滤隐藏)")
133
+ return None
134
+ logger.info(
135
+ f"🔍 查询 {self.model.__name__} id={id} → {'命中' if obj else '未找到'}"
136
+ )
137
+ return obj
138
+
139
+ def get_or_raise(self, session: Session, id: Any) -> ModelType:
140
+ """根据主键获取记录,不存在(或已软删除)时抛出 NotFoundError"""
141
+ obj = session.get(self.model, id)
142
+ if obj is None or not self._is_visible(obj):
143
+ logger.warning(
144
+ f"❌ {self.model.__name__} id={id} 不存在,抛出 NotFoundError"
145
+ )
146
+ raise NotFoundError(f"{self.model.__name__} id={id} 不存在")
147
+ logger.info(f"🔍 查询 {self.model.__name__} id={id} → 命中")
148
+ return obj
149
+
150
+ def get_multi(
151
+ self,
152
+ session: Session,
153
+ *,
154
+ skip: int = 0,
155
+ limit: int = 100,
156
+ order_by: str | None = None,
157
+ desc: bool = False,
158
+ ) -> list[ModelType]:
159
+ """获取多条记录(分页 + 排序)"""
160
+ statement = self._select_all()
161
+
162
+ if order_by:
163
+ column = getattr(self.model, order_by, None)
164
+ if column is None:
165
+ raise DBError(f"模型 {self.model.__name__} 不存在字段: {order_by}")
166
+ statement = statement.order_by(column.desc() if desc else column.asc())
167
+
168
+ statement = statement.offset(skip).limit(limit)
169
+ results = list(session.exec(statement).all())
170
+ logger.info(f"🔍 查询 {self.model.__name__} 多条记录 → 返回 {len(results)} 条")
171
+ return results
172
+
173
+ def get_by_field(
174
+ self, session: Session, field_name: str, field_value: Any
175
+ ) -> ModelType | None:
176
+ """根据字段值获取单条记录"""
177
+ column = getattr(self.model, field_name, None)
178
+ if column is None:
179
+ raise DBError(f"模型 {self.model.__name__} 不存在字段: {field_name}")
180
+ result = session.exec(self._select_all().where(column == field_value)).first()
181
+ logger.info(
182
+ f"🔍 按字段查询 {self.model.__name__}({field_name}={field_value}) "
183
+ f"→ {'命中' if result else '未找到'}"
184
+ )
185
+ return result
186
+
187
+ def get_multi_by_field(
188
+ self,
189
+ session: Session,
190
+ field_name: str,
191
+ field_value: Any,
192
+ *,
193
+ skip: int = 0,
194
+ limit: int = 100,
195
+ ) -> list[ModelType]:
196
+ """根据字段值获取多条记录"""
197
+ column = getattr(self.model, field_name, None)
198
+ if column is None:
199
+ raise DBError(f"模型 {self.model.__name__} 不存在字段: {field_name}")
200
+ statement = (
201
+ self._select_all().where(column == field_value).offset(skip).limit(limit)
202
+ )
203
+ return list(session.exec(statement).all())
204
+
205
+ # ==================== 写入方法(不提交) ====================
206
+
207
+ def create(
208
+ self, session: Session, obj_in: CreateSchemaType | dict[str, Any]
209
+ ) -> ModelType:
210
+ """创建记录(仅 add + flush,不 commit)"""
211
+ data = (
212
+ obj_in
213
+ if isinstance(obj_in, dict)
214
+ else obj_in.model_dump(exclude_unset=True)
215
+ )
216
+ db_obj = self.model(**data)
217
+ session.add(db_obj)
218
+ session.flush() # 刷新以获取主键,但不提交
219
+ logger.info(
220
+ f"✅ 创建 {self.model.__name__} 记录 id={getattr(db_obj, 'id', '?')}"
221
+ )
222
+ return db_obj
223
+
224
+ def create_multi(
225
+ self, session: Session, objs_in: list[CreateSchemaType | dict[str, Any]]
226
+ ) -> list[ModelType]:
227
+ """批量创建记录(仅 add_all + flush,不 commit)"""
228
+ db_objs = []
229
+ for obj_in in objs_in:
230
+ data = (
231
+ obj_in
232
+ if isinstance(obj_in, dict)
233
+ else obj_in.model_dump(exclude_unset=True)
234
+ )
235
+ db_objs.append(self.model(**data))
236
+ session.add_all(db_objs)
237
+ session.flush()
238
+ logger.info(f"✅ 批量创建 {len(db_objs)} 条 {self.model.__name__} 记录")
239
+ return db_objs
240
+
241
+ def update(
242
+ self,
243
+ session: Session,
244
+ db_obj: ModelType,
245
+ obj_in: UpdateSchemaType | dict[str, Any],
246
+ ) -> ModelType:
247
+ """更新记录(仅 add + flush,不 commit)"""
248
+ update_data = (
249
+ obj_in
250
+ if isinstance(obj_in, dict)
251
+ else obj_in.model_dump(exclude_unset=True)
252
+ )
253
+ for field, value in update_data.items():
254
+ setattr(db_obj, field, value)
255
+ session.add(db_obj)
256
+ session.flush()
257
+ logger.info(
258
+ f"✅ 更新 {self.model.__name__} id={getattr(db_obj, 'id', '?')} "
259
+ f"→ 字段: {update_data}"
260
+ )
261
+ return db_obj
262
+
263
+ def update_multi(
264
+ self,
265
+ session: Session,
266
+ ids: list[Any],
267
+ obj_in: UpdateSchemaType | dict[str, Any],
268
+ ) -> int:
269
+ """批量更新记录(单条 UPDATE SQL,不 commit)
270
+
271
+ 启用审计填充时自动补 ``updated_at`` / ``updated_by``
272
+ (不碰 ``created_*`` 与 ``deleted``)。
273
+ """
274
+ update_data = dict(
275
+ obj_in
276
+ if isinstance(obj_in, dict)
277
+ else obj_in.model_dump(exclude_unset=True)
278
+ )
279
+ fill_update(update_data, self._column_names())
280
+ id_col = self._id_col()
281
+ statement = update(self.model).where(id_col.in_(ids)).values(**update_data)
282
+ result = session.execute(statement)
283
+ count = getattr(result, "rowcount", 0) or 0
284
+ logger.info(
285
+ f"✅ 批量更新 {count} 条 {self.model.__name__} 记录 "
286
+ f"ids={ids} → 字段: {update_data}"
287
+ )
288
+ return count
289
+
290
+ def delete(self, session: Session, id: Any) -> ModelType | None:
291
+ """删除记录(仅 delete,不 commit)"""
292
+ db_obj = session.get(self.model, id)
293
+ if db_obj:
294
+ session.delete(db_obj)
295
+ logger.info(f"✅ 删除 {self.model.__name__} id={id} → 已删除")
296
+ else:
297
+ logger.info(f"🔍 删除 {self.model.__name__} id={id} → 记录不存在")
298
+ return db_obj
299
+
300
+ def delete_multi(self, session: Session, ids: list[Any]) -> int:
301
+ """批量删除记录(单条 DELETE SQL,不 commit)"""
302
+ id_col = self._id_col()
303
+ statement = delete(self.model).where(id_col.in_(ids))
304
+ result = session.execute(statement)
305
+ count = getattr(result, "rowcount", 0) or 0
306
+ logger.info(f"✅ 批量删除 {count} 条 {self.model.__name__} 记录 ids={ids}")
307
+ return count
308
+
309
+ # ==================== 聚合查询 ====================
310
+
311
+ def count(self, session: Session) -> int:
312
+ """获取记录总数(开启软删除过滤时不计已删除记录)"""
313
+ statement = select(func.count()).select_from(self.model)
314
+ condition = self._deleted_condition()
315
+ if condition is not None:
316
+ statement = statement.where(condition)
317
+ total = session.exec(statement).one()
318
+ logger.info(f"🔍 统计 {self.model.__name__} 记录总数 → {total}")
319
+ return total
320
+
321
+ def exists(self, session: Session, id: Any) -> bool:
322
+ """检查记录是否存在(仅查询主键列,不载入整对象)"""
323
+ id_col = self._id_col()
324
+ statement = select(id_col).where(id_col == id)
325
+ condition = self._deleted_condition()
326
+ if condition is not None:
327
+ statement = statement.where(condition)
328
+ found = (
329
+ session.exec(cast(SelectOfScalar[object], statement)).first() is not None
330
+ )
331
+ logger.info(
332
+ f"🔍 检查 {self.model.__name__} id={id} 是否存在 → "
333
+ f"{'是' if found else '否'}"
334
+ )
335
+ return found
336
+
337
+ def upsert(
338
+ self,
339
+ session: Session,
340
+ obj_in: CreateSchemaType | dict[str, Any],
341
+ conflict_fields: list[str],
342
+ ) -> ModelType:
343
+ """插入或更新记录(原生 upsert,原子单语句)
344
+
345
+ 根据 conflict_fields 对应的唯一约束判断冲突,存在则更新,不存在则插入。
346
+ 注意:conflict_fields 必须对应表上的唯一索引/约束,否则数据库会报错。
347
+ 不 commit,由外层事务管理。
348
+
349
+ Args:
350
+ session: 数据库会话
351
+ obj_in: 创建/更新数据
352
+ conflict_fields: 用于判断冲突的字段列表(需为唯一约束)
353
+ """
354
+ data = dict(
355
+ obj_in
356
+ if isinstance(obj_in, dict)
357
+ else obj_in.model_dump(exclude_unset=True)
358
+ )
359
+ if not conflict_fields:
360
+ raise DBError("upsert 必须提供 conflict_fields")
361
+
362
+ columns = self._column_names()
363
+
364
+ # 更新集:排除冲突字段、主键,以及**只在 INSERT 填充**的 created_*
365
+ # (含内置别名 create_time;若带进 set_,每次冲突更新都会把创建时间刷成 now)
366
+ insert_only = insert_only_columns()
367
+ pk_cols = {c.name for c in self._table().primary_key.columns}
368
+ update_cols = {
369
+ k: v
370
+ for k, v in data.items()
371
+ if k not in conflict_fields
372
+ and k not in pk_cols
373
+ and k not in insert_only
374
+ }
375
+ if not update_cols:
376
+ # 无更新字段时退化为空更新(保持合法 SQL)
377
+ update_cols = {conflict_fields[0]: data[conflict_fields[0]]}
378
+
379
+ # INSERT 半区补 created_*/updated_*/deleted;UPDATE 半区补 updated_*
380
+ fill_insert(data, columns)
381
+ fill_update(update_cols, columns)
382
+
383
+ # 各数据库方言的 INSERT ... ON CONFLICT / ON DUPLICATE KEY(原子单语句)
384
+ dialect = session.get_bind().dialect.name
385
+ if dialect == "postgresql":
386
+ session.execute(
387
+ pg_dialect.insert(self.model)
388
+ .values(**data)
389
+ .on_conflict_do_update(index_elements=conflict_fields, set_=update_cols)
390
+ )
391
+ elif dialect == "mysql":
392
+ session.execute(
393
+ mysql_dialect.insert(self.model)
394
+ .values(**data)
395
+ .on_duplicate_key_update(**update_cols)
396
+ )
397
+ elif dialect == "sqlite":
398
+ session.execute(
399
+ sqlite_dialect.insert(self.model)
400
+ .values(**data)
401
+ .on_conflict_do_update(index_elements=conflict_fields, set_=update_cols)
402
+ )
403
+ else:
404
+ raise DBError(f"不支持的数据库类型: {dialect}")
405
+
406
+ # 按冲突字段回查返回实例(populate_existing 强制刷新,避免身份映射返回旧值);
407
+ # 回查**必须跳过软删除过滤**:冲突行可能已被软删除,否则会误报回查失败
408
+ conditions = [
409
+ getattr(self.model, field) == data.get(field) for field in conflict_fields
410
+ ]
411
+ re_stmt = (
412
+ self._select_all(include_deleted=True)
413
+ .where(*conditions)
414
+ .execution_options(populate_existing=True)
415
+ )
416
+ obj = session.exec(re_stmt).first()
417
+ if obj is None:
418
+ raise DBError(f"upsert {self.model.__name__} 后回查失败")
419
+ obj_id = getattr(obj, "id", "?")
420
+ logger.info(
421
+ f"🔄 upsert {self.model.__name__} 冲突字段 {conflict_fields} → id={obj_id}"
422
+ )
423
+ return obj
yimo/kit/db/engine.py ADDED
@@ -0,0 +1,235 @@
1
+ """
2
+ Copyright (c) 2021-2026 溢墨修心(Yimo). All Rights Reserved.
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+
16
+ Project: yimo
17
+ Author: 溢墨修心(Yimo)
18
+ """
19
+
20
+ # date: 2025-04-19
21
+ """数据库引擎管理(线程安全单例)
22
+
23
+ 支持 PostgreSQL、MySQL、SQLite 三种数据库。
24
+ 使用 threading.Lock 保护 _engines 字典,避免 TOCTOU 竞态。
25
+
26
+ `build_pg_url` / `build_mysql_url` / `build_sqlite_url` 为**公开**的连接串构造器:
27
+ 除本模块创建引擎外,测试与外部工具(如迁移脚本)也应复用它们,避免各自手抄导致取值漂移
28
+ (历史问题:`tests/db/conftest.py` 曾手抄 MySQL 串,漏了 `MYSQL_USER` 覆盖)。
29
+ """
30
+
31
+ import threading
32
+ import urllib.parse
33
+ from typing import Any, Type, cast
34
+
35
+ from sqlalchemy import Engine, create_engine, event, inspect
36
+ from sqlmodel import SQLModel
37
+
38
+ from yimo.kit.config.kit_config import Settings, get_settings
39
+ from yimo.kit.config.log_config import get_default_logger
40
+
41
+ logger = get_default_logger(__name__)
42
+
43
+ # 数据库类型常量
44
+ POSTGRESQL = "postgresql"
45
+ MYSQL = "mysql"
46
+ SQLITE = "sqlite"
47
+
48
+ # 线程安全的引擎缓存
49
+ _engines: dict[str, Engine] = {}
50
+ _lock = threading.Lock()
51
+
52
+
53
+ def build_pg_url(settings: Settings) -> str:
54
+ """构建 PostgreSQL 连接字符串
55
+
56
+ 取值全部来自 `DB_*` 配置(密码经 `quote_plus` 转义)。
57
+ """
58
+ password = urllib.parse.quote_plus(settings.DB_PASSWORD)
59
+ return (
60
+ f"postgresql://{settings.DB_USER}:{password}"
61
+ f"@{settings.DB_HOST}:{settings.DB_PORT}"
62
+ f"/{settings.DB_DATABASE}"
63
+ )
64
+
65
+
66
+ def build_mysql_url(settings: Settings) -> str:
67
+ """构建 MySQL 连接字符串
68
+
69
+ 端口 / 用户 / 库名 / 字符集通过 `MYSQL_*` 覆盖,主机与密码共用 `DB_HOST` / `DB_PASSWORD`。
70
+ """
71
+ password = urllib.parse.quote_plus(settings.DB_PASSWORD)
72
+ port = getattr(settings, "MYSQL_PORT", settings.DB_PORT)
73
+ database = getattr(settings, "MYSQL_DATABASE", settings.DB_DATABASE)
74
+ user = getattr(settings, "MYSQL_USER", settings.DB_USER)
75
+ charset = getattr(settings, "MYSQL_CHARSET", "utf8mb4")
76
+ return (
77
+ f"mysql+pymysql://{user}:{password}"
78
+ f"@{settings.DB_HOST}:{port}"
79
+ f"/{database}?charset={charset}"
80
+ )
81
+
82
+
83
+ def build_sqlite_url(settings: Settings) -> str:
84
+ """构建 SQLite 连接字符串"""
85
+ db_path = getattr(settings, "SQLITE_DB_PATH", "./data/sqlite.db")
86
+ return f"sqlite:///{db_path}"
87
+
88
+
89
+ def _resolve_db_type(db_type: str | None) -> str:
90
+ """解析数据库类型,回退到配置默认值"""
91
+ if db_type:
92
+ return db_type
93
+ return get_settings().DEFAULT_DB_TYPE
94
+
95
+
96
+ def _receive_connect(dbapi_connection: Any, connection_record: Any) -> None:
97
+ """每次 SQLite 连接建立时自动加载 sqlite-vector 扩展"""
98
+ try:
99
+ import importlib.resources
100
+
101
+ dbapi_connection.enable_load_extension(True)
102
+ ext_path = importlib.resources.files("sqlite_vector.binaries") / "vector"
103
+ dbapi_connection.load_extension(str(ext_path))
104
+ dbapi_connection.enable_load_extension(False)
105
+ logger.debug("🔌 sqlite-vector 扩展已加载")
106
+ except Exception as e:
107
+ logger.warning(f"⚠️ 加载 sqlite-vector 扩展失败: {e}")
108
+
109
+
110
+ def _register_vector_events(eng: Engine) -> None:
111
+ """注册 sqlite-vector 扩展加载事件"""
112
+ event.listen(eng, "connect", _receive_connect)
113
+
114
+
115
+ def _create_engine(db_type: str, **kwargs: object) -> Engine:
116
+ """根据数据库类型创建引擎
117
+
118
+ SQLite 使用 check_same_thread=False 以支持多线程;
119
+ SQLite 内存模式(:memory:)额外使用 StaticPool 保持单连接共享。
120
+ MySQL / PostgreSQL 使用 QueuePool 连接池(pool_size=10, max_overflow=20)。
121
+ """
122
+ settings = get_settings()
123
+
124
+ if db_type == POSTGRESQL:
125
+ url = build_pg_url(settings)
126
+ elif db_type == MYSQL:
127
+ url = build_mysql_url(settings)
128
+ elif db_type == SQLITE:
129
+ url = build_sqlite_url(settings)
130
+ else:
131
+ raise ValueError(f"不支持的数据库类型: {db_type}")
132
+
133
+ # 默认连接池参数(仅对支持连接池的数据库有效)
134
+ default_config: dict[str, object] = {
135
+ "pool_pre_ping": True,
136
+ "pool_recycle": 3600,
137
+ "echo": False,
138
+ }
139
+
140
+ if db_type == SQLITE:
141
+ # SQLite 使用线程安全的连接配置
142
+ default_config["connect_args"] = {"check_same_thread": False}
143
+ sqlite_path = getattr(settings, "SQLITE_DB_PATH", "./data/sqlite.db")
144
+ if ":memory:" in sqlite_path:
145
+ from sqlalchemy.pool import StaticPool
146
+
147
+ default_config["poolclass"] = StaticPool
148
+
149
+ else:
150
+ # MySQL / PostgreSQL 使用 QueuePool
151
+ default_config["pool_size"] = 10
152
+ default_config["max_overflow"] = 20
153
+
154
+ default_config.update(kwargs)
155
+
156
+ try:
157
+ # create_engine 接受 dict[str, Any] 风格 kwargs,此处为安全子集 cast
158
+ engine = create_engine(url, **cast(dict[str, Any], default_config))
159
+ if db_type == SQLITE:
160
+ _register_vector_events(engine)
161
+ logger.info(f"✅ {db_type} 数据库引擎已创建")
162
+ return engine
163
+ except Exception as e:
164
+ logger.error(f"❌ 创建 {db_type} 数据库引擎失败: {e}")
165
+ raise
166
+
167
+
168
+ def get_engine(db_type: str | None = None, **kwargs: object) -> Engine:
169
+ """获取数据库引擎(线程安全单例)
170
+
171
+ Args:
172
+ db_type: 数据库类型(postgresql/mysql/sqlite),None 时使用配置默认值
173
+ **kwargs: 传递给 create_engine 的额外参数(仅首次创建时生效)
174
+
175
+ Returns:
176
+ SQLAlchemy Engine 实例
177
+ """
178
+ resolved = _resolve_db_type(db_type)
179
+
180
+ # 双重检查锁,避免已创建时仍获取锁
181
+ if resolved not in _engines:
182
+ with _lock:
183
+ if resolved not in _engines:
184
+ _engines[resolved] = _create_engine(resolved, **kwargs)
185
+
186
+ return _engines[resolved]
187
+
188
+
189
+ def create_tables(models: list[Type[SQLModel]], db_type: str | None = None) -> None:
190
+ """创建数据库表(单次调用 metadata.create_all)
191
+
192
+ Args:
193
+ models: 需要创建表的 SQLModel 模型类列表(仅用于确认模型已注册)
194
+ db_type: 数据库类型,None 时使用配置默认值
195
+ """
196
+ engine = get_engine(db_type)
197
+ try:
198
+ # 所有 SQLModel 模型共享同一个 metadata,只需调用一次
199
+ SQLModel.metadata.create_all(engine)
200
+ logger.info(f"✅ 成功创建表(模型数: {len(models)})")
201
+ except Exception as e:
202
+ logger.error(f"❌ 创建表失败: {e}")
203
+ raise
204
+
205
+
206
+ def list_tables(db_type: str | None = None) -> list[str]:
207
+ """列出数据库中的所有表"""
208
+ engine = get_engine(db_type)
209
+ return inspect(engine).get_table_names()
210
+
211
+
212
+ def table_exists(table_name: str, db_type: str | None = None) -> bool:
213
+ """检查表是否存在"""
214
+ return table_name in list_tables(db_type)
215
+
216
+
217
+ def close_all_engines() -> None:
218
+ """关闭并清理所有数据库引擎"""
219
+ with _lock:
220
+ for db_type, engine in _engines.items():
221
+ try:
222
+ engine.dispose()
223
+ logger.info(f"🔌 {db_type} 数据库引擎已关闭")
224
+ except Exception as e:
225
+ logger.error(f"❌ 关闭 {db_type} 引擎失败: {e}")
226
+ _engines.clear()
227
+
228
+
229
+ def close_engine(db_type: str) -> None:
230
+ """关闭指定类型的数据库引擎"""
231
+ with _lock:
232
+ engine = _engines.pop(db_type, None)
233
+ if engine:
234
+ engine.dispose()
235
+ logger.info(f"🔌 {db_type} 数据库引擎已关闭")