tocsmith 0.1.0__tar.gz

tocsmith-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: tocsmith
+Version: 0.1.0
+Summary: Create PDF bookmarks automatically using heuristics, with CLI and async tkinter GUI
+Author-email: Wesley Yang <yxnian@outlook.com>
+Project-URL: Homepage, https://github.com/wesleyel/pdf-bookmark
+Project-URL: Source, https://github.com/wesleyel/pdf-bookmark
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pypdf>=4.2.0
+Requires-Dist: tomli>=2.0.1; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+
+# TocSmith
+
+为 PDF 添加目录书签的实用工具，支持命令行与简易 GUI。通过“手动粘贴目录文本 + 页码偏移”的方式生成 PDF 书签（大纲/Outline）。
+
+- 运行环境：Python 3.9+
+- 依赖：pypdf（写书签）
+- 提供方式：CLI、Tk GUI、Python API
+
+## 功能概览
+- 手动粘贴目录文本（每行以书中页码结尾），自动解析标题、页码与层级（1..6）
+- 支持页码偏移（实际页码 - 书籍页码），用于扫描件/前置页差异
+- 编号前缀会被保留到标题中：如 `第1章`、`1.1` 将出现在最终书签标题里
+- 支持行首星号标记：允许输入 `*1.1 Title` 或 `* 1.1 Title`，输出统一为 `*1.1 Title`
+- 将条目以父子层级写入 PDF 书签
+- 提供 CLI 与 GUI；亦可通过 Python API 使用
+
+## 快速开始
+
+### 安装与运行（uv 推荐）
+本仓库使用 uv 管理与分发工具。
+
+1) 通过uv安装命令行工具（推荐）：
+```bash
+uv tool install tocsmith
+# 安装后可直接使用：
+tocsmith --help
+tocsmith-gui
+```
+
+2) 使用 pip 安装（备选）：
+```bash
+pip install tocsmith
+
+# 现在可直接使用：
+tocsmith --help
+tocsmith-gui
+```
+
+3) 本地开发
+```bash
+git clone https://github.com/wesleyel/pdf-bookmark.git
+cd pdf-bookmark
+uv sync
+
+uv tool install . --reinstall
+
+tocsmith --help
+tocsmith-gui
+```
+
+## 命令行使用（CLI）
+
+```bash
+tocsmith --help
+```
+
+### 通过 TOML 批量执行（自定义格式）
+支持通过 TOML 配置批量执行多个任务。相对路径均以配置文件所在目录为基准；还可以通过 `defaults.input_prefix` 与 `defaults.output_prefix` 设定输入/输出根目录。
+
+示例 `config.toml`：
+
+```toml
+[defaults]
+# global page offset
+page_offset = 0
+# global minimum length
+min_len = 3
+
+# input folder
+input_prefix = "input"
+# output folder
+output_prefix = "output"
+# output file name append
+output_suffix = ".bookmarked.pdf"
+
+[[tasks]]
+# input file name. relative to input_prefix
+input_file = "book1.pdf"
+toc = """
+第一章 绪论 1
+1.1 引言 3
+1.2 数学分析的基本概念 5
+"""
+page_offset = 10
+min_len = 2
+```
+
+运行：
+
+```bash
+tocsmith --config config.toml
+```
+
+说明：
+- `defaults` 中的 `page_offset`、`min_len` 可被每个任务覆盖。
+- `input_prefix` 用于解析任务中的 `input_file`；`output_prefix` 为输出目录根。
+- 输出文件名为 `{stem}{output_suffix}`，其中 `stem` 来源于 `input_file`。
+- 任务可直接内联 `toc` 文本；也兼容 `toc_file` 指定外部文件。
+
+## 图形界面（GUI）
+提供一个基于 Tk 的简易界面，便于在桌面环境下操作：
+```bash
+tocsmith-gui
+# 或
+uv run python -m tocsmith.gui
+```
+基本流程：
+- 选择输入 PDF
+- 可选：修改输出路径
+- 在 “TOC text” 中粘贴目录文本；在 “Page Offset” 填写偏移（实际 - 书籍）
+- 点击 “Parse TOC Text” 查看解析结果
+- 点击 “Generate” 生成带书签的 PDF
+
+提示：Linux 上若缺少 tkinter，可通过安装系统包启用（例如 Debian/Ubuntu：`sudo apt-get update && sudo apt-get install -y python3-tk`）。
+
+## 开发与测试
+
+- 代码检查与测试：
+```bash
+uv tool install .  # 安装命令，便于本地手动验证
+uv run pytest -q
+# 可选：
+uv run ruff check
+uv run mypy tocsmith
+```
+
+- 项目结构：
+```
+tocsmith/
+  core.py   # 目录解析与书签生成核心逻辑
+  cli.py    # 命令行入口
+  gui.py    # Tk GUI 入口
+  tests/    # 单元测试（pytest）
+```
+
+## 许可证
+
+MIT

tocsmith-0.1.0/README.md

