Book-to-Skill RTF Parser: How It Handles Rich Text Files with striprtf and Regex Fallback

Book-to-Skill uses the striprtf Python library as its primary RTF parser, automatically falling back to a built-in regex-based stripper when the dependency is unavailable or fails.

Book-to-Skill is an open-source document processing tool that extracts plain text from various file formats to enable skill extraction and analysis. When processing Rich Text Format (RTF) documents, the project implements a resilient dual-strategy parsing architecture. Understanding this Book-to-Skill RTF parser design helps developers configure deployments correctly and troubleshoot extraction edge cases.

Primary Parser: The striprtf Library

When available, Book-to-Skill delegates RTF conversion to the striprtf library, which properly handles RTF control words, Unicode escapes (\uN), and embedded formatting tokens. In [book_to_skill/parsers/rtf.py](https://github.com/virgiliojr94/book-to-skill/blob/master/book_to_skill/parsers/rtf.py), the extract_rtf() function attempts to import and utilize striprtf.striprtf.rtf_to_text() to convert raw RTF content into clean plain text. This approach preserves character encoding integrity and correctly processes complex RTF structures that simple pattern matching might corrupt, including nested groups and hexadecimal-encoded characters.

Fallback Mechanism: Regex-Based Text Extraction

If striprtf is not installed or raises an exception during execution, the parser automatically switches to strip_rtf_fallback(), implemented in the same module. This internal routine first normalizes Unicode escape sequences using _rtf_unicode_repl and then applies regular expressions to remove RTF control words, braces, and optional groups. While this fallback Book-to-Skill RTF parser method produces less faithful output than the full library—potentially leaving residual formatting artifacts—it guarantees that text extraction succeeds even in minimal environments lacking optional dependencies.

Architecture and File Organization

The parsing logic resides in specific modules that separate concerns between low-level extraction and high-level dispatch:

• [book_to_skill/parsers/rtf.py](https://github.com/virgiliojr94/book-to-skill/blob/master/book_to_skill/parsers/rtf.py): Contains extract_rtf(), strip_rtf_fallback(), and Unicode processing utilities. The fallback logic occupies lines 107–112, while the primary striprtf integration appears around lines 131–140.
• [book_to_skill/utils.py](https://github.com/virgiliojr94/book-to-skill/blob/master/book_to_skill/utils.py): The extract_text() function detects .rtf extensions and routes calls to the appropriate parser, returning both the extracted content and a metadata string indicating which method succeeded.
• [book_to_skill/config.py](https://github.com/virgiliojr94/book-to-skill/blob/master/book_to_skill/config.py): Defines supported file extensions and maps optional dependencies for validation.
• [pyproject.toml](https://github.com/virgiliojr94/book-to-skill/blob/master/pyproject.toml): Declares striprtf as an optional dependency under the rtf extra, allowing lightweight installations without RTF support.

Working with the Parser in Code

Developers can interact with the Book-to-Skill RTF parser through high-level utilities or direct module access.

Using the automatic dispatcher:

from book_to_skill.utils import extract_text

text, method = extract_text("document.rtf")
print(f"Extraction method: {method}")  # Outputs "striprtf" or "rtf-regex"

print(text[:500])

Direct parser access for custom error handling:

from book_to_skill.parsers.rtf import extract_rtf, strip_rtf_fallback

# Attempt primary parsing

try:
    content, used_parser = extract_rtf("document.rtf")
except Exception:
    # Manual fallback invocation

    with open("document.rtf", "rb") as f:
        raw_bytes = f.read().decode(errors="ignore")
    content = strip_rtf_fallback(raw_bytes)
    used_parser = "rtf-regex"

print(f"Parsed using: {used_parser}")

Summary

• Book-to-Skill prioritizes the striprtf library for accurate RTF-to-text conversion when the optional dependency is installed.
• A regex-based fallback in strip_rtf_fallback() ensures extraction succeeds even without external dependencies.
• The dispatcher pattern in utils.py automatically selects the appropriate parser based on file extension and availability.
• Source code for both parsing strategies resides in [book_to_skill/parsers/rtf.py](https://github.com/virgiliojr94/book-to-skill/blob/master/book_to_skill/parsers/rtf.py).
• The optional dependency is declared in [pyproject.toml](https://github.com/virgiliojr94/book-to-skill/blob/master/pyproject.toml) under the rtf extra.

Frequently Asked Questions

What Python library does Book-to-Skill use to parse RTF files?

Book-to-Skill uses the striprtf library as its primary parser. According to the source code in book_to_skill/parsers/rtf.py, this library correctly handles RTF control words, Unicode sequences, and formatting tokens that basic text extraction might miss.

Does Book-to-Skill require striprtf to be installed?

No, striprtf is optional. The project declares it as an extra dependency in pyproject.toml. If not installed, Book-to-Skill automatically falls back to an internal regex-based parser defined in strip_rtf_fallback() within the same RTF parser module.

How does Book-to-Skill handle RTF files when striprtf fails?

When the primary library raises an exception or is unavailable, the extract_rtf() function catches the error and delegates to strip_rtf_fallback(). This method uses regular expressions to strip RTF markup after normalizing Unicode escapes, ensuring the extraction pipeline never fails silently.

Where is the RTF parsing logic located in the repository?

The core implementation lives in [book_to_skill/parsers/rtf.py](https://github.com/virgiliojr94/book-to-skill/blob/master/book_to_skill/parsers/rtf.py), while the high-level dispatcher that routes .rtf files to this parser is implemented in [book_to_skill/utils.py](https://github.com/virgiliojr94/book-to-skill/blob/master/book_to_skill/utils.py).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}