cloudoll 4.0.0__tar.gz → 4.2.1__tar.gz

cloudoll-4.2.1/AGENTS.md

@@ -0,0 +1,5 @@
+# Cloudoll library maintenance
+
+This repository implements Cloudoll; it is not a generated application. Read `AI.md` before changing AI assets. Public API behavior must be verified against source and tests, not inferred from other frameworks. The application-development skill is `cloudoll/ai/skills/cloudoll/SKILL.md`; read it when creating application examples.
+
+Official documentation is maintained in the sibling `cloudoll-py-docs` repository, under `src/views`. Bundled copies in `cloudoll/ai/docs` are generated: edit the original docs, then run the sync command in `AI.md`. Update docs and tests together when changing public behavior. Preserve Python 3.9 compatibility.

cloudoll-4.2.1/AI.md

@@ -0,0 +1,32 @@
+# AI-assisted Cloudoll development
+
+For application developers, `cloudoll create PROJECT` installs an `AGENTS.md` entry and `.agents/skills/cloudoll/SKILL.md`. Existing projects can run `python -m cloudoll.cli ai init .`. Existing user instructions are preserved; a different/customized skill is never silently replaced.
+
+No MCP server is required:
+
+```sh
+python -m cloudoll.cli ai list
+python -m cloudoll.cli ai read structure
+python -m cloudoll.cli ai read database
+python -m cloudoll.cli ai search Body
+```
+
+Use the project's Python environment. Ask your coding agent to read the project `AGENTS.md` and Cloudoll skill before coding. Tools that do not discover these files automatically can be given the paths explicitly. These instructions improve discoverability; they cannot guarantee that every model obeys them.
+
+## Maintaining the assets
+
+`cloudoll/ai/docs` contains verbatim snapshots of the official site's Markdown, not hand-maintained API summaries. `manifest.json` records the library version, source path, public URL, and SHA-256 for every topic. Relative site links in these snapshots refer to https://cloudoll.chuchur.com.
+
+From the library root, with the documentation repository available:
+
+```sh
+python scripts/sync_ai_docs.py --docs-root ../cloudoll-py-docs
+python scripts/sync_ai_docs.py --docs-root ../cloudoll-py-docs --check
+python -m pytest tests/test_ai.py
+python -m build
+python tests/check_wheel.py dist/cloudoll-VERSION-py3-none-any.whl
+```
+
+The sync also generates the site's `public/llms.txt` and `public/llms-full.txt`. Commit both repositories' changes. These files are discovery aids, not a replacement for version-matched local docs. When upgrading Cloudoll in an existing application, review its installed skill against the packaged skill and merge intentional changes; initialization refuses a differing skill to avoid overwriting custom instructions.
+
+Before release, run the cross-repository `--check` command. Tests validate the packaged snapshot integrity and version; they cannot detect uncommitted changes in an unavailable documentation repository.

