isanic-e 0.1.0__tar.gz

isanic_e-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: isanic-e
+Version: 0.1.0
+Summary: 基于 Sanic 的类型化表单验证后端脚手架
+Author: iSanic-e contributors
+License-Expression: MIT
+Keywords: sanic,scaffold,backend,pydantic,api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: sanic<26,>=25.12
+Requires-Dist: pydantic<3,>=2.12
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.3; extra == "dev"
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: sanic-testing<26,>=24; extra == "dev"
+
+# iSanic-e
+
+基于 Sanic 的类型化表单验证后端脚手架。
+
+安装后可以通过 `isanic init` 快速生成一个完整可运行的 Sanic 项目，内置：
+
+- 控制器自动路由注册
+- Pydantic v2 表单验证
+- 统一成功和错误响应
+- 全局异常处理
+- 示例控制器、表单模型和测试
+
+## 安装
+
+```bash
+python -m pip install isanic-e
+```
+
+## 初始化项目
+
+```bash
+isanic init demo
+cd demo
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m app.main
+```
+
+## 控制器示例
+
+```python
+from app.api.schemas.login import LoginForm
+from isanic import ApiController
+
+
+class Login(ApiController):
+    async def post_submit(self, form: LoginForm) -> dict[str, str]:
+        return {"token": f"token-for-{form.username}"}
+```
+
+上面的代码会自动注册为：
+
+```text
+POST /login/submit
+```
+
+## 业务异常
+
+```python
+from isanic import AppError
+
+raise AppError("用户已被禁用", code="USER_DISABLED", status_code=403)
+```
+
+返回：
+
+```json
+{
+  "code": "USER_DISABLED",
+  "message": "用户已被禁用",
+  "data": null
+}
+```

isanic_e-0.1.0/README.md

@@ -0,0 +1,63 @@
+# iSanic-e
+
+基于 Sanic 的类型化表单验证后端脚手架。
+
+安装后可以通过 `isanic init` 快速生成一个完整可运行的 Sanic 项目，内置：
+
+- 控制器自动路由注册
+- Pydantic v2 表单验证
+- 统一成功和错误响应
+- 全局异常处理
+- 示例控制器、表单模型和测试
+
+## 安装
+
+```bash
+python -m pip install isanic-e
+```
+
+## 初始化项目
+
+```bash
+isanic init demo
+cd demo
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m app.main
+```
+
+## 控制器示例
+
+```python
+from app.api.schemas.login import LoginForm
+from isanic import ApiController
+
+
+class Login(ApiController):
+    async def post_submit(self, form: LoginForm) -> dict[str, str]:
+        return {"token": f"token-for-{form.username}"}
+```
+
+上面的代码会自动注册为：
+
+```text
+POST /login/submit
+```
+
+## 业务异常
+
+```python
+from isanic import AppError
+
+raise AppError("用户已被禁用", code="USER_DISABLED", status_code=403)
+```
+
+返回：
+
+```json
+{
+  "code": "USER_DISABLED",
+  "message": "用户已被禁用",
+  "data": null
+}
+```

isanic_e-0.1.0/isanic/__init__.py

@@ -0,0 +1,19 @@
+"""iSanic-e 框架公共接口。"""
+
+from isanic.controller import ApiController
+from isanic.exceptions import AppError, ValidationAppError
+from isanic.handlers import setup_exception_handlers
+from isanic.response import ApiResponse, fail, success, wrap_response
+from isanic.routing import register_controllers
+
+__all__ = [
+    "ApiController",
+    "ApiResponse",
+    "AppError",
+    "ValidationAppError",
+    "fail",
+    "register_controllers",
+    "setup_exception_handlers",
+    "success",
+    "wrap_response",
+]

isanic_e-0.1.0/isanic/cli.py

