Metadata-Version: 2.5
Name: pdfwright
Version: 0.2.2
Summary: 配置驱动的 PDF 生成基础库：JSON 配置 → 模板求值（变量/循环/条件）→ 高保真 PDF。纯 Python 引擎（ReportLab + fontTools + Jinja2 + pikepdf），无外部软件依赖。
License: Proprietary
Requires-Python: >=3.12
Requires-Dist: fonttools>=4.53
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: jsonschema>=4.23
Requires-Dist: openpyxl>=3.1
Requires-Dist: pikepdf>=8.0
Requires-Dist: pillow>=10.0
Requires-Dist: python-barcode>=0.16.1
Requires-Dist: python-docx>=1.1
Requires-Dist: reportlab<6,>=5.0
Requires-Dist: segno>=1.6.6
Description-Content-Type: text/markdown

# pdfwright — 配置驱动的 PDF 生成基础库

纯 Python 引擎（ReportLab + fontTools + Jinja2 + pikepdf），**无外部软件依赖**
（不依赖 pango/cairo/Chromium/LibreOffice 等系统级软件）。

## 定位

`pdfwright` 是**基础库**：输入「页面 JSON 配置（schema）+ 数据（data）」，输出
高保真 PDF 或 HTML 预览。**不包含任何 web 服务与存储**。

- 需要可视化配置编辑器 / 对外 API 服务 → 使用 [`pdfwright-web`](../pdfwright-web/)。
- 只需本地渲染 → 直接 import 本库即可。

## 使用

```python
from pdfwright import DocumentConfig, SchemaError, render_pdf, render_pdf_to_file

config = {
    "version": "1.0",
    "page": {"size": "A4", "margin": {"top": 40, "bottom": 40, "left": 40, "right": 40}},
    "variables": [
        {"name": "title", "type": "string", "label": "标题", "default": "示例文档"},
        {"name": "items", "type": "array", "label": "明细"},
    ],
    "body": [
        {"type": "heading", "text": "{{ title }}", "style": {"textAlign": "center", "fontSize": 18}},
        {"type": "for", "each": "items", "as": "item",
         "children": [{"type": "paragraph", "text": "{{ loop.index }}. {{ item.name }}"}],
        },
    ],
}
doc = DocumentConfig.from_dict(config)   # 解析 + 校验
data = {"items": [{"name": "A"}, {"name": "B"}]}
pdf_bytes = render_pdf(doc, data=data)   # 服务器端生成，需要字体目录可用
render_pdf_to_file(doc, "out.pdf", data=data)
```

## 核心能力

- **Schema 嵌套模型**：`table > thead/tbody/tfoot > tr > td/th`，单元格内容为任意元素树
  （可再嵌表格 / 文本 / 控件 / for / if）。
- **模板引擎（Jinja2）**：`{{ }}` 表达式、`{% for %}` / `{% if %}` 标签任意层级摆放、
  内置过滤器（数字/百分比/货币/截断/日期…），空变量宽松求值。
- **字体系统**：枚举系统字体（macOS/Linux/Windows），字符级回退
  （CJK / 数字 / 拉丁 各自回退，类似 Word 字体绑定），中文字号（初号~八号），
  TTC 抽取嵌入，PDF/A 输出。
- **双样式**：元素 `style`（通用/HTML 预览）+ `pdfStyle`（PDF 覆盖）；
  文档级 `html` / `pdf` 配置节。
- **布局**：流式布局 + 绝对定位（`position: "absolute"` + x/y）并存；
  A4/A3/自定义任意尺寸；分页符、页眉页脚、页码。

## 开发

```bash
uv sync --all-extras   # 安装（含 dev 依赖）
uv run pytest          # 跑测试（真实渲染 PDF，禁止 mock）
uv run ruff check .    # lint
uv run mypy src        # 类型检查
```

质量红线：测试必须真实跑渲染（在 tmp_path 生成 PDF 并断言存在/页数/内容），
禁止 mock 渲染对象。