buchwandler

Python API reference

This page documents the stable public API exposed from text2epub.__init__.

Models

class text2epub.Author(name: 'str', file_as: 'str | None' = None, role: 'str | None' = None)[source]
name: str
file_as: str | None
role: str | None
__init__(name: str, file_as: str | None = None, role: str | None = None) → None
class text2epub.EpubMetadata(title: 'str', language: 'str' = 'en', creators: 'list[str | Author]' = <factory>, contributors: 'list[str | Author]' = <factory>, publisher: 'str | None' = None, description: 'str | None' = None, identifier: 'str | None' = None, rights: 'str | None' = None, date: 'str | None' = None)[source]
title: str
language: str
creators: list[str | Author]
contributors: list[str | Author]
publisher: str | None
description: str | None
identifier: str | None
rights: str | None
date: str | None
__init__(title: str, language: str = 'en', creators: list[str | Author] = <factory>, contributors: list[str | Author] = <factory>, publisher: str | None = None, description: str | None = None, identifier: str | None = None, rights: str | None = None, date: str | None = None) → None
class text2epub.BuildOptions(epub_version: 'str' = '3.0', include_ncx: 'bool' = True, pretty_print: 'bool' = False, css_text: 'str | None' = None, css_files: 'list[Path]' = <factory>, deterministic: 'bool' = True, fail_on_unresolved_tokens: 'bool' = True, unresolved_token_patterns: 'list[str]' = <factory>, include_default_css: 'bool' = True, allow_remote_resources: 'bool' = False, allow_inline_xhtml: 'bool' = False, include_title_page: 'bool' = False, include_toc_page: 'bool' = False, toc_page_numbers: 'bool' = False)[source]
epub_version: str
include_ncx: bool
pretty_print: bool
css_text: str | None
css_files: list[Path]
deterministic: bool
fail_on_unresolved_tokens: bool
unresolved_token_patterns: list[str]
include_default_css: bool
allow_remote_resources: bool
allow_inline_xhtml: bool
include_title_page: bool
include_toc_page: bool
toc_page_numbers: bool
__init__(epub_version: str = '3.0', include_ncx: bool = True, pretty_print: bool = False, css_text: str | None = None, css_files: list[Path] = <factory>, deterministic: bool = True, fail_on_unresolved_tokens: bool = True, unresolved_token_patterns: list[str] = <factory>, include_default_css: bool = True, allow_remote_resources: bool = False, allow_inline_xhtml: bool = False, include_title_page: bool = False, include_toc_page: bool = False, toc_page_numbers: bool = False) → None
class text2epub.MarkdownBook(metadata: 'EpubMetadata', chapters: 'list[MarkdownChapter]', options: 'BuildOptions' = <factory>)[source]
metadata: EpubMetadata
chapters: list[MarkdownChapter]
options: BuildOptions
__init__(metadata: ~text2epub.models.EpubMetadata, chapters: list[~text2epub.models.MarkdownChapter], options: ~text2epub.models.BuildOptions = <factory>) → None
class text2epub.MarkdownChapter(path: 'Path', title: 'str | None' = None, href: 'str | None' = None, id: 'str | None' = None)[source]
path: Path
title: str | None
href: str | None
id: str | None
__init__(path: Path, title: str | None = None, href: str | None = None, id: str | None = None) → None
class text2epub.XhtmlChapter(id: 'str', href: 'str', title: 'str', body_xhtml: 'str', media_type: 'str' = 'application/xhtml+xml')[source]
id: str
href: str
title: str
body_xhtml: str
media_type: str
__init__(id: str, href: str, title: str, body_xhtml: str, media_type: str = 'application/xhtml+xml') → None
class text2epub.Replacement(block_id: 'str', text: 'str', expected_source: 'str | None' = None, allow_inline_xhtml: 'bool' = True)[source]
block_id: str
text: str
expected_source: str | None
allow_inline_xhtml: bool
__init__(block_id: str, text: str, expected_source: str | None = None, allow_inline_xhtml: bool = True) → None
class text2epub.ReplacementPlan(source_epub: 'Path | str', extraction_manifest: 'Path | str | Mapping[str, Any] | None'=None, replacements: 'list[Replacement]' = <factory>, options: 'BuildOptions' = <factory>, output_rewrite: 'OutputRewriteOptions | None' = None)[source]
source_epub: Path | str
extraction_manifest: Path | str | Mapping[str, Any] | None
replacements: list[Replacement]
options: BuildOptions
output_rewrite: OutputRewriteOptions | None
__init__(source_epub: Path | str, extraction_manifest: Mapping[str, ~typing.Any] | None=None, replacements: list[Replacement] = <factory>, options: BuildOptions = <factory>, output_rewrite: OutputRewriteOptions | None = None) → None
class text2epub.ReplacementReport(output_path: 'Path', changed_entries: 'list[str]', unchanged_entries: 'list[str]', replacement_count: 'int', unresolved_token_count: 'int', warnings: 'list[str]' = <factory>, output_rewrite: 'OutputRewriteReport | None' = None)[source]
output_path: Path
changed_entries: list[str]
unchanged_entries: list[str]
replacement_count: int
unresolved_token_count: int
warnings: list[str]
output_rewrite: OutputRewriteReport | None
__init__(output_path: ~pathlib.Path, changed_entries: list[str], unchanged_entries: list[str], replacement_count: int, unresolved_token_count: int, warnings: list[str] = <factory>, output_rewrite: ~text2epub.models.OutputRewriteReport | None = None) → None
class text2epub.OutputRewriteOptions(language: str | None = None, patch_package_language: bool = False, patch_content_language: bool = False, patch_body_language: bool = False, css_text: str | None = None, style_id: str = 'text2epub-output-policy', content_scope: Literal['replacement-manifest', 'spine', 'spine-and-navigation', 'explicit']='spine-and-navigation', content_hrefs: list[str] = <factory>, inject_css_into_fixed_layout: bool = False)[source]

