Convenience functions

Module-level shortcuts that create a UnifiedDocumentLoader for one call. The loader gets ocr_provider (default "openai"), api_key and ocr_cache. Every other keyword argument goes where it belongs: the options of load() (or of the batch method) to that call, all other loader settings (table_style, cache_dir, model, judge, …) to the loader; a name that is neither raises TypeError (Loading documents).

Function

Does

doc2mark.load()

Convert one file, return a ProcessedDocument.

doc2mark.document_to_markdown()

Convert one file, return the Markdown string; with output_path also write it (parent folders are created) and print Markdown saved to: ... unless show_progress=False.

doc2mark.batch_convert_to_markdown()

batch_process() with Markdown output and save_files=True: without output_dir the .md files are written next to the inputs.

doc2mark.batch_process_documents()

batch_process() with every option (output format, save_files).

doc2mark.batch_process_files()

batch_process_files() for an explicit list of paths. Importable from doc2mark but not listed in doc2mark.__all__.

The batch functions return the per-file result dictionaries described in Loading documents ({"status": "success" | "failed", ...}). ocr_images=True does not need extract_images=True: with an OCR provider it turns extraction on itself. Pictures of Word, PowerPoint and Excel files are returned as bytes, not base64 (The result: ProcessedDocument), and ocr_cache lives as long as the cache object, not one request (Caching); the docstrings below predate both.

from doc2mark import batch_process_files

results = batch_process_files(
    ["reports/q1.pdf", "reports/q2.pdf", "notes/meeting.docx"],
    output_dir="out",
    ocr_provider=None,
)
print({path: info["status"] for path, info in results.items()})
doc2mark.load(file_path, output_format=OutputFormat.MARKDOWN, extract_images=False, ocr_images=False, ocr_provider='openai', api_key=None, ocr_cache=None, **kwargs)[source]

Quick load function for single documents.

Parameters:

  • file_path (str | Path) – Path to the document

  • output_format (str | OutputFormat) – Output format (default: markdown)

  • extract_images (bool) – Whether to extract images from documents - True: Extract images as base64 data - False: Skip image extraction entirely

  • ocr_images (bool) – Whether to perform OCR on extracted images (requires extract_images=True) - True: Use batch OCR processing to convert images to text descriptions - False: Keep images as base64 data in output

  • ocr_provider (str | OCRProvider) – OCR provider to use

  • api_key (str | None) – API key for OCR provider

  • ocr_cache (OCRCache | None) – Optional request-scoped OCR cache handler

  • **kwargs (Any) – Additional options: any UnifiedDocumentLoader setting (table_style, cache_dir, model, judge, …) goes to the loader; encoding, delimiter and show_progress go to UnifiedDocumentLoader.load(). Any other name is a TypeError.

Returns:

ProcessedDocument

Return type:

ProcessedDocument

Examples

# Basic text extraction only load(“document.pdf”)

# Extract images as base64 (no OCR) load(“document.pdf”, extract_images=True, ocr_images=False)

# Extract images and perform OCR load(“document.pdf”, extract_images=True, ocr_images=True)

doc2mark.document_to_markdown(file_path, output_path=None, extract_images=False, ocr_images=False, ocr_provider='openai', api_key=None, ocr_cache=None, show_progress=True, **kwargs)[source]

Convert any supported document to Markdown (backward compatibility function).

Parameters:

  • file_path (str | Path) – Path to the document

  • output_path (str | Path | None) – Optional path to save the markdown file

  • extract_images (bool) – Whether to extract images from documents - True: Extract images as base64 data - False: Skip image extraction entirely

  • ocr_images (bool) – Whether to perform OCR on extracted images (requires extract_images=True) - True: Use batch OCR processing to convert images to text descriptions - False: Keep images as base64 data in output

  • ocr_provider (str | OCRProvider) – OCR provider to use

  • api_key (str | None) – API key for OCR provider

  • ocr_cache (OCRCache | None) – Optional request-scoped OCR cache handler

  • show_progress (bool) – Whether to show progress messages

  • **kwargs (Any) – Additional options, routed as for load()

Returns:

Markdown string

Return type:

str

doc2mark.batch_convert_to_markdown(input_dir, output_dir=None, extract_images=False, ocr_images=False, recursive=True, ocr_provider='openai', api_key=None, ocr_cache=None, show_progress=True, **kwargs)[source]

