Class DoclingParser

raganything/parser.py:1455–2049

Docling document parsing utility class. Specialized in parsing Office documents and HTML files, converting the content into structured data and generating markdown and JSON output. Backed by the Docling Python API (`docling.document_converter.DocumentConverter`) to avoid subpr

class DoclingParser(Parser):
    """
    Docling document parsing utility class.

    Specialized in parsing Office documents and HTML files, converting the content
    into structured data and generating markdown and JSON output.

    Backed by the Docling Python API (`docling.document_converter.DocumentConverter`)
    to avoid subprocess overhead and re-initialization of Docling's deep-learning
    models on every call. A `DocumentConverter` instance is built lazily on first
    use and cached per pipeline-option combination so that subsequent parses
    against the same configuration reuse already-loaded models.

    Compatibility changes vs. earlier CLI-subprocess implementation
    ----------------------------------------------------------------
    - `check_installation()` now returns True iff the Docling Python package
      can be imported (`docling.document_converter.DocumentConverter`). The
      previous behavior of probing the `docling` CLI executable on PATH is
      gone; environments that ship the CLI without the importable package
      (or vice versa) will see a different result than before.
    - The legacy `env={...}` kwarg is still accepted for source-level
      compatibility but is **ignored**: the Python API does not run a
      subprocess, so per-call environment overrides no longer take effect.
      Callers needing model-cache, proxy, or CUDA configuration should set
      the corresponding environment variables in the parent process before
      instantiating `DoclingParser`, or configure Docling directly via
      `_get_converter` kwargs (`artifacts_path`, `table_mode`, ...).
    - JSON and Markdown artifacts are still written to
      `<output_dir>/<file_stem>/docling/` for backward compatibility, but
      they are produced by Docling&#x27;s `export_to_dict()` /
      `export_to_markdown()` rather than by the CLI&#x27;s serializer; expect the
      same logical content but not byte-identical files (key ordering,
      whitespace, optional fields may differ).

    Concurrency
    -----------
    The internal converter cache is guarded by a lock so that a single
    `DoclingParser` instance can be safely shared across threads without
    duplicating Docling model loads on first use.
    """

    # Define Docling-specific formats
    HTML_FORMATS = {".html", ".htm", ".xhtml"}

    def __init__(self) -> None:
        """Initialize DoclingParser"""
        super().__init__()
        # Cache of DocumentConverter instances keyed by pipeline-option tuple,
        # so that loaded layout/OCR/table models are reused across calls.
        # The lock guards concurrent first-use from creating duplicate
        # converters (and re-loading models) when the same DoclingParser
        # instance is shared across threads.
        self._converter_cache: Dict[Tuple, Any] = {}
        self._converter_cache_lock = threading.Lock()

    def parse_pdf(
        self,
        pdf_path: Union[str, Path],