all2md.options.common

Common options shared across multiple parsers and renderers.

This module defines options for file access, network operations, and other cross-cutting concerns used throughout the conversion pipeline.

class all2md.options.common.NetworkFetchOptions

Bases: CloneFrozenMixin

Network security options for remote resource fetching.

This dataclass contains settings that control how remote resources (images, CSS, etc.) are fetched, including security constraints to prevent SSRF attacks.

Parameters:

• allow_remote_fetch (bool, default False) – Whether to allow fetching remote URLs for images and other resources. When False, prevents SSRF attacks by blocking all network requests.

• allowed_hosts (list[str] | None, default None) – List of allowed hostnames or CIDR blocks for remote fetching. If None and allow_remote_fetch=True, all hosts are allowed, which may pose an SSRF (Server-Side Request Forgery) risk. A security warning will be logged. In security-sensitive contexts, explicitly set this to an allowlist of trusted hosts.

• require_https (bool, default True) – Whether to require HTTPS for all remote URL fetching.

• require_head_success (bool, default True) – Whether to require a successful HEAD request before fetching remote URLs.

• network_timeout (float, default 10.0) – Timeout in seconds for remote URL fetching.

• max_requests_per_second (float, default 10.0) – Maximum number of network requests per second (rate limiting).

• max_concurrent_requests (int, default 5) – Maximum number of concurrent network requests.

Notes

Asset size limits are inherited from BaseParserOptions.max_asset_size_bytes.

allow_remote_fetch: bool = False

allowed_hosts: list[str] | None = None

require_https: bool = True

require_head_success: bool = True

network_timeout: float = 10.0

max_redirects: int = 5

allowed_content_types: tuple[str, ...] | None = ('image/',)

max_requests_per_second: float = 10.0

max_concurrent_requests: int = 5

__init__(allow_remote_fetch: bool = False, allowed_hosts: list[str] | None = None, require_https: bool = True, require_head_success: bool = True, network_timeout: float = 10.0, max_redirects: int = 5, allowed_content_types: tuple[str, ...] | None = ('image/',), max_requests_per_second: float = 10.0, max_concurrent_requests: int = 5) → None

class all2md.options.common.LocalFileAccessOptions

Bases: CloneFrozenMixin

Local file access security options.

This dataclass contains settings that control access to local files via file:// URLs and similar mechanisms.

Parameters:

• allow_local_files (bool, default False) – Whether to allow access to local files via file:// URLs.

• local_file_allowlist (list[str] | None, default None) – List of directories allowed for local file access. Only applies when allow_local_files=True.

• local_file_denylist (list[str] | None, default None) – List of directories denied for local file access.

• allow_cwd_files (bool, default False) – Whether to allow local files from current working directory and subdirectories.

allow_local_files: bool = False

local_file_allowlist: list[str] | None = None

local_file_denylist: list[str] | None = None

allow_cwd_files: bool = False

__init__(allow_local_files: bool = False, local_file_allowlist: list[str] | None = None, local_file_denylist: list[str] | None = None, allow_cwd_files: bool = False) → None

class all2md.options.common.AttachmentOptionsMixin

Bases: CloneFrozenMixin

Mixin providing attachment handling options for parsers.

This mixin adds attachment-related configuration options to parser classes that need to handle embedded images, downloads, and other binary assets. Only parsers that actually process attachments should inherit from this mixin.

Parameters:

• attachment_mode (AttachmentMode) – How to handle attachments/images during parsing

• alt_text_mode (AltTextMode) – How to render alt-text content

• attachment_output_dir (str or None) – Directory to save attachments when using save mode

• attachment_base_url (str or None) – Base URL for resolving attachment references

• max_asset_size_bytes (int) – Maximum allowed size in bytes for any single asset

• attachment_filename_template (str) – Template for attachment filenames

• attachment_overwrite (Literal["unique", "overwrite", "skip"]) – File collision strategy

• attachment_deduplicate_by_hash (bool) – Avoid saving duplicate attachments by content hash

• attachments_footnotes_section (str or None) – Section title for footnote-style attachment references

Notes

This mixin should be used by parsers that handle formats with embedded images or binary assets (PDF, DOCX, HTML, EPUB, etc.). Pure text formats (CSV, plaintext, source code) should not use this mixin.

Examples

Parser with attachments:

@dataclass(frozen=True)
class PdfOptions(BaseParserOptions, AttachmentOptionsMixin):
    # PDF-specific options here
    pass

Pure text parser without attachments:

@dataclass(frozen=True)
class CsvOptions(BaseParserOptions):
    # CSV-specific options here
    pass

attachment_mode: Literal['skip', 'alt_text', 'save', 'base64'] = 'alt_text'

alt_text_mode: Literal['default', 'plain_filename', 'strict_markdown', 'footnote'] = 'default'

attachment_output_dir: str | None = None

attachment_base_url: str | None = None

max_asset_size_bytes: int = 52428800

attachment_filename_template: str = '{stem}_{type}{seq}.{ext}'

attachment_overwrite: Literal['unique', 'overwrite', 'skip'] = 'unique'

