kksanic 0.1.0__tar.gz

kksanic-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Python卡皮巴拉
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kksanic-0.1.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include README.md
+include LICENSE
+include pyproject.toml
+
+include settings.py
+
+recursive-include kksanic *.py
+recursive-include tests *.py
+recursive-include docs *.md
+recursive-include tools *.py
+
+global-exclude *.py[cod] __pycache__ *.so .DS_Store

kksanic-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: kksanic
+Version: 0.1.0
+Summary: 基于 Sanic + Tortoise 的后端小工具箱：统一响应、入参校验、出参序列化、RESTful 一键接口、后台管理站、接口文档、分表
+Author: Python卡皮巴拉
+License-Expression: MIT
+Keywords: sanic,tortoise-orm,restful,validator,serializer,scaffold,async
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sanic<26,>=24.12
+Requires-Dist: tortoise-orm<2,>=1.1
+Requires-Dist: python-dateutil>=2.8
+Requires-Dist: python-jose>=3.3
+Requires-Dist: tzdata; sys_platform == "win32"
+Provides-Extra: redis
+Requires-Dist: redis>=4.0; extra == "redis"
+Provides-Extra: mysql
+Requires-Dist: aiomysql>=0.2; extra == "mysql"
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == "postgres"
+Provides-Extra: all
+Requires-Dist: redis>=4.0; extra == "all"
+Requires-Dist: aiomysql>=0.2; extra == "all"
+Requires-Dist: asyncpg>=0.29; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# kksanic
+
+基于 Sanic + Tortoise 的小工具箱。写业务不用再拼那套骨架：请求对象、统一响应、
+入参校验、出参序列化、RESTful 增删改查、后台管理站、接口文档、分表分库，
+都在同一个包里，且互相接得上。
+
+| 能力 | 入口 | 一行说明 |
+|---|---|---|
+| 统一响应 | `ApiException` / `get_response` | 状态码走 HTTP，body 只有 `msg` / `data` |
+| 入参校验 | `Validator` + `Rule` 系列 | 按字段类型选规则，写错维度定义期就报 `TypeError` |
+| 出参序列化 | `ModelSerializer` | 模型 → dict，`Meta.include` / `exclude` 收窄字段 |
+| 一键增删改查 | `add_restful_apis` | 6 个接口（含 PATCH）一次注册，分页、软删、事务都带着 |
+| 后台管理站 | `@admin` + `python -m kksanic admin` | 生成单文件管理页，挂成 `/admin` |
+| 接口文档 | `python -m kksanic doc` / `add_swagger_ui` | Markdown + OpenAPI + 自带登录框的 Swagger UI |
+| 分表 | `ShardRule` + `expand()` | 一表一类，两种用法（声明式 / 运行期给表名） |
+| 请求日志 | `add_request_logging` | 一行一请求，慢请求与 5xx 升 WARNING |
+
+## 环境要求
+
+| 依赖 | 版本 | 说明 |
+|---|---|---|
+| Python | **>= 3.10** | `sanic` 25.12 与 `tortoise-orm` 1.1.8 都要求 >= 3.10 |
+| `sanic` | `>=24.12,<26` | 24.12 与 25.12 实测全绿；26 起内部 API 有变动，未验证 |
+| `tortoise-orm` | `>=1.1,<2`（实测 1.1.8） | 连接注册表在 1.1 改成了 contextvar |
+| `python-dateutil` | 必需 | `DateRule` / `DateTimeRule` 的日期解析 |
+| `python-jose` | 必需 | token 编解码 |
+| `tzdata` | **Windows 自动装** | 缺了 `Asia/Shanghai` 会抛 `ZoneInfoNotFoundError` |
+| `redis` | 可选（`kksanic[redis]`） | 缺了就 `ImportError` 兜住，退回进程内缓存 |
+| `aiomysql` / `asyncpg` | 可选（`kksanic[mysql]` / `kksanic[postgres]`） | 用 MySQL / PostgreSQL 时才要 |
+
+Python 3.10 及以上都能装；3.12 / 3.13 也已验证可用。
+
+```bash
+pip install kksanic                 # 装到环境里
+pip install -e .                    # 在本仓库里改代码
+pip install 'kksanic[mysql]'        # 顺带装 MySQL 驱动
+```
+
+没装进环境（只在 `PYTHONPATH` 里）就没有 `kksanic` 这个命令，此时 CLI 要写成
+`python -m kksanic ...`；装过之后两种写法等价。
+
+库被装进 `site-packages` 后无法从自身位置推断 **你的项目根**。探测链覆盖不到的
+部署方式（典型是 `sanic server:app`），在启动代码里显式指定一次，或用环境变量
+`KKSANIC_PROJECT_ROOT`：
+
+```python
+import kksanic
+kksanic.set_project_root('/path/to/your/project')
+```
+
+## 快速开始
+
+```bash
+python -m kksanic init                 # 生成骨架，默认 sqlite
+python -m kksanic init --db postgres   # 或 mysql / postgres
+```
+
+生成 `main.py` / `settings.py` / `models.py` / `serializers.py` / `validators.py`
+与 `migrations/ static/ media/` 目录。同时会写一个 `pyproject.toml`，
+里面只有一段 `[tool.tortoise]`（指向 `settings.TORTOISE_ORM`），
+所以下面的 CLI 不用再传 `-c`：
+
+```bash
+tortoise init            # 生成 migrations/ 包
+tortoise makemigrations
+tortoise migrate
+python main.py           # 默认 0.0.0.0:8000
+```
+
+要显式指定配置就传 `-c`，但 **必须写在子命令前面** —— 写在后面会报
+`tortoise: error: unrecognized arguments: -c`：
+
+```bash
+tortoise -c settings.TORTOISE_ORM makemigrations   # 对
+tortoise makemigrations -c settings.TORTOISE_ORM   # 错
+```
+
+生成的 `main.py` 长这样，**块的顺序是有意义的**，下面三个坑说的就是它：
+
+```python
+from sanic import Sanic
+from tortoise.contrib.sanic import register_tortoise
+
+import settings
+from kksanic import Request, add_request_logging, register_exception_handler
+
+app = Sanic('App', request_class=Request)      # request_class 必须换，否则 Request 用不上
+
+register_exception_handler(app)                # ① 统一异常响应
+add_request_logging(app)                       # ② 请求日志：排在鉴权中间件之前
+register_tortoise(app, config=settings.TORTOISE_ORM)
+
+if __name__ == '__main__':
+    app.run(host=settings.HOST, port=settings.PORT, workers=settings.WORKERS)
+```
+
+加一组增删改查：
+
+```python
+from kksanic import add_restful_apis
+from models import Article
+
+add_restful_apis(app, Article, base_path='/api/article')
+# GET/POST /api/article，GET/PUT/PATCH/DELETE /api/article/<pk>
+```
+
+路由都注册完再挂文档页与后台站（两者都要扫路由表才知道有哪些页面）：
+
+```python
+from kksanic import add_admin_site, add_swagger_ui
+
+add_swagger_ui(app)           # GET /swagger
+add_admin_site(app, 'admin')  # GET /admin，软删开着时自带回收站接口
+```
+
+到这里跑起来就是能用的：`POST` 返回 200 + 新行，`GET` 返回分页结构
+（`current_page` / `total` / `list`），`title` 超长返回 400 +
+`title长度不能超过50`，`DELETE` 走软删所以之后 `GET /api/article/1` 是 404
+`Article不存在`。
+
+## 三个必踩的坑
+
+### 1. 手写 `Tortoise.init()` 必须传 `_enable_global_fallback=True`
+
+Tortoise 1.1 把连接注册表换成了 contextvar。Sanic 的 `before_server_start`
+和请求处理不在同一个 task，于是请求里取连接直接抛：
+
+```
+RuntimeError: No TortoiseContext is currently active.
+```
+
+两条路的默认值 **不一样**，这是最容易踩的地方：
+
+| 写法 | `_enable_global_fallback` | 结果 |
+|---|---|---|
+| `register_tortoise(app, config=...)`（`tortoise.contrib.sanic`） | 默认 `True`，框架已替你传 | 正常 |
+| 自己 `await Tortoise.init(config=...)` | 默认 **`False`** | 请求里取连接就抛 RuntimeError |
+
+所以只要不走 `register_tortoise`，就得自己补上：
+
+```python
+@app.before_server_start
+async def init_orm(app, _):
+    # Sanic 的 startup 与请求处理不在同一个 task，1.1 起必须开全局兜底
+    await Tortoise.init(config=settings.TORTOISE_ORM, _enable_global_fallback=True)
+```
+
+### 2. `register_exception_handler(app)` 要自己调一次
+
+Sanic 对没有注册处理器的异常一律 500 + 纯文本 `Internal Server Error`。
+库里每一处 `raise ApiException(status_code=400, msg='手机号已注册')`，
+不注册处理器就全变成「服务器错误」，前端既拿不到状态码也拿不到提示。
+
+`add_restful_apis` **刻意不替你注册**：它一注册，你在后面写的
+`@app.exception(ApiException)` 就会在启动期撞成 `ServerError`。
+调用本身是幂等的，重复调不会覆盖你写得更精细的那份。
+
+### 3. `add_request_logging(app)` 必须排在鉴权中间件之前
+
+中间件按注册顺序执行。排在后面时，被 401 挡下的请求拿不到开始时间，
+日志里耗时那一栏只剩一个 `-`（行还是会记）。
+
+## 文档
+
+| 文档 | 讲什么 |
+|---|---|
+| [docs/restful.md](docs/restful.md) | `add_restful_apis` 全参数、方法级配置对象、事务与并发写 |
+| [docs/validator.md](docs/validator.md) | `Validator` 与各类 `Rule` 的判定口径 |
+| [docs/serializer.md](docs/serializer.md) | `ModelSerializer` 的 include / exclude 与嵌套 |
+| [docs/admin.md](docs/admin.md) | `@admin` 装饰器与后台站生成 |
+| [docs/doc.md](docs/doc.md) | `kksanic doc` 导出 Markdown / OpenAPI |
+| [docs/swagger.md](docs/swagger.md) | 运行期把文档页挂成 `/swagger` |
+| [docs/shard.md](docs/shard.md) | 分表两种用法、迁移行为、方言差异、m2m 的限制 |
+| [docs/i18n.md](docs/i18n.md) | `settings.LANG` 与译文表 |
+| [docs/access_log.md](docs/access_log.md) | 请求日志的口径与自定义字段 |