@@ -0,0 +1,138 @@
+# TocSmith
+
+为 PDF 添加目录书签的实用工具，支持命令行与简易 GUI。通过“手动粘贴目录文本 + 页码偏移”的方式生成 PDF 书签（大纲/Outline）。
+
+- 运行环境：Python 3.9+
+- 依赖：pypdf（写书签）
+- 提供方式：CLI、Tk GUI、Python API
+
+## 功能概览
+- 手动粘贴目录文本（每行以书中页码结尾），自动解析标题、页码与层级（1..6）
+- 支持页码偏移（实际页码 - 书籍页码），用于扫描件/前置页差异
+- 编号前缀会被保留到标题中：如 `第1章`、`1.1` 将出现在最终书签标题里
+- 支持行首星号标记：允许输入 `*1.1 Title` 或 `* 1.1 Title`，输出统一为 `*1.1 Title`
+- 将条目以父子层级写入 PDF 书签
+- 提供 CLI 与 GUI；亦可通过 Python API 使用
+
+## 快速开始
+
+### 安装与运行（uv 推荐）
+本仓库使用 uv 管理与分发工具。
+
+1) 通过uv安装命令行工具（推荐）：
+```bash
+uv tool install tocsmith
+# 安装后可直接使用：
+tocsmith --help
+tocsmith-gui
+```
+
+2) 使用 pip 安装（备选）：
+```bash
+pip install tocsmith
+
+# 现在可直接使用：
+tocsmith --help
+tocsmith-gui
+```
+
+3) 本地开发
+```bash
+git clone https://github.com/wesleyel/pdf-bookmark.git
+cd pdf-bookmark
+uv sync
+
+uv tool install . --reinstall
+
+tocsmith --help
+tocsmith-gui
+```
+
+## 命令行使用（CLI）
+
+```bash
+tocsmith --help
+```
+
+### 通过 TOML 批量执行（自定义格式）
+支持通过 TOML 配置批量执行多个任务。相对路径均以配置文件所在目录为基准；还可以通过 `defaults.input_prefix` 与 `defaults.output_prefix` 设定输入/输出根目录。
+
+示例 `config.toml`：
+
+```toml
+[defaults]
+# global page offset
+page_offset = 0
+# global minimum length
+min_len = 3
+
+# input folder
+input_prefix = "input"
+# output folder
+output_prefix = "output"
+# output file name append
+output_suffix = ".bookmarked.pdf"
+
+[[tasks]]
+# input file name. relative to input_prefix
+input_file = "book1.pdf"
+toc = """
+第一章 绪论 1
+1.1 引言 3
+1.2 数学分析的基本概念 5
+"""
+page_offset = 10
+min_len = 2
+```
+
+运行：
+
+```bash
+tocsmith --config config.toml
+```
+
+说明：
+- `defaults` 中的 `page_offset`、`min_len` 可被每个任务覆盖。
+- `input_prefix` 用于解析任务中的 `input_file`；`output_prefix` 为输出目录根。
+- 输出文件名为 `{stem}{output_suffix}`，其中 `stem` 来源于 `input_file`。
+- 任务可直接内联 `toc` 文本；也兼容 `toc_file` 指定外部文件。
+
+## 图形界面（GUI）
+提供一个基于 Tk 的简易界面，便于在桌面环境下操作：
+```bash
+tocsmith-gui
+# 或
+uv run python -m tocsmith.gui
+```
+基本流程：
+- 选择输入 PDF
+- 可选：修改输出路径
+- 在 “TOC text” 中粘贴目录文本；在 “Page Offset” 填写偏移（实际 - 书籍）
+- 点击 “Parse TOC Text” 查看解析结果
+- 点击 “Generate” 生成带书签的 PDF
+
+提示：Linux 上若缺少 tkinter，可通过安装系统包启用（例如 Debian/Ubuntu：`sudo apt-get update && sudo apt-get install -y python3-tk`）。
+
+## 开发与测试
+
+- 代码检查与测试：
+```bash
+uv tool install .  # 安装命令，便于本地手动验证
+uv run pytest -q
+# 可选：
+uv run ruff check
+uv run mypy tocsmith
+```
+
+- 项目结构：
+```
+tocsmith/
+  core.py   # 目录解析与书签生成核心逻辑
+  cli.py    # 命令行入口
+  gui.py    # Tk GUI 入口
+  tests/    # 单元测试（pytest）
+```
+
+## 许可证
+
+MIT

tocsmith-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "tocsmith"
+version = "0.1.0"
+description = "Create PDF bookmarks automatically using heuristics, with CLI and async tkinter GUI"
+authors = [{ name = "Wesley Yang", email = "yxnian@outlook.com" }]
+urls = { Homepage = "https://github.com/wesleyel/pdf-bookmark", Source = "https://github.com/wesleyel/pdf-bookmark" }
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+
+dependencies = [
+  "pypdf>=4.2.0",
+  "tomli>=2.0.1; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.2",
+  "pytest-cov>=5.0",
+  "ruff>=0.5.0",
+  "mypy>=1.10.0",
+]
+
+[project.scripts]
+tocsmith = "tocsmith.cli:main"
+tocsmith-gui = "tocsmith.gui:main"
+
+[tool.uv]
+package = true
+
+[tool.pytest.ini_options]
+addopts = "-q"
+pythonpath = ["."]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tocsmith*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.mypy]
+python_version = "3.9"
+strict = false
+warn_unused_ignores = true
+ignore_missing_imports = true

tocsmith-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tocsmith-0.1.0/tocsmith/__init__.py

@@ -0,0 +1,9 @@
+__all__ = [
+    "Heading",
+    "parse_toc_lines",
+    "generate_bookmarks",
+]
+
+from .core import Heading, parse_toc_lines, generate_bookmarks  # noqa: E402
+
+