@@ -0,0 +1,103 @@
+import argparse
+import re
+import shutil
+import sys
+from pathlib import Path
+
+TEMPLATE_ROOT = Path(__file__).parent / "templates" / "full"
+PROJECT_NAME_PATTERN = re.compile(r"^[A-Za-z][A-Za-z0-9_-]*$")
+
+
+def main(argv: list[str] | None = None) -> int:
+    """命令行入口。"""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "init":
+        return init_project(args.project_name)
+
+    parser.print_help()
+    return 0
+
+
+def init_project(project_name: str, base_dir: Path | None = None) -> int:
+    """初始化完整示例项目。"""
+    if not PROJECT_NAME_PATTERN.fullmatch(project_name):
+        print(
+            "项目名只能包含字母、数字、短横线和下划线，并且必须以字母开头。",
+            file=sys.stderr,
+        )
+        return 2
+
+    root_dir = base_dir or Path.cwd()
+    target_dir = root_dir / project_name
+    if target_dir.exists() and any(target_dir.iterdir()):
+        print(f"目标目录已存在且非空：{target_dir}", file=sys.stderr)
+        return 1
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+    _copy_template(TEMPLATE_ROOT, target_dir, project_name)
+    _print_success(project_name)
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """构建命令行参数解析器。"""
+    parser = argparse.ArgumentParser(
+        prog="isanic",
+        description="iSanic-e 项目脚手架",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    init_parser = subparsers.add_parser("init", help="初始化一个 Sanic 项目")
+    init_parser.add_argument("project_name", help="要创建的项目目录名")
+    return parser
+
+
+def _copy_template(source_dir: Path, target_dir: Path, project_name: str) -> None:
+    """递归复制模板文件到目标目录。"""
+    for source_path in source_dir.rglob("*"):
+        if _should_skip_template_path(source_path):
+            continue
+
+        relative_path = source_path.relative_to(source_dir)
+        target_path = target_dir / _render_text(str(relative_path), project_name)
+
+        if source_path.is_dir():
+            target_path.mkdir(parents=True, exist_ok=True)
+            continue
+
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+        text = source_path.read_text(encoding="utf-8")
+        target_path.write_text(_render_text(text, project_name), encoding="utf-8")
+
+    gitignore_template = target_dir / "_gitignore"
+    if gitignore_template.exists():
+        shutil.move(str(gitignore_template), str(target_dir / ".gitignore"))
+
+
+def _should_skip_template_path(path: Path) -> bool:
+    """跳过安装后自动生成的缓存文件。"""
+    if "__pycache__" in path.parts:
+        return True
+    return path.suffix in {".pyc", ".pyo"}
+
+
+def _render_text(value: str, project_name: str) -> str:
+    """替换模板中的占位符。"""
+    return value.replace("{{ project_name }}", project_name)
+
+
+def _print_success(project_name: str) -> None:
+    """输出初始化成功提示。"""
+    print(f"项目已创建：{project_name}")
+    print("")
+    print("下一步：")
+    print(f"  cd {project_name}")
+    print('  python -m pip install -e ".[dev]"')
+    print("  python -m pytest")
+    print("  python -m app.main")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

isanic_e-0.1.0/isanic/controller.py

@@ -0,0 +1,13 @@
+from typing import ClassVar
+
+from sanic import Request
+
+
+class ApiController:
+    """控制器基类。"""
+
+    prefix: ClassVar[str | None] = None
+    request: Request
+
+    def __init__(self, request: Request) -> None:
+        self.request = request

isanic_e-0.1.0/isanic/exceptions.py

@@ -0,0 +1,31 @@
+from typing import Any
+
+
+class AppError(Exception):
+    """业务异常基类。"""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: int | str = "APP_ERROR",
+        status_code: int = 400,
+        data: Any = None,
+    ) -> None:
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+        self.data = data
+        super().__init__(message)
+
+
+class ValidationAppError(AppError):
+    """请求参数校验失败。"""
+
+    def __init__(self, errors: list[dict[str, Any]]) -> None:
+        super().__init__(
+            "请求参数校验失败",
+            code="VALIDATION_ERROR",
+            status_code=422,
+            data=errors,
+        )

