ライブラリ API¶
ライブラリとして使うだけなら pip install kogo で十分です — serve 追加パッケージ
(FastAPI、uvicorn)はWebアプリ用にのみ必要です。
import kogo
result: kogo.ComparisonResult = kogo.compare_pdfs("old.pdf", "new.pdf", "out/")
kogo.compare_pdfs がエントリーポイントです。このページの残りは戻り値の型付けの
ためのものです — 戻り値自体は実行時には通常の dict です
(output_dir/result.json にも書き出されます)。型付けの有無で挙動は変わりません。
以下のAPIリファレンスは英語で表示されます
このセクションはPythonのdocstringからmkdocstrings によって自動生成されており、docstring自体は英語で書かれています。日本語訳への 貢献に興味があれば、コントリビュートを参照してください。
kogo.compare_pdfs(old_path, new_path, output_dir, *, old_name=None, new_name=None, dpi=144, sensitivity='standard', max_pages=200, previews=True, artifacts=True, on_progress=None)
¶
Compare two revisions of a PDF document and produce marked outputs.
Text is compared at word precision (character precision for CJK text, including supplementary-plane kanji), after reconstructing a reading order from page layout. Figures, equations, and layout changes are detected visually outside text areas, and existing PDF annotations (highlights, comments, ink) are fingerprinted and diffed. Style-only changes (bold, italic, font size) on unchanged text are reported as well. All markers are baked into the output PDFs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
old_path
|
Path
|
PDF of the previous revision. |
required |
new_path
|
Path
|
PDF of the updated revision. |
required |
output_dir
|
Path
|
Directory for results; created if missing. |
required |
old_name
|
str | None
|
Display name of the old file; defaults to its file name. |
None
|
new_name
|
str | None
|
Display name of the new file; defaults to its file name. |
None
|
dpi
|
int
|
Rendering resolution for the visual diff, 96-180. |
144
|
sensitivity
|
str
|
Figure detection sensitivity: "high", "standard", or "low". |
'standard'
|
max_pages
|
int
|
Maximum number of pages allowed per file. |
200
|
previews
|
bool
|
Whether to generate per-page JPEG previews. |
True
|
artifacts
|
bool
|
Whether to bake and save the marked old/new/side-by-side
PDFs. Set to False to skip that I/O when only the JSON summary
is needed (e.g. a CI step); |
True
|
on_progress
|
Callable[[str, int, int], None] | None
|
Optional callback invoked as
|
None
|
Returns:
| Type | Description |
|---|---|
ComparisonResult
|
A |
ComparisonResult
|
|
ComparisonResult
|
|
ComparisonResult
|
|
ComparisonResult
|
|
ComparisonResult
|
|
ComparisonResult
|
|
ComparisonResult
|
Files written to output_dir: result.json always; old-highlighted.pdf, |
ComparisonResult
|
new-highlighted.pdf, and side-by-side.pdf when artifacts is True; |
ComparisonResult
|
previews/ when previews is True. |
Raises:
| Type | Description |
|---|---|
ComparisonError
|
user-facing problems such as encrypted, empty, oversized, unreadable, or non-PDF input. |
Example
import kogo
result = kogo.compare_pdfs("old.pdf", "new.pdf", "out/")
print(result["summary"]["changed_pages"])
ComparisonResult とその仲間¶
これらは TypedDict で、結果を保存したりやり取りしたりする際の型チェックや
エディタの自動補完に役立ちます:
def summarize(result: kogo.ComparisonResult) -> str:
return f"{result['summary']['changed_pages']} pages changed"
kogo.ComparisonResult
¶
Bases: TypedDict
kogo.Files
¶
Bases: TypedDict
kogo.FileInfo
¶
Bases: TypedDict
kogo.Settings
¶
Bases: TypedDict
kogo.Summary
¶
Bases: TypedDict
kogo.Legend
¶
Bases: TypedDict
kogo.Artifacts
¶
Bases: TypedDict
kogo.ArtifactInfo
¶
Bases: TypedDict
kogo.Row
¶
Bases: TypedDict
kogo.RowChanges
¶
Bases: TypedDict
kogo.PageRef
¶
Bases: _PageRefRequired
ComparisonError¶
kogo.ComparisonError
¶
Bases: ValueError
A user-facing PDF comparison error.