tocsmith-0.1.0/tocsmith/cli.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+import sys
+
+from .core import generate_bookmarks, parse_toc_lines
+
+try:  # Python 3.11+
+    import tomllib  # type: ignore[attr-defined]
+except ModuleNotFoundError:  # Python 3.9-3.10
+    try:
+        import tomli as tomllib  # type: ignore[assignment]
+    except ModuleNotFoundError:
+        tomllib = None  # type: ignore[assignment]
+
+
+def parse_args(argv: List[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(prog="tocsmith", description="Auto add bookmarks to PDF")
+    p.add_argument("pdf", nargs="?", help="Input PDF path")
+    p.add_argument("-o", "--out", help="Output PDF path; default: <name>.bookmarked.pdf")
+    p.add_argument("--min-len", type=int, default=3, help="Minimum heading text length")
+    p.add_argument("--page-offset", type=int, default=0, help="Page offset: actual - book page")
+    p.add_argument("--toc-file", help="Path to a text file containing TOC lines")
+    p.add_argument(
+        "-c",
+        "--config",
+        help="Path to a TOML config file for batch tasks (overrides single-run args)",
+    )
+    return p.parse_args(argv)
+
+
+def _resolve_relative(base_dir: Path, maybe_path: Optional[str]) -> Optional[Path]:
+    """Resolve a path relative to base_dir if provided; return None if empty."""
+    if not maybe_path:
+        return None
+    p = Path(maybe_path)
+    return (base_dir / p).resolve() if not p.is_absolute() else p
+
+
+def _run_single(
+    src: Path,
+    out: Optional[Path],
+    toc_file: Optional[Path],
+    page_offset: int,
+    min_len: int,
+    toc_text: Optional[str] = None,
+) -> int:
+    """Run a single task and return process exit code."""
+    if not src.exists():
+        print(f"File not found: {src}")
+        return 2
+    out_path = out if out else src.with_suffix(".bookmarked.pdf")
+
+    headings = []
+    if toc_text is not None and toc_text.strip():
+        headings = parse_toc_lines(toc_text, page_offset=page_offset, min_len=min_len)
+    elif toc_file:
+        file_text = Path(toc_file).read_text(encoding="utf-8")
+        headings = parse_toc_lines(file_text, page_offset=page_offset, min_len=min_len)
+    else:
+        print("No TOC source provided (use --toc-file). Producing a copy without outline.")
+        headings = []
+    if not headings:
+        print("No headings; output will be a copy without outline.")
+    generate_bookmarks(str(src), str(out_path), headings)
+    print(f"Wrote: {out_path}")
+    return 0
+
+
+def _run_batch(config_path: Path) -> int:
+    '''Run batch tasks from a TOML config file.
+
+    Config schema (customized):
+    [defaults]
+    page_offset = 0
+    min_len = 3
+    input_prefix = "input"              # optional; base dir for input files
+    output_prefix = "output"            # optional; base dir for outputs
+    output_suffix = ".bookmarked.pdf"   # optional; appended to stem
+
+    [[tasks]]
+    input_file = "book1.pdf"            # required; relative to input_prefix
+    toc = """..."""                     # optional inline TOC text
+    # Alternatively: toc_file = "toc.txt"
+    page_offset = 10                     # optional overrides default
+    min_len = 2                          # optional overrides default
+    '''
+    if tomllib is None:
+        print("Error: TOML support not available. Please install 'tomli' for Python < 3.11.")
+        return 2
+
+    if not config_path.exists():
+        print(f"Config file not found: {config_path}")
+        return 2
+
+    with open(config_path, "rb") as f:
+        data = tomllib.load(f)
+
+    base_dir = config_path.parent
+    defaults: Dict[str, Any] = data.get("defaults", {}) or {}
+    tasks: List[Dict[str, Any]] = data.get("tasks", []) or []
+    if not isinstance(tasks, list) or not tasks:
+        print("No tasks found in config (expected [[tasks]] array)")
+        return 2
+
+    default_page_offset = int(defaults.get("page_offset", 0) or 0)
+    default_min_len = int(defaults.get("min_len", 3) or 3)
+    input_prefix = str(defaults.get("input_prefix", "")).strip() or ""
+    output_prefix = str(defaults.get("output_prefix", "")).strip() or ""
+    output_suffix = (
+        str(defaults.get("output_suffix", ".bookmarked.pdf")).strip() or ".bookmarked.pdf"
+    )
+
+    input_base = (base_dir / input_prefix).resolve() if input_prefix else base_dir
+    output_base = (base_dir / output_prefix).resolve() if output_prefix else base_dir
+
+    failures = 0
+    for idx, t in enumerate(tasks, start=1):
+        input_file_val = t.get("input_file")
+        if not input_file_val:
+            print(f"[Task {idx}] Skipped: missing 'input_file'")
+            failures += 1
+            continue
+
+        # Resolve input file relative to input_base
+        src = (input_base / str(input_file_val)).resolve()
+
+        # Determine output path {output_base}/{stem}{output_suffix}
+        try:
+            out_stem = Path(str(input_file_val)).stem
+        except Exception:
+            out_stem = "output"
+        out = (output_base / f"{out_stem}{output_suffix}").resolve()
+
+        # Obtain TOC from inline 'toc' or optional 'toc_file' fallback
+        toc_inline: Optional[str] = t.get("toc")
+        toc_file = _resolve_relative(base_dir, t.get("toc_file"))
+        page_offset = int(t.get("page_offset", default_page_offset) or default_page_offset)
+        min_len = int(t.get("min_len", default_min_len) or default_min_len)
+
+        print(
+            f"[Task {idx}] Running: src={src} out={out} "
+            f"toc={'inline' if (toc_inline and toc_inline.strip()) else (toc_file or '<none>')} "
+            f"offset={page_offset} min_len={min_len}"
+        )
+        try:
+            # Ensure output directory exists
+            out.parent.mkdir(parents=True, exist_ok=True)
+            code = _run_single(
+                src=Path(src),
+                out=out,
+                toc_file=toc_file,
+                page_offset=page_offset,
+                min_len=min_len,
+                toc_text=toc_inline,
+            )
+            if code != 0:
+                failures += 1
+        except Exception as e:
+            failures += 1
+            print(f"[Task {idx}] Failed: {e}")
+
+    if failures:
+        print(f"Completed with {failures} failure(s)")
+        return 1
+    print("All tasks completed successfully")
+    return 0
+
+
+def main(argv: List[str] | None = None) -> int:
+    ns = parse_args(argv)
+    if ns.config:
+        return _run_batch(Path(ns.config))
+
+    if not ns.pdf:
+        print("Error: either specify a PDF or use --config for batch mode.")
+        return 2
+
+    src = Path(ns.pdf)
+    out = Path(ns.out) if ns.out else None
+    return _run_single(
+        src=src,
+        out=out,
+        toc_file=Path(ns.toc_file) if ns.toc_file else None,
+        page_offset=ns.page_offset,
+        min_len=ns.min_len,
+    )
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())
+
+

tocsmith-0.1.0/tocsmith/core.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+from typing import Iterable, List, Tuple, Optional
+
+from pypdf import PdfReader, PdfWriter
+
+
+@dataclass
+class Heading:
+    title: str
+    page: int  # 1-based
+    level: int  # 1..6
+
+
+def generate_bookmarks(src_pdf: str, out_pdf: str, headings: Iterable[Heading]) -> None:
+    """Write given headings into a new PDF file as outline/bookmarks."""
+    reader = PdfReader(src_pdf)
+    writer = PdfWriter()
+    for page in reader.pages:
+        writer.add_page(page)
+
+    # Build hierarchical outlines using a simple stack by levels
+    stack: List[Tuple[int, object]] = []  # (level, parent_ref)
+
+    for h in headings:
+        page_index = max(0, min(len(reader.pages) - 1, h.page - 1))
+        while stack and stack[-1][0] >= h.level:
+            stack.pop()
+        parent = stack[-1][1] if stack else None
+        dest = writer.add_outline_item(h.title, page_index, parent=parent)
+        stack.append((h.level, dest))
+
+    with open(out_pdf, "wb") as f:
+        writer.write(f)
+
+
+# -------------------- TOC parsing utilities --------------------
+
+_NUM_PREFIX_RE = re.compile(
+    r"^\s*(?P<num>(第\s*\d+[一二三四五六七八九十百千]*[章节节部分编]?)|((\d+\.)+\d+)|\d+)?\s*"
+)
+_TRAILING_PAGE_RE = re.compile(r"(?P<page>\d{1,5})\s*$")
+
+
+def _infer_level_from_numbering(num: Optional[str]) -> int:
+    if not num:
+        return 1
+    num = num.strip()
+    if num.startswith("第"):
+        # "第1章" style => top-level
+        return 1
+    if "." in num:
+        # "1.2.3" => level = segments + 1 (so 1.2 is level 2)
+        return min(6, max(1, num.count(".") + 1))
+    # Simple leading integer like "1" => level 1
+    return 1
+
+
+def parse_toc_lines(toc_text: str, page_offset: int = 0, min_len: int = 1) -> List[Heading]:
+    """
+    Parse a pasted TOC text into Heading entries.
+    - Each line should end with the book page number (digits)
+    - Leading numbering like "第1章" or "1.2" is used to infer the level
+    - page_offset is added to the parsed page number to map to PDF actual pages
+    """
+    headings: List[Heading] = []
+    for raw_line in toc_text.splitlines():
+        line = raw_line.strip()
+        if len(line) < min_len:
+            continue
+        # Detect and temporarily strip leading asterisk marker(s)
+        star_prefix = ""
+        m_star = re.match(r"^\*+\s*", line)
+        if m_star:
+            stars = m_star.group(0)
+            star_count = stars.count("*")
+            # Preserve star(s) without trailing space; spacing will be normalized later
+            star_prefix = ("*" * star_count)
+            line = line[m_star.end() :].lstrip()
+
+        # Extract trailing page digits
+        page_m = _TRAILING_PAGE_RE.search(line)
+        if not page_m:
+            continue
+        page_num = int(page_m.group("page"))
+        # Remove trailing page from the line
+        line_wo_page = line[: page_m.start()].rstrip()
+        # Extract leading numbering if exists
+        num_m = _NUM_PREFIX_RE.match(line_wo_page)
+        numbering = None
+        title_part = line_wo_page
+        if num_m:
+            numbering = num_m.group("num")
+            title_part = line_wo_page[num_m.end() :].strip()
+        # Build title while preserving numbering prefix (e.g., "第1章" or "1.1")
+        if numbering:
+            combined = f"{numbering.strip()} {title_part}".strip()
+        else:
+            combined = title_part
+        # Cleanup whitespace
+        title = re.sub(r"\s+", " ", combined)
+        if not title:
+            # fallback to raw without numbering
+            title = line_wo_page.strip()
+        # Restore asterisk prefix if present
+        if star_prefix:
+            # No space between star(s) and numbering/title
+            title = f"{star_prefix}{title}".strip()
+        level = _infer_level_from_numbering(numbering)
+        pdf_page = max(1, page_num + page_offset)
+        headings.append(Heading(title=title, page=pdf_page, level=level))
+
+    # Sort by page then by inferred level
+    headings.sort(key=lambda h: (h.page, h.level, h.title.lower()))
+    return headings
+
+
+## URL/website TOC fetching intentionally removed; only manual text input is supported.
+
+

tocsmith-0.1.0/tocsmith/gui.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import asyncio
+import threading
+import tkinter as tk
+from tkinter import filedialog, messagebox, ttk
+from tkinter import font as tkfont
+from pathlib import Path
+from typing import Optional
+import platform
+import subprocess
+import os
+
+from .core import generate_bookmarks, parse_toc_lines
+
+
+# Run blocking CPU/IO bound function in thread to keep UI responsive
+async def run_in_thread(func, *args, **kwargs):
+    loop = asyncio.get_event_loop()
+    return await loop.run_in_executor(None, lambda: func(*args, **kwargs))
+
+
+class App:
+    def __init__(self, root: tk.Tk) -> None:
+        self.root = root
+        self.root.title("TocSmith")
+        self.root.geometry("820x640")
+
+        self.input_path: Optional[Path] = None
+        self.output_path: Optional[Path] = None
+
+        self._build_ui()
+        self._setup_event_loop()
+
+    def _build_ui(self) -> None:
+        frm = ttk.Frame(self.root, padding=10)
+        frm.pack(fill=tk.BOTH, expand=True)
+
+        # Prominent primary action
+        style = ttk.Style(self.root)
+        big_font = tkfont.Font(size=12, weight="bold")
+        style.configure("Primary.TButton", font=big_font, padding=(10, 12))
+
+        # Input selector
+        in_row = ttk.Frame(frm)
+        in_row.pack(fill=tk.X)
+        ttk.Label(in_row, text="Input PDF:").pack(side=tk.LEFT)
+        self.in_var = tk.StringVar()
+        self.in_entry = ttk.Entry(in_row, textvariable=self.in_var)
+        self.in_entry.pack(side=tk.LEFT, fill=tk.X, expand=True, padx=6)
+        ttk.Button(in_row, text="Browse", command=self.choose_input).pack(side=tk.LEFT)
+
+        # Output path
+        out_row = ttk.Frame(frm)
+        out_row.pack(fill=tk.X, pady=(8, 0))
+        ttk.Label(out_row, text="Output PDF:").pack(side=tk.LEFT)
+        self.out_var = tk.StringVar()
+        self.out_entry = ttk.Entry(out_row, textvariable=self.out_var)
+        self.out_entry.pack(side=tk.LEFT, fill=tk.X, expand=True, padx=6)
+        ttk.Button(out_row, text="Browse", command=self.choose_output).pack(side=tk.LEFT)
+        ttk.Button(out_row, text="Open Folder", command=self.open_output_folder).pack(side=tk.LEFT, padx=(6, 0))
+
+        # Offset + Controls
+        ctrl = ttk.Frame(frm)
+        ctrl.pack(fill=tk.X, pady=10)
+        ttk.Label(ctrl, text="Page Offset:").pack(side=tk.LEFT)
+        self.offset_var = tk.StringVar(value="0")
+        self.offset_entry = ttk.Entry(ctrl, textvariable=self.offset_var, width=6)
+        self.offset_entry.pack(side=tk.LEFT, padx=(4, 12))
+
+        # TOC input
+        toc_row = ttk.Frame(frm)
+        toc_row.pack(fill=tk.BOTH, expand=True)
+        left = ttk.Frame(toc_row)
+        left.pack(side=tk.LEFT, fill=tk.BOTH, expand=True)
+        right = ttk.Frame(toc_row, width=260)
+        right.pack(side=tk.LEFT, fill=tk.Y)
+
+        ttk.Label(left, text="TOC text:").pack(anchor=tk.W)
+        self.toc_text = tk.Text(left, height=10)
+        self.toc_text.pack(fill=tk.BOTH, expand=True)
+        btns = ttk.Frame(left)
+        btns.pack(fill=tk.X, pady=4)
+        ttk.Button(btns, text="Parse TOC Text", command=self._on_parse_toc_text).pack(side=tk.LEFT)
+
+        # Tree view for headings
+        self.tree = ttk.Treeview(right, columns=("title", "page", "level"), show="headings", height=15)
+        self.tree.heading("title", text="Title")
+        self.tree.heading("page", text="Page")
+        self.tree.heading("level", text="Level")
+        self.tree.column("title", width=160)
+        self.tree.pack(fill=tk.BOTH, expand=True)
+
+        ttk.Button(frm, text="Generate", command=self._on_generate, style="Primary.TButton").pack(
+            fill=tk.X, pady=(0, 10)
+        )
+
+        self.status_var = tk.StringVar(value="Ready")
+        ttk.Label(frm, textvariable=self.status_var).pack(anchor=tk.W, pady=(8, 0))
+
+    def _setup_event_loop(self) -> None:
+        # tkinter mainloop is blocking; integrate asyncio by polling
+        self.loop = asyncio.new_event_loop()
+        self.loop_thread = threading.Thread(target=self.loop.run_forever, daemon=True)
+        self.loop_thread.start()
+        self.root.after(50, self._poll_loop)
+
+    def _poll_loop(self) -> None:
+        # UI heartbeat
+        if self.root.winfo_exists():
+            self.root.after(50, self._poll_loop)
+
+    def _set_status(self, text: str) -> None:
+        self.status_var.set(text)
+        self.root.update_idletasks()
+
+    def choose_input(self) -> None:
+        path = filedialog.askopenfilename(filetypes=[("PDF", "*.pdf")])
+        if path:
+            self.input_path = Path(path)
+            self.in_var.set(path)
+            if not self.out_var.get():
+                # Default output to Downloads directory with suffixed name
+                downloads = self._get_downloads_dir()
+                default_out = downloads / f"{self.input_path.stem}.bookmarked.pdf"
+                self.output_path = default_out
+                self.out_var.set(str(default_out))
+
+    def choose_output(self) -> None:
+        # Suggest Downloads as default directory, and a sensible default filename
+        downloads = self._get_downloads_dir()
+        initialdir = str(downloads)
+        initialfile = ""
+        if self.input_path:
+            initialfile = f"{self.input_path.stem}.bookmarked.pdf"
+        elif self.out_var.get():
+            try:
+                p = Path(self.out_var.get())
+                initialdir = str(p.parent)
+                initialfile = p.name
+            except Exception:
+                pass
+
+        path = filedialog.asksaveasfilename(
+            defaultextension=".pdf",
+            filetypes=[("PDF", "*.pdf")],
+            initialdir=initialdir,
+            initialfile=initialfile,
+        )
+        if path:
+            self.output_path = Path(path)
+            self.out_var.set(path)
+
+    def _clear_tree(self) -> None:
+        for i in self.tree.get_children():
+            self.tree.delete(i)
+
+    def _populate_tree(self, headings) -> None:
+        self._clear_tree()
+        for h in headings:
+            self.tree.insert("", tk.END, values=(h.title, h.page, h.level))
+
+    # Auto analysis removed
+
+    def _on_generate(self) -> None:
+        if not self.in_var.get():
+            messagebox.showwarning("Missing", "Please choose an input PDF")
+            return
+        if not self.out_var.get():
+            messagebox.showwarning("Missing", "Please choose an output path")
+            return
+
+        async def task():
+            self._set_status("Generating…")
+            # Prefer TOC from text if present
+            text = self.toc_text.get("1.0", tk.END).strip()
+            hs = []
+            if text:
+                try:
+                    offset = int(self.offset_var.get() or 0)
+                except ValueError:
+                    offset = 0
+                hs = await run_in_thread(parse_toc_lines, text, offset)
+            else:
+                hs = []
+            await run_in_thread(generate_bookmarks, self.in_var.get(), self.out_var.get(), hs)
+            self._set_status("Done")
+            messagebox.showinfo("Success", f"Wrote: {self.out_var.get()}")
+
+        asyncio.run_coroutine_threadsafe(task(), self.loop)
+
+    def _on_parse_toc_text(self) -> None:
+        text = self.toc_text.get("1.0", tk.END).strip()
+        if not text:
+            messagebox.showwarning("Empty", "Please paste TOC text or URL first")
+            return
+        try:
+            offset = int(self.offset_var.get() or 0)
+        except ValueError:
+            offset = 0
+
+        async def task():
+            self._set_status("Parsing TOC…")
+            hs = await run_in_thread(parse_toc_lines, text, offset)
+            self._populate_tree(hs)
+            self._set_status(f"Parsed {len(hs)} entries")
+
+        asyncio.run_coroutine_threadsafe(task(), self.loop)
+
+    # URL fetch removed: manual TOC input only
+
+    def _get_downloads_dir(self) -> Path:
+        """Return the user's Downloads directory, fallback to home if missing."""
+        downloads = Path.home() / "Downloads"
+        return downloads if downloads.exists() else Path.home()
+
+    def open_output_folder(self) -> None:
+        """Open the output directory in the system file manager.
+
+        If an explicit output path is set, opens its parent directory;
+        otherwise opens the Downloads directory.
+        """
+        target_dir: Path
+        try:
+            if self.out_var.get():
+                target_dir = Path(self.out_var.get()).expanduser().resolve().parent
+            else:
+                target_dir = self._get_downloads_dir()
+        except Exception:
+            target_dir = self._get_downloads_dir()
+
+        if not target_dir.exists():
+            messagebox.showwarning("Missing", f"Directory does not exist: {target_dir}")
+            return
+
+        system = platform.system().lower()
+        try:
+            if system == "windows":
+                os.startfile(str(target_dir))  # type: ignore[attr-defined]
+            elif system == "darwin":
+                subprocess.run(["open", str(target_dir)], check=False)
+            else:
+                subprocess.run(["xdg-open", str(target_dir)], check=False)
+        except Exception as e:
+            messagebox.showerror("Error", f"Failed to open folder: {e}")
+
+
+def main() -> None:  # pragma: no cover
+    root = tk.Tk()
+    App(root)
+    root.mainloop()
+
+

tocsmith-0.1.0/tocsmith/tests/test_core.py

@@ -0,0 +1,165 @@
+from pathlib import Path
+import re
+
+import pytest
+
+from tocsmith.core import Heading, generate_bookmarks, parse_toc_lines
+from tocsmith import cli
+import textwrap
+
+
+@pytest.fixture()
+def tmp_pdf(tmp_path: Path) -> Path:
+    # Create a minimal single-page PDF using pypdf
+    from pypdf import PdfWriter
+
+    out = tmp_path / "a.pdf"
+    w = PdfWriter()
+    w.add_blank_page(width=595, height=842)  # A4
+    with out.open("wb") as f:
+        w.write(f)
+    return out
+
+
+def test_generate_bookmarks_no_headings(tmp_pdf: Path, tmp_path: Path):
+    out = tmp_path / "out.pdf"
+    generate_bookmarks(str(tmp_pdf), str(out), [])
+    assert out.exists() and out.stat().st_size > 0
+
+
+def test_generate_bookmarks_with_headings(tmp_pdf: Path, tmp_path: Path):
+    out = tmp_path / "out.pdf"
+    hs = [Heading(title="Intro", page=1, level=1)]
+    generate_bookmarks(str(tmp_pdf), str(out), hs)
+    assert out.exists() and out.stat().st_size > 0
+
+
+def test_no_auto_analysis_copy_only(tmp_pdf: Path):
+    # Without headings, we can still generate a copy
+    from pypdf import PdfReader
+    out = tmp_pdf.with_name("copy.pdf")
+    generate_bookmarks(str(tmp_pdf), str(out), [])
+    r = PdfReader(str(out))
+    assert len(r.pages) == 1
+
+
+def test_parse_toc_lines_basic_offset():
+    toc = """
+    第1章 基础 1
+    1.1 Scala解释器 3
+    1.2 声明值和变量 4
+    2 进阶 10
+    """.strip()
+    hs = parse_toc_lines(toc, page_offset=14)
+    assert [h.page for h in hs] == [15, 17, 18, 24]
+    # Ensure titles exist and have reasonable levels
+    assert hs[0].level == 1
+    assert hs[1].level >= 2
+
+
+def test_parse_toc_lines_robust_trailing_spaces_and_tabs():
+    toc = "\n".join([
+        "第1章   基础\t 1",
+        " 1.1\tScala解释器 \t 3 ",
+        "附录 A  100",
+    ])
+    hs = parse_toc_lines(toc, page_offset=0)
+    assert hs[0].page == 1
+    assert hs[1].page == 3
+    # When no numeric prefix (like "附录 A"), default to level 1
+    assert any(h.title.startswith("附录") and h.level == 1 for h in hs)
+
+
+def test_parse_toc_lines_preserve_asterisk_prefix():
+    toc = "\n".join([
+        "*1.1 subdirectory 12",
+        "* 1.2 another subdirectory 13",
+        "1.3 normal 14",
+    ])
+    hs = parse_toc_lines(toc, page_offset=0)
+    titles = [h.title for h in hs]
+    assert titles[0].startswith("*") and "subdirectory" in titles[0]
+    assert titles[1].startswith("*") and "another subdirectory" in titles[1]
+    assert not titles[2].startswith("*")
+
+
+def test_batch_config_custom_format(tmp_path: Path, monkeypatch):
+    # Arrange input/output structure
+    input_dir = tmp_path / "input"
+    output_dir = tmp_path / "output"
+    input_pdf = input_dir / "book1.pdf"
+    input_dir.mkdir(parents=True, exist_ok=True)
+    # Create a tiny but valid one-page PDF for reading
+    from pypdf import PdfWriter
+    writer = PdfWriter()
+    writer.add_blank_page(width=100, height=100)
+    with input_pdf.open("wb") as f:
+        writer.write(f)
+
+    config_text = textwrap.dedent('''
+        [defaults]
+        page_offset = 1
+        min_len = 1
+        input_prefix = "input"
+        output_prefix = "output"
+        output_suffix = ".bookmarked.pdf"
+
+        [[tasks]]
+        input_file = "book1.pdf"
+        toc = """
+        第一章 绪论 1
+        1.1 引言 2
+        """
+        page_offset = 2
+        min_len = 1
+        ''').strip()
+
+    config_path = tmp_path / "config.toml"
+    config_path.write_text(config_text, encoding="utf-8")
+
+    # Capture calls to generate_bookmarks
+    captured = {}
+
+    def fake_generate(src: str, out: str, headings):
+        captured["src"] = Path(src)
+        captured["out"] = Path(out)
+        captured["headings"] = list(headings)
+
+    monkeypatch.setattr(cli, "generate_bookmarks", fake_generate)
+
+    # Act
+    code = cli._run_batch(config_path)
+
+    # Assert
+    assert code == 0
+    assert captured["src"].resolve() == input_pdf.resolve()
+    assert captured["out"].resolve() == (output_dir / "book1.bookmarked.pdf").resolve()
+    assert len(captured["headings"]) == 2
+
+
+def test_parse_toc_lines_preserve_numbering_prefix_in_title():
+    toc = "\n".join([
+        "第1章 计算机系统概述 1",
+        "1.1 操作系统的基本概念 2",
+        "2 其他章节 10",
+    ])
+    hs = parse_toc_lines(toc, page_offset=0)
+    titles = [h.title for h in hs]
+    # Ensure numbering like "第1章" and "1.1" are preserved in the final title
+    assert any(t.startswith("第1章 ") and "计算机系统概述" in t for t in titles)
+    assert any(t.startswith("1.1 ") and "操作系统的基本概念" in t for t in titles)
+    assert any(t.startswith("2 ") and "其他章节" in t for t in titles)
+
+
+def test_parse_toc_lines_preserve_numbering_with_asterisk():
+    toc = "\n".join([
+        "*1.1 星标小节 12",
+        "* 2 星标章节 13",
+    ])
+    hs = parse_toc_lines(toc, page_offset=0)
+    titles = [h.title for h in hs]
+    # Star prefix should precede the numbering, and numbering should remain
+    assert any(t.startswith("*1.1 ") and "星标小节" in t for t in titles)
+    assert any(t.startswith("*2 ") and "星标章节" in t for t in titles)
+
+

tocsmith-0.1.0/tocsmith.egg-info/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: tocsmith
+Version: 0.1.0
+Summary: Create PDF bookmarks automatically using heuristics, with CLI and async tkinter GUI
+Author-email: Wesley Yang <yxnian@outlook.com>
+Project-URL: Homepage, https://github.com/wesleyel/pdf-bookmark
+Project-URL: Source, https://github.com/wesleyel/pdf-bookmark
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pypdf>=4.2.0
+Requires-Dist: tomli>=2.0.1; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+
+# TocSmith
+
+为 PDF 添加目录书签的实用工具，支持命令行与简易 GUI。通过“手动粘贴目录文本 + 页码偏移”的方式生成 PDF 书签（大纲/Outline）。
+
+- 运行环境：Python 3.9+
+- 依赖：pypdf（写书签）
+- 提供方式：CLI、Tk GUI、Python API
+
+## 功能概览
+- 手动粘贴目录文本（每行以书中页码结尾），自动解析标题、页码与层级（1..6）
+- 支持页码偏移（实际页码 - 书籍页码），用于扫描件/前置页差异
+- 编号前缀会被保留到标题中：如 `第1章`、`1.1` 将出现在最终书签标题里
+- 支持行首星号标记：允许输入 `*1.1 Title` 或 `* 1.1 Title`，输出统一为 `*1.1 Title`
+- 将条目以父子层级写入 PDF 书签
+- 提供 CLI 与 GUI；亦可通过 Python API 使用
+
+## 快速开始
+
+### 安装与运行（uv 推荐）
+本仓库使用 uv 管理与分发工具。
+
+1) 通过uv安装命令行工具（推荐）：
+```bash
+uv tool install tocsmith
+# 安装后可直接使用：
+tocsmith --help
+tocsmith-gui
+```
+
+2) 使用 pip 安装（备选）：
+```bash
+pip install tocsmith
+
+# 现在可直接使用：
+tocsmith --help
+tocsmith-gui
+```
+
+3) 本地开发
+```bash
+git clone https://github.com/wesleyel/pdf-bookmark.git
+cd pdf-bookmark
+uv sync
+
+uv tool install . --reinstall
+
+tocsmith --help
+tocsmith-gui
+```
+
+## 命令行使用（CLI）
+
+```bash
+tocsmith --help
+```
+
+### 通过 TOML 批量执行（自定义格式）
+支持通过 TOML 配置批量执行多个任务。相对路径均以配置文件所在目录为基准；还可以通过 `defaults.input_prefix` 与 `defaults.output_prefix` 设定输入/输出根目录。
+
+示例 `config.toml`：
+
+```toml
+[defaults]
+# global page offset
+page_offset = 0
+# global minimum length
+min_len = 3
+
+# input folder
+input_prefix = "input"
+# output folder
+output_prefix = "output"
+# output file name append
+output_suffix = ".bookmarked.pdf"
+
+[[tasks]]
+# input file name. relative to input_prefix
+input_file = "book1.pdf"
+toc = """
+第一章 绪论 1
+1.1 引言 3
+1.2 数学分析的基本概念 5
+"""
+page_offset = 10
+min_len = 2
+```
+
+运行：
+
+```bash
+tocsmith --config config.toml
+```
+
+说明：
+- `defaults` 中的 `page_offset`、`min_len` 可被每个任务覆盖。
+- `input_prefix` 用于解析任务中的 `input_file`；`output_prefix` 为输出目录根。
+- 输出文件名为 `{stem}{output_suffix}`，其中 `stem` 来源于 `input_file`。
+- 任务可直接内联 `toc` 文本；也兼容 `toc_file` 指定外部文件。
+
+## 图形界面（GUI）
+提供一个基于 Tk 的简易界面，便于在桌面环境下操作：
+```bash
+tocsmith-gui
+# 或
+uv run python -m tocsmith.gui
+```
+基本流程：
+- 选择输入 PDF
+- 可选：修改输出路径
+- 在 “TOC text” 中粘贴目录文本；在 “Page Offset” 填写偏移（实际 - 书籍）
+- 点击 “Parse TOC Text” 查看解析结果
+- 点击 “Generate” 生成带书签的 PDF
+
+提示：Linux 上若缺少 tkinter，可通过安装系统包启用（例如 Debian/Ubuntu：`sudo apt-get update && sudo apt-get install -y python3-tk`）。
+
+## 开发与测试
+
+- 代码检查与测试：
+```bash
+uv tool install .  # 安装命令，便于本地手动验证
+uv run pytest -q
+# 可选：
+uv run ruff check
+uv run mypy tocsmith
+```
+
+- 项目结构：
+```
+tocsmith/
+  core.py   # 目录解析与书签生成核心逻辑
+  cli.py    # 命令行入口
+  gui.py    # Tk GUI 入口
+  tests/    # 单元测试（pytest）
+```
+
+## 许可证
+
+MIT

tocsmith-0.1.0/tocsmith.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+tocsmith/__init__.py
+tocsmith/cli.py
+tocsmith/core.py
+tocsmith/gui.py
+tocsmith.egg-info/PKG-INFO
+tocsmith.egg-info/SOURCES.txt
+tocsmith.egg-info/dependency_links.txt
+tocsmith.egg-info/entry_points.txt
+tocsmith.egg-info/requires.txt
+tocsmith.egg-info/top_level.txt
+tocsmith/tests/test_core.py

tocsmith-0.1.0/tocsmith.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tocsmith-0.1.0/tocsmith.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+tocsmith = tocsmith.cli:main
+tocsmith-gui = tocsmith.gui:main

tocsmith-0.1.0/tocsmith.egg-info/requires.txt

@@ -0,0 +1,10 @@
+pypdf>=4.2.0
+
+[:python_version < "3.11"]
+tomli>=2.0.1
+
+[dev]
+pytest>=8.2
+pytest-cov>=5.0
+ruff>=0.5.0
+mypy>=1.10.0

tocsmith-0.1.0/tocsmith.egg-info/top_level.txt

@@ -0,0 +1 @@
+tocsmith