kksanic-0.1.0/README.md

@@ -0,0 +1,175 @@
+# kksanic
+
+基于 Sanic + Tortoise 的小工具箱。写业务不用再拼那套骨架：请求对象、统一响应、
+入参校验、出参序列化、RESTful 增删改查、后台管理站、接口文档、分表分库，
+都在同一个包里，且互相接得上。
+
+| 能力 | 入口 | 一行说明 |
+|---|---|---|
+| 统一响应 | `ApiException` / `get_response` | 状态码走 HTTP，body 只有 `msg` / `data` |
+| 入参校验 | `Validator` + `Rule` 系列 | 按字段类型选规则，写错维度定义期就报 `TypeError` |
+| 出参序列化 | `ModelSerializer` | 模型 → dict，`Meta.include` / `exclude` 收窄字段 |
+| 一键增删改查 | `add_restful_apis` | 6 个接口（含 PATCH）一次注册，分页、软删、事务都带着 |
+| 后台管理站 | `@admin` + `python -m kksanic admin` | 生成单文件管理页，挂成 `/admin` |
+| 接口文档 | `python -m kksanic doc` / `add_swagger_ui` | Markdown + OpenAPI + 自带登录框的 Swagger UI |
+| 分表 | `ShardRule` + `expand()` | 一表一类，两种用法（声明式 / 运行期给表名） |
+| 请求日志 | `add_request_logging` | 一行一请求，慢请求与 5xx 升 WARNING |
+
+## 环境要求
+
+| 依赖 | 版本 | 说明 |
+|---|---|---|
+| Python | **>= 3.10** | `sanic` 25.12 与 `tortoise-orm` 1.1.8 都要求 >= 3.10 |
+| `sanic` | `>=24.12,<26` | 24.12 与 25.12 实测全绿；26 起内部 API 有变动，未验证 |
+| `tortoise-orm` | `>=1.1,<2`（实测 1.1.8） | 连接注册表在 1.1 改成了 contextvar |
+| `python-dateutil` | 必需 | `DateRule` / `DateTimeRule` 的日期解析 |
+| `python-jose` | 必需 | token 编解码 |
+| `tzdata` | **Windows 自动装** | 缺了 `Asia/Shanghai` 会抛 `ZoneInfoNotFoundError` |
+| `redis` | 可选（`kksanic[redis]`） | 缺了就 `ImportError` 兜住，退回进程内缓存 |
+| `aiomysql` / `asyncpg` | 可选（`kksanic[mysql]` / `kksanic[postgres]`） | 用 MySQL / PostgreSQL 时才要 |
+
+Python 3.10 及以上都能装；3.12 / 3.13 也已验证可用。
+
+```bash
+pip install kksanic                 # 装到环境里
+pip install -e .                    # 在本仓库里改代码
+pip install 'kksanic[mysql]'        # 顺带装 MySQL 驱动
+```
+
+没装进环境（只在 `PYTHONPATH` 里）就没有 `kksanic` 这个命令，此时 CLI 要写成
+`python -m kksanic ...`；装过之后两种写法等价。
+
+库被装进 `site-packages` 后无法从自身位置推断 **你的项目根**。探测链覆盖不到的
+部署方式（典型是 `sanic server:app`），在启动代码里显式指定一次，或用环境变量
+`KKSANIC_PROJECT_ROOT`：
+
+```python
+import kksanic
+kksanic.set_project_root('/path/to/your/project')
+```
+
+## 快速开始
+
+```bash
+python -m kksanic init                 # 生成骨架，默认 sqlite
+python -m kksanic init --db postgres   # 或 mysql / postgres
+```
+
+生成 `main.py` / `settings.py` / `models.py` / `serializers.py` / `validators.py`
+与 `migrations/ static/ media/` 目录。同时会写一个 `pyproject.toml`，
+里面只有一段 `[tool.tortoise]`（指向 `settings.TORTOISE_ORM`），
+所以下面的 CLI 不用再传 `-c`：
+
+```bash
+tortoise init            # 生成 migrations/ 包
+tortoise makemigrations
+tortoise migrate
+python main.py           # 默认 0.0.0.0:8000
+```
+
+要显式指定配置就传 `-c`，但 **必须写在子命令前面** —— 写在后面会报
+`tortoise: error: unrecognized arguments: -c`：
+
+```bash
+tortoise -c settings.TORTOISE_ORM makemigrations   # 对
+tortoise makemigrations -c settings.TORTOISE_ORM   # 错
+```
+
+生成的 `main.py` 长这样，**块的顺序是有意义的**，下面三个坑说的就是它：
+
+```python
+from sanic import Sanic
+from tortoise.contrib.sanic import register_tortoise
+
+import settings
+from kksanic import Request, add_request_logging, register_exception_handler
+
+app = Sanic('App', request_class=Request)      # request_class 必须换，否则 Request 用不上
+
+register_exception_handler(app)                # ① 统一异常响应
+add_request_logging(app)                       # ② 请求日志：排在鉴权中间件之前
+register_tortoise(app, config=settings.TORTOISE_ORM)
+
+if __name__ == '__main__':
+    app.run(host=settings.HOST, port=settings.PORT, workers=settings.WORKERS)
+```
+
+加一组增删改查：
+
+```python
+from kksanic import add_restful_apis
+from models import Article
+
+add_restful_apis(app, Article, base_path='/api/article')
+# GET/POST /api/article，GET/PUT/PATCH/DELETE /api/article/<pk>
+```
+
+路由都注册完再挂文档页与后台站（两者都要扫路由表才知道有哪些页面）：
+
+```python
+from kksanic import add_admin_site, add_swagger_ui
+
+add_swagger_ui(app)           # GET /swagger
+add_admin_site(app, 'admin')  # GET /admin，软删开着时自带回收站接口
+```
+
+到这里跑起来就是能用的：`POST` 返回 200 + 新行，`GET` 返回分页结构
+（`current_page` / `total` / `list`），`title` 超长返回 400 +
+`title长度不能超过50`，`DELETE` 走软删所以之后 `GET /api/article/1` 是 404
+`Article不存在`。
+
+## 三个必踩的坑
+
+### 1. 手写 `Tortoise.init()` 必须传 `_enable_global_fallback=True`
+
+Tortoise 1.1 把连接注册表换成了 contextvar。Sanic 的 `before_server_start`
+和请求处理不在同一个 task，于是请求里取连接直接抛：
+
+```
+RuntimeError: No TortoiseContext is currently active.
+```
+
+两条路的默认值 **不一样**，这是最容易踩的地方：
+
+| 写法 | `_enable_global_fallback` | 结果 |
+|---|---|---|
+| `register_tortoise(app, config=...)`（`tortoise.contrib.sanic`） | 默认 `True`，框架已替你传 | 正常 |
+| 自己 `await Tortoise.init(config=...)` | 默认 **`False`** | 请求里取连接就抛 RuntimeError |
+
+所以只要不走 `register_tortoise`，就得自己补上：
+
+```python
+@app.before_server_start
+async def init_orm(app, _):
+    # Sanic 的 startup 与请求处理不在同一个 task，1.1 起必须开全局兜底
+    await Tortoise.init(config=settings.TORTOISE_ORM, _enable_global_fallback=True)
+```
+
+### 2. `register_exception_handler(app)` 要自己调一次
+
+Sanic 对没有注册处理器的异常一律 500 + 纯文本 `Internal Server Error`。
+库里每一处 `raise ApiException(status_code=400, msg='手机号已注册')`，
+不注册处理器就全变成「服务器错误」，前端既拿不到状态码也拿不到提示。
+
+`add_restful_apis` **刻意不替你注册**：它一注册，你在后面写的
+`@app.exception(ApiException)` 就会在启动期撞成 `ServerError`。
+调用本身是幂等的，重复调不会覆盖你写得更精细的那份。
+
+### 3. `add_request_logging(app)` 必须排在鉴权中间件之前
+
+中间件按注册顺序执行。排在后面时，被 401 挡下的请求拿不到开始时间，
+日志里耗时那一栏只剩一个 `-`（行还是会记）。
+
+## 文档
+
+| 文档 | 讲什么 |
+|---|---|
+| [docs/restful.md](docs/restful.md) | `add_restful_apis` 全参数、方法级配置对象、事务与并发写 |
+| [docs/validator.md](docs/validator.md) | `Validator` 与各类 `Rule` 的判定口径 |
+| [docs/serializer.md](docs/serializer.md) | `ModelSerializer` 的 include / exclude 与嵌套 |
+| [docs/admin.md](docs/admin.md) | `@admin` 装饰器与后台站生成 |
+| [docs/doc.md](docs/doc.md) | `kksanic doc` 导出 Markdown / OpenAPI |
+| [docs/swagger.md](docs/swagger.md) | 运行期把文档页挂成 `/swagger` |
+| [docs/shard.md](docs/shard.md) | 分表两种用法、迁移行为、方言差异、m2m 的限制 |
+| [docs/i18n.md](docs/i18n.md) | `settings.LANG` 与译文表 |
+| [docs/access_log.md](docs/access_log.md) | 请求日志的口径与自定义字段 |