ssmdconvert 0.1.0__py3-none-any.whl

ssmdconvert/__init__.py

@@ -0,0 +1,64 @@
+"""Source-neutral conversion into Speech Synthesis Markdown (SSMD)."""
+
+from __future__ import annotations
+
+from .books import convert_book, inspect_book
+from .bundle import load_book_bundle, validate_book_bundle, write_book_bundle
+from .converter import Converter, convert
+from .errors import (
+    BookBundleError,
+    BookBundleValidationError,
+    BookError,
+    ChapterSelectionError,
+    MissingDependencyError,
+    SSMDConvertError,
+    UnsupportedBookSourceError,
+    UnsupportedInputError,
+)
+from .models import (
+    Book,
+    BookChapter,
+    BookInspection,
+    BookInspectionChapter,
+    ConversionResult,
+    Document,
+    Section,
+    SourceInfo,
+)
+
+try:
+    from ._version import version as __version__
+except ImportError:  # generated by setuptools-scm in builds/editable installs
+    try:
+        from importlib.metadata import version
+
+        __version__ = version("ssmdconvert")
+    except Exception:  # pragma: no cover - bare source tree
+        __version__ = "0+unknown"
+
+__all__ = [
+    "Book",
+    "BookBundleError",
+    "BookBundleValidationError",
+    "BookChapter",
+    "BookError",
+    "BookInspection",
+    "BookInspectionChapter",
+    "ChapterSelectionError",
+    "ConversionResult",
+    "Converter",
+    "Document",
+    "MissingDependencyError",
+    "SSMDConvertError",
+    "Section",
+    "SourceInfo",
+    "UnsupportedBookSourceError",
+    "UnsupportedInputError",
+    "__version__",
+    "convert",
+    "convert_book",
+    "inspect_book",
+    "load_book_bundle",
+    "validate_book_bundle",
+    "write_book_bundle",
+]

ssmdconvert/__main__.py

@@ -0,0 +1,4 @@
+from .cli import app
+
+if __name__ == "__main__":
+    app()

ssmdconvert/_epub.py

