typact 0.2.1__tar.gz → 0.2.2a2__tar.gz

typact-0.2.2a2/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+本文件区分未发布改动与已在 PyPI 发布的版本。当前预发布版本为 0.2.2a2，正式版 0.2.2 尚未发布。
+
+## [Unreleased]
+
+## [0.2.2a2] - 2026-09-22
+
+### 变更
+
+- 最低 Python 版本从 3.13 下调至 3.10，并在 Linux 与 Windows CI 中覆盖 Python 3.10 至 3.14。
+- 英文 README 和文档成为默认入口，原中文 README 保留为 `README.zh-CN.md`。
+
+## [0.2.2a1] - 2026-09-14
+
+### 新增
+
+- 请求生命周期事件：`request`、`retry`、`response`、`failure`；支持同步和异步监听器。
+- `RetryConfig.should_retry_response`：对完整 `typact.Response` 执行同步布尔判断，支持业务响应码重试。
+- 公开 `default_should_retry_response`，允许自定义策略复用默认 HTTP 状态码规则。
+- GitHub Actions 测试、安装包与文档检查；手动准备 Draft Release 的工作流。
+- `py.typed`、项目链接、贡献指南、发布规范与历史发行审计记录。
+
+### 行为说明
+
+- 原有 `retry_status_codes` 保持支持；同时指定非 None 的状态码集合和响应回调会报配置错误。
+- 回调完全接管普通响应判断，仍受方法、次数和退避限制；回调错误直接传播。
+- 流式/SSE 请求不支持完整响应回调，需路由级状态码策略或关闭重试。原有首分片前重试规则不变。
+
+### 工程调整
+
+- 流式集成测试按完整字节内容验证，避免依赖不同平台与 Runtime 的网络分块边界。
+- 测试服务器在客户端提前断开时清理连接，避免 Windows CI 拆除服务器时挂起；测试增加有界超时诊断。
+- 标准文档构建与 Sites 专用打包分离；使用 Node 22 和固定前端依赖版本。
+- 修正文档 canonical 站点地址，增加 AtomGit/GitHub 托管入口。
+- 补录历史附注标签与 GitHub Releases，不代表发布了新的 PyPI 版本。
+
+## [0.2.1] - 2026-08-31
+
+- 新增路由级超时和重试策略覆盖，适用于 HTTP 装饰器与 `client.request()`。
+- 未指定时继承 Client 配置，显式 `None` 关闭对应继承。
+- 流式请求仅在第一个分片交付前允许重试。
+
+## [0.2.0] - 2026-08-17
+
+- 请求超时、网络异常与状态码重试，使用指数退避。
+- SSE 与普通流式响应转换。
+- 修正 httpx Runtime 的 Cookie 处理。
+
+## [0.2.0a1] - 2026-08-13
+
+- 0.2.0 系列测试发行。发布包的 Python 源码与后续 0.2.0 一致。
+- 历史 Git 没有相同版本元数据的提交；标签使用经校验的 PyPI sdist 恢复快照。
+
+## [0.1.4] - 2026-07-24
+
+- 统一公共 `Response` 类型，保留 `SimpleResponse` 兼容别名。
+- 支持原始响应、文本与字节下载。
+
+## [0.1.3] - 2026-07-14
+
+- 早期发行修订，与 0.1.2 的 Python 源码相同。
+- 历史标签使用 PyPI sdist 恢复快照，不将版本元数据修订描述为新增功能。
+
+## [0.1.2] - 2026-07-14
+
+- `FileData` 承载文件内容、文件名和媒体类型，`File` 负责参数声明。
+- MIT 许可证。历史标签使用 PyPI sdist 恢复快照。
+
+## [0.1.1] - 2026-07-14
+
+- 首个保留在 PyPI 的 Typact 版本，支持声明式 HTTP 请求、参数注解、响应转换、多 Runtime 和认证扩展。
+
+历史日期采用 PyPI 首次上传日期。版本映射、原始 sdist 地址及哈希见 [发行审计记录](docs/release-history.json)。原始发布包是历史事实来源；恢复快照不代表找到了原始发布提交。

