epub-generator 0.1.3__py3-none-any.whl

epub_generator/generation/gen_chapter.py

@@ -0,0 +1,177 @@
+from typing import Generator
+from xml.etree.ElementTree import Element
+
+from ..context import Context
+from ..i18n import I18N
+from ..types import (
+    Chapter,
+    ContentBlock,
+    Formula,
+    HTMLTag,
+    Image,
+    Mark,
+    Table,
+    TextBlock,
+    TextKind,
+)
+from .gen_asset import process_formula, process_image, process_table
+from .xml_utils import serialize_element, set_epub_type
+
+
+def generate_chapter(
+    context: Context,
+    chapter: Chapter,
+    i18n: I18N,
+) -> str:
+    return context.template.render(
+        template="part.xhtml",
+        i18n=i18n,
+        content=[
+            serialize_element(child)
+            for child in _render_contents(context, chapter)
+        ],
+        citations=[
+            serialize_element(child)
+            for child in _render_footnotes(context, chapter)
+        ],
+    )
+
+def _render_contents(
+    context: Context,
+    chapter: Chapter,
+) -> Generator[Element, None, None]:
+    for block in chapter.elements:
+        layout = _render_content_block(context, block)
+        if layout is not None:
+            yield layout
+
+def _render_footnotes(
+    context: Context,
+    chapter: Chapter,
+) -> Generator[Element, None, None]:
+    for footnote in chapter.footnotes:
+        if not footnote.has_mark or not footnote.contents:
+            continue
+
+        # Use <aside> with EPUB 3.0 semantic attributes
+        citation_aside = Element("aside")
+        citation_aside.attrib = {
+            "id": f"fn-{footnote.id}",
+            "class": "footnote",
+        }
+        set_epub_type(citation_aside, "footnote")
+
+        for block in footnote.contents:
+            layout = _render_content_block(context, block)
+            if layout is not None:
+                citation_aside.append(layout)
+
+        if len(citation_aside) == 0:
+            continue
+
+        # Back-reference link with EPUB 3.0 attributes
+        ref = Element("a")
+        ref.text = f"[{footnote.id}]"
+        ref.attrib = {
+            "href": f"#ref-{footnote.id}",
+        }
+        first_layout = citation_aside[0]
+        if first_layout.tag == "p":
+            ref.tail = first_layout.text
+            first_layout.text = None
+            first_layout.insert(0, ref)
+        else:
+            inject_p = Element("p")
+            inject_p.append(ref)
+            citation_aside.insert(0, inject_p)
+
+        yield citation_aside
+
+
+def _render_content_block(context: Context, block: ContentBlock) -> Element | None:
+    if isinstance(block, TextBlock):
+        if block.kind == TextKind.HEADLINE:
+            container = Element("h1")
+        elif block.kind == TextKind.QUOTE:
+            container = Element("p")
+        elif block.kind == TextKind.BODY:
+            container = Element("p")
+        else:
+            raise ValueError(f"Unknown TextKind: {block.kind}")
+
+        _render_text_content(
+            context=context, 
+            parent=container, 
+            content=block.content,
+        )
+        if block.kind == TextKind.QUOTE:
+            blockquote = Element("blockquote")
+            blockquote.append(container)
+            return blockquote
+
+        return container
+
+    elif isinstance(block, Table):
+        return process_table(context, block)
+
+    elif isinstance(block, Formula):
+        return process_formula(context, block, inline_mode=False)
+
+    elif isinstance(block, Image):
+        return process_image(context, block)
+
+    else:
+        return None
+
+
+def _render_text_content(context: Context, parent: Element, content: list[str | Mark | Formula | HTMLTag]) -> None:
+    """Render text content with inline citation marks."""
+    current_element = parent
+    for item in content:
+        if isinstance(item, str):
+            if current_element is parent:
+                if parent.text is None:
+                    parent.text = item
+                else:
+                    parent.text += item
+            else:
+                if current_element.tail is None:
+                    current_element.tail = item
+                else:
+                    current_element.tail += item
+
+        elif isinstance(item, HTMLTag):
+            tag_element = Element(item.name)
+            for attr, value in item.attributes:
+                tag_element.set(attr, value)
+            _render_text_content(
+                context=context,
+                parent=tag_element,
+                content=item.content,
+            )
+            parent.append(tag_element)
+            current_element = tag_element
+
+        elif isinstance(item, Formula):
+            formula_element = process_formula(
+                context=context,
+                formula=item,
+                inline_mode=True,
+            )
+            if formula_element is not None:
+                parent.append(formula_element)
+                current_element = formula_element
+
+        elif isinstance(item, Mark):
+            # EPUB 3.0 noteref with semantic attributes
+            anchor = Element("a")
+            anchor.attrib = {
+                "id": f"ref-{item.id}",
+                "href": f"#fn-{item.id}",
+                "class": "super",
+            }
+            # Set epub:type using utility function (avoids global namespace pollution)
+            set_epub_type(anchor, "noteref")
+            anchor.text = f"[{item.id}]"
+            parent.append(anchor)
+            current_element = anchor