isanic_e-0.1.0/isanic/handlers.py

@@ -0,0 +1,39 @@
+from sanic import Sanic
+from sanic.exceptions import MethodNotAllowed, NotFound, SanicException
+
+from isanic.exceptions import AppError
+from isanic.response import fail
+
+
+def setup_exception_handlers(app: Sanic) -> None:
+    """注册全局异常处理器。"""
+
+    @app.exception(AppError)
+    async def handle_app_error(request, exception: AppError):
+        return fail(
+            exception.code,
+            exception.message,
+            exception.data,
+            status=exception.status_code,
+        )
+
+    @app.exception(NotFound)
+    async def handle_not_found(request, exception: NotFound):
+        return fail("NOT_FOUND", "接口不存在", status=404)
+
+    @app.exception(MethodNotAllowed)
+    async def handle_method_not_allowed(request, exception: MethodNotAllowed):
+        return fail("METHOD_NOT_ALLOWED", "请求方法不允许", status=405)
+
+    @app.exception(Exception)
+    async def handle_unknown_error(request, exception: Exception):
+        if isinstance(exception, SanicException):
+            status_code = exception.status_code or 500
+            return fail(
+                "HTTP_ERROR",
+                str(exception) or "请求处理失败",
+                status=status_code,
+            )
+
+        request.app.ctx.logger.exception("未捕获异常", exc_info=exception)
+        return fail("INTERNAL_SERVER_ERROR", "服务器内部错误", status=500)

isanic_e-0.1.0/isanic/response.py

@@ -0,0 +1,67 @@
+from dataclasses import asdict, is_dataclass
+from typing import Any, Generic, TypeAlias, TypeVar
+
+from pydantic import BaseModel
+from sanic.response import HTTPResponse, json
+
+T = TypeVar("T")
+
+JsonValue: TypeAlias = (
+    dict[str, Any] | list[Any] | str | int | float | bool | None
+)
+
+
+class ApiResponse(Generic[T]):
+    """统一响应结构的类型标记。"""
+
+    code: int | str
+    message: str
+    data: T | None
+
+
+def success(data: Any = None, message: str = "success", code: int = 0) -> HTTPResponse:
+    """返回成功响应。"""
+    return json(
+        {
+            "code": code,
+            "message": message,
+            "data": _to_jsonable(data),
+        }
+    )
+
+
+def fail(
+    code: int | str,
+    message: str,
+    data: Any = None,
+    status: int = 400,
+) -> HTTPResponse:
+    """返回失败响应。"""
+    return json(
+        {
+            "code": code,
+            "message": message,
+            "data": _to_jsonable(data),
+        },
+        status=status,
+    )
+
+
+def wrap_response(value: Any) -> HTTPResponse:
+    """把业务返回值包装为统一响应。"""
+    if isinstance(value, HTTPResponse):
+        return value
+    return success(value)
+
+
+def _to_jsonable(value: Any) -> Any:
+    """转换常见 Python 对象为可 JSON 序列化的数据。"""
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json")
+    if is_dataclass(value) and not isinstance(value, type):
+        return asdict(value)
+    if isinstance(value, dict):
+        return {key: _to_jsonable(item) for key, item in value.items()}
+    if isinstance(value, list | tuple | set):
+        return [_to_jsonable(item) for item in value]
+    return value

isanic_e-0.1.0/isanic/routing.py