@@ -0,0 +1,107 @@
+"""Canonical private EPUB extraction backend."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, replace
+from pathlib import Path
+from typing import Any
+
+from epub2text import ChapterDocument, ChapterMarkdownOptions, EPUBParser, Metadata
+
+from .errors import BookError, UnsupportedBookSourceError
+
+
+@dataclass(frozen=True, slots=True)
+class ExtractedChapter:
+    id: str
+    source_number: int
+    title: str
+    markdown: str
+    source_id: str | None
+    source_parent_id: str | None
+    parent_id: str | None
+    href: str | None
+    level: int
+    char_count: int
+    diagnostics: tuple[dict[str, Any], ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ExtractedEpub:
+    source: Path
+    metadata: dict[str, Any]
+    chapters: tuple[ExtractedChapter, ...]
+
+
+def _chapter_markdown_options() -> ChapterMarkdownOptions:
+    return ChapterMarkdownOptions(
+        include_title=False,
+        minimum_body_heading_level=2,
+        preserve_emphasis=True,
+        preserve_strong=True,
+        link_mode="unwrap",
+        code_mode="preserve",
+        resolve_css_emphasis=True,
+        preserve_scene_breaks=True,
+    )
+
+
+def _source_metadata(value: Metadata, source: Path) -> dict[str, Any]:
+    metadata: dict[str, Any] = {"title": value.title or source.stem}
+    if value.authors:
+        metadata["authors"] = list(value.authors)
+    for key in ("language", "publisher", "identifier"):
+        item = getattr(value, key)
+        if item:
+            metadata[key] = item
+    return metadata
+
+
+def _extract_chapter(number: int, document: ChapterDocument) -> ExtractedChapter:
+    return ExtractedChapter(
+        id=f"chapter-{number:04d}",
+        source_number=number,
+        title=str(document.title or f"Chapter {number}"),
+        markdown=document.to_markdown(include_title=True, title_level=1),
+        source_id=str(document.id) if document.id is not None else None,
+        source_parent_id=(str(document.parent_id) if document.parent_id is not None else None),
+        parent_id=None,
+        href=document.href,
+        level=int(document.level),
+        char_count=int(document.char_count),
+        diagnostics=tuple(asdict(item) for item in document.diagnostics),
+    )
+
+
+def load_epub(source: str | Path) -> ExtractedEpub:
+    """Extract EPUB metadata and ordered chapter documents once for all projections."""
+    path = Path(source).expanduser().resolve()
+    if not path.is_file():
+        raise BookError(f"book source is not a regular file: {path}")
+    if path.suffix.lower() != ".epub":
+        raise UnsupportedBookSourceError(
+            f"unsupported book source format: {path.suffix or '<none>'}"
+        )
+
+    try:
+        parser = EPUBParser(str(path))
+        documents = parser.get_chapter_documents(options=_chapter_markdown_options())
+        metadata = _source_metadata(parser.get_metadata(), path)
+    except (OSError, ValueError) as exc:
+        raise BookError(f"could not inspect EPUB {path.name}: {exc}") from exc
+    if not documents:
+        raise BookError(f"EPUB did not yield any readable chapters: {path.name}")
+
+    extracted_chapters = tuple(
+        _extract_chapter(number, document) for number, document in enumerate(documents, start=1)
+    )
+    source_ids = {
+        chapter.source_id: chapter.id
+        for chapter in extracted_chapters
+        if chapter.source_id is not None
+    }
+    chapters = tuple(
+        replace(chapter, parent_id=source_ids.get(chapter.source_parent_id))
+        for chapter in extracted_chapters
+    )
+    return ExtractedEpub(source=path, metadata=metadata, chapters=chapters)

ssmdconvert/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = 'g3b6cdd1d6'

ssmdconvert/adapters/__init__.py

@@ -0,0 +1,34 @@
+from .base import InputAdapter
+from .docx import DocxAdapter
+from .epub import EpubAdapter
+from .html import HtmlAdapter
+from .markdown import MarkdownAdapter
+from .pdf import PdfAdapter
+from .ssmd import SsmdAdapter
+from .text import TextAdapter
+
+
+def default_adapters() -> list[InputAdapter]:
+    # Specific formats first; TXT is deliberately last.
+    return [
+        SsmdAdapter(),
+        EpubAdapter(),
+        MarkdownAdapter(),
+        HtmlAdapter(),
+        PdfAdapter(),
+        DocxAdapter(),
+        TextAdapter(),
+    ]
+
+
+__all__ = [
+    "DocxAdapter",
+    "EpubAdapter",
+    "HtmlAdapter",
+    "InputAdapter",
+    "MarkdownAdapter",
+    "PdfAdapter",
+    "SsmdAdapter",
+    "TextAdapter",
+    "default_adapters",
+]

ssmdconvert/adapters/base.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol
+
+from ..models import Document
+
+
+class InputAdapter(Protocol):
+    name: str
+
+    def supports(self, source: Path) -> bool: ...
+
+    def load(self, source: Path) -> Document: ...

ssmdconvert/adapters/common.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+_CHAPTER_RE = re.compile(
+    r"^(?P<title>(?:chapter|part|book)\s+(?:[0-9ivxlcdm]+|[\w'’-]+)(?:\s*[:.—-]\s*.*)?|prologue|epilogue)\s*$",
+    re.IGNORECASE,
+)
+
+
+def is_ssmd_path(path: Path) -> bool:
+    name = path.name.lower()
+    return name.endswith((".ssmd", ".ssmd.md"))
+
+
+def read_text_file(path: Path) -> str:
+    data = path.read_bytes()
+    for encoding in ("utf-8-sig", "utf-8", "cp1252"):
+        try:
+            return data.decode(encoding)
+        except UnicodeDecodeError:
+            continue
+    return data.decode("utf-8", errors="replace")
+
+
+def split_plain_text(text: str) -> list[tuple[str | None, str]]:
+    """Split common prose chapter headings while preserving all text."""
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+    lines = text.splitlines()
+    starts: list[int] = []
+    titles: dict[int, str] = {}
+    for idx, line in enumerate(lines):
+        match = _CHAPTER_RE.match(line.strip())
+        if match:
+            starts.append(idx)
+            titles[idx] = match.group("title").strip()
+    if not starts:
+        return [(None, text.strip())]
+
+    sections: list[tuple[str | None, str]] = []
+    if starts[0] > 0 and any(line.strip() for line in lines[: starts[0]]):
+        sections.append((None, "\n".join(lines[: starts[0]]).strip()))
+    for pos, start in enumerate(starts):
+        end = starts[pos + 1] if pos + 1 < len(starts) else len(lines)
+        title = titles[start]
+        body = "\n".join(lines[start + 1 : end]).strip()
+        markdown = f"# {title}"
+        if body:
+            markdown += f"\n\n{body}"
+        sections.append((title, markdown))
+    return sections

ssmdconvert/adapters/docx.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..errors import MissingDependencyError
+from ..models import Document, Section, SourceInfo
+
+
+class DocxAdapter:
+    name = "docx"
+
+    def supports(self, source: Path) -> bool:
+        return source.suffix.lower() == ".docx"
+
+    def load(self, source: Path) -> Document:
+        try:
+            from docx import Document as DocxDocument
+        except ImportError as exc:  # pragma: no cover - environment dependent
+            raise MissingDependencyError(
+                "DOCX input requires: pip install 'ssmdconvert[docx]'"
+            ) from exc
+        docx = DocxDocument(str(source))
+        lines: list[str] = []
+        for paragraph in docx.paragraphs:
+            text = paragraph.text.strip()
+            if not text:
+                if lines and lines[-1] != "":
+                    lines.append("")
+                continue
+            style = (paragraph.style.name if paragraph.style else "").lower()
+            if style.startswith("heading"):
+                try:
+                    level = int(style.rsplit(" ", 1)[-1])
+                except ValueError:
+                    level = 1
+                lines.extend(["#" * max(1, min(level, 6)) + " " + text, ""])
+            else:
+                lines.extend([text, ""])
+        props = docx.core_properties
+        metadata = {"title": props.title or source.stem}
+        if props.author:
+            metadata["author"] = props.author
+        return Document(
+            source=SourceInfo(
+                format="docx",
+                media_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+                path=source,
+                name=source.name,
+            ),
+            sections=[Section("section-0001", "\n".join(lines).strip())],
+            metadata=metadata,
+        )

ssmdconvert/adapters/epub.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .._epub import load_epub
+from ..models import Document, Section, SourceInfo
+
+
+class EpubAdapter:
+    name = "epub"
+
+    def supports(self, source: Path) -> bool:
+        return source.suffix.lower() == ".epub"
+
+    def load(self, source: Path) -> Document:
+        extracted = load_epub(source)
+        metadata = dict(extracted.metadata)
+        authors = metadata.pop("authors", [])
+        if authors:
+            metadata["author"] = authors[0]
+        sections = [
+            Section(
+                id=chapter.id,
+                markdown=chapter.markdown,
+                title=chapter.title,
+                level=chapter.level,
+                source_ref=chapter.href,
+            )
+            for chapter in extracted.chapters
+        ]
+        return Document(
+            source=SourceInfo(
+                format="epub",
+                media_type="application/epub+zip",
+                path=extracted.source,
+                name=extracted.source.name,
+            ),
+            sections=sections,
+            metadata=metadata,
+        )

ssmdconvert/adapters/html.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import re
+from html.parser import HTMLParser
+from pathlib import Path
+
+from ..models import Document, Section, SourceInfo
+from .common import read_text_file
+
+_BLOCKS = {
+    "p",
+    "div",
+    "section",
+    "article",
+    "header",
+    "footer",
+    "aside",
+    "nav",
+    "ul",
+    "ol",
+    "blockquote",
+}
+
+
+class _HTMLToMarkdown(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.parts: list[str] = []
+        self.ignore_depth = 0
+        self.title_parts: list[str] = []
+        self.in_title = False
+        self.first_heading: str | None = None
+        self._heading_text: list[str] | None = None
+
+    def _newline(self, count: int = 1) -> None:
+        if not self.parts:
+            return
+        current = "".join(self.parts)
+        missing = count - (len(current) - len(current.rstrip("\n")))
+        if missing > 0:
+            self.parts.append("\n" * missing)
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        tag = tag.lower()
+        if tag in {"script", "style", "svg", "math"}:
+            self.ignore_depth += 1
+            return
+        if self.ignore_depth:
+            return
+        if tag == "title":
+            self.in_title = True
+        elif re.fullmatch(r"h[1-6]", tag):
+            self._newline(2)
+            level = int(tag[1])
+            self.parts.append("#" * level + " ")
+            self._heading_text = []
+        elif tag in _BLOCKS:
+            self._newline(2)
+            if tag == "blockquote":
+                self.parts.append("> ")
+        elif tag == "br":
+            self._newline(1)
+        elif tag == "li":
+            self._newline(1)
+            self.parts.append("- ")
+        elif tag in {"em", "i"}:
+            self.parts.append("*")
+        elif tag in {"strong", "b"}:
+            self.parts.append("**")
+        elif tag == "code":
+            self.parts.append("`")
+        elif tag == "img":
+            alt = dict(attrs).get("alt")
+            if alt:
+                self.parts.append(str(alt))
+
+    def handle_endtag(self, tag: str) -> None:
+        tag = tag.lower()
+        if tag in {"script", "style", "svg", "math"}:
+            if self.ignore_depth:
+                self.ignore_depth -= 1
+            return
+        if self.ignore_depth:
+            return
+        if tag == "title":
+            self.in_title = False
+        elif re.fullmatch(r"h[1-6]", tag):
+            if self.first_heading is None and self._heading_text:
+                self.first_heading = "".join(self._heading_text).strip()
+            self._heading_text = None
+            self._newline(2)
+        elif tag in _BLOCKS:
+            self._newline(2)
+        elif tag in {"em", "i"}:
+            self.parts.append("*")
+        elif tag in {"strong", "b"}:
+            self.parts.append("**")
+        elif tag == "code":
+            self.parts.append("`")
+
+    def handle_data(self, data: str) -> None:
+        if self.ignore_depth:
+            return
+        if self.in_title:
+            self.title_parts.append(data)
+            return
+        if self._heading_text is not None:
+            self._heading_text.append(data)
+        if not data:
+            return
+        collapsed = re.sub(r"\s+", " ", data)
+        core = collapsed.strip()
+        if not core:
+            if self.parts and not self.parts[-1].endswith((" ", "\n")):
+                self.parts.append(" ")
+            return
+        if collapsed.startswith(" ") and self.parts and not self.parts[-1].endswith((" ", "\n")):
+            self.parts.append(" ")
+        elif (
+            self.parts
+            and not self.parts[-1].endswith(("\n", " ", "*", "`", "> ", "- "))
+            and not core.startswith((".", ",", ";", ":", "!", "?", "”", "’"))
+        ):
+            self.parts.append(" ")
+        self.parts.append(core)
+        if collapsed.endswith(" "):
+            self.parts.append(" ")
+
+    def result(self) -> tuple[str, str | None, str | None]:
+        text = "".join(self.parts)
+        text = re.sub(r"[ \t]+\n", "\n", text)
+        text = re.sub(r"\n{3,}", "\n\n", text).strip()
+        title = re.sub(r"\s+", " ", "".join(self.title_parts)).strip() or None
+        return text, title, self.first_heading
+
+
+def html_to_markdown(html: str) -> tuple[str, str | None, str | None]:
+    parser = _HTMLToMarkdown()
+    parser.feed(html)
+    parser.close()
+    return parser.result()
+
+
+class HtmlAdapter:
+    name = "html"
+    suffixes = {".html", ".htm", ".xhtml"}
+
+    def supports(self, source: Path) -> bool:
+        return source.suffix.lower() in self.suffixes
+
+    def load(self, source: Path) -> Document:
+        markdown, title, first_heading = html_to_markdown(read_text_file(source))
+        metadata = {"title": title or first_heading or source.stem}
+        return Document(
+            source=SourceInfo(format="html", media_type="text/html", path=source, name=source.name),
+            sections=[Section("section-0001", markdown, first_heading)],
+            metadata=metadata,
+        )

ssmdconvert/adapters/markdown.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from ..models import Document, Section, SourceInfo
+from .common import is_ssmd_path, read_text_file
+
+_H1_RE = re.compile(r"^#\s+(.+?)\s*$")
+
+
+def split_markdown(text: str) -> list[tuple[str | None, str]]:
+    lines = text.replace("\r\n", "\n").replace("\r", "\n").splitlines()
+    starts = [
+        (idx, match.group(1).strip())
+        for idx, line in enumerate(lines)
+        if (match := _H1_RE.match(line))
+    ]
+    if not starts:
+        return [(None, "\n".join(lines).strip())]
+    result: list[tuple[str | None, str]] = []
+    if starts[0][0] > 0 and any(line.strip() for line in lines[: starts[0][0]]):
+        result.append((None, "\n".join(lines[: starts[0][0]]).strip()))
+    for pos, (start, title) in enumerate(starts):
+        end = starts[pos + 1][0] if pos + 1 < len(starts) else len(lines)
+        result.append((title, "\n".join(lines[start:end]).strip()))
+    return result
+
+
+class MarkdownAdapter:
+    name = "markdown"
+    suffixes = {".md", ".markdown", ".mdown", ".mkd"}
+
+    def supports(self, source: Path) -> bool:
+        return source.suffix.lower() in self.suffixes and not is_ssmd_path(source)
+
+    def load(self, source: Path) -> Document:
+        text = read_text_file(source)
+        sections = [
+            Section(id=f"section-{index:04d}", title=title, markdown=body)
+            for index, (title, body) in enumerate(split_markdown(text), start=1)
+            if body
+        ]
+        return Document(
+            source=SourceInfo(
+                format="markdown", media_type="text/markdown", path=source, name=source.name
+            ),
+            sections=sections or [Section("section-0001", "")],
+            metadata={"title": source.stem},
+        )

ssmdconvert/adapters/pdf.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..errors import MissingDependencyError
+from ..models import Document, Section, SourceInfo
+
+
+class PdfAdapter:
+    name = "pdf"
+
+    def supports(self, source: Path) -> bool:
+        return source.suffix.lower() == ".pdf"
+
+    def load(self, source: Path) -> Document:
+        try:
+            from pypdf import PdfReader
+        except ImportError as exc:  # pragma: no cover - environment dependent
+            raise MissingDependencyError(
+                "PDF input requires: pip install 'ssmdconvert[pdf]'"
+            ) from exc
+        reader = PdfReader(str(source))
+        parts: list[str] = []
+        for page in reader.pages:
+            text = (page.extract_text() or "").strip()
+            if text:
+                parts.append(text)
+        metadata: dict[str, str] = {"title": source.stem}
+        if reader.metadata:
+            if reader.metadata.title:
+                metadata["title"] = str(reader.metadata.title)
+            if reader.metadata.author:
+                metadata["author"] = str(reader.metadata.author)
+        text = "\n\n".join(parts)
+        return Document(
+            source=SourceInfo(
+                format="pdf", media_type="application/pdf", path=source, name=source.name
+            ),
+            sections=[Section("section-0001", text)],
+            metadata=metadata,
+        )

ssmdconvert/adapters/ssmd.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from ssmd import parse_front_matter
+
+from ..models import Document, Section, SourceInfo
+from .common import is_ssmd_path, read_text_file
+
+
+class SsmdAdapter:
+    name = "ssmd"
+
+    def supports(self, source: Path) -> bool:
+        return is_ssmd_path(source)
+
+    def load(self, source: Path) -> Document:
+        raw = read_text_file(source)
+        parsed = parse_front_matter(raw)
+        metadata = dict(parsed.data) if parsed.present else {}
+        metadata.setdefault("title", source.stem)
+        return Document(
+            source=SourceInfo(
+                format="ssmd", media_type="text/markdown", path=source, name=source.name
+            ),
+            sections=[Section("section-0001", parsed.body if parsed.present else raw)],
+            metadata=metadata,
+        )