attachment_deduplicate_by_hash: bool = False

attachments_footnotes_section: str | None = 'Attachments'

__init__(attachment_mode: Literal['skip', 'alt_text', 'save', 'base64'] = 'alt_text', alt_text_mode: Literal['default', 'plain_filename', 'strict_markdown', 'footnote'] = 'default', attachment_output_dir: str | None = None, attachment_base_url: str | None = None, max_asset_size_bytes: int = 52428800, attachment_filename_template: str = '{stem}_{type}{seq}.{ext}', attachment_overwrite: Literal['unique', 'overwrite', 'skip'] = 'unique', attachment_deduplicate_by_hash: bool = False, attachments_footnotes_section: str | None = 'Attachments') → None

class all2md.options.common.PaginatedParserOptions

Bases: BaseParserOptions, AttachmentOptionsMixin

Base class for parsers that handle paginated documents (PDF, PPTX, ODP).

This base class provides common options for documents with pages/slides, including page separator templates. Inherits attachment handling from AttachmentOptionsMixin since paginated documents typically contain images.

Parameters:

page_separator_template (str, default "-----") – Template for page/slide separators between pages. Supports placeholders: {page_num}, {total_pages}.

page_separator_template: str = '-----'

__init__(attachment_mode: Literal['skip', 'alt_text', 'save', 'base64'] = 'alt_text', alt_text_mode: Literal['default', 'plain_filename', 'strict_markdown', 'footnote'] = 'default', attachment_output_dir: str | None = None, attachment_base_url: str | None = None, max_asset_size_bytes: int = 52428800, attachment_filename_template: str = '{stem}_{type}{seq}.{ext}', attachment_overwrite: Literal['unique', 'overwrite', 'skip'] = 'unique', attachment_deduplicate_by_hash: bool = False, attachments_footnotes_section: str | None = 'Attachments', extract_metadata: bool = False, page_separator_template: str = '-----') → None

class all2md.options.common.SpreadsheetParserOptions

Bases: BaseParserOptions, AttachmentOptionsMixin

Base class for spreadsheet parsers (XLSX, ODS).

This base class provides common options for spreadsheet documents, including sheet selection, data limits, and cell formatting. Inherits attachment handling from AttachmentOptionsMixin since spreadsheets can contain embedded charts and images.

Parameters:

• sheets (list[str] | str | None, default None) – List of exact sheet names to include or a regex pattern. If None, includes all sheets.

• include_sheet_titles (bool, default True) – Prepend each sheet with a ‘## {sheet_name}’ heading.

• render_formulas (bool, default True) – When True, uses stored cell values. When False, shows formulas.

• max_rows (int | None, default None) – Maximum number of data rows per table (excluding header). None = unlimited.

• max_cols (int | None, default None) – Maximum number of columns per table. None = unlimited.

• truncation_indicator (str, default "...") – Appended note when rows/columns are truncated.

• preserve_newlines_in_cells (bool, default False) – Preserve line breaks within cells as <br> tags.

• trim_empty ({"none", "leading", "trailing", "both"}, default "trailing") – Trim empty rows/columns: none, leading, trailing, or both.

• header_case ({"preserve", "title", "upper", "lower"}, default "preserve") – Transform header case: preserve, title, upper, or lower.

• chart_mode ({"data", "skip"}, default "skip") – How to handle embedded charts: - “data”: Extract chart data as markdown tables - “skip”: Ignore charts entirely

• merged_cell_mode ({"spans", "flatten", "skip"}, default "flatten") – How to handle merged cells: - “spans”: Use colspan/rowspan in AST (future enhancement, currently behaves like “flatten”) - “flatten”: Replace merged followers with empty strings (current behavior) - “skip”: Skip merged cell detection entirely

sheets: list[str] | str | None = None

include_sheet_titles: bool = True

render_formulas: bool = True

max_rows: int | None = None

max_cols: int | None = None

truncation_indicator: str = '...'

preserve_newlines_in_cells: bool = False

trim_empty: Literal['none', 'leading', 'trailing', 'both'] = 'trailing'

header_case: Literal['preserve', 'title', 'upper', 'lower'] = 'preserve'

chart_mode: Literal['data', 'skip'] = 'skip'

merged_cell_mode: Literal['spans', 'flatten', 'skip'] = 'flatten'

__init__(attachment_mode: Literal['skip', 'alt_text', 'save', 'base64'] = 'alt_text', alt_text_mode: Literal['default', 'plain_filename', 'strict_markdown', 'footnote'] = 'default', attachment_output_dir: str | None = None, attachment_base_url: str | None = None, max_asset_size_bytes: int = 52428800, attachment_filename_template: str = '{stem}_{type}{seq}.{ext}', attachment_overwrite: Literal['unique', 'overwrite', 'skip'] = 'unique', attachment_deduplicate_by_hash: bool = False, attachments_footnotes_section: str | None = 'Attachments', extract_metadata: bool = False, sheets: list[str] | str | None = None, include_sheet_titles: bool = True, render_formulas: bool = True, max_rows: int | None = None, max_cols: int | None = None, truncation_indicator: str = '...', preserve_newlines_in_cells: bool = False, trim_empty: Literal['none', 'leading', 'trailing', 'both'] = 'trailing', header_case: Literal['preserve', 'title', 'upper', 'lower'] = 'preserve', chart_mode: Literal['data', 'skip'] = 'skip', merged_cell_mode: Literal['spans', 'flatten', 'skip'] = 'flatten') → None