{cloudoll-4.0.0 → cloudoll-4.2.1}/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 4.2.1
+
+- Correct the AI initialization regression test to compare the original bytes
+  rather than assume LF newlines on Windows. Keep preservation and idempotence
+  assertions enabled on every platform.
+- Normalize the generated full documentation's trailing newline.
+- Include all 4.2.0 features. The 4.2.0 tag was blocked by Windows CI and was
+  not published to PyPI; 4.2.1 is the replacement release.
+
+## 4.2.0
+
+Backward-compatible AI-assisted development release. Python 3.9+ remains supported.
+
+- Add offline `cloudoll ai list`, `read`, and `search` commands for bundled official
+  documentation, with source URLs, version metadata and content integrity checks.
+- Add `cloudoll ai init` for existing projects. New scaffolds automatically include
+  an AGENTS.md entry and a project-local Cloudoll skill covering documented project
+  structure, validation, ORM, resource lifecycle, security and verification.
+- Preserve existing project instructions and refuse to overwrite customized skills
+  or write through symbolic links. Initialization is repeatable.
+- Add documentation synchronization tooling and website LLM discovery assets.
+  Test both instruction initialization and AI resources in the built wheel.
+
+## 4.1.0
+
+Backward-compatible feature release. Pydantic 2 (`>=2.0,<3`) is now a core
+runtime dependency. Existing handlers and explicit ORM engine bindings remain
+supported. Python 3.9+ remains supported by the CI matrix.
+
+Publication date is recorded by the release tag/PyPI; preparing these files does
+not publish the package.
+
+- Correct lifecycle callback and JWT payload type declarations for strict
+  checking with current dependency annotations.
+- Include HTTP method and actual request path in exception logs; emit 4xx access
+  logs at WARNING and 5xx at ERROR so failed requests remain visible above INFO.
+
+- Add Pydantic 2 request validation with typed `Body`, `Query`, `Form`, and
+  `Path` bindings, repeated collection parameters and structured HTTP 400 errors.
+  Preserve legacy request and streaming multipart handlers.
+
+- Add application-local named ORM datasources via `orm.default` and model
+  `__datasource__`, independent class-level queries, `Model.query()` and
+  `Model.transaction()`. Reuse existing task-owned engine transactions.
+- Add `datasource_context` for scoped standalone/test engine bindings. Keep
+  explicit `.use(engine)`, offline SQL compilation and bound records compatible.
+
 ## 4.0.0
 
 Release notes for 4.0.0. Publication date is recorded by the release tag/PyPI;

{cloudoll-4.0.0 → cloudoll-4.2.1}/MANIFEST.in

@@ -1,4 +1,6 @@
 recursive-include tests *.py
 include README.zh-CN.md
+include AI.md AGENTS.md
+include scripts/sync_ai_docs.py
 include CHANGELOG.md SECURITY.md
 recursive-include docs *.md