epub_generator/generation/gen_epub.py

@@ -0,0 +1,198 @@
+from datetime import datetime, timezone
+from os import PathLike
+from pathlib import Path
+from typing import Callable, Literal
+from uuid import uuid4
+from zipfile import ZipFile
+
+from ..context import Context, Template
+from ..html_tag import search_content
+from ..i18n import I18N
+from ..options import LaTeXRender, TableRender
+from ..types import Chapter, EpubData, Formula, TextBlock
+from .gen_chapter import generate_chapter
+from .gen_nav import gen_nav
+from .gen_toc import NavPoint, gen_toc
+
+
+def generate_epub(
+    epub_data: EpubData,
+    epub_file_path: PathLike,
+    lan: Literal["zh", "en"] = "zh",
+    table_render: TableRender = TableRender.HTML,
+    latex_render: LaTeXRender = LaTeXRender.MATHML,
+    assert_not_aborted: Callable[[], None] = lambda: None,
+) -> None:
+    i18n = I18N(lan)
+    template = Template()
+    epub_file_path = Path(epub_file_path)
+
+    # Generate navigation points from TOC structure
+    has_cover = epub_data.cover_image_path is not None
+    nav_points = gen_toc(epub_data=epub_data, has_cover=has_cover)
+
+    epub_file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with ZipFile(epub_file_path, "w") as file:
+        context = Context(
+            file=file,
+            template=template,
+            table_render=table_render,
+            latex_render=latex_render,
+        )
+        file.writestr(
+            zinfo_or_arcname="mimetype",
+            data=template.render("mimetype").encode("utf-8"),
+        )
+        assert_not_aborted()
+
+        _write_chapters_from_data(
+            context=context,
+            i18n=i18n,
+            nav_points=nav_points,
+            epub_data=epub_data,
+            latex_render=latex_render,
+            assert_not_aborted=assert_not_aborted,
+        )
+        nav_xhtml = gen_nav(
+            template=template,
+            i18n=i18n,
+            epub_data=epub_data,
+            nav_points=nav_points,
+            has_cover=has_cover,
+        )
+        file.writestr(
+            zinfo_or_arcname="OEBPS/nav.xhtml",
+            data=nav_xhtml.encode("utf-8"),
+        )
+        assert_not_aborted()
+
+        _write_basic_files(
+            context=context,
+            i18n=i18n,
+            epub_data=epub_data,
+            nav_points=nav_points,
+        )
+        assert_not_aborted()
+
+        _write_assets_from_data(
+            context=context,
+            i18n=i18n,
+            epub_data=epub_data,
+        )
+
+def _write_assets_from_data(
+    context: Context,
+    i18n: I18N,
+    epub_data: EpubData,
+):
+    context.file.writestr(
+        zinfo_or_arcname="OEBPS/styles/style.css",
+        data=context.template.render("style.css").encode("utf-8"),
+    )
+    if epub_data.cover_image_path:
+        context.file.writestr(
+            zinfo_or_arcname="OEBPS/Text/cover.xhtml",
+            data=context.template.render(
+                template="cover.xhtml",
+                i18n=i18n,
+            ).encode("utf-8"),
+        )
+        if epub_data.cover_image_path:
+            context.file.write(
+                filename=epub_data.cover_image_path,
+                arcname="OEBPS/assets/cover.png",
+            )
+
+def _write_chapters_from_data(
+    context: Context,
+    i18n: I18N,
+    nav_points: list[NavPoint],
+    epub_data: EpubData,
+    latex_render: LaTeXRender,
+    assert_not_aborted: Callable[[], None],
+):
+    if epub_data.get_head is not None:
+        chapter = epub_data.get_head()
+        data = generate_chapter(context, chapter, i18n)
+        context.file.writestr(
+            zinfo_or_arcname="OEBPS/Text/head.xhtml",
+            data=data.encode("utf-8"),
+        )
+        if latex_render == LaTeXRender.MATHML and _chapter_has_formula(chapter):
+            context.mark_chapter_has_mathml("head.xhtml")
+        assert_not_aborted()
+
+    for nav_point in nav_points:
+        if nav_point.get_chapter is not None:
+            chapter = nav_point.get_chapter()
+            data = generate_chapter(context, chapter, i18n)
+            context.file.writestr(
+                zinfo_or_arcname="OEBPS/Text/" + nav_point.file_name,
+                data=data.encode("utf-8"),
+            )
+            if latex_render == LaTeXRender.MATHML and _chapter_has_formula(chapter):
+                context.mark_chapter_has_mathml(nav_point.file_name)
+            assert_not_aborted()
+
+
+def _chapter_has_formula(chapter: Chapter) -> bool:
+    """Check if chapter contains any formulas (block-level or inline)."""
+    for element in chapter.elements:
+        if isinstance(element, Formula):
+            return True
+        if isinstance(element, TextBlock):
+            for item in search_content(element.content):
+                if isinstance(item, Formula):
+                    return True
+    for footnote in chapter.footnotes:
+        for content_block in footnote.contents:
+            if isinstance(content_block, Formula):
+                return True
+            if isinstance(content_block, TextBlock):
+                for item in search_content(content_block.content):
+                    if isinstance(item, Formula):
+                        return True
+    return False
+
+def _write_basic_files(
+    context: Context,
+    i18n: I18N,
+    epub_data: EpubData,
+    nav_points: list[NavPoint],
+):
+    meta = epub_data.meta
+    has_cover = epub_data.cover_image_path is not None
+    has_head_chapter = epub_data.get_head is not None
+
+    context.file.writestr(
+        zinfo_or_arcname="META-INF/container.xml",
+        data=context.template.render("container.xml").encode("utf-8"),
+    )
+    isbn = (meta.isbn if meta else None) or str(uuid4())
+    if meta and meta.modified:
+        modified_timestamp = meta.modified.strftime("%Y-%m-%dT%H:%M:%SZ")
+    else:
+        modified_timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    chapters_with_mathml = {
+        nav_point.file_name
+        for nav_point in nav_points
+        if context.chapter_has_mathml(nav_point.file_name)
+    }
+    content = context.template.render(
+        template="content.opf",
+        meta=meta,
+        i18n=i18n,
+        ISBN=isbn,
+        modified_timestamp=modified_timestamp,
+        nav_points=nav_points,
+        has_head_chapter=has_head_chapter,
+        has_cover=has_cover,
+        asset_files=context.used_files,
+        chapters_with_mathml=chapters_with_mathml,
+    )
+    context.file.writestr(
+        zinfo_or_arcname="OEBPS/content.opf",
+        data=content.encode("utf-8"),
+    )