Opt-in output rewrite applied during rebuild_epub().

The options describe generic, product-agnostic changes. text2epub does not resolve a target language for a caller and does not interpret injected CSS.

language: str | None
patch_package_language: bool
patch_content_language: bool
patch_body_language: bool
css_text: str | None
style_id: str
content_scope: Literal['replacement-manifest', 'spine', 'spine-and-navigation', 'explicit']
content_hrefs: list[str]
inject_css_into_fixed_layout: bool
__init__(language: str | None = None, patch_package_language: bool = False, patch_content_language: bool = False, patch_body_language: bool = False, css_text: str | None = None, style_id: str = 'text2epub-output-policy', content_scope: Literal['replacement-manifest', 'spine', 'spine-and-navigation', 'explicit']='spine-and-navigation', content_hrefs: list[str] = <factory>, inject_css_into_fixed_layout: bool = False) → None
class text2epub.OutputRewriteReport(applied: bool = False, opf_path: str | None = None, changed_entries: list[str] = <factory>, targeted_content_entries: list[str] = <factory>, language_patched_entries: list[str] = <factory>, css_injected_entries: list[str] = <factory>, fixed_layout_skipped_entries: list[str] = <factory>, old_primary_language: str | None = None, new_primary_language: str | None = None, warnings: list[str] = <factory>)[source]

Structured detail for an output rewrite applied during a rebuild.

applied: bool
opf_path: str | None
changed_entries: list[str]
targeted_content_entries: list[str]
language_patched_entries: list[str]
css_injected_entries: list[str]
fixed_layout_skipped_entries: list[str]
old_primary_language: str | None
new_primary_language: str | None
warnings: list[str]
__init__(applied: bool = False, opf_path: str | None = None, changed_entries: list[str] = <factory>, targeted_content_entries: list[str] = <factory>, language_patched_entries: list[str] = <factory>, css_injected_entries: list[str] = <factory>, fixed_layout_skipped_entries: list[str] = <factory>, old_primary_language: str | None = None, new_primary_language: str | None = None, warnings: list[str] = <factory>) → None

Markdown builders

Use these helpers for general-purpose Markdown projects.

text2epub.discover_markdown_chapters(input_path: Path | str, *, pattern: str = '*.md', recursive: bool = False) → list[MarkdownChapter][source]

Discover Markdown chapters from a file or folder.

Files are returned in filename order, which makes naming schemes such as 00-front-matter.md, 01-introduction.md and 02-chapter.md a stable way to control EPUB spine order.

Parameters:

  • input_path – A Markdown file or a directory containing Markdown files.

  • pattern – Glob pattern used when input_path is a directory.

  • recursive – Use recursive directory discovery with Path.rglob.

Returns:

Markdown chapters ready to pass to MarkdownBook.

Raises:

BuildError – If the input does not exist or no matching Markdown files are found.

text2epub.create_epub_from_markdown_folder(input_dir: Path | str, output_path: Path | str, *, metadata: EpubMetadata | None = None, options: BuildOptions | None = None, pattern: str = '*.md', recursive: bool = False) → Path[source]

Create an EPUB from Markdown files discovered in a folder.

Direct children matching pattern are sorted by filename by default. This supports simple manuscript folder conventions such as 00-front-matter.md, 01-introduction.md and 02-chapter.md. Set recursive=True to sort matching files by relative path.

text2epub.create_epub_from_markdown_files(chapter_paths: Sequence[Path | str], output_path: Path | str, *, metadata: EpubMetadata | None = None, options: BuildOptions | None = None) → Path[source]

Create an EPUB from an explicit list of Markdown files.

The supplied order is the EPUB spine order. Use this helper when your application already knows the chapter files and should not rely on folder discovery. Metadata may come from the first file’s front matter when metadata is omitted or fields are left empty.

text2epub.create_epub_from_markdown(book: MarkdownBook, output_path: Path | str) → Path[source]

XHTML builder

text2epub.create_epub(metadata: EpubMetadata, chapters: Sequence[XhtmlChapter], output_path: Path | str, *, options: BuildOptions | None = None, assets: Sequence[RenderedAsset] | None = None) → Path[source]

Rebuilds

text2epub.rebuild_epub(plan: ReplacementPlan, output_path: Path | str) → ReplacementReport[source]

Exceptions

exception text2epub.errors.Text2EpubError[source]

Base exception for text2epub.

exception text2epub.errors.BuildError[source]

Raised when generated EPUB creation fails.

exception text2epub.errors.ValidationError[source]

Raised when validation detects an unsafe or invalid EPUB.

exception text2epub.errors.ReplacementError[source]

Raised when a replacement plan cannot be applied safely.

exception text2epub.errors.PackageError[source]

Raised when ZIP package handling fails.

exception text2epub.errors.UnsafeFragmentError[source]

Raised when inline XHTML fragments are unsafe.