epub-generator 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

epub_generator/__init__.py

@@ -8,10 +8,11 @@ from .types import (
     EpubData,
     Footnote,
     Formula,
+    HTMLTag,
     Image,
     Mark,
     Table,
-    Text,
+    TextBlock,
     TextKind,
     TocItem,
 )
@@ -29,10 +30,11 @@ __all__ = [
     "Chapter",
     "ChapterGetter",
     "ContentBlock",
-    "Text",
+    "TextBlock",
     "TextKind",
     "Table",
     "Formula",
+    "HTMLTag",
     "Image",
     "Footnote",
     "Mark",

epub_generator/generation/gen_chapter.py

@@ -7,15 +7,18 @@ from ..types import (
     Chapter,
     ContentBlock,
     Formula,
+    HTMLTag,
     Image,
     Mark,
     Table,
-    Text,
+    TextBlock,
     TextKind,
 )
 from .gen_asset import process_formula, process_image, process_table
 from .xml_utils import serialize_element, set_epub_type
 
+_MAX_HEADING_LEVEL = 6 # HTML standard defines heading levels from h1 to h6
+
 
 def generate_chapter(
     context: Context,
@@ -88,9 +91,10 @@ def _render_footnotes(
 
 
 def _render_content_block(context: Context, block: ContentBlock) -> Element | None:
-    if isinstance(block, Text):
+    if isinstance(block, TextBlock):
         if block.kind == TextKind.HEADLINE:
-            container = Element("h1")
+            heading_level = min(block.level + 1, _MAX_HEADING_LEVEL)
+            container = Element(f"h{heading_level}")
         elif block.kind == TextKind.QUOTE:
             container = Element("p")
         elif block.kind == TextKind.BODY:
@@ -98,8 +102,11 @@ def _render_content_block(context: Context, block: ContentBlock) -> Element | No
         else:
             raise ValueError(f"Unknown TextKind: {block.kind}")
 
-        _render_text_content(context, container, block.content)
-
+        _render_text_content(
+            context=context,
+            parent=container,
+            content=block.content,
+        )
         if block.kind == TextKind.QUOTE:
             blockquote = Element("blockquote")
             blockquote.append(container)
@@ -120,7 +127,7 @@ def _render_content_block(context: Context, block: ContentBlock) -> Element | No
         return None
 
 
-def _render_text_content(context: Context, parent: Element, content: list[str | Mark | Formula]) -> 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:
@@ -136,6 +143,18 @@ def _render_text_content(context: Context, parent: Element, content: list[str |
                 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,

epub_generator/generation/gen_epub.py

@@ -6,9 +6,10 @@ 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 EpubData, Formula, Text
+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
@@ -135,21 +136,21 @@ def _write_chapters_from_data(
             assert_not_aborted()
 
 
-def _chapter_has_formula(chapter) -> bool:
+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, Text):
-            for item in element.content:
+        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, Text):
-                for item in content_block.content:
+            if isinstance(content_block, TextBlock):
+                for item in search_content(content_block.content):
                     if isinstance(item, Formula):
                         return True
     return False

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/types.py

@@ -107,10 +107,12 @@ class Image:
     """Alt text (defaults to "image")"""
 
 @dataclass
-class Text:
+class TextBlock:
     kind: TextKind
     """Kind of text block."""
-    content: list[str | Mark | Formula]
+    level: int
+    """Heading level starting from 0 (only for HEADLINE: level 0 → h1, level 1 → h2, max h6; ignored for BODY and QUOTE)."""
+    content: list["str | Mark | Formula | HTMLTag"]
     """Text content with optional citation marks."""
 
 @dataclass
@@ -126,7 +128,7 @@ class Footnote:
     """Content blocks"""
 
 
-ContentBlock = Text | Table | Formula | Image
+ContentBlock = TextBlock | Table | Formula | Image
 """Union of all content blocks that appear in main chapter content."""
 
 @dataclass
@@ -138,4 +140,17 @@ class Chapter:
     footnotes: list[Footnote] = field(default_factory=list)
     """Footnotes"""
 
-ChapterGetter = Callable[[], Chapter]
+ChapterGetter = Callable[[], Chapter]
+
+@dataclass
+class HTMLTag:
+    """Generic HTML tag representation."""
+
+    name: str
+    """Tag name"""
+
+    attributes: list[tuple[str, str]] = field(default_factory=list)
+    """List of (attribute, value) pairs"""
+
+    content: list["str | Mark | Formula | HTMLTag"] = field(default_factory=list)
+    """Inner HTML content"""

{epub_generator-0.1.2.dist-info → epub_generator-0.1.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: epub-generator
-Version: 0.1.2
+Version: 0.1.4
 Summary: A simple Python EPUB 3.0 generator with a single API call
 License: MIT
 Keywords: epub,epub3,ebook,generator,publishing
@@ -48,7 +48,7 @@ pip install epub-generator
 ### Generate Your First Book in 5 Minutes
 
 ```python
-from epub_generator import generate_epub, EpubData, BookMeta, TocItem, Chapter, Text, TextKind
+from epub_generator import generate_epub, EpubData, BookMeta, TocItem, Chapter, TextBlock, TextKind
 
 # Prepare book data
 epub_data = EpubData(
@@ -61,9 +61,9 @@ epub_data = EpubData(
             title="Chapter 1",
             get_chapter=lambda: Chapter(
                 elements=[
-                    Text(kind=TextKind.HEADLINE, content=["Chapter 1"]),
-                    Text(kind=TextKind.BODY, content=["This is the first paragraph."]),
-                    Text(kind=TextKind.BODY, content=["This is the second paragraph."]),
+                    TextBlock(kind=TextKind.HEADLINE, level=0, content=["Chapter 1"]),
+                    TextBlock(kind=TextKind.BODY, level=0, content=["This is the first paragraph."]),
+                    TextBlock(kind=TextKind.BODY, level=0, content=["This is the second paragraph."]),
                 ]
             ),
         ),
@@ -80,7 +80,7 @@ That's it! You now have a valid EPUB 3.0 ebook file.
 
 - **Minimal API**: Just one function call `generate_epub()`
 - **EPUB 3.0**: Generates standards-compliant EPUB 3.0 format
-- **Rich Content**: Supports text, images, tables, math formulas (block-level and inline), footnotes
+- **Rich Content**: Supports text, images, tables, math formulas (block-level and inline), footnotes, custom HTML tags
 - **Flexible Structure**: Nested chapters, prefaces, cover images
 - **Math Support**: LaTeX to MathML/SVG conversion with inline formula support
 - **Type Safe**: Full type annotations included
@@ -92,7 +92,7 @@ That's it! You now have a valid EPUB 3.0 ebook file.
 ```python
 from datetime import datetime, timezone
 from pathlib import Path
-from epub_generator import generate_epub, EpubData, BookMeta, TocItem, Chapter, Text, TextKind
+from epub_generator import generate_epub, EpubData, BookMeta, TocItem, Chapter, TextBlock, TextKind
 
 epub_data = EpubData(
     meta=BookMeta(
@@ -111,8 +111,8 @@ epub_data = EpubData(
             title="Chapter 1",
             get_chapter=lambda: Chapter(
                 elements=[
-                    Text(kind=TextKind.HEADLINE, content=["Chapter 1"]),
-                    Text(kind=TextKind.BODY, content=["Main content..."]),
+                    TextBlock(kind=TextKind.HEADLINE, level=0, content=["Chapter 1"]),
+                    TextBlock(kind=TextKind.BODY, level=0, content=["Main content..."]),
                 ]
             ),
         ),
@@ -125,7 +125,7 @@ generate_epub(epub_data, "book_with_cover.epub")
 ### Nested Chapter Structure
 
 ```python
-from epub_generator import generate_epub, EpubData, TocItem, Chapter, Text, TextKind
+from epub_generator import generate_epub, EpubData, TocItem, Chapter, TextBlock, TextKind
 
 epub_data = EpubData(
     chapters=[
@@ -136,7 +136,7 @@ epub_data = EpubData(
                     title="Chapter 1.1",
                     get_chapter=lambda: Chapter(
                         elements=[
-                            Text(kind=TextKind.BODY, content=["Content 1.1..."]),
+                            TextBlock(kind=TextKind.BODY, level=0, content=["Content 1.1..."]),
                         ]
                     ),
                 ),
@@ -144,7 +144,7 @@ epub_data = EpubData(
                     title="Chapter 1.2",
                     get_chapter=lambda: Chapter(
                         elements=[
-                            Text(kind=TextKind.BODY, content=["Content 1.2..."]),
+                            TextBlock(kind=TextKind.BODY, level=0, content=["Content 1.2..."]),
                         ]
                     ),
                 ),
@@ -160,7 +160,7 @@ generate_epub(epub_data, "book_with_nested_chapters.epub")
 
 ```python
 from pathlib import Path
-from epub_generator import generate_epub, EpubData, TocItem, Chapter, Text, TextKind, Image
+from epub_generator import generate_epub, EpubData, TocItem, Chapter, TextBlock, TextKind, Image
 
 epub_data = EpubData(
     chapters=[
@@ -168,7 +168,7 @@ epub_data = EpubData(
             title="Chapter 1",
             get_chapter=lambda: Chapter(
                 elements=[
-                    Text(kind=TextKind.BODY, content=["Here's an image:"]),
+                    TextBlock(kind=TextKind.BODY, level=0, content=["Here's an image:"]),
                     Image(
                         path=Path("image.png"),  # Image path
                         alt_text="Image description",
@@ -185,7 +185,7 @@ generate_epub(epub_data, "book_with_images.epub")
 ### Add Footnotes
 
 ```python
-from epub_generator import generate_epub, EpubData, TocItem, Chapter, Text, TextKind, Mark, Footnote
+from epub_generator import generate_epub, EpubData, TocItem, Chapter, TextBlock, TextKind, Mark, Footnote
 
 epub_data = EpubData(
     chapters=[
@@ -193,8 +193,9 @@ epub_data = EpubData(
             title="Chapter 1",
             get_chapter=lambda: Chapter(
                 elements=[
-                    Text(
+                    TextBlock(
                         kind=TextKind.BODY,
+                        level=0,
                         content=[
                             "This is text with a footnote",
                             Mark(id=1),  # Footnote marker
@@ -206,7 +207,7 @@ epub_data = EpubData(
                     Footnote(
                         id=1,
                         contents=[
-                            Text(kind=TextKind.BODY, content=["This is the footnote content."]),
+                            TextBlock(kind=TextKind.BODY, level=0, content=["This is the footnote content."]),
                         ],
                     ),
                 ],
@@ -221,7 +222,7 @@ generate_epub(epub_data, "book_with_footnotes.epub")
 ### Add Tables
 
 ```python
-from epub_generator import generate_epub, EpubData, TocItem, Chapter, Text, TextKind, Table
+from epub_generator import generate_epub, EpubData, TocItem, Chapter, TextBlock, TextKind, Table
 
 epub_data = EpubData(
     chapters=[
@@ -229,7 +230,7 @@ epub_data = EpubData(
             title="Chapter 1",
             get_chapter=lambda: Chapter(
                 elements=[
-                    Text(kind=TextKind.BODY, content=["Here's a table:"]),
+                    TextBlock(kind=TextKind.BODY, level=0, content=["Here's a table:"]),
                     Table(
                         html_content="""
                         <table>
@@ -253,7 +254,7 @@ generate_epub(epub_data, "book_with_tables.epub")
 Block-level formulas:
 
 ```python
-from epub_generator import generate_epub, EpubData, TocItem, Chapter, Text, TextKind, Formula, LaTeXRender
+from epub_generator import generate_epub, EpubData, TocItem, Chapter, TextBlock, TextKind, Formula, LaTeXRender
 
 epub_data = EpubData(
     chapters=[
@@ -261,7 +262,7 @@ epub_data = EpubData(
             title="Chapter 1",
             get_chapter=lambda: Chapter(
                 elements=[
-                    Text(kind=TextKind.BODY, content=["Pythagorean theorem:"]),
+                    TextBlock(kind=TextKind.BODY, level=0, content=["Pythagorean theorem:"]),
                     Formula(latex_expression="x^2 + y^2 = z^2"),  # Block-level formula
                 ]
             ),
@@ -282,8 +283,9 @@ epub_data = EpubData(
             title="Chapter 1",
             get_chapter=lambda: Chapter(
                 elements=[
-                    Text(
+                    TextBlock(
                         kind=TextKind.BODY,
+                        level=0,
                         content=[
                             "The Pythagorean theorem ",
                             Formula(latex_expression="a^2 + b^2 = c^2"),  # Inline formula
@@ -301,10 +303,46 @@ epub_data = EpubData(
 generate_epub(epub_data, "book_with_inline_math.epub", latex_render=LaTeXRender.MATHML)
 ```
 
+### Add Custom HTML Tags
+
+You can embed custom HTML tags within text content:
+
+```python
+from epub_generator import generate_epub, EpubData, TocItem, Chapter, TextBlock, TextKind, HTMLTag
+
+epub_data = EpubData(
+    chapters=[
+        TocItem(
+            title="Chapter 1",
+            get_chapter=lambda: Chapter(elements=[TextBlock(
+                kind=TextKind.BODY,
+                level=0,
+                content=[
+                    "This is normal text with ",
+                    HTMLTag(
+                        name="span",
+                        attributes=[("class", "highlight"), ("style", "color: red;")],
+                        content=["highlighted content"],
+                    ),
+                    " and more text with ",
+                    HTMLTag(
+                        name="strong",
+                        content=["bold text"],
+                    ),
+                    ".",
+                ],
+            )]),
+        ),
+    ],
+)
+
+generate_epub(epub_data, "book_with_html_tags.epub")
+```
+
 ### Add Prefaces
 
 ```python
-from epub_generator import generate_epub, EpubData, BookMeta, TocItem, Chapter, Text, TextKind
+from epub_generator import generate_epub, EpubData, BookMeta, TocItem, Chapter, TextBlock, TextKind
 
 epub_data = EpubData(
     meta=BookMeta(title="Book with Prefaces"),
@@ -313,8 +351,8 @@ epub_data = EpubData(
             title="Preface",
             get_chapter=lambda: Chapter(
                 elements=[
-                    Text(kind=TextKind.HEADLINE, content=["Preface"]),
-                    Text(kind=TextKind.BODY, content=["This is the preface content..."]),
+                    TextBlock(kind=TextKind.HEADLINE, level=0, content=["Preface"]),
+                    TextBlock(kind=TextKind.BODY, level=0, content=["This is the preface content..."]),
                 ]
             ),
         ),
@@ -324,7 +362,7 @@ epub_data = EpubData(
             title="Chapter 1",
             get_chapter=lambda: Chapter(
                 elements=[
-                    Text(kind=TextKind.BODY, content=["Main content..."]),
+                    TextBlock(kind=TextKind.BODY, level=0, content=["Main content..."]),
                 ]
             ),
         ),
@@ -417,12 +455,13 @@ class Chapter:
 
 `ContentBlock` is a union of:
 
-- **`Text`**: Text paragraph
+- **`TextBlock`**: Text paragraph
   ```python
   @dataclass
-  class Text:
-      kind: TextKind                            # BODY | HEADLINE | QUOTE
-      content: list[str | Mark | Formula]       # Text with optional marks and inline formulas
+  class TextBlock:
+      kind: TextKind                                # BODY | HEADLINE | QUOTE
+      level: int                                    # Heading level (0→h1, 1→h2, max h6; only for HEADLINE)
+      content: list[str | Mark | Formula | HTMLTag] # Text with optional marks, inline formulas, and HTML tags
   ```
 
 - **`Image`**: Image reference
@@ -447,6 +486,15 @@ class Chapter:
       latex_expression: str                     # LaTeX expression
   ```
 
+- **`HTMLTag`**: HTML tag
+  ```python
+  @dataclass
+  class HTMLTag:
+      name: str                                 # Tag name (e.g., "span", "div")
+      attributes: list[tuple[str, str]] = []    # List of (attribute, value) pairs
+      content: list[str | Mark | Formula | HTMLTag] = [] # Inner HTML content
+  ```
+
 #### `Footnote`
 
 Footnote/citation.

{epub_generator-0.1.2.dist-info → epub_generator-0.1.4.dist-info}/RECORD

@@ -1,4 +1,4 @@
-epub_generator/__init__.py,sha256=x6MQEJhzPPINI4Y2yvPStuxVuOEC3ZwQWEHgaLBUcsI,610
+epub_generator/__init__.py,sha256=CRtP7zjqNPxOA_m4S8Jgavuw_KgaKpoBW5kdgqUivLQ,648
 epub_generator/context.py,sha256=AggXhRiOg70WZTLXF78LHA4coo3fa77OvKVe5wtgP6A,4495
 epub_generator/data/container.xml.jinja,sha256=SkACyZgsAVUS5lmiCEhq3SpbFspYdyCnRNjWnLztLt0,252
 epub_generator/data/content.opf.jinja,sha256=DDaR9GZnSBcpNk2BWUu56Uo_248TA91AxE4tKsBuKnQ,2839
@@ -9,16 +9,17 @@ epub_generator/data/part.xhtml.jinja,sha256=FEQaUjHfCy7EJyyvYZj-6T-lkDcsmz1wvsk0
 epub_generator/data/style.css.jinja,sha256=HyGWoevaZD9xPDJeMQY_1xmM0f6aK0prmqoW3mhTGp0,1072
 epub_generator/generation/__init__.py,sha256=UIscwHa8ocr2D1mk1KaP-zi3P1x9eYJzxTo0RJ2dnks,35
 epub_generator/generation/gen_asset.py,sha256=0muwCvAohODC76F9G9_UBibRPQSpmMJkgQxlCsM7QcQ,4480
-epub_generator/generation/gen_chapter.py,sha256=RWNfESp8ZMBKqBv531OAhGPhlKH4gw0nwK6GXOfi4J8,4827
-epub_generator/generation/gen_epub.py,sha256=ev149NLw8hVkMC-6bMbYVtDf3abhv74APrZVNtB6HVo,6309
+epub_generator/generation/gen_chapter.py,sha256=Irb0uJjK8Q5PnHoK4PFP7CIKKzbfhIK_4thvin6hg6g,5505
+epub_generator/generation/gen_epub.py,sha256=zkG0U5_g3FY-D6zkYGqp844IgWYJhbAqf6CnX2Do71Y,6412
 epub_generator/generation/gen_nav.py,sha256=D-ZNsbm26AEAovbXtx1wSwTfH4Q8H2WYfoYeQ1Sb9bk,2813
 epub_generator/generation/gen_toc.py,sha256=yt7GYu8Rfz9aw_GPZFUl9H3BKd1za1hSm2hhp8wyI68,2488
 epub_generator/generation/xml_utils.py,sha256=xMcNZl8CaV21XYx2yeykkHhvnq5N7yRHfIFu5KRlRHc,1261
+epub_generator/html_tag.py,sha256=P_Y0uRStCEEh7cCtpvK4t432NEcY9OLntAznvdxUF5k,343
 epub_generator/i18n.py,sha256=GQjpHO7t8_0rXNuoYmO-G7_9nCF7S5kluBG0ip_2jIA,622
 epub_generator/options.py,sha256=Er1dnaNvzDSnZRSRJGSqhkJsv1XtsCW2Ym_hUc8o_QI,181
 epub_generator/template.py,sha256=RdN2QRICIrYMzpxCU_x4m4V9WWZEP9VvT6QLp2YCm90,1556
-epub_generator/types.py,sha256=iXvFVx2tVfru9c73OsBaXeDNol7mAa9ckSE2QpkhbsM,3565
-epub_generator-0.1.2.dist-info/LICENSE,sha256=9Zt_a4mrzkvR2rc0UbqTgbboIjWuumDFgeQyKos0H2E,1066
-epub_generator-0.1.2.dist-info/METADATA,sha256=31E1oqO29ieBZ7y1_KqbRTzIAIFrBG5n3r5cnvbZEaU,14740
-epub_generator-0.1.2.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-epub_generator-0.1.2.dist-info/RECORD,,
+epub_generator/types.py,sha256=Raz6MT-aIkMp6Yw9hTu4HP_ySg4kMC-YJ_o0cjYzu_A,4059
+epub_generator-0.1.4.dist-info/LICENSE,sha256=9Zt_a4mrzkvR2rc0UbqTgbboIjWuumDFgeQyKos0H2E,1066
+epub_generator-0.1.4.dist-info/METADATA,sha256=cpydosW4bVyknIbCxKP4DAhl-M8NSct7-9jX9M4BISw,16555
+epub_generator-0.1.4.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+epub_generator-0.1.4.dist-info/RECORD,,