epub2text 0.1.0__py3-none-any.whl

epub2text/__init__.py

@@ -0,0 +1,96 @@
+"""
+epub2text - Extract text from EPUB files with smart cleaning.
+
+A niche CLI tool for extracting and processing text from EPUB files.
+Supports selective chapter extraction, smart text cleaning, and
+both CLI and library usage.
+"""
+
+import tempfile
+import urllib.request
+from pathlib import Path
+from typing import Union
+from .parser import EPUBParser
+from .models import Chapter, Metadata
+from .cleaner import clean_text, TextCleaner
+
+__all__ = [
+    "EPUBParser",
+    "Chapter",
+    "Metadata",
+    "clean_text",
+    "TextCleaner",
+    "epub2txt",
+]
+
+try:
+    from ._version import version as __version__
+except ImportError:
+    __version__ = "0.0.0+unknown"
+
+
+def epub2txt(
+    filepath: str,
+    outputlist: bool = False,
+    clean: bool = True,
+) -> Union[str, list[str]]:
+    """
+    Extract text from EPUB file (compatibility function for old epub2txt API).
+
+    Args:
+        filepath: Path to EPUB file or URL
+        outputlist: If True, return list of chapter texts; if False,
+            return single string
+        clean: If True, apply text cleaning; if False, minimal processing
+
+    Returns:
+        Either a single string of all text (outputlist=False) or list of
+        chapter texts (outputlist=True)
+
+    Examples:
+        >>> text = epub2txt("book.epub")
+        >>> chapters = epub2txt("book.epub", outputlist=True)
+        >>> raw_text = epub2txt("book.epub", clean=False)
+        >>> text = epub2txt("https://example.com/book.epub")
+    """
+    # Check if filepath is a URL
+    is_url = filepath.startswith("http://") or filepath.startswith("https://")
+
+    tmp_path = None
+    if is_url:
+        # Download to temporary file
+        with tempfile.NamedTemporaryFile(suffix=".epub", delete=False) as tmp:
+            tmp_path = tmp.name
+            urllib.request.urlretrieve(filepath, tmp_path)
+            actual_path = tmp_path
+    else:
+        actual_path = filepath
+
+    try:
+        # Use compact format (single newlines) to match old epub2txt behavior
+        parser = EPUBParser(actual_path, paragraph_separator="\n")
+
+        # Get all chapters
+        chapters = parser.get_chapters()
+
+        if outputlist:
+            # Return list of chapter texts
+            result = []
+            for chapter in chapters:
+                text = parser.extract_chapters([chapter.id])
+                if clean:
+                    cleaner = TextCleaner(preserve_single_newlines=True)
+                    text = cleaner.clean(text)
+                result.append(text)
+            return result
+        else:
+            # Return single concatenated string
+            text = parser.extract_chapters()
+            if clean:
+                cleaner = TextCleaner(preserve_single_newlines=True)
+                text = cleaner.clean(text)
+            return text
+    finally:
+        # Clean up temporary file if we downloaded one
+        if is_url and tmp_path:
+            Path(tmp_path).unlink(missing_ok=True)

epub2text/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running epub2text as a module: python -m epub2text."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

epub2text/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

epub2text/cleaner.py