@@ -0,0 +1,141 @@
+import inspect
+import pkgutil
+import re
+from collections.abc import Awaitable, Callable
+from importlib import import_module
+from types import ModuleType
+from typing import Any, TypeAlias
+
+from sanic import Request, Sanic
+from sanic.response import HTTPResponse
+
+from isanic.controller import ApiController
+from isanic.response import wrap_response
+from isanic.validation import build_form_model, resolve_form_binding
+
+ControllerClass: TypeAlias = type[ApiController]
+HandlerResult: TypeAlias = HTTPResponse | dict[str, Any] | list[Any] | str | int | float | bool | None
+ControllerMethod: TypeAlias = Callable[..., Awaitable[HandlerResult]]
+
+HTTP_METHODS = {"get", "post", "put", "patch", "delete"}
+CONTROLLER_SUFFIX = "Controller"
+
+
+def register_controllers(app: Sanic, package: str) -> None:
+    """扫描指定包并注册所有控制器路由。"""
+    root_module = import_module(package)
+    for module in _walk_modules(root_module):
+        for controller_class in _iter_controller_classes(module):
+            _register_controller(app, controller_class)
+
+
+def _walk_modules(root_module: ModuleType) -> list[ModuleType]:
+    """递归加载包下所有模块。"""
+    modules = [root_module]
+    if not hasattr(root_module, "__path__"):
+        return modules
+
+    for module_info in pkgutil.walk_packages(
+        root_module.__path__,
+        prefix=f"{root_module.__name__}.",
+    ):
+        modules.append(import_module(module_info.name))
+    return modules
+
+
+def _iter_controller_classes(module: ModuleType) -> list[ControllerClass]:
+    """查找模块中定义的控制器类。"""
+    controllers: list[ControllerClass] = []
+    for _, item in inspect.getmembers(module, inspect.isclass):
+        if item is ApiController:
+            continue
+        if item.__module__ != module.__name__:
+            continue
+        if issubclass(item, ApiController):
+            controllers.append(item)
+    return controllers
+
+
+def _register_controller(app: Sanic, controller_class: ControllerClass) -> None:
+    """注册单个控制器上的所有 HTTP 方法。"""
+    controller_prefix = _controller_prefix(controller_class)
+    for route in _iter_routes(controller_class):
+        uri = f"/{controller_prefix}/{route.path}".rstrip("/")
+        app.add_route(
+            _build_route_handler(controller_class, route.method_name),
+            uri,
+            methods=[route.http_method],
+            name=f"{controller_class.__name__}.{route.method_name}",
+        )
+
+
+class RouteInfo:
+    """控制器方法对应的路由信息。"""
+
+    def __init__(self, http_method: str, method_name: str, path: str) -> None:
+        self.http_method = http_method
+        self.method_name = method_name
+        self.path = path
+
+
+def _iter_routes(controller_class: ControllerClass) -> list[RouteInfo]:
+    """解析控制器类中的路由方法。"""
+    routes: list[RouteInfo] = []
+    for name, member in inspect.getmembers(controller_class, inspect.isfunction):
+        http_method, path = _parse_route_method(name)
+        if http_method is None or path is None:
+            continue
+        routes.append(RouteInfo(http_method, name, path))
+    return routes
+
+
+def _parse_route_method(name: str) -> tuple[str | None, str | None]:
+    """把方法名解析为 HTTP 方法和路径。"""
+    parts = name.split("_", 1)
+    method = parts[0].lower()
+    if method not in HTTP_METHODS:
+        return None, None
+
+    action = parts[1] if len(parts) > 1 else "index"
+    return method.upper(), _to_kebab_case(action)
+
+
+def _build_route_handler(
+    controller_class: ControllerClass,
+    method_name: str,
+) -> Callable[[Request], Awaitable[HTTPResponse]]:
+    """创建 Sanic 可识别的路由处理函数。"""
+    controller_method = getattr(controller_class, method_name)
+    form_binding = resolve_form_binding(controller_method)
+
+    async def route_handler(request: Request) -> HTTPResponse:
+        controller = controller_class(request)
+        method = getattr(controller, method_name)
+        if form_binding is None:
+            result = await method()
+        else:
+            form = build_form_model(request, form_binding)
+            result = await method(form)
+        return wrap_response(result)
+
+    route_handler.__name__ = f"{controller_class.__name__}_{method_name}"
+    return route_handler
+
+
+def _controller_prefix(controller_class: ControllerClass) -> str:
+    """生成控制器路径前缀。"""
+    if controller_class.prefix:
+        return controller_class.prefix.strip("/")
+
+    name = controller_class.__name__
+    if name.endswith(CONTROLLER_SUFFIX):
+        name = name[: -len(CONTROLLER_SUFFIX)]
+    return _to_kebab_case(name)
+
+
+def _to_kebab_case(value: str) -> str:
+    """把类名或方法名片段转换为短横线命名。"""
+    value = value.replace("_", "-")
+    value = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "-", value)
+    value = re.sub(r"(?<=[A-Z])(?=[A-Z][a-z])", "-", value)
+    return value.lower()