typact-0.2.2a2/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# 贡献指南
+
+Typact 是开源 HTTP 客户端库。设计变更应考虑通用场景、公共 API、可选依赖、不同 Runtime 的一致性，以及已有用户的升级成本。
+
+## 开发环境
+
+Python 3.10 至 3.14；使用 uv 管理环境：
+
+```sh
+uv sync --all-extras --group dev
+uv run --no-sync pytest -q
+```
+
+CI 在 Windows 和 Linux 上运行上述 Python 版本的完整测试，包含 urllib、httpx 和 aiohttp。Python 元数据允许更新版本，但未经 CI 验证的版本不在当前保证范围内。
+
+文档使用 Node.js 22，版本记录在 `docs-site/.node-version`：
+
+```sh
+cd docs-site
+npm ci
+npm run build
+```
+
+标准静态构建不需要 Sites 配置；仅在已配置 `.openai/hosting.json` 的专用环境中使用 `npm run build:sites`。Netlify 使用同一标准构建命令。Windows 上请使用约定的 Node 22，避免已观察到的 Node 24.19.0 退出断言。
+
+## 提交要求
+
+- 每次变更聚焦一个问题，新增公开行为需补文档和边界测试。
+- 修改重试、认证、超时、取消或流式行为时，说明组合语义与资源生命周期。
+- 保持可选 HTTP 依赖可选；核心安装不可因新增功能而强制导入它们。
+- 将用户可见变化写入 `CHANGELOG.md` 的 Unreleased 部分。
+- 公共 API 的删除、更名或默认语义变化必须说明迁移方式；不要用实现更简单作为唯一理由。
+- 不提交凭据、依赖缓存或生成的构建产物。不要改写已公开的版本标签。
+
+发布流程见 [RELEASING.md](RELEASING.md)。

typact-0.2.2a2/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md README.zh-CN.md LICENSE CHANGELOG.md CONTRIBUTING.md RELEASING.md
+recursive-include src/typact *.py py.typed
+recursive-include tests *.py
+prune docs-site
+prune .release-audit
+prune .publish-dist
+global-exclude __pycache__ *.py[cod]

typact-0.2.2a2/PKG-INFO