epub_generator/generation/gen_nav.py

@@ -0,0 +1,92 @@
+from html import escape
+
+from ..context import Template
+from ..i18n import I18N
+from ..types import BookMeta, EpubData, TocItem
+from .gen_toc import NavPoint
+
+
+def gen_nav(
+    template: Template,
+    i18n: I18N,
+    epub_data: EpubData,
+    nav_points: list[NavPoint],
+    has_cover: bool = False,
+) -> str:
+    meta: BookMeta | None = epub_data.meta
+    has_head_chapter = epub_data.get_head is not None
+    toc_list = _generate_toc_list(epub_data.prefaces, epub_data.chapters, nav_points)
+    first_chapter_file = nav_points[0].file_name if nav_points else None
+    head_chapter_title = ""
+    if has_head_chapter and epub_data.get_head:
+        # Try to extract title from first heading if available
+        head_chapter_title = "Preface"  # Default title
+
+    return template.render(
+        template="nav.xhtml",
+        i18n=i18n,
+        meta=meta,
+        has_cover=has_cover,
+        has_head_chapter=has_head_chapter,
+        head_chapter_title=head_chapter_title,
+        toc_list=toc_list,
+        first_chapter_file=first_chapter_file,
+    )
+
+
+def _generate_toc_list(
+    prefaces: list[TocItem],
+    chapters: list[TocItem],
+    nav_points: list[NavPoint],
+) -> str:
+    nav_point_index = 0
+
+    html_parts = []
+    for chapters_list in (prefaces, chapters):
+        for toc_item in chapters_list:
+            nav_point_index, item_html = _generate_toc_item(
+                toc_item, nav_points, nav_point_index
+            )
+            html_parts.append(item_html)
+
+    return "\n".join(html_parts)
+
+
+def _generate_toc_item(
+    toc_item: TocItem,
+    nav_points: list[NavPoint],
+    nav_point_index: int,
+) -> tuple[int, str]:
+    title_escaped = escape(toc_item.title)
+    file_name = None
+    if toc_item.get_chapter is not None and nav_point_index < len(nav_points):
+        file_name = nav_points[nav_point_index].file_name
+        nav_point_index += 1
+
+    children_html = []
+    for child in toc_item.children:
+        nav_point_index, child_html = _generate_toc_item(
+            child, nav_points, nav_point_index
+        )
+        children_html.append(child_html)
+
+    if file_name is None and children_html:
+        if nav_point_index > 0:
+            for i in range(nav_point_index - len(toc_item.children), nav_point_index):
+                if i < len(nav_points):
+                    file_name = nav_points[i].file_name
+                    break
+
+    if file_name:
+        html_parts = [f'      <li>\n        <a href="Text/{file_name}">{title_escaped}</a>']
+    else:
+        html_parts = [f'      <li>\n        <span>{title_escaped}</span>']
+
+    if children_html:
+        html_parts.append('        <ol>')
+        html_parts.extend(children_html)
+        html_parts.append('        </ol>')
+
+    html_parts.append('      </li>')
+
+    return nav_point_index, "\n".join(html_parts)