isanic_e-0.1.0/isanic/templates/full/README.md

@@ -0,0 +1,32 @@
+# {{ project_name }}
+
+这是通过 `isanic init` 生成的 Sanic 后端项目。
+
+## 快速开始
+
+安装依赖：
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+运行测试：
+
+```bash
+python -m pytest
+```
+
+启动服务：
+
+```bash
+python -m app.main
+```
+
+示例接口：
+
+```text
+GET  /hello/test
+POST /login/submit
+GET  /users/list?page=1&size=10
+GET  /users/raw
+```

isanic_e-0.1.0/isanic/templates/full/_gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+*.egg-info/

isanic_e-0.1.0/isanic/templates/full/app/__init__.py

@@ -0,0 +1 @@
+"""应用包。"""

isanic_e-0.1.0/isanic/templates/full/app/api/__init__.py

@@ -0,0 +1 @@
+"""业务接口包。"""

isanic_e-0.1.0/isanic/templates/full/app/api/controllers/__init__.py

@@ -0,0 +1 @@
+"""控制器包。"""

isanic_e-0.1.0/isanic/templates/full/app/api/controllers/hello.py

@@ -0,0 +1,9 @@
+from isanic import ApiController
+
+
+class Hello(ApiController):
+    """示例控制器。"""
+
+    async def get_test(self) -> dict[str, str]:
+        """测试接口。"""
+        return {"message": "hello"}

isanic_e-0.1.0/isanic/templates/full/app/api/controllers/login.py

@@ -0,0 +1,28 @@
+from sanic.response import text
+
+from app.api.schemas.login import LoginForm, UserQueryForm
+from isanic import ApiController, AppError
+
+
+class Login(ApiController):
+    """登录控制器。"""
+
+    async def post_submit(self, form: LoginForm) -> dict[str, str]:
+        """提交登录表单。"""
+        if form.username == "disabled":
+            raise AppError("用户已被禁用", code="USER_DISABLED", status_code=403)
+        return {"token": f"token-for-{form.username}"}
+
+
+class UserProfile(ApiController):
+    """用户资料控制器。"""
+
+    prefix = "users"
+
+    async def get_list(self, form: UserQueryForm) -> dict[str, int]:
+        """查询用户列表。"""
+        return {"page": form.page, "size": form.size}
+
+    async def get_raw(self):
+        """直接返回 Sanic 原生响应。"""
+        return text("raw response")

isanic_e-0.1.0/isanic/templates/full/app/api/schemas/__init__.py

@@ -0,0 +1 @@
+"""请求和响应模型包。"""

isanic_e-0.1.0/isanic/templates/full/app/api/schemas/login.py

@@ -0,0 +1,15 @@
+from pydantic import BaseModel, Field
+
+
+class LoginForm(BaseModel):
+    """登录表单。"""
+
+    username: str = Field(min_length=3, max_length=32)
+    password: str = Field(min_length=6, max_length=128)
+
+
+class UserQueryForm(BaseModel):
+    """用户列表查询表单。"""
+
+    page: int = Field(default=1, ge=1)
+    size: int = Field(default=10, ge=1, le=100)

isanic_e-0.1.0/isanic/templates/full/app/common/__init__.py

@@ -0,0 +1 @@
+"""通用工具包。"""

isanic_e-0.1.0/isanic/templates/full/app/core/__init__.py

@@ -0,0 +1 @@
+"""核心配置和应用工厂包。"""