sqlalchemy-lite 0.1.0__tar.gz

sqlalchemy_lite-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.3
+Name: sqlalchemy-lite
+Version: 0.1.0
+Summary: A future-proof, greenlet-free adapter for SQLAlchemy 2.0 and databases.
+Keywords: sqlalchemy,asyncio,pydantic,databases,sqlite,mysql,postgresql,embedded,arm,lite
+Author: gnakw
+Author-email: gnakw <gnakw@outlook.com>
+Requires-Dist: aiosqlite>=0.22.1
+Requires-Dist: databases>=0.9.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: sqlalchemy>=2.0.46
+Requires-Dist: aiomysql ; extra == 'mysql'
+Requires-Dist: pymysql ; extra == 'mysql'
+Requires-Dist: asyncpg ; extra == 'postgres'
+Requires-Dist: psycopg2-binary ; extra == 'postgres'
+Requires-Dist: aiosqlite ; extra == 'sqlite'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/gnakw/sqlalchemy-lite
+Project-URL: Documentation, https://github.com/gnakw/sqlalchemy-lite#readme
+Project-URL: Repository, https://github.com/gnakw/sqlalchemy-lite.git
+Project-URL: Bug Tracker, https://github.com/gnakw/sqlalchemy-lite/issues
+Project-URL: Changelog, https://github.com/gnakw/sqlalchemy-lite/releases
+Provides-Extra: mysql
+Provides-Extra: postgres
+Provides-Extra: sqlite
+Description-Content-Type: text/markdown
+
+# SQLAlchemy-Lite 🚀
+
+**SQLAlchemy-Lite** 是一个专为受限环境（如老旧 ARM 设备、嵌入式系统）设计的轻量级异步数据库适配层。
+
+> **核心定位**：A future-proof, greenlet-free adapter for SQLAlchemy 2.0 and databases.
+
+它通过缝合 **SQLAlchemy 2.0 的表达式能力**、**databases 的异步驱动桥接** 以及 **Pydantic 的数据校验**，在彻底摆脱 `greenlet` 依赖的同时，提供了一套现代化的开发体验。
+
+---
+
+## 🌟 核心特性
+
+- **去 Greenlet 化**: 彻底避开原生 `AsyncSession` 对 `greenlet` 的硬依赖，解决在特定硬件上无法编译或运行的问题。
+- **Schema 驱动查询**: 配合 `select_for` 工具，自动根据 Pydantic 模型生成精简的 SQL 投影，仅查询所需字段，极大压榨老旧设备的 IO 性能。
+- **2.0 风格语法**: 100% 兼容 SQLAlchemy 2.0 的 `select`, `insert`, `update`, `delete` 表达式构造。
+- **多数据库适配**: 原生支持 **SQLite**, **MySQL**, 及 **PostgreSQL**，支持连接池管理。
+- **类型安全**: 内置 `py.typed`，对 Mypy 和 IDE 自动补全友好。
+- **原生分页支持**：内置 `fetch_page` 异步工具，支持物理分页与总数自动统计，并提供包含 `total_pages`、`has_next` 等智能属性的返回容器。
+
+---
+
+## 📦 安装
+
+使用 [uv](https://github.com/astral-sh/uv) 或 pip 进行安装：
+
+```bash
+# 基础安装 (含核心逻辑)
+uv add sqlalchemy-lite
+
+# 根据需求安装数据库驱动扩展
+uv add "sqlalchemy-lite[sqlite]"   # 默认 SQLite
+uv add "sqlalchemy-lite[mysql]"    # MySQL 支持
+uv add "sqlalchemy-lite[postgres]" # PostgreSQL 支持
+
+```
+
+---
+
+## 🛠️ 快速上手
+
+### 1. 定义数据结构
+
+```python
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from pydantic import BaseModel
+
+class Base(DeclarativeBase): pass
+
+# 数据库模型
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    username: Mapped[str] = mapped_column()
+    email: Mapped[str] = mapped_column()
+    bio: Mapped[str] = mapped_column() # 大字段，非必要不查询
+
+# 业务视图模型
+class UserSimple(BaseModel):
+    username: str
+    email: str
+
+```
+
+### 2. 核心查询示例
+
+```python
+from sqlalchemy_lite import Engine, select_for
+
+async def main():
+    db = Engine("sqlite+aiosqlite:///app.db")
+    db.init_db(Base.metadata)
+
+    await db.connect()
+
+    async with db.session() as sess:
+        # 自动生成精简 SQL: SELECT username, email FROM users
+        stmt = select_for(User, UserSimple)
+        result = await sess.execute(stmt)
+        
+        # 映射为 Pydantic 对象列表
+        users = [UserSimple.model_validate(m) for m in result.mappings()]
+    
+    await db.disconnect()
+
+```
+
+---
+
+## 📖 标准业务服务模板 (Best Practice)
+
+为了确保代码的健壮性与可移植性，推荐采用以下模式：
+
+```python
+from sqlalchemy_lite import auto_query, PageResult, select_for, fetch_page
+
+class UserService:
+    def __init__(self, db: Engine):
+        self.db = db
+
+    @auto_query(User, UserSimple, single=True)
+    async def get_by_name(self, stmt, name: str):
+        """使用装饰器：自动处理 session 开启、SQL 投影与模型验证"""
+        return stmt.where(User.username == name)
+
+    async def list_paged(self, page: int, size: int) -> PageResult[UserSimple]:
+        """标准分页：计算总数 + 物理分页 + 结果包装"""
+        async with self.db.session() as sess:
+            base_stmt = select_for(User, UserSimple)
+            return await fetch_page(sess, base_stmt, UserSimple, page, size)
+
+```
+
+---
+
+## 🛡️ 模板关键原则 (The Principles)
+
+| 维度 | 推荐做法 (未来证明) | 禁忌做法 |
+| --- | --- | --- |
+| **查询列** | 使用 `select_for` 或明确指定列 | 严禁 `select(User)` (全实体查询) |
+| **单条转换** | `Schema.model_validate(dict(row))` | 严禁依赖 ORM 的延迟加载属性 |
+| **结果访问** | 使用 `result.mappings()` 或 `result.scalar()` | 严禁依赖 `result.scalars().all()` 获取整个对象 |
+| **事务** | 始终使用 `async with session.begin():` | 手动显式调用 `commit()` |
+
+---
+
+## 🔗 高级配置与连接池
+
+对于 **MySQL** 或 **PostgreSQL**，建议配置连接池以提升性能：
+
+```python
+db = Engine(
+    url="mysql+aiomysql://root:pass@localhost/db",
+    min_size=5,
+    max_size=20,
+    pool_recycle=3600
+)
+
+```
+
+---
+
+## 💎 未来证明 (Future-Proofing)
+
+**SQLAlchemy-Lite** 的设计理念是“不产生负担”。当你不再受限于硬件环境，想要迁移回官方的 SQLAlchemy `AsyncSession` 时：
+
+1. **零逻辑修改**: 由于 `select_for` 生成的是标准 SQLAlchemy 语句，你的业务函数体无需任何修改。
+2. **零迁移成本**: 我们的 `Session` 和 `Result` 接口高度模拟了官方 API。你只需将 `Engine` 替换为 `create_async_engine`，并调整 `Session` 获取方式即可。
+
+---
+
+## ⚖️ 开源协议
+
+本项目采用 **MIT** 协议。
+
+
+## Acknowledgment
+
+This project was developed with the assistance of AI (Gemini). While the core architecture and logic were human-steered and rigorously reviewed to ensure security and compliance with SQLAlchemy 2.0 standards, this collaboration allowed for a more rapid exploration of lite-weight patterns for restricted environments.
+

sqlalchemy_lite-0.1.0/README.md

@@ -0,0 +1,159 @@
+# SQLAlchemy-Lite 🚀
+
+**SQLAlchemy-Lite** 是一个专为受限环境（如老旧 ARM 设备、嵌入式系统）设计的轻量级异步数据库适配层。
+
+> **核心定位**：A future-proof, greenlet-free adapter for SQLAlchemy 2.0 and databases.
+
+它通过缝合 **SQLAlchemy 2.0 的表达式能力**、**databases 的异步驱动桥接** 以及 **Pydantic 的数据校验**，在彻底摆脱 `greenlet` 依赖的同时，提供了一套现代化的开发体验。
+
+---
+
+## 🌟 核心特性
+
+- **去 Greenlet 化**: 彻底避开原生 `AsyncSession` 对 `greenlet` 的硬依赖，解决在特定硬件上无法编译或运行的问题。
+- **Schema 驱动查询**: 配合 `select_for` 工具，自动根据 Pydantic 模型生成精简的 SQL 投影，仅查询所需字段，极大压榨老旧设备的 IO 性能。
+- **2.0 风格语法**: 100% 兼容 SQLAlchemy 2.0 的 `select`, `insert`, `update`, `delete` 表达式构造。
+- **多数据库适配**: 原生支持 **SQLite**, **MySQL**, 及 **PostgreSQL**，支持连接池管理。
+- **类型安全**: 内置 `py.typed`，对 Mypy 和 IDE 自动补全友好。
+- **原生分页支持**：内置 `fetch_page` 异步工具，支持物理分页与总数自动统计，并提供包含 `total_pages`、`has_next` 等智能属性的返回容器。
+
+---
+
+## 📦 安装
+
+使用 [uv](https://github.com/astral-sh/uv) 或 pip 进行安装：
+
+```bash
+# 基础安装 (含核心逻辑)
+uv add sqlalchemy-lite
+
+# 根据需求安装数据库驱动扩展
+uv add "sqlalchemy-lite[sqlite]"   # 默认 SQLite
+uv add "sqlalchemy-lite[mysql]"    # MySQL 支持
+uv add "sqlalchemy-lite[postgres]" # PostgreSQL 支持
+
+```
+
+---
+
+## 🛠️ 快速上手
+
+### 1. 定义数据结构
+
+```python
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from pydantic import BaseModel
+
+class Base(DeclarativeBase): pass
+
+# 数据库模型
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    username: Mapped[str] = mapped_column()
+    email: Mapped[str] = mapped_column()
+    bio: Mapped[str] = mapped_column() # 大字段，非必要不查询
+
+# 业务视图模型
+class UserSimple(BaseModel):
+    username: str
+    email: str
+
+```
+
+### 2. 核心查询示例
+
+```python
+from sqlalchemy_lite import Engine, select_for
+
+async def main():
+    db = Engine("sqlite+aiosqlite:///app.db")
+    db.init_db(Base.metadata)
+
+    await db.connect()
+
+    async with db.session() as sess:
+        # 自动生成精简 SQL: SELECT username, email FROM users
+        stmt = select_for(User, UserSimple)
+        result = await sess.execute(stmt)
+        
+        # 映射为 Pydantic 对象列表
+        users = [UserSimple.model_validate(m) for m in result.mappings()]
+    
+    await db.disconnect()
+
+```
+
+---
+
+## 📖 标准业务服务模板 (Best Practice)
+
+为了确保代码的健壮性与可移植性，推荐采用以下模式：
+
+```python
+from sqlalchemy_lite import auto_query, PageResult, select_for, fetch_page
+
+class UserService:
+    def __init__(self, db: Engine):
+        self.db = db
+
+    @auto_query(User, UserSimple, single=True)
+    async def get_by_name(self, stmt, name: str):
+        """使用装饰器：自动处理 session 开启、SQL 投影与模型验证"""
+        return stmt.where(User.username == name)
+
+    async def list_paged(self, page: int, size: int) -> PageResult[UserSimple]:
+        """标准分页：计算总数 + 物理分页 + 结果包装"""
+        async with self.db.session() as sess:
+            base_stmt = select_for(User, UserSimple)
+            return await fetch_page(sess, base_stmt, UserSimple, page, size)
+
+```
+
+---
+
+## 🛡️ 模板关键原则 (The Principles)
+
+| 维度 | 推荐做法 (未来证明) | 禁忌做法 |
+| --- | --- | --- |
+| **查询列** | 使用 `select_for` 或明确指定列 | 严禁 `select(User)` (全实体查询) |
+| **单条转换** | `Schema.model_validate(dict(row))` | 严禁依赖 ORM 的延迟加载属性 |
+| **结果访问** | 使用 `result.mappings()` 或 `result.scalar()` | 严禁依赖 `result.scalars().all()` 获取整个对象 |
+| **事务** | 始终使用 `async with session.begin():` | 手动显式调用 `commit()` |
+
+---
+
+## 🔗 高级配置与连接池
+
+对于 **MySQL** 或 **PostgreSQL**，建议配置连接池以提升性能：
+
+```python
+db = Engine(
+    url="mysql+aiomysql://root:pass@localhost/db",
+    min_size=5,
+    max_size=20,
+    pool_recycle=3600
+)
+
+```
+
+---
+
+## 💎 未来证明 (Future-Proofing)
+
+**SQLAlchemy-Lite** 的设计理念是“不产生负担”。当你不再受限于硬件环境，想要迁移回官方的 SQLAlchemy `AsyncSession` 时：
+
+1. **零逻辑修改**: 由于 `select_for` 生成的是标准 SQLAlchemy 语句，你的业务函数体无需任何修改。
+2. **零迁移成本**: 我们的 `Session` 和 `Result` 接口高度模拟了官方 API。你只需将 `Engine` 替换为 `create_async_engine`，并调整 `Session` 获取方式即可。
+
+---
+
+## ⚖️ 开源协议
+
+本项目采用 **MIT** 协议。
+
+
+## Acknowledgment
+
+This project was developed with the assistance of AI (Gemini). While the core architecture and logic were human-steered and rigorously reviewed to ensure security and compliance with SQLAlchemy 2.0 standards, this collaboration allowed for a more rapid exploration of lite-weight patterns for restricted environments.
+

sqlalchemy_lite-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "sqlalchemy-lite"
+version = "0.1.0"
+description = "A future-proof, greenlet-free adapter for SQLAlchemy 2.0 and databases."
+keywords = [
+    "sqlalchemy",
+    "asyncio",
+    "pydantic",
+    "databases",
+    "sqlite",
+    "mysql",
+    "postgresql",
+    "embedded",
+    "arm",
+    "lite"
+]
+readme = "README.md"
+authors = [
+    { name = "gnakw", email = "gnakw@outlook.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "aiosqlite>=0.22.1",
+    "databases>=0.9.0",
+    "pydantic>=2.12.5",
+    "sqlalchemy>=2.0.46",
+]
+
+[project.optional-dependencies]
+sqlite = ["aiosqlite"]
+mysql = ["aiomysql", "pymysql"]
+postgres = ["asyncpg", "psycopg2-binary"]
+
+[project.urls]
+"Homepage" = "https://github.com/gnakw/sqlalchemy-lite"
+"Documentation" = "https://github.com/gnakw/sqlalchemy-lite#readme"
+"Repository" = "https://github.com/gnakw/sqlalchemy-lite.git"
+"Bug Tracker" = "https://github.com/gnakw/sqlalchemy-lite/issues"
+"Changelog" = "https://github.com/gnakw/sqlalchemy-lite/releases"
+
+[build-system]
+requires = ["uv_build>=0.9.29,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "aiosqlite>=0.22.1",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "ruff>=0.15.0",
+]
+
+[tool.ruff.lint]
+select = ["I", "E", "F"]

sqlalchemy_lite-0.1.0/src/sqlalchemy_lite/__init__.py

@@ -0,0 +1,15 @@
+from .engine import Engine
+from .ext import auto_query
+from .proxy import Result, Session
+from .types import PageResult
+from .utils import fetch_page, select_for
+
+__all__ = [
+    "Engine",
+    "Session",
+    "Result",
+    "PageResult",
+    "auto_query",
+    "select_for",
+    "fetch_page",
+]

sqlalchemy_lite-0.1.0/src/sqlalchemy_lite/engine.py

@@ -0,0 +1,56 @@
+import logging
+from typing import TypeVar
+
+import sqlalchemy
+from databases import Database
+from pydantic import BaseModel
+from sqlalchemy import create_engine
+
+from .proxy import Session
+
+logger = logging.getLogger(__name__)
+T = TypeVar("T", bound=BaseModel)
+
+
+class Engine:
+    def __init__(self, url: str, **kwargs):
+        self.url = url
+        self.db = Database(url, **kwargs)
+
+        sync_url = (
+            url.replace("+aiosqlite", "")
+            .replace("+aiomysql", "+pymysql")  # MySQL 异步转同步
+            .replace("+asyncpg", "")  # PostgreSQL 异步转同步
+        )
+        self._sync_engine = create_engine(sync_url)
+
+    def init_db(self, metadata: sqlalchemy.MetaData):
+        """
+        根据定义的 Base.metadata 自动在数据库中创建所有缺失的表。
+        """
+        try:
+            metadata.create_all(self._sync_engine)
+            logger.info(">>> [SQLAlchemy-Lite] 数据库表结构初始化成功")
+        except Exception as e:
+            logger.exception(f">>> [SQLAlchemy-Lite] 数据库初始化失败: {e}")
+            raise
+
+    async def connect(self):
+        await self.db.connect()
+
+    async def disconnect(self):
+        await self.db.disconnect()
+
+    from contextlib import asynccontextmanager
+
+    @asynccontextmanager
+    async def session(self):
+        async with self.db.connection() as conn:
+            yield Session(conn)
+
+    # def select_for(self, model: Any, schema: Type[T]):
+    #     """根据 Pydantic Schema 自动投影列"""
+    #     cols = [
+    #         getattr(model, f) for f in schema.model_fields.keys() if hasattr(model, f)
+    #     ]
+    #     return select(*(cols or [model]))

sqlalchemy_lite-0.1.0/src/sqlalchemy_lite/ext.py

@@ -0,0 +1,40 @@
+from functools import wraps
+from typing import Type
+
+from pydantic import BaseModel
+
+from sqlalchemy_lite.utils import select_for
+
+
+def auto_query(db_model, schema: Type[BaseModel], single: bool = False):
+    """业务级装饰器, 自动查询
+
+    Args:
+        db_model (_type_): SQLAlchemy 模型
+        schema (Type[BaseModel]): Pydantic 模型 (用于 select_for)
+        single (bool, optional): 是否只返回单条数据 (result.first vs result.all)
+
+    """
+
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(self, *args, **kwargs):
+            # 1. 自动根据 Schema 构建基础语句
+            base_stmt = select_for(db_model, schema)
+
+            # 2. 执行原函数获取过滤条件 (如 .where())
+            final_stmt = await func(self, base_stmt, *args, **kwargs)
+
+            # 3. 统一处理 Session 执行逻辑
+            async with self.db.session() as sess:
+                result = await sess.execute(final_stmt)
+
+                if single:
+                    row = result.first()
+                    return schema.model_validate(dict(row)) if row else None
+
+                return [schema.model_validate(m) for m in result.mappings()]
+
+        return wrapper
+
+    return decorator

sqlalchemy_lite-0.1.0/src/sqlalchemy_lite/proxy.py

@@ -0,0 +1,97 @@
+from typing import Any, Dict, List, Optional, Union
+
+from databases.interfaces import Record
+from sqlalchemy.exc import MultipleResultsFound, NoResultFound
+
+
+class ScalarResult:
+    """处理 .scalars() 的降维结果集"""
+
+    def __init__(self, rows: List[Record]):
+        self._data = [row[0] for row in rows] if rows else []
+
+    def all(self) -> List[Any]:
+        return self._data
+
+    def first(self) -> Optional[Any]:
+        return self._data[0] if self._data else None
+
+    def __iter__(self):
+        return iter(self._data)
+
+
+class Result:
+    """模拟 SQLAlchemy 2.0 Result 接口"""
+
+    def __init__(self, rows: Union[List[Record], Any]):
+        self._rows = (
+            rows if isinstance(rows, list) else ([rows] if rows is not None else [])
+        )
+
+    def all(self) -> List[Record]:
+        return self._rows
+
+    def first(self) -> Optional[Record]:
+        return self._rows[0] if self._rows else None
+
+    def one_or_none(self):
+        """取第一行，如果有第二行则报错"""
+        if len(self._rows) > 1:
+            raise MultipleResultsFound(
+                f"Expected at most one result, got {len(self._rows)}"
+            )
+        return self._rows[0] if self._rows else None
+
+    def one(self):
+        """必须有一行，且只能有一行"""
+        if not self._rows:
+            raise NoResultFound("No result found")
+        if len(self._rows) > 1:
+            raise MultipleResultsFound(
+                f"Expected exactly one result, got {len(self._rows)}"
+            )
+        return self._rows[0]
+
+    def scalar(self) -> Any:
+        return self._rows[0][0] if self._rows and len(self._rows[0]) > 0 else None
+
+    def scalar_one_or_none(self):
+        """安全返回单值"""
+        row = self.one_or_none()
+        return row[0] if row else None
+
+    def scalars(self) -> ScalarResult:
+        return ScalarResult(self._rows)
+
+    def mappings(self) -> List[Dict[str, Any]]:
+        return [dict(row) for row in self._rows]
+
+    def __iter__(self):
+        return iter(self._rows)
+
+
+class Session:
+    """映射 SQLAlchemy Session 到 databases.Connection"""
+
+    def __init__(self, conn):
+        self._conn = conn
+
+    from contextlib import asynccontextmanager
+
+    @asynccontextmanager
+    async def begin(self):
+        async with self._conn.transaction():
+            yield self
+
+    async def execute(self, statement: Any) -> Result:
+        raw_sql = str(statement).strip().upper()
+        # 简单判别 SELECT 逻辑，亦可扩展更严谨的判断
+        if raw_sql.startswith("SELECT") or "RETURNING" in raw_sql:
+            rows = await self._conn.fetch_all(statement)
+            return Result(rows)
+        res = await self._conn.execute(statement)
+        return Result(res)
+
+    async def scalar(self, statement):
+        res = await self.execute(statement)
+        return res.scalar()

sqlalchemy_lite-0.1.0/src/sqlalchemy_lite/types.py

@@ -0,0 +1,32 @@
+import math
+from typing import Generic, List, TypeVar
+
+from pydantic import BaseModel, ConfigDict, computed_field
+
+T = TypeVar("T")
+
+
+class PageResult(BaseModel, Generic[T]):
+    items: List[T]
+    total: int
+    page: int
+    size: int
+
+    @computed_field
+    @property
+    def total_pages(self) -> int:
+        if self.size <= 0:
+            return 0
+        return math.ceil(self.total / self.size)
+
+    @computed_field
+    @property
+    def has_next(self) -> bool:
+        return self.page < self.total_pages
+
+    @computed_field
+    @property
+    def has_prev(self) -> bool:
+        return self.page > 1
+
+    model_config = ConfigDict(from_attributes=True)

sqlalchemy_lite-0.1.0/src/sqlalchemy_lite/utils.py

@@ -0,0 +1,52 @@
+from typing import Any, Type, TypeVar
+
+from pydantic import BaseModel
+from sqlalchemy import func, select
+
+from sqlalchemy_lite.types import PageResult
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def get_select_columns(db_model: Any, schema: Type[T]):
+    """
+    根据 Pydantic Schema 提取 SQLAlchemy Model 的 Column 对象
+    """
+    selected_columns = [
+        getattr(db_model, field_name)
+        for field_name in schema.model_fields.keys()
+        if hasattr(db_model, field_name)
+    ]
+
+    # 如果没有匹配到任何列，默认返回模型本身 (SELECT *)
+    return selected_columns if selected_columns else [db_model]
+
+
+def select_for(db_model: Any, schema: Type[T]):
+    """
+    根据 Pydantic 模型自动生成精简字段的SQLAlchemy select 语句
+    """
+    columns = get_select_columns(db_model, schema)
+    return select(*columns)
+
+
+async def fetch_page(
+    session, stmt, schema: Type[T], page: int, size: int
+) -> PageResult[T]:
+    safe_page = max(1, page)
+    safe_size = max(1, size)
+
+    count_stmt = select(func.count()).select_from(stmt.subquery())
+    total = await session.scalar(count_stmt) or 0
+
+    total_pages = (total + safe_size - 1) // safe_size if total > 0 else 1
+
+    if safe_page > total_pages or total == 0:
+        return PageResult(items=[], total=total, page=safe_page, size=safe_size)
+
+    offset = (safe_page - 1) * safe_size
+    paged_stmt = stmt.offset(offset).limit(safe_size)
+    result = await session.execute(paged_stmt)
+
+    items = [schema.model_validate(m) for m in result.mappings()]
+    return PageResult(items=items, total=total, page=safe_page, size=safe_size)