@@ -0,0 +1,151 @@
+"""Text cleaning utilities extracted from abogen."""
+
+import re
+
+# Pre-compile frequently used regex patterns for better performance
+_BRACKETED_NUMBERS_PATTERN = re.compile(r"\[\s*\d+\s*\]")
+_STANDALONE_PAGE_NUMBERS_PATTERN = re.compile(r"^\s*\d+\s*$", re.MULTILINE)
+_PAGE_NUMBERS_AT_END_PATTERN = re.compile(r"\s+\d+\s*$", re.MULTILINE)
+_PAGE_NUMBERS_WITH_DASH_PATTERN = re.compile(
+    r"\s+[-–—]\s*\d+\s*[-–—]?\s*$", re.MULTILINE
+)
+_WHITESPACE_PATTERN = re.compile(r"[^\S\n]+")
+_MULTIPLE_NEWLINES_PATTERN = re.compile(r"\n{3,}")
+_SINGLE_NEWLINE_PATTERN = re.compile(r"(?<!\n)\n(?!\n)")
+_CHAPTER_MARKER_PATTERN = re.compile(r"<<CHAPTER_MARKER:[^>]*>>")
+_METADATA_TAG_PATTERN = re.compile(r"<<METADATA_[^:]+:[^>]*>>")
+
+
+class TextCleaner:
+    """Smart text cleaning with configurable options."""
+
+    def __init__(
+        self,
+        remove_page_numbers: bool = True,
+        remove_footnotes: bool = True,
+        replace_single_newlines: bool = True,
+        normalize_whitespace: bool = True,
+        preserve_single_newlines: bool = False,
+    ):
+        """Initialize text cleaner with options.
+
+        Args:
+            remove_page_numbers: Remove standalone and end-of-line page
+                numbers
+            remove_footnotes: Remove bracketed footnote markers like [1]
+            replace_single_newlines: Replace single newlines with spaces
+                (preserve paragraphs)
+            normalize_whitespace: Collapse multiple spaces to single space
+            preserve_single_newlines: Keep single newlines as paragraph
+                separators (overrides replace_single_newlines)
+        """
+        self.remove_page_numbers = remove_page_numbers
+        self.remove_footnotes = remove_footnotes
+        self.replace_single_newlines = replace_single_newlines
+        self.normalize_whitespace = normalize_whitespace
+        self.preserve_single_newlines = preserve_single_newlines
+
+    def clean(self, text: str) -> str:
+        """Clean text with configured options.
+
+        Args:
+            text: Raw text to clean
+
+        Returns:
+            Cleaned text
+        """
+        # Remove metadata tags
+        text = _METADATA_TAG_PATTERN.sub("", text)
+
+        # Remove page numbers and footnotes if requested
+        if self.remove_page_numbers:
+            text = _BRACKETED_NUMBERS_PATTERN.sub("", text)
+            text = _STANDALONE_PAGE_NUMBERS_PATTERN.sub("", text)
+            text = _PAGE_NUMBERS_AT_END_PATTERN.sub("", text)
+            text = _PAGE_NUMBERS_WITH_DASH_PATTERN.sub("", text)
+
+        if self.remove_footnotes:
+            text = _BRACKETED_NUMBERS_PATTERN.sub("", text)
+
+        # Normalize whitespace
+        if self.normalize_whitespace:
+            # Collapse all whitespace (excluding newlines) into single spaces per line
+            lines = [
+                _WHITESPACE_PATTERN.sub(" ", line).strip() for line in text.splitlines()
+            ]
+            text = "\n".join(lines)
+
+            # Standardize paragraph breaks (multiple newlines become exactly two)
+            # Unless preserve_single_newlines is True (for compact format)
+            if not self.preserve_single_newlines:
+                text = _MULTIPLE_NEWLINES_PATTERN.sub("\n\n", text).strip()
+            else:
+                # For compact format, collapse multiple newlines to single
+                text = _MULTIPLE_NEWLINES_PATTERN.sub("\n", text).strip()
+
+        # Replace single newlines with spaces, but preserve double newlines
+        # Unless preserve_single_newlines is True (for compact format)
+        if self.replace_single_newlines and not self.preserve_single_newlines:
+            text = _SINGLE_NEWLINE_PATTERN.sub(" ", text)
+
+        return text
+
+    def calculate_length(self, text: str) -> int:
+        """Calculate text length excluding chapter markers and metadata.
+
+        Args:
+            text: Text to measure
+
+        Returns:
+            Character count
+        """
+        # Ignore chapter markers and metadata patterns
+        text = _CHAPTER_MARKER_PATTERN.sub("", text)
+        text = _METADATA_TAG_PATTERN.sub("", text)
+        # Ignore newlines and leading/trailing spaces
+        text = text.replace("\n", "").strip()
+        return len(text)
+
+
+def clean_text(
+    text: str,
+    remove_page_numbers: bool = True,
+    remove_footnotes: bool = True,
+    replace_single_newlines: bool = True,
+    normalize_whitespace: bool = True,
+    preserve_single_newlines: bool = False,
+) -> str:
+    """Clean text with smart options (convenience function).
+
+    Args:
+        text: Raw text to clean
+        remove_page_numbers: Remove standalone and end-of-line page numbers
+        remove_footnotes: Remove bracketed footnote markers like [1]
+        replace_single_newlines: Replace single newlines with spaces
+        normalize_whitespace: Collapse multiple spaces to single space
+        preserve_single_newlines: Keep single newlines as paragraph separators
+
+    Returns:
+        Cleaned text
+    """
+    cleaner = TextCleaner(
+        remove_page_numbers=remove_page_numbers,
+        remove_footnotes=remove_footnotes,
+        replace_single_newlines=replace_single_newlines,
+        normalize_whitespace=normalize_whitespace,
+        preserve_single_newlines=preserve_single_newlines,
+    )
+    return cleaner.clean(text)
+
+
+def calculate_text_length(text: str) -> int:
+    """Calculate text length excluding markers and metadata.
+
+    Args:
+        text: Text to measure
+
+    Returns:
+        Character count
+    """
+    cleaner = TextCleaner()
+    return cleaner.calculate_length(text)