@@ -0,0 +1,324 @@
+Metadata-Version: 2.4
+Name: typact
+Version: 0.2.2a2
+Summary: Build production-ready Python API clients with FastAPI-style declarations.
+License-Expression: MIT
+Project-URL: Homepage, https://typact.zzq.jl.cn
+Project-URL: Documentation, https://typact.zzq.jl.cn/docs/getting-started/
+Project-URL: GitHub, https://github.com/zzqjlcn/typact
+Project-URL: AtomGit, https://atomgit.com/zhangzhanqi/typact
+Project-URL: Issues, https://github.com/zzqjlcn/typact/issues
+Project-URL: Changelog, https://github.com/zzqjlcn/typact/blob/main/CHANGELOG.md
+Keywords: http,api-client,async,typing,declarative,fastapi,pydantic,sse,retry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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: Programming Language :: Python :: 3.14
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.13.4
+Provides-Extra: aiohttp
+Requires-Dist: aiohttp>=3.14.1; extra == "aiohttp"
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.28.1; extra == "httpx"
+Dynamic: license-file
+
+# <img src="https://typact.zzq.jl.cn/favicon.svg" alt="Typact" width="28" height="28" style="vertical-align: middle;"/> Typact
+
+[![Documentation](https://img.shields.io/badge/docs-typact.zzq.jl.cn-blue)](https://typact.zzq.jl.cn)
+[![PyPI](https://img.shields.io/pypi/v/typact)](https://pypi.org/project/typact/)
+[![Python](https://img.shields.io/pypi/pyversions/typact)](https://pypi.org/project/typact/)
+[![CI](https://github.com/zzqjlcn/typact/actions/workflows/ci.yml/badge.svg)](https://github.com/zzqjlcn/typact/actions/workflows/ci.yml)
+[![License](https://img.shields.io/pypi/l/typact)](https://github.com/zzqjlcn/typact/blob/main/LICENSE)
+
+[Documentation](https://typact.zzq.jl.cn) · [PyPI](https://pypi.org/project/typact/) · [中文 README](https://github.com/zzqjlcn/typact/blob/main/README.zh-CN.md) · [Changelog](https://github.com/zzqjlcn/typact/blob/main/CHANGELOG.md)
+
+**Build production-ready Python API clients with FastAPI-style declarations.**
+
+Typact turns an annotated Python function into an executable HTTP contract. Declare the request parameters and return type once; Typact handles request building, transport, response validation, retries, authentication, streaming, and test doubles.
+
+```python
+from pydantic import BaseModel
+
+from typact import HttpClient, Path
+
+
+class User(BaseModel):
+    id: int
+    name: str
+
+
+client = HttpClient("https://api.example.com")
+
+
+@client.get("/users/{user_id}")
+async def get_user(user_id: int = Path()) -> User:
+    pass
+
+
+user = await get_user(1)
+```
+
+## Why Typact?
+
+Handwritten clients tend to repeat the same plumbing: assemble URLs and headers, serialize bodies, check status codes, validate JSON, retry transient failures, refresh tokens, and mock the network in tests. Typact keeps that behavior behind one typed contract.
+
+- **FastAPI-style declarations** with `Path`, `Query`, `Header`, `Cookie`, `Body`, `Form`, and `File`.
+- **Validated return types** powered by Pydantic v2 `TypeAdapter`.
+- **Production request policies** including timeouts, exponential backoff, response-aware retries, and token refresh.
+- **Streaming support** for raw byte/text streams and typed Server-Sent Events.
+- **Pluggable transports** using the standard library, httpx, aiohttp, or a custom Runtime.
+- **Deterministic tests** through a Mock Runtime that records the request Typact built.
+- **Small core install** with Pydantic as the only required dependency.
+
+Typact is async-first and targets Python 3.10 through 3.14.
+
+## Installation
+
+The default Runtime uses Python's standard library:
+
+```bash
+pip install typact
+```
+
+Install an optional transport when you need httpx or aiohttp:
+
+```bash
+pip install "typact[httpx]"
+pip install "typact[aiohttp]"
+```
+
+## Quick start
+
+```python
+import asyncio
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from typact import Body, HttpClient, Path, Query
+
+
+class Todo(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    user_id: int = Field(alias="userId")
+    id: int | None = None
+    title: str
+    completed: bool
+
+
+client = HttpClient("https://jsonplaceholder.typicode.com")
+
+
+@client.get("/todos/{todo_id}")
+async def get_todo(todo_id: int = Path()) -> Todo:
+    pass
+
+
+@client.get("/todos")
+async def list_todos(user_id: int = Query(alias="userId")) -> list[Todo]:
+    pass
+
+
+@client.post("/todos")
+async def create_todo(todo: Todo = Body()) -> Todo:
+    pass
+
+
+async def main():
+    todo = await get_todo(1)
+    todos = await list_todos(user_id=1)
+    created = await create_todo(
+        Todo(user_id=1, title="Try Typact", completed=False)
+    )
+    print(todo, todos[0], created)
+    await client.close()
+
+
+asyncio.run(main())
+```
+
+## Production request policies
+
+Configure shared timeout and retry behavior on the client, then override it per route when an endpoint needs different semantics:
+
+```python
+from typact import HttpClient, Path, RetryConfig
+
+
+client = HttpClient(
+    "https://api.example.com",
+    timeout=10,
+    retry_config=RetryConfig(max_retries=3, initial_delay=0.5),
+)
+
+
+@client.get(
+    "/reports/{report_id}",
+    timeout=60,
+    retry_config=RetryConfig(max_retries=2),
+)
+async def get_report(report_id: int = Path()) -> dict:
+    pass
+```
+
+Retries are disabled by default. When enabled, the default policy retries network and timeout failures plus `429`, `502`, `503`, and `504` responses for idempotent methods.
+
+Typact can also retry a successful HTTP response that carries a transient business error:
+
+```python
+from typact import Response, RetryConfig, default_should_retry_response
+
+
+def should_retry(response: Response) -> bool:
+    if default_should_retry_response(response):
+        return True
+    data = response.json()
+    return (
+        response.status_code == 200
+        and isinstance(data, dict)
+        and data.get("code") in {"SYSTEM_BUSY", "RATE_LIMITED"}
+    )
+
+
+client = HttpClient(
+    "https://api.example.com",
+    retry_config=RetryConfig(
+        max_retries=3,
+        should_retry_response=should_retry,
+    ),
+)
+```
+
+See the [Runtime guide](https://typact.zzq.jl.cn/docs/runtime/) for inheritance rules, streaming behavior, and lifecycle events.
+
+## Authentication and cross-cutting behavior
+
+Interceptors keep authentication, logging, and tracing out of endpoint declarations:
+
+```python
+from typact import BearerTokenInterceptor, HttpClient, InterceptorChain
+
+
+client = HttpClient(
+    "https://api.example.com",
+    interceptor_chain=InterceptorChain(
+        request_interceptors=[BearerTokenInterceptor("your-token")],
+    ),
+)
+```
+
+Built-in interceptors include bearer tokens, refreshable bearer tokens, API keys, trace IDs, and logging.
+
+## Files and streaming
+
+Upload multipart files with `FileData`:
+
+```python
+from typact import File, FileData
+
+
+@client.post("/upload")
+async def upload(file: FileData = File()) -> dict:
+    pass
+
+
+await upload(
+    FileData(
+        content=b"hello",
+        filename="hello.txt",
+        content_type="text/plain",
+    )
+)
+```
+
+Use `AsyncIterator[bytes]` or `AsyncIterator[str]` for raw streams. Other item types are decoded from Server-Sent Events:
+
+```python
+from collections.abc import AsyncIterator
+
+
+@client.get("/events")
+async def events() -> AsyncIterator[dict]:
+    pass
+
+
+async for event in events():
+    print(event)
+```
+
+Streaming requires the httpx or aiohttp Runtime. Retries stop after the first chunk has been delivered, preventing duplicate data.
+
+## Pluggable Runtimes
+
+The default `UrllibRuntime` needs no extra HTTP dependency. Existing httpx and aiohttp clients can be injected when you need their connection settings or ecosystem integrations:
+
+```python
+import httpx
+
+from typact import HttpClient, HttpxRuntime
+
+
+client = HttpClient(
+    "https://api.example.com",
+    client_runtime=HttpxRuntime(httpx.AsyncClient(timeout=30)),
+)
+```
+
+Endpoint declarations and return types stay unchanged when the Runtime changes.
+
+## Testing without a server
+
+The Mock Runtime replaces the transport boundary and records every built request:
+
+```python
+from typact import HttpClient, MockRuntime, Query
+
+
+runtime = MockRuntime()
+runtime.add_response(
+    "GET",
+    "https://api.example.com/items",
+    json_data={"items": []},
+)
+client = HttpClient("https://api.example.com", client_runtime=runtime)
+
+
+@client.get("/items")
+async def list_items(page: int = Query(1)) -> dict:
+    pass
+
+
+result = await list_items(page=2)
+assert result == {"items": []}
+assert runtime.requests[0].params == {"page": 2}
+```
+
+## Documentation and examples
+
+- [Getting started](https://typact.zzq.jl.cn/docs/getting-started/)
+- [Parameter annotations](https://typact.zzq.jl.cn/docs/annotations/)
+- [Runtimes, retries, streaming, and events](https://typact.zzq.jl.cn/docs/runtime/)
+- [Interceptors](https://typact.zzq.jl.cn/docs/interceptors/)
+- [Testing](https://typact.zzq.jl.cn/docs/testing/)
+- [`examples/`](https://github.com/zzqjlcn/typact/tree/main/examples)
+
+## Development
+
+```bash
+uv sync --all-extras --group dev
+uv run --no-sync pytest -q
+```
+
+Design changes must account for public API clarity, Runtime consistency, backward compatibility, and migration cost. See [CONTRIBUTING.md](https://github.com/zzqjlcn/typact/blob/main/CONTRIBUTING.md) and [RELEASING.md](https://github.com/zzqjlcn/typact/blob/main/RELEASING.md) before contributing or publishing.
+
+## License
+
+Typact is released under the [MIT License](https://github.com/zzqjlcn/typact/blob/main/LICENSE).