class all2md.options.common.OCROptions

Bases: CloneFrozenMixin

Configuration options for OCR (Optical Character Recognition).

This dataclass contains settings for detecting and extracting text from images. Can be used by any parser that needs to extract text from images (PDF scanned pages, standalone images, etc.). Two OCR backends are supported via engine: Tesseract (default) and EasyOCR.

Parameters:

• enabled (bool, default False) – Master switch to enable/disable OCR functionality. When False, all OCR processing is skipped regardless of other settings.

• engine ({"tesseract", "easyocr"}, default "tesseract") –

  OCR backend to use:

  • ”tesseract”: Thin wrapper over the Tesseract engine. Requires the system Tesseract binary to be installed and on PATH (plus the pytesseract Python package via pip install all2md[ocr]).

  • ”easyocr”: Pure-pip backend requiring no system binary. Pulls in PyTorch transitively (a large download) and fetches recognition models on first use (network access needed once). Install with pip install all2md[ocr-easyocr].

• gpu (bool, default False) – EasyOCR only: enable GPU acceleration when a compatible device is available. Ignored by the Tesseract engine.

• mode ({"auto", "force", "off"}, default "auto") –

  OCR triggering mode:

  • ”auto”: Automatically detect when OCR is needed (format-specific logic)

  • ”force”: Apply OCR unconditionally

  • ”off”: Disable OCR (same as enabled=False)

• languages (str or list[str], default "eng") –

  Tesseract language code(s) for OCR. Can be:

  • Single language: “eng”, “fra”, “deu”, “spa”, “chi_sim”, etc.

  • Multiple languages: “eng+fra” or [“eng”, “fra”]

  See Tesseract documentation for available language codes.

• auto_detect_language (bool, default False) – Attempt to automatically detect the document language before OCR. Requires Tesseract language detection support (experimental).

• dpi (int, default 300) – DPI (dots per inch) for rendering images for OCR. Higher values improve OCR accuracy but increase processing time. Recommended: 150 (fast), 300 (balanced), 600 (high quality).

• text_threshold (int, default 50) – Minimum number of characters to consider content as text-based. Used by parsers in “auto” mode to decide if OCR is needed.

• doc_text_threshold (int, default 16) – Whole-document floor on meaningful (alphanumeric) characters. In “auto” mode, if no page triggered OCR yet the rendered document has fewer meaningful characters than this, the PDF parser retries once with OCR forced. Catches scanned/image-only documents the per-page heuristic missed.

• image_area_threshold (float, default 0.5) – Minimum ratio of image area to total area (0.0-1.0) to consider content as image-based. Used by parsers in “auto” mode.

• preserve_existing_text (bool, default False) –

  Whether to preserve existing text when OCR is applied:

  • False: Replace existing text entirely with OCR results

  • True: Combine existing text with OCR results

• tesseract_config (str, default "") – Custom Tesseract configuration flags (advanced users). Example: “–psm 6 –oem 3” for custom page segmentation mode.

Notes

The default tesseract engine requires the optional dependencies pytesseract and Pillow, plus the Tesseract OCR engine installed on your system. Install with:

pip install all2md[ocr]

Then install the Tesseract system package (platform-specific).

The easyocr engine needs no system binary; install with:

pip install all2md[ocr-easyocr]

It downloads recognition models on first use and is considerably heavier (PyTorch) than Tesseract.

Examples

Enable OCR with auto-detection:

>>> ocr = OCROptions(enabled=True, mode="auto")

Force OCR on all pages with French language:

>>> ocr = OCROptions(enabled=True, mode="force", languages="fra")

High-quality OCR with multiple languages:

>>> ocr = OCROptions(
...     enabled=True,
...     mode="auto",
...     languages="eng+fra+deu",
...     dpi=600,
...     preserve_existing_text=True
... )

enabled: bool = False

engine: Literal['tesseract', 'easyocr'] = 'tesseract'

gpu: bool = False

mode: Literal['auto', 'force', 'off'] = 'auto'

languages: str | list[str] = 'eng'

auto_detect_language: bool = False

dpi: int = 300

text_threshold: int = 50

doc_text_threshold: int = 16

image_area_threshold: float = 0.5

preserve_existing_text: bool = False

tesseract_config: str = ''

__init__(enabled: bool = False, engine: Literal['tesseract', 'easyocr'] = 'tesseract', gpu: bool = False, mode: Literal['auto', 'force', 'off'] = 'auto', languages: str | list[str] = 'eng', auto_detect_language: bool = False, dpi: int = 300, text_threshold: int = 50, doc_text_threshold: int = 16, image_area_threshold: float = 0.5, preserve_existing_text: bool = False, tesseract_config: str = '') → None