Batch convert documents to Markdown (backward compatibility function).

Parameters:

  • input_dir (str | Path) – Directory containing documents

  • output_dir (str | Path | None) – Optional output directory

  • extract_images (bool) – Whether to extract images from documents - True: Extract images as base64 data - False: Skip image extraction entirely

  • ocr_images (bool) – Whether to perform OCR on extracted images (requires extract_images=True) - True: Use batch OCR processing to convert images to text descriptions - False: Keep images as base64 data in output

  • recursive (bool) – Whether to process subdirectories

  • ocr_provider (str | OCRProvider) – OCR provider to use

  • api_key (str | None) – API key for OCR provider

  • ocr_cache (OCRCache | None) – Optional request-scoped OCR cache handler

  • show_progress (bool) – Whether to show progress messages

  • **kwargs (Any) – Additional options: UnifiedDocumentLoader settings (table_style, cache_dir, …) go to the loader; encoding, delimiter, max_workers and progress_callback to UnifiedDocumentLoader.batch_process() (max_workers there means files converted at once). Any other name is a TypeError.

Returns:

Dictionary mapping input paths to results

Return type:

Dict[str, Dict[str, Any]]

doc2mark.batch_process_documents(input_dir, output_dir=None, output_format=OutputFormat.MARKDOWN, extract_images=False, ocr_images=False, recursive=True, ocr_provider='openai', api_key=None, ocr_cache=None, show_progress=True, save_files=True, **kwargs)[source]

Advanced batch processing with full configuration options.

Parameters:

  • input_dir (str | Path) – Directory containing documents

  • output_dir (str | Path | None) – Optional output directory

  • output_format (str | OutputFormat) – Output format

  • extract_images (bool) – Whether to extract images from documents - True: Extract images as base64 data - False: Skip image extraction entirely

  • ocr_images (bool) – Whether to perform OCR on extracted images (requires extract_images=True) - True: Use batch OCR processing to convert images to text descriptions - False: Keep images as base64 data in output

  • recursive (bool) – Whether to process subdirectories

  • ocr_provider (str | OCRProvider) – OCR provider to use

  • api_key (str | None) – API key for OCR provider

  • ocr_cache (OCRCache | None) – Optional request-scoped OCR cache handler

  • show_progress (bool) – Whether to show progress messages

  • save_files (bool) – Whether to save output files

  • **kwargs (Any) – Additional options, routed as for batch_convert_to_markdown()

Returns:

Dictionary mapping input paths to results with detailed metadata

Return type:

Dict[str, Dict[str, Any]]

doc2mark.batch_process_files(file_paths, output_dir=None, output_format=OutputFormat.MARKDOWN, extract_images=False, ocr_images=False, ocr_provider='openai', api_key=None, ocr_cache=None, show_progress=True, save_files=True, **kwargs)[source]

Batch process a specific list of files.

Parameters:

  • file_paths (List[str | Path]) – List of file paths to process

  • output_dir (str | Path | None) – Optional output directory

  • output_format (str | OutputFormat) – Output format

  • extract_images (bool) – Whether to extract images from documents - True: Extract images as base64 data - False: Skip image extraction entirely

  • ocr_images (bool) – Whether to perform OCR on extracted images (requires extract_images=True) - True: Use batch OCR processing to convert images to text descriptions - False: Keep images as base64 data in output

  • ocr_provider (str | OCRProvider) – OCR provider to use

  • api_key (str | None) – API key for OCR provider

  • ocr_cache (OCRCache | None) – Optional request-scoped OCR cache handler

  • show_progress (bool) – Whether to show progress messages

  • save_files (bool) – Whether to save output files

  • **kwargs (Any) – Additional options: UnifiedDocumentLoader settings (table_style, cache_dir, …) go to the loader; encoding, delimiter, max_workers and progress_callback to UnifiedDocumentLoader.batch_process_files(). Any other name is a TypeError.

Returns:

Dictionary mapping input paths to results

Return type:

Dict[str, Dict[str, Any]]

Examples

# Basic text extraction only batch_process_files([“doc1.pdf”, “doc2.docx”])

# Extract images as base64 (no OCR) batch_process_files(files, extract_images=True, ocr_images=False)

# Extract images and perform batch OCR batch_process_files(files, extract_images=True, ocr_images=True)