ziban 0.1.0__tar.gz

ziban-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / py${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.9", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Test
+        run: python -m pytest -q
+
+  demo:
+    name: CLI demo
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: python -m pip install -e .
+      - name: Break a sentence
+        run: |
+          printf '他说：「这次不一样。」然后关掉了对话框。' | ziban wrap - --width-em 10 --ruler
+      - name: Show the ruleset
+        run: ziban rules

ziban-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.venv/
+venv/
+.idea/
+.vscode/
+.DS_Store

ziban-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ziban contributors
+
+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.

ziban-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.5
+Name: ziban
+Version: 0.1.0
+Summary: CJK typesetting for programmatic renderers: line breaking, kinsoku, punctuation compression, hanging punctuation.
+License: MIT
+License-File: LICENSE
+Keywords: chinese,cjk,kinsoku,line-breaking,pdf,pillow,text-layout,typography
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Text Processing :: Fonts
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.9
+Requires-Dist: tomli>=1.1.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pillow>=9.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: pillow
+Requires-Dist: pillow>=9.0; extra == 'pillow'
+Description-Content-Type: text/markdown
+
+# ziban
+
+**Correct CJK line breaking for everything that is not a browser.**
+
+[中文说明 →](README.zh-CN.md)
+
+Browsers got `text-spacing-trim`, `line-break: strict` and proper kinsoku years
+ago. Everything else — Pillow, ReportLab, SVG, ffmpeg subtitles, `python-pptx`,
+canvas — still reimplements it badly, because there is nothing to ask.
+
+`ziban` is that thing: a pure-Python typesetting engine that turns a string and
+a box into lines a Chinese typesetter would accept — and tells you, in machine
+readable form, every time it had to compromise.
+
+![Same text, same column: naive chunking on the left, ziban on the right](docs/compare.png)
+
+## The problem, in eight seconds
+
+Naive `if len(s) > N: cut()`:
+
+```
+他说：「这次不一样。
+」然后关掉了对话框。
+```
+
+`ziban`:
+
+```
+他说：「这次不一样。」
+然后关掉了对话框。
+```
+
+The first version starts a line with `」`. That is not a matter of taste:
+[《中文排版需求》(CLREQ)](https://www.w3.org/TR/clreq/) forbids closing
+punctuation at line start (避头) and opening punctuation at line end (避尾).
+Every renderer that is not a browser quietly breaks that rule — and the
+punctuation it breaks is exactly the punctuation readers notice.
+
+The image above is generated, not drawn by hand:
+`python examples/compare.py --font <path-to-a-CJK-font>`. Re-run it after any
+change to the rules and you will see immediately whether the typography got
+better or worse.
+
+## Install
+
+```bash
+pip install ziban              # core, zero dependencies
+pip install "ziban[pillow]"    # + measuring with real font files
+```
+
+Python 3.9+. No browser, no native build, no ICU, no model.
+
+## Use it
+
+### As a CLI
+
+```console
+$ echo "这是一个比较长的段落，用来看断行在真实文本上的表现。" \
+    | ziban wrap - --width-em 8 --ruler
+      +----------------+
+  1   | 这是一个比较长的 |   8.0em
+  2   | 段落，用来看断行 |   8.0em
+  3   | 在真实文本上的表 |   8.0em
+  4   | 现。             |   2.0em
+
+4 line(s), box 8.0em, no diagnostics
+```
+
+`> ` in the gutter means the line ends with a hanging mark, `<` means a
+compressed one, `!` means it overflowed. `--json` gives you the same thing
+as structured data, for scripts and agents.
+
+### As a library
+
+```python
+from ziban import Style, layout, EmMetrics
+
+page = layout(
+    "他说：「这次不一样。」然后关掉了对话框。",
+    width=10 * 32,                     # 10 characters wide
+    style=Style(size=32, leading=1.7),
+    metrics=EmMetrics(32),             # or PillowMetrics("NotoSerifSC.otf", 32)
+)
+
+for line in page.lines:
+    print(line.text, line.width)
+
+page.diagnostics
+# [Diagnostic(code='ORPHAN_LINE', line=1, ...)]
+```
+
+Every line carries its own explanation:
+
+```python
+line.adjustments   # (Adjustment(kind='hang', index=10, delta=32.0),)
+line.slack         # pixels left over
+line.overflow      # pixels past the box, 0 if it fits
+line.justify_spacing
+```
+
+## What it does
+
+| | |
+|---|---|
+| **避头尾 (kinsoku)** | closing marks never start a line, opening marks never end one |
+| **标点挤压 (compression)** | a full-width mark is drawn at half width when that is what makes the line fit |
+| **行末悬挂 (hanging)** | a mark may sit outside the margin rather than be pushed down — capped at one em *and* a quarter of the measure |
+| **中西混排** | breaks between CJK and Latin, never inside a Latin word, numbers stay glued to their units |
+| **硬断行** | `\n` is always honoured, blank lines survive |
+| **诊断** | `OVERFLOW`, `NO_BREAK_OPPORTUNITY`, `KINSOKU_FALLBACK`, `ORPHAN_LINE` — with a suggested fix |
+| **确定性** | same text + same font + same size → byte-identical output, on every platform |
+
+## What it does not do
+
+- No AI. No API keys. No "generate my copy".
+- No browser, no headless Chromium, no layout engine to install.
+- No GUI editor.
+- No auto-publishing to any platform.
+- **No bundled fonts.** Microsoft YaHei and PingFang are not redistributable;
+  bring your own, or use Noto Sans SC / Noto Serif SC (OFL).
+
+Being explicit about the last one is not pedantry: a library that ships a
+proprietary font is a library companies cannot use.
+
+## Rules are data, not `if`-statements
+
+The whole policy lives in [`src/ziban/data/clreq.toml`](src/ziban/data/clreq.toml):
+
+```toml
+[kinsoku]
+head_forbidden = "　，、。．；：？！）〕〉》」』】”’｝…"
+tail_forbidden = "（〔〈《「『【“‘｛"
+
+[compress]
+compressed_ratio = 0.5
+chars = "，、。．；：？！）〕〉》」』】”’…"
+
+[hang]
+max_ratio = 1.0
+max_share = 0.25
+```
+
+Change the file to change the behaviour. A Japanese ruleset is a second TOML,
+not a second engine. This is also why contributing is cheap: most typographic
+bugs are one line of data.
+
+## How it compares
+
+| | kinsoku | compression | hanging | works outside a browser | deterministic |
+|---|---|---|---|---|---|
+| [heti](https://github.com/sivan/heti) | via browser | partial | ✗ | ✗ | ✗ |
+| [pangu.py](https://github.com/vinta/pangu.py) | ✗ | ✗ | ✗ | ✓ | ✓ |
+| [budoux](https://github.com/google/budoux) | ✗ | ✗ | ✗ | ✓ | ✓ |
+| browser `text-spacing-trim` | ✓ | ✓ | partial | ✗ | ✓ |
+| **ziban** | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+`budoux` decides *where* a break is semantically acceptable; `ziban` decides
+whether the break is typographically legal. They compose.
+
+## Status
+
+`0.1.0` — engine complete for horizontal text, 958 tests green
+(144 corpus × width combinations (24 paragraphs × 6 measures) checked against six invariants, plus golden
+cases). Not yet on PyPI.
+
+Next:
+
+- **0.2** font probing across Windows/macOS/Linux, pair compression (「。」 in
+  one em), a Knuth–Plass-style cost function so the last line stops being an
+  orphan
+- **0.3** adapters: ReportLab, SVG, `python-pptx`; vertical text behind a flag
+- **0.4** a `cards` example that renders real 1080×1440 image sets, and a
+  `SKILL.md` wrapper so agents can call it
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+The ruleset follows [CLREQ](https://www.w3.org/TR/clreq/) (W3C). Character
+classes follow a curated subset of [UAX #14](https://www.unicode.org/reports/tr14/).

ziban-0.1.0/README.md

@@ -0,0 +1,180 @@
+# ziban
+
+**Correct CJK line breaking for everything that is not a browser.**
+
+[中文说明 →](README.zh-CN.md)
+
+Browsers got `text-spacing-trim`, `line-break: strict` and proper kinsoku years
+ago. Everything else — Pillow, ReportLab, SVG, ffmpeg subtitles, `python-pptx`,
+canvas — still reimplements it badly, because there is nothing to ask.
+
+`ziban` is that thing: a pure-Python typesetting engine that turns a string and
+a box into lines a Chinese typesetter would accept — and tells you, in machine
+readable form, every time it had to compromise.
+
+![Same text, same column: naive chunking on the left, ziban on the right](docs/compare.png)
+
+## The problem, in eight seconds
+
+Naive `if len(s) > N: cut()`:
+
+```
+他说：「这次不一样。
+」然后关掉了对话框。
+```
+
+`ziban`:
+
+```
+他说：「这次不一样。」
+然后关掉了对话框。
+```
+
+The first version starts a line with `」`. That is not a matter of taste:
+[《中文排版需求》(CLREQ)](https://www.w3.org/TR/clreq/) forbids closing
+punctuation at line start (避头) and opening punctuation at line end (避尾).
+Every renderer that is not a browser quietly breaks that rule — and the
+punctuation it breaks is exactly the punctuation readers notice.
+
+The image above is generated, not drawn by hand:
+`python examples/compare.py --font <path-to-a-CJK-font>`. Re-run it after any
+change to the rules and you will see immediately whether the typography got
+better or worse.
+
+## Install
+
+```bash
+pip install ziban              # core, zero dependencies
+pip install "ziban[pillow]"    # + measuring with real font files
+```
+
+Python 3.9+. No browser, no native build, no ICU, no model.
+
+## Use it
+
+### As a CLI
+
+```console
+$ echo "这是一个比较长的段落，用来看断行在真实文本上的表现。" \
+    | ziban wrap - --width-em 8 --ruler
+      +----------------+
+  1   | 这是一个比较长的 |   8.0em
+  2   | 段落，用来看断行 |   8.0em
+  3   | 在真实文本上的表 |   8.0em
+  4   | 现。             |   2.0em
+
+4 line(s), box 8.0em, no diagnostics
+```
+
+`> ` in the gutter means the line ends with a hanging mark, `<` means a
+compressed one, `!` means it overflowed. `--json` gives you the same thing
+as structured data, for scripts and agents.
+
+### As a library
+
+```python
+from ziban import Style, layout, EmMetrics
+
+page = layout(
+    "他说：「这次不一样。」然后关掉了对话框。",
+    width=10 * 32,                     # 10 characters wide
+    style=Style(size=32, leading=1.7),
+    metrics=EmMetrics(32),             # or PillowMetrics("NotoSerifSC.otf", 32)
+)
+
+for line in page.lines:
+    print(line.text, line.width)
+
+page.diagnostics
+# [Diagnostic(code='ORPHAN_LINE', line=1, ...)]
+```
+
+Every line carries its own explanation:
+
+```python
+line.adjustments   # (Adjustment(kind='hang', index=10, delta=32.0),)
+line.slack         # pixels left over
+line.overflow      # pixels past the box, 0 if it fits
+line.justify_spacing
+```
+
+## What it does
+
+| | |
+|---|---|
+| **避头尾 (kinsoku)** | closing marks never start a line, opening marks never end one |
+| **标点挤压 (compression)** | a full-width mark is drawn at half width when that is what makes the line fit |
+| **行末悬挂 (hanging)** | a mark may sit outside the margin rather than be pushed down — capped at one em *and* a quarter of the measure |
+| **中西混排** | breaks between CJK and Latin, never inside a Latin word, numbers stay glued to their units |
+| **硬断行** | `\n` is always honoured, blank lines survive |
+| **诊断** | `OVERFLOW`, `NO_BREAK_OPPORTUNITY`, `KINSOKU_FALLBACK`, `ORPHAN_LINE` — with a suggested fix |
+| **确定性** | same text + same font + same size → byte-identical output, on every platform |
+
+## What it does not do
+
+- No AI. No API keys. No "generate my copy".
+- No browser, no headless Chromium, no layout engine to install.
+- No GUI editor.
+- No auto-publishing to any platform.
+- **No bundled fonts.** Microsoft YaHei and PingFang are not redistributable;
+  bring your own, or use Noto Sans SC / Noto Serif SC (OFL).
+
+Being explicit about the last one is not pedantry: a library that ships a
+proprietary font is a library companies cannot use.
+
+## Rules are data, not `if`-statements
+
+The whole policy lives in [`src/ziban/data/clreq.toml`](src/ziban/data/clreq.toml):
+
+```toml
+[kinsoku]
+head_forbidden = "　，、。．；：？！）〕〉》」』】”’｝…"
+tail_forbidden = "（〔〈《「『【“‘｛"
+
+[compress]
+compressed_ratio = 0.5
+chars = "，、。．；：？！）〕〉》」』】”’…"
+
+[hang]
+max_ratio = 1.0
+max_share = 0.25
+```
+
+Change the file to change the behaviour. A Japanese ruleset is a second TOML,
+not a second engine. This is also why contributing is cheap: most typographic
+bugs are one line of data.
+
+## How it compares
+
+| | kinsoku | compression | hanging | works outside a browser | deterministic |
+|---|---|---|---|---|---|
+| [heti](https://github.com/sivan/heti) | via browser | partial | ✗ | ✗ | ✗ |
+| [pangu.py](https://github.com/vinta/pangu.py) | ✗ | ✗ | ✗ | ✓ | ✓ |
+| [budoux](https://github.com/google/budoux) | ✗ | ✗ | ✗ | ✓ | ✓ |
+| browser `text-spacing-trim` | ✓ | ✓ | partial | ✗ | ✓ |
+| **ziban** | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+`budoux` decides *where* a break is semantically acceptable; `ziban` decides
+whether the break is typographically legal. They compose.
+
+## Status
+
+`0.1.0` — engine complete for horizontal text, 958 tests green
+(144 corpus × width combinations (24 paragraphs × 6 measures) checked against six invariants, plus golden
+cases). Not yet on PyPI.
+
+Next:
+
+- **0.2** font probing across Windows/macOS/Linux, pair compression (「。」 in
+  one em), a Knuth–Plass-style cost function so the last line stops being an
+  orphan
+- **0.3** adapters: ReportLab, SVG, `python-pptx`; vertical text behind a flag
+- **0.4** a `cards` example that renders real 1080×1440 image sets, and a
+  `SKILL.md` wrapper so agents can call it
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+The ruleset follows [CLREQ](https://www.w3.org/TR/clreq/) (W3C). Character
+classes follow a curated subset of [UAX #14](https://www.unicode.org/reports/tr14/).

ziban-0.1.0/README.zh-CN.md

@@ -0,0 +1,164 @@
+# ziban
+
+**给"浏览器之外"的一切，做对中文断行。**
+
+[English →](README.md)
+
+浏览器很多年前就有了 `text-spacing-trim`、`line-break: strict` 和真正的禁则处理。
+但除了浏览器，别的地方全都得自己重写一遍——Pillow、ReportLab、SVG、ffmpeg 烧字幕、
+`python-pptx`、canvas——而且几乎都写错了，因为**没有一个地方可以去问**。
+
+`ziban` 就是那个地方：一个纯 Python 的中文排版引擎，把「一段文字 + 一个盒子」
+变成排版师认可的若干行，并且在每次不得不妥协时，给出机器可读的说明。
+
+![同一段文字、同一个栏宽：左边按字数硬切，右边是 ziban](docs/compare.png)
+
+## 八秒钟看懂问题
+
+`if len(s) > N: cut()` 的结果：
+
+```
+他说：「这次不一样。
+」然后关掉了对话框。
+```
+
+`ziban`：
+
+```
+他说：「这次不一样。」
+然后关掉了对话框。
+```
+
+第一行以 `」` 开头。这不是审美问题：[《中文排版需求》(CLREQ)](https://www.w3.org/TR/clreq/)
+明确规定收尾标点不可出现在行首（避头）、起首标点不可出现在行尾（避尾）。
+所有非浏览器的渲染器都在默默违反这条规则——而它违反的，恰恰是读者一眼就能看见的那些标点。
+
+## 安装
+
+```bash
+pip install ziban              # 核心，零依赖
+pip install "ziban[pillow]"    # 需要用真实字体度量时
+```
+
+Python 3.9+。不要浏览器、不要编译、不要 ICU、不要模型。
+
+## 用法
+
+### 命令行
+
+```console
+$ echo "这是一个比较长的段落，用来看断行在真实文本上的表现。" \
+    | ziban wrap - --width-em 8 --ruler
+      +----------------+
+  1   | 这是一个比较长的 |   8.0em
+  2   | 段落，用来看断行 |   8.0em
+  3   | 在真实文本上的表 |   8.0em
+  4   | 现。             |   2.0em
+
+4 line(s), box 8.0em, no diagnostics
+```
+
+行号后面那一列：`>` 表示本行末尾有标点悬挂，`<` 表示有标点挤压，`!` 表示溢出。
+加 `--json` 得到结构化结果，给脚本和 agent 用。
+
+### 库
+
+```python
+from ziban import Style, layout, EmMetrics
+
+page = layout(
+    "他说：「这次不一样。」然后关掉了对话框。",
+    width=10 * 32,                     # 一行 10 个字
+    style=Style(size=32, leading=1.7),
+    metrics=EmMetrics(32),             # 或 PillowMetrics("NotoSerifSC.otf", 32)
+)
+
+for line in page.lines:
+    print(line.text, line.width)
+
+page.diagnostics
+# [Diagnostic(code='ORPHAN_LINE', line=1, ...)]
+```
+
+每一行都带着自己的解释：
+
+```python
+line.adjustments   # (Adjustment(kind='hang', index=10, delta=32.0),)
+line.slack         # 剩余空间
+line.overflow      # 超出盒子的像素，放得下就是 0
+line.justify_spacing
+```
+
+## 它做了什么
+
+| | |
+|---|---|
+| **避头尾** | 收尾标点不进行首，起首标点不留行尾 |
+| **标点挤压** | 差一点点放得下时，全角标点压到半宽 |
+| **行末悬挂** | 宁可让标点悬出边界，也不把它挤到下一行；上限 1 em，且不超过行宽的 1/4 |
+| **中西混排** | 汉字与拉丁文之间可断，拉丁单词内部不断，数字不与单位分家 |
+| **硬断行** | `\n` 一定生效，空行保留 |
+| **诊断** | `OVERFLOW`、`NO_BREAK_OPPORTUNITY`、`KINSOKU_FALLBACK`、`ORPHAN_LINE`，每条都带修复建议 |
+| **确定性** | 同文本 + 同字体 + 同字号 → 逐字节相同的输出，跨平台一致 |
+
+## 它不做什么
+
+- 不调 AI，不要 API key，不做"帮我写文案"。
+- 不要浏览器、不要无头 Chromium、不要装排版引擎。
+- 不做 GUI 编辑器。
+- 不自动发布到任何平台。
+- **不打包任何字体。** 微软雅黑、苹方都不能随包分发；要么自带，要么用思源黑体/Noto（OFL）。
+
+最后一条不是洁癖：一个内置专有字体的库，公司是不能用的。
+
+## 规则是数据，不是 if-else
+
+所有排版策略都在 [`src/ziban/data/clreq.toml`](src/ziban/data/clreq.toml) 里：
+
+```toml
+[kinsoku]
+head_forbidden = "　，、。．；：？！）〕〉》」』】”’｝…"
+tail_forbidden = "（〔〈《「『【“‘｛"
+
+[compress]
+compressed_ratio = 0.5
+chars = "，、。．；：？！）〕〉》」』】”’…"
+
+[hang]
+max_ratio = 1.0
+max_share = 0.25
+```
+
+改行为就改这张表。日文规则集是第二个 TOML，不是第二个引擎。这也是为什么贡献很便宜：
+**绝大多数排版 bug 只值一行数据。**
+
+## 和它们比
+
+| | 禁则 | 挤压 | 悬挂 | 浏览器之外可用 | 确定性 |
+|---|---|---|---|---|---|
+| [heti](https://github.com/sivan/heti) | 靠浏览器 | 部分 | ✗ | ✗ | ✗ |
+| [pangu.py](https://github.com/vinta/pangu.py) | ✗ | ✗ | ✗ | ✓ | ✓ |
+| [budoux](https://github.com/google/budoux) | ✗ | ✗ | ✗ | ✓ | ✓ |
+| 浏览器 `text-spacing-trim` | ✓ | ✓ | 部分 | ✗ | ✓ |
+| **ziban** | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+`budoux` 决定"断在哪里语义上说得过去"，`ziban` 决定"这个断点排版上合不合法"。两者可以叠加。
+
+## 状态
+
+`0.1.0` —— 横排引擎完成，958 个测试全绿（24 段语料 × 6 种行宽 × 6 条不变量，
+外加金标用例）。尚未发布到 PyPI。
+
+接下来：
+
+- **0.2** 跨平台字体探测；连续标点挤压（「。」占一个 em）；Knuth–Plass 式代价断行，
+  让最后一行不再孤零零
+- **0.3** 适配器：ReportLab、SVG、`python-pptx`；竖排放到开关后面
+- **0.4** `cards` 示例：真正渲染 1080×1440 组图；再包一层 `SKILL.md` 让 agent 能调用
+
+## 许可
+
+MIT，见 [LICENSE](LICENSE)。
+
+规则集依照 [CLREQ](https://www.w3.org/TR/clreq/)（W3C）；字符分类是
+[UAX #14](https://www.unicode.org/reports/tr14/) 的裁剪子集。