epub_generator/generation/gen_toc.py

@@ -0,0 +1,88 @@
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from ..types import EpubData, TocItem
+
+
+@dataclass
+class NavPoint:
+    toc_id: int
+    file_name: str
+    order: int
+    get_chapter: Callable[[], Any] | None = None
+
+
+def gen_toc(
+    epub_data: EpubData,
+    has_cover: bool = False,
+) -> list[NavPoint]:
+    prefaces = epub_data.prefaces
+    chapters = epub_data.chapters
+
+    nav_point_generation = _NavPointGenerator(
+        has_cover=has_cover,
+        chapters_count=(
+            _count_toc_items(prefaces) +
+            _count_toc_items(chapters)
+        ),
+    )
+    for chapters_list in (prefaces, chapters):
+        for toc_item in chapters_list:
+            nav_point_generation.generate(toc_item)
+
+    return nav_point_generation.nav_points
+
+
+def _count_toc_items(items: list[TocItem]) -> int:
+    count: int = 0
+    for item in items:
+        count += 1 + _count_toc_items(item.children)
+    return count
+
+
+def _max_depth_toc_items(items: list[TocItem]) -> int:
+    max_depth: int = 0
+    for item in items:
+        max_depth = max(
+            max_depth,
+            _max_depth_toc_items(item.children) + 1,
+        )
+    return max_depth
+
+
+class _NavPointGenerator:
+    def __init__(self, has_cover: bool, chapters_count: int):
+        self._nav_points: list[NavPoint] = []
+        self._next_order: int = 2 if has_cover else 1
+        self._next_id: int = 1
+        self._digits = len(str(chapters_count))
+
+    @property
+    def nav_points(self) -> list[NavPoint]:
+        return self._nav_points
+
+    def generate(self, toc_item: TocItem) -> None:
+        self._create_nav_point(toc_item)
+
+    def _create_nav_point(self, toc_item: TocItem) -> NavPoint:
+        nav_point: NavPoint | None = None
+        if toc_item.get_chapter is not None:
+            toc_id = self._next_id
+            self._next_id += 1
+            part_id = str(toc_id).zfill(self._digits)
+            nav_point = NavPoint(
+                toc_id=toc_id,
+                file_name=f"part{part_id}.xhtml",
+                order=self._next_order,
+                get_chapter=toc_item.get_chapter,
+            )
+            self._nav_points.append(nav_point)
+            self._next_order += 1
+
+        for child in toc_item.children:
+            child_nav_point = self._create_nav_point(child)
+            if nav_point is None:
+                nav_point = child_nav_point
+
+        assert nav_point is not None, "TocItem has no chapter and no valid children"
+        return nav_point

epub_generator/generation/xml_utils.py