{cloudoll-4.0.0/cloudoll.egg-info → cloudoll-4.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudoll
-Version: 4.0.0
+Version: 4.2.1
 Summary: Assist in quickly creating distributable microservices based on aiohttp, with a focus on simplicity and ease of use.
 Author-email: Qiu <smallerqiu@gmail.com>
 License-Expression: MIT
@@ -17,6 +17,7 @@ License-File: LICENSE
 Requires-Dist: watchfiles
 Requires-Dist: colorlog
 Requires-Dist: aiohttp
+Requires-Dist: pydantic<3,>=2.0
 Requires-Dist: jinja2
 Requires-Dist: pyjwt
 Requires-Dist: aiohttp_session[secure]
@@ -53,16 +54,25 @@ Dynamic: license-file
 
 English | [简体中文](README.zh-CN.md)
 
-Cloudoll 4.0.0 is an aiohttp-based Python library for routing, middleware,
+Cloudoll 4.2.1 is an aiohttp-based Python library for routing, middleware,
 templates, sessions, JWT, database access and application scaffolding.
 
+## AI-assisted development
+
+New scaffolds include `AGENTS.md` and a project-local Cloudoll skill. For existing
+projects, run `cloudoll ai init .` in the project's Python environment. Query the
+bundled official documentation offline with `cloudoll ai list`,
+`cloudoll ai read database`, or `cloudoll ai search Body`. No MCP is required.
+See [AI.md](AI.md) for version matching and maintenance. If your installed release
+does not have `cloudoll ai --help`, consult its matching README and source first.
+
 ## Install
 
 Python 3.9+ is required. Install only the optional drivers you use:
 
 ```sh
-python -m pip install 'cloudoll==4.0.0'
-python -m pip install 'cloudoll[mysql,postgres,cache]==4.0.0'
+python -m pip install 'cloudoll==4.2.1'
+python -m pip install 'cloudoll[mysql,postgres,cache]==4.2.1'
 ```
 
 The AWS extra requires Python 3.10+. Aurora remains untested; see
@@ -77,7 +87,7 @@ python -m pip install -r requirements.txt
 cloudoll start -n myapp
 ```
 
-The generated project targets 4.0.0 and receives a random JWT secret. Controllers
+The generated project targets 4.2.1 and receives a random JWT secret. Controllers
 and authentication middleware are examples: replace demo credentials and supply
 your own authorization and upload policies before deployment.
 
@@ -162,8 +172,8 @@ python -m ruff check cloudoll tests
 python -m mypy
 python -m pytest -q -m 'not integration' -k 'not aws'
 python -m build
-python tests/check_wheel.py dist/cloudoll-4.0.0-py3-none-any.whl
-python tests/check_release.py dist/cloudoll-4.0.0-py3-none-any.whl
+python tests/check_wheel.py dist/cloudoll-4.2.1-py3-none-any.whl
+python tests/check_release.py dist/cloudoll-4.2.1-py3-none-any.whl
 ```
 
 Native integration tests require explicitly configured disposable databases.
@@ -178,3 +188,64 @@ from ordinary CI. Passing CI is not a substitute for workload-specific testing.
 - [Compatibility and release policy](docs/maintenance.md)
 - [Security reporting](SECURITY.md)
 - [MIT license](LICENSE)
+
+## Named ORM datasources
+
+Configure `orm: {default: blog}` with a matching `database.blog` connection.
+Models may set `__datasource__ = "analytics"` to select another named connection.
+Within an active application, `await User.select().where(User.id > 0).all()`
+creates a fresh query using that engine. `User.query()` retains `Query[User]`
+typing. Existing `User.use(engine)` and offline `User.use(None)` are unchanged.
+
+`async with User.transaction():` delegates to the engine's task-owned transaction
+and nested-savepoint implementation. Queries using the same engine participate
+in that transaction; separate datasources are not a distributed transaction.
+Loaded records keep their original engine. Each JOIN executes on its Query's
+engine, not across independently bound model datasources.
+
+Scripts/tests can use `with datasource_context({"blog": engine}, default="blog"):`
+(imported from `cloudoll.orm`). This scopes existing engines without managing
+engine lifetime. Missing contexts/defaults/uninitialized engines fail explicitly.
+See the [configuration and examples](README.zh-CN.md#默认数据源与模型绑定).
+
+## Request validation
+
+Pydantic 2 is a core dependency. Define module-level input models and explicitly
+bind sources with `Body[T]`, `Query[T]`, `Form[T]`, or `Path[T]`. Handlers receive
+validated model instances; the aliases also preserve editor/type-checker support.
+
+```python
+from pydantic import BaseModel, ConfigDict, Field
+from cloudoll.web import Query
+
+class ArticleQuery(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    page: int = Field(default=1, ge=1)
+    size: int = Field(default=20, ge=1, le=100)
+    tags: list[str] = Field(default_factory=list)
+
+@app.get("/articles")
+async def list_articles(query: Query[ArticleQuery]):
+    return query.model_dump()
+```
+
+`?page=2&tags=python&tags=life` produces an integer and a list. Repeated
+Query/Form values are retained for list/set/tuple fields (including string aliases);
+scalar fields use the first value. Comma-separated values and bracket-style nested
+query syntax are not expanded. Use JSON Body for nested objects.
+
+Combine Query and Path with one Body **or** Form, optionally preceded by the raw
+request parameter. Body accepts JSON/`+json`; Form accepts URL-encoded and multipart
+forms. Validation happens before the handler and always returns JSON HTTP 400 with
+`error.status`, `message`, `request_id`, and `details`. Each detail contains `source`,
+`loc` (including nested field/index locations), `code`, and `message`. Raw inputs
+and exception context are omitted; custom validator errors use `Invalid value`.
+Middleware can catch the exported `RequestValidationError` to customize this response.
+Malformed JSON (400) and unsupported media types (415) retain the existing
+`server.json_errors` behavior.
+
+Legacy handlers and streaming `(request, field)` uploads remain supported. Typed
+handlers only parse declared sources. Unknown fields follow model configuration
+(Pydantic defaults to ignoring them); use `extra="forbid"` for strict write inputs.
+Separate create/update models and use `model_dump(exclude_unset=True)` for partial
+updates. Validation does not replace authorization or database constraints.

{cloudoll-4.0.0 → cloudoll-4.2.1}/README.md

@@ -2,16 +2,25 @@
 
 English | [简体中文](README.zh-CN.md)
 
-Cloudoll 4.0.0 is an aiohttp-based Python library for routing, middleware,
+Cloudoll 4.2.1 is an aiohttp-based Python library for routing, middleware,
 templates, sessions, JWT, database access and application scaffolding.
 
+## AI-assisted development
+
+New scaffolds include `AGENTS.md` and a project-local Cloudoll skill. For existing
+projects, run `cloudoll ai init .` in the project's Python environment. Query the
+bundled official documentation offline with `cloudoll ai list`,
+`cloudoll ai read database`, or `cloudoll ai search Body`. No MCP is required.
+See [AI.md](AI.md) for version matching and maintenance. If your installed release
+does not have `cloudoll ai --help`, consult its matching README and source first.
+
 ## Install
 
 Python 3.9+ is required. Install only the optional drivers you use:
 
 ```sh
-python -m pip install 'cloudoll==4.0.0'
-python -m pip install 'cloudoll[mysql,postgres,cache]==4.0.0'
+python -m pip install 'cloudoll==4.2.1'
+python -m pip install 'cloudoll[mysql,postgres,cache]==4.2.1'
 ```
 
 The AWS extra requires Python 3.10+. Aurora remains untested; see
@@ -26,7 +35,7 @@ python -m pip install -r requirements.txt
 cloudoll start -n myapp
 ```
 
-The generated project targets 4.0.0 and receives a random JWT secret. Controllers
+The generated project targets 4.2.1 and receives a random JWT secret. Controllers
 and authentication middleware are examples: replace demo credentials and supply
 your own authorization and upload policies before deployment.
 
@@ -111,8 +120,8 @@ python -m ruff check cloudoll tests
 python -m mypy
 python -m pytest -q -m 'not integration' -k 'not aws'
 python -m build
-python tests/check_wheel.py dist/cloudoll-4.0.0-py3-none-any.whl
-python tests/check_release.py dist/cloudoll-4.0.0-py3-none-any.whl
+python tests/check_wheel.py dist/cloudoll-4.2.1-py3-none-any.whl
+python tests/check_release.py dist/cloudoll-4.2.1-py3-none-any.whl
 ```
 
 Native integration tests require explicitly configured disposable databases.
@@ -127,3 +136,64 @@ from ordinary CI. Passing CI is not a substitute for workload-specific testing.
 - [Compatibility and release policy](docs/maintenance.md)
 - [Security reporting](SECURITY.md)
 - [MIT license](LICENSE)
+
+## Named ORM datasources
+
+Configure `orm: {default: blog}` with a matching `database.blog` connection.
+Models may set `__datasource__ = "analytics"` to select another named connection.
+Within an active application, `await User.select().where(User.id > 0).all()`
+creates a fresh query using that engine. `User.query()` retains `Query[User]`
+typing. Existing `User.use(engine)` and offline `User.use(None)` are unchanged.
+
+`async with User.transaction():` delegates to the engine's task-owned transaction
+and nested-savepoint implementation. Queries using the same engine participate
+in that transaction; separate datasources are not a distributed transaction.
+Loaded records keep their original engine. Each JOIN executes on its Query's
+engine, not across independently bound model datasources.
+
+Scripts/tests can use `with datasource_context({"blog": engine}, default="blog"):`
+(imported from `cloudoll.orm`). This scopes existing engines without managing
+engine lifetime. Missing contexts/defaults/uninitialized engines fail explicitly.
+See the [configuration and examples](README.zh-CN.md#默认数据源与模型绑定).
+
+## Request validation
+
+Pydantic 2 is a core dependency. Define module-level input models and explicitly
+bind sources with `Body[T]`, `Query[T]`, `Form[T]`, or `Path[T]`. Handlers receive
+validated model instances; the aliases also preserve editor/type-checker support.
+
+```python
+from pydantic import BaseModel, ConfigDict, Field
+from cloudoll.web import Query
+
+class ArticleQuery(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    page: int = Field(default=1, ge=1)
+    size: int = Field(default=20, ge=1, le=100)
+    tags: list[str] = Field(default_factory=list)
+
+@app.get("/articles")
+async def list_articles(query: Query[ArticleQuery]):
+    return query.model_dump()
+```
+
+`?page=2&tags=python&tags=life` produces an integer and a list. Repeated
+Query/Form values are retained for list/set/tuple fields (including string aliases);
+scalar fields use the first value. Comma-separated values and bracket-style nested
+query syntax are not expanded. Use JSON Body for nested objects.
+
+Combine Query and Path with one Body **or** Form, optionally preceded by the raw
+request parameter. Body accepts JSON/`+json`; Form accepts URL-encoded and multipart
+forms. Validation happens before the handler and always returns JSON HTTP 400 with
+`error.status`, `message`, `request_id`, and `details`. Each detail contains `source`,
+`loc` (including nested field/index locations), `code`, and `message`. Raw inputs
+and exception context are omitted; custom validator errors use `Invalid value`.
+Middleware can catch the exported `RequestValidationError` to customize this response.
+Malformed JSON (400) and unsupported media types (415) retain the existing
+`server.json_errors` behavior.
+
+Legacy handlers and streaming `(request, field)` uploads remain supported. Typed
+handlers only parse declared sources. Unknown fields follow model configuration
+(Pydantic defaults to ignoring them); use `extra="forbid"` for strict write inputs.
+Separate create/update models and use `model_dump(exclude_unset=True)` for partial
+updates. Validation does not replace authorization or database constraints.

{cloudoll-4.0.0 → cloudoll-4.2.1}/README.zh-CN.md

@@ -6,7 +6,16 @@
 
 Cloudoll 是一个基于 aiohttp 的 Python Web 开发库，提供路由自动注册、中间件、模板渲染、会话管理、JWT、数据库访问及命令行脚手架，帮助快速构建 Web 应用和微服务。
 
-本文适用于 Cloudoll 4.0.0。从 3.x 升级前请阅读下方迁移说明。
+本文适用于 Cloudoll 4.2.1。从 3.x 升级前请阅读下方迁移说明。
+
+## AI 辅助开发
+
+新建项目会自带 `AGENTS.md` 和项目级 Cloudoll Skill；已有项目可以在其 Python
+环境中运行 `cloudoll ai init .` 补装。通过 `cloudoll ai list`、
+`cloudoll ai read database` 和 `cloudoll ai search Body` 离线查询随包分发的官方文档，
+不需要 MCP。请让 AI 先读项目指令，再按文档设计实现。
+版本匹配及维护方式见 [AI.md](AI.md)。如果安装版本还不支持 `cloudoll ai --help`，
+请先查阅该版本的 README 和源码。
 
 ## 环境要求
 
@@ -16,10 +25,10 @@ Cloudoll 是一个基于 aiohttp 的 Python Web 开发库，提供路由自动
 
 ## 安装
 
-安装 4.0.0：
+安装 4.2.1：
 
 ```sh
-python -m pip install 'cloudoll==4.0.0'
+python -m pip install 'cloudoll==4.2.1'
 ```
 
 在当前仓库目录安装源码：
@@ -32,16 +41,16 @@ python -m pip install -e .
 
 ```sh
 # MySQL
-python -m pip install 'cloudoll[mysql]==4.0.0'
+python -m pip install 'cloudoll[mysql]==4.2.1'
 
 # PostgreSQL
-python -m pip install 'cloudoll[postgres]==4.0.0'
+python -m pip install 'cloudoll[postgres]==4.2.1'
 
 # AWS 数据库驱动
-python -m pip install 'cloudoll[aws]==4.0.0'
+python -m pip install 'cloudoll[aws]==4.2.1'
 
 # Redis / Memcached 会话或 Redis 数据库
-python -m pip install 'cloudoll[cache]==4.0.0'
+python -m pip install 'cloudoll[cache]==4.2.1'
 ```
 
 源码开发时可用 `python -m pip install -e '.[mysql,postgres,cache,dev]'` 安装。
@@ -128,6 +137,114 @@ async def create_user(request):
 
 单参数处理函数通过 `request.params` 获取路径参数、`request.qs` 获取查询参数、`request.body` 获取已解析的 JSON 或表单数据。路由装饰器还包括 `put`、`delete`，类视图可使用 `View` 和 `routes`。
 
+### 控制台与请求错误日志
+
+通过 `cloudoll` CLI 启动时，默认开启控制台和文件日志。直接在 Python 中创建应用时，
+在启动入口显式配置（导入 Cloudoll 本身不会配置日志）：
+
+```python
+import logging
+from cloudoll.logging import configure_logging
+
+configure_logging(level=logging.INFO, console=True, files=True)
+```
+
+`files=False` 可关闭文件输出；`level=logging.WARNING` 只看警告和错误。
+每条请求日志包含请求方法、实际路径、HTTP 状态码、耗时和 request ID。
+2xx/3xx 使用 INFO，4xx 使用 WARNING，5xx 使用 ERROR；未捕获异常同时记录请求方法、
+路径和完整堆栈。路径不包含查询参数。响应头 `X-Request-ID` 可用于关联同一次请求的日志。
+
+文件默认位于 macOS/Linux 的 `~/.cloudoll/logs/`，按日期写入 `YYYY-MM-DD-all.log`
+和 `YYYY-MM-DD-error.log`；可用 `CLOUDOLL_LOG_DIR` 环境变量指定目录。控制台输出使用
+stderr，服务由 systemd 托管时应查看该服务的 journal。`server.json_errors` 只控制
+HTTP 错误响应格式，不是日志开关。
+
+
+启动阶段会分别记录 `Initializing database '名称'`、`Initialized database '名称' (耗时ms)`，
+以及 Session 的开始与完成时间。数据库连接仍并行初始化，各项耗时不可直接相加。
+如果停在某项 Initializing，可据此定位尚未完成的资源；失败或取消会分别记录
+Initialization failed / cancelled，并继续传播异常及清理已创建资源。
+日志只标识配置中的连接名称，不打印连接字符串、密码或完整配置。
+可选生命周期入口缺失只在 DEBUG 下提示一次；静态文件的反向代理建议也降为 DEBUG。
+
+### 声明式参数校验
+
+使用 Pydantic 2 模型声明输入，通过 `Body[T]`（JSON）、`Query[T]`（查询参数）、
+`Form[T]`（表单）和 `Path[T]`（路径参数）指定来源。Pydantic 已作为基础依赖安装。
+模型应定义在模块级，尤其是启用 `from __future__ import annotations` 时。
+这些注解保留模型的静态类型，函数收到的是校验后的模型实例。
+
+```python
+from pydantic import BaseModel, ConfigDict, Field
+from cloudoll.web import Application, Body, Query, Path, Form
+
+app = Application()
+
+class ArticleQuery(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    page: int = Field(default=1, ge=1)
+    size: int = Field(default=20, ge=1, le=100)
+    tags: list[str] = Field(default_factory=list)
+
+class ArticlePath(BaseModel):
+    id: int = Field(gt=0)
+
+class ArticleInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    title: str = Field(min_length=1, max_length=200)
+    content: str = Field(min_length=1)
+
+@app.get("/articles")
+async def list_articles(query: Query[ArticleQuery]):
+    return query.model_dump()
+
+@app.post("/articles/{id}")
+async def save_article(request, path: Path[ArticlePath], body: Body[ArticleInput]):
+    return {"id": path.id, "article": body.model_dump()}
+
+@app.post("/article-form")
+async def submit_article(data: Form[ArticleInput]):
+    return data.model_dump()
+```
+
+`GET /articles?page=2&tags=python&tags=生活` 得到整数 `page=2` 和列表
+`tags=["python", "生活"]`。未传字段使用模型默认值；必填字段缺失、类型或范围不符
+均在执行接口函数前返回 HTTP 400。Query/Form 的列表、集合和元组字段保留重复值
+（支持字符串字段别名）；标量字段沿用原接口取第一个值的行为，不自动拆分逗号。
+嵌套对象建议通过 JSON Body 传递，不解析 `filter[name]` 这类查询字符串语法。
+
+校验失败始终返回 JSON，无需启用 `server.json_errors`：
+
+```json
+{
+  "error": {
+    "status": 400,
+    "message": "Request validation failed",
+    "request_id": "...",
+    "details": [
+      {"source": "query", "loc": ["page"], "code": "greater_than_equal", "message": "Input should be greater than or equal to 1"}
+    ]
+  }
+}
+```
+
+`loc` 保留嵌套字段和列表下标，例如 `["items", 0, "title"]`。错误不附带原始输入、
+异常上下文或文档 URL；自定义校验器错误使用通用 `Invalid value` 提示，前端可按
+`code` 提供文案。可通过中间件捕获公开的 `RequestValidationError` 定制响应。
+格式错误的 JSON 返回 400，不支持的 Content-Type 返回 415，这两类解析错误仍遵循
+已有的 `server.json_errors` 设置。
+
+可以组合 Query、Path 与一个 Body 或 Form；Body 和 Form 不能同时使用。Body 接受
+`application/json` 和 `+json` 类型，Form 接受 URL 编码与 multipart 表单。
+可选的原始 request 必须是第一个参数，其后每个参数须声明来源。
+旧的 `handler()`、`handler(request)`、`handler(request, field)` 文件流上传接口保持兼容。
+声明来源的接口只解析所声明的数据；需要流式上传文件时继续使用原来的上传接口。
+
+未知字段策略由模型决定：Pydantic 默认忽略，写接口建议使用上例的
+`ConfigDict(extra="forbid")`。新增与更新定义独立输入模型；局部更新用
+`model_dump(exclude_unset=True)` 区分“没传字段”和“显式传 null”。字段校验不替代
+权限检查、数据库唯一约束等业务规则。
+
 ## 模板与静态文件
 
 模板引擎使用 Jinja2。创建 `templates/index.html`：
@@ -273,6 +390,7 @@ db = await create_engine(
 - 未配置会话密钥时，会使用应用实例内的随机密钥，重启后旧会话失效。
 - 通过 HTTPS 提供服务时，将 `session.secure` 设置为 `true`。本地 HTTP 调试可保持 `false`。
 - `request.session` 可以读写会话数据；`request.app.jwt_encode(payload)` 和 `request.app.jwt_decode(token)` 使用应用中的 JWT 配置。
+- Session 中间件在错误处理完成后将会话保存到最终响应；返回 `render_json`、`render_error` 或由业务中间件替换错误响应时，会话修改仍会保存。渲染函数每次创建新响应，手动设置在其他响应上的 Cookie 仍需显式复制；框架的 `json_errors` 转换会保留 HTTP 异常上的 Cookie 和可重复响应头。
 - 会话也支持 Redis 或 Memcached。配置 Redis 时，可使用 `session.redis.url`，或在 `session.redis` 下设置 `host`、`port`、`password` 和 `db`。
 
 生成随机密钥：
@@ -305,6 +423,63 @@ async def list_users(request):
 
 `Model.use(pool)` 返回绑定到指定连接的查询对象，不会修改其他查询或模型类的数据库绑定。每次独立查询应创建自己的查询对象。
 
+### 默认数据源与模型绑定
+
+`orm.default` 指向 `database` 中的连接名称，既不是驱动类型，也不是实际库名。
+每个数据源独立配置服务器、库名和连接池：
+
+```yaml
+database:
+  blog:
+    url: mysql://username:password@host:3306/db1
+  analytics:
+    url: postgres://username:password@pg2:5432/db3
+orm:
+  default: blog
+```
+
+```python
+class AccessLog(Model):
+    __table__ = "access_logs"
+    __datasource__ = "analytics"
+    id = models.IntegerField(primary_key=True)
+
+# 在路由或已初始化数据库的应用生命周期内：
+users = await User.select().where(User.id > 0).all()
+logs = await AccessLog.where(AccessLog.id > 0).all()
+
+# 每次 Model.query() 返回独立、带 Query[User] 类型的查询构造器。
+query = User.query().select()
+
+# 事务内，同一数据源的隐式查询自动复用事务连接。
+async with User.transaction():
+    await User.where(User.id == 1).update(name="Alice")
+    await User.where(User.id == 2).update(name="Bob")
+```
+
+数据源解析优先级：显式 `.use(engine)` → `datasource_context` 中的映射或当前应用映射。
+在映射内优先使用模型的 `__datasource__`，否则使用默认名称；模型绑定可继承。
+映射中缺少指定名称时直接报错，不会退回其他数据库。
+每次类级查询都创建新的 Query，不在模型类上缓存连接或查询条件。
+已有记录仍使用读取它时绑定的引擎；`.use(None)` 仍可用于离线 SQL 编译。
+
+`User.transaction()` 复用引擎现有事务实现，嵌套事务使用保存点。直接使用
+`async with engine.transaction()` 也能让同一引擎的隐式查询参与事务。
+多个数据源不构成分布式事务，不能保证一起提交或回滚。事务连接不能在子任务间共享。
+不同数据源的模型不能通过一次 JOIN 自动跨实例查询；JOIN 始终在当前 Query 的数据源执行。
+
+独立脚本、测试或没有应用上下文的任务，可绑定已创建的引擎：
+
+```python
+from cloudoll.orm import datasource_context
+
+with datasource_context({"blog": engine}, default="blog"):
+    users = await User.select().all()
+```
+
+此上下文不创建或关闭引擎，退出时恢复上层绑定。没有活动应用/显式上下文、未配置默认值、
+或者数据库尚未初始化时，隐式查询明确报错。现有 `.use(engine)` 用法不需要增加配置。
+
 ### 从数据库生成模型
 
 ```sh
@@ -371,8 +546,8 @@ cloudoll restart -n myapp
 python -m pip install -e '.[mysql,postgres,cache,dev]'
 python -m pytest -q -m 'not integration' -k 'not aws'
 python -m build
-python tests/check_wheel.py dist/cloudoll-4.0.0-py3-none-any.whl
-python tests/check_release.py dist/cloudoll-4.0.0-py3-none-any.whl
+python tests/check_wheel.py dist/cloudoll-4.2.1-py3-none-any.whl
+python tests/check_release.py dist/cloudoll-4.2.1-py3-none-any.whl
 ```
 
 最后一条命令用于验证构建出的 wheel，版本号变化后请调整文件名。测试使用模拟数据库连接及本机 HTTP 服务；真实数据库连接和 AWS 故障切换需要单独的集成环境。

{cloudoll-4.0.0 → cloudoll-4.2.1}/SECURITY.md

@@ -15,7 +15,7 @@ reproduction, impact and any mitigation. No response-time SLA is promised.
 
 Security fixes target the latest stable release. Older release branches have no
 guaranteed backports; upgrade or contact the maintainer about a specific issue.
-This policy accompanies Cloudoll 4.0.0; published versions are identified by PyPI
+This policy accompanies Cloudoll 4.1.0; published versions are identified by PyPI
 and repository release tags, not by documentation edits alone.
 CI compatibility with a Python version is not an extension of that runtime's
 upstream security support. Deploy on a runtime still supported by its vendor.

cloudoll-4.2.1/cloudoll/__init__.py

@@ -0,0 +1 @@
+__version__ = "4.2.1"

cloudoll-4.2.1/cloudoll/ai/AGENTS.md

@@ -0,0 +1,7 @@
+## Cloudoll development
+
+Before building or changing a Cloudoll application, read `.agents/skills/cloudoll/SKILL.md` completely and follow its documentation workflow. Use the project's Python environment, not a globally installed version.
+
+Official documentation is bundled with the installed library: `python -m cloudoll.cli ai list`, `ai read <topic>`, and `ai search <query>`. These commands work offline without MCP. Read `structure`, `config`, `router`, and `validation` before designing an application; read `database` before database work. Consult the installed source when resolving a signature discrepancy; report the discrepancy rather than inventing an API.
+
+Prefer the documented scaffold, auto-discovered controllers/middlewares, YAML configuration, framework-owned database lifecycle, typed request validation, and ORM for ordinary CRUD. Low-level alternatives require a task-specific reason. Never silently replace Cloudoll's architecture with patterns from another framework.

cloudoll-4.2.1/cloudoll/ai/__init__.py

@@ -0,0 +1 @@
+"""Versioned documentation and project instructions for AI-assisted development."""