@@ -0,0 +1,31 @@
+import re
+from xml.etree.ElementTree import Element, tostring
+
+_EPUB_NS = "http://www.idpf.org/2007/ops"
+_MATHML_NS = "http://www.w3.org/1998/Math/MathML"
+
+
+def set_epub_type(element: Element, epub_type: str) -> None:
+    element.set(f"{{{_EPUB_NS}}}type", epub_type)
+
+def serialize_element(element: Element) -> str:
+    xml_string = tostring(element, encoding="unicode")
+    for prefix, namespace_uri, keep_xmlns in (
+        ("epub", _EPUB_NS, False),  # EPUB namespace: remove xmlns (declared at root)
+        ("m", _MATHML_NS, True),     # MathML namespace: keep xmlns with clean prefix
+    ):
+        xml_string = xml_string.replace(f"{{{namespace_uri}}}", f"{prefix}:")
+        pattern = r"xmlns:(ns\d+)=\"" + re.escape(namespace_uri) + r"\""
+        matches = re.findall(pattern, xml_string)
+
+        for ns_prefix in matches:
+            if keep_xmlns:
+                xml_string = xml_string.replace(
+                    f" xmlns:{ns_prefix}=\"{namespace_uri}\"",
+                    f" xmlns:{prefix}=\"{namespace_uri}\""
+                )
+            else:
+                xml_string = xml_string.replace(f" xmlns:{ns_prefix}=\"{namespace_uri}\"", "")
+            xml_string = xml_string.replace(f"{ns_prefix}:", f"{prefix}:")
+
+    return xml_string

epub_generator/html_tag.py

@@ -0,0 +1,11 @@
+from typing import Generator
+
+from .types import Formula, HTMLTag, Mark
+
+
+def search_content(content: list[str | Mark | Formula | HTMLTag]) -> Generator[str | Mark | Formula, None, None]:
+    for child in content:
+        if isinstance(child, HTMLTag):
+            yield from search_content(child.content)
+        else:
+            yield child

epub_generator/i18n.py

@@ -0,0 +1,17 @@
+from typing import Literal
+
+
+class I18N:
+    def __init__(self, lan: Literal["zh", "en"]):
+        if lan == "zh":
+            self.unnamed: str = "未命名"
+            self.cover: str = "封面"
+            self.table_of_contents: str = "目录"
+            self.landmarks: str = "路标"
+            self.start_of_content: str = "正文开始"
+        elif lan == "en":
+            self.unnamed: str = "Unnamed"
+            self.cover: str = "Cover"
+            self.table_of_contents: str = "Table of Contents"
+            self.landmarks: str = "Landmarks"
+            self.start_of_content: str = "Start of Content"

epub_generator/options.py

@@ -0,0 +1,12 @@
+from enum import Enum, auto
+
+
+class TableRender(Enum):
+    HTML = auto()
+    CLIPPING = auto()
+
+
+class LaTeXRender(Enum):
+    MATHML = auto()
+    SVG = auto()
+    CLIPPING = auto()

epub_generator/template.py

@@ -0,0 +1,52 @@
+import re
+from pathlib import Path
+from typing import Callable, Tuple
+
+from jinja2 import BaseLoader, Environment, TemplateNotFound
+
+
+def create_env(dir_path: Path) -> Environment:
+    return Environment(
+        loader=_DSLoader(dir_path),
+        autoescape=True,
+        trim_blocks=True,
+        keep_trailing_newline=True,
+    )
+
+
+_LoaderResult = Tuple[str, str | None, Callable[[], bool] | None]
+
+
+class _DSLoader(BaseLoader):
+    def __init__(self, dir_path: Path):
+        super().__init__()
+        self._dir_path: Path = dir_path
+
+    def get_source(self, environment: Environment, template: str) -> _LoaderResult:
+        template = self._norm_template(template)
+        target_path = (self._dir_path / template).resolve()
+
+        if not target_path.exists():
+            raise TemplateNotFound(f"cannot find {template}")
+
+        return self._get_source_with_path(target_path)
+
+    def _norm_template(self, template: str) -> str:
+        if bool(re.match(r"^\.+/", template)):
+            raise TemplateNotFound(f"invalid path {template}")
+
+        template = re.sub(r"^/", "", template)
+        template = re.sub(r"\.jinja$", "", template, flags=re.IGNORECASE)
+        template = f"{template}.jinja"
+
+        return template
+
+    def _get_source_with_path(self, path: Path) -> _LoaderResult:
+        mtime = path.stat().st_mtime
+        with open(path, "r", encoding="utf-8") as f:
+            source = f.read()
+
+        def is_updated() -> bool:
+            return mtime == path.stat().st_mtime
+
+        return source, str(path), is_updated