all2md.converter_metadata

Converter metadata definitions for the all2md library.

This module defines dataclasses that describe converter capabilities, requirements, and registration information for the plugin registry system.

class all2md.converter_metadata.ConverterMetadata

Bases: object

Metadata describing a converter’s capabilities and requirements.

This dataclass contains all information needed to register and use a converter, including format detection patterns, module locations, and dependency requirements.

Parameters:

  • format_name (str) – Unique identifier for the format (e.g., “pdf”, “docx”)

  • extensions (list[str]) – File extensions supported (e.g., [“.pdf”])

  • mime_types (list[str]) – MIME types that indicate this format

  • magic_bytes (list[tuple[bytes, int]]) – Magic byte patterns and their offset for content detection. Each tuple is (pattern, offset) where offset is position in file

  • content_detector (Callable[[bytes], bool], optional) – Custom content-based detection function that receives file content bytes and returns True if this converter should handle the content

  • content_detector_path (str, optional) – Fully-qualified dotted path to a content-detection function (e.g. "all2md.parsers.json._detect_json_content"). Used by the generated converter manifest so detection metadata can be registered without importing the parser module; the function is imported lazily the first time detection actually needs it. Prefer content_detector when you already hold the callable (e.g. plugins).

  • parser_class (Union[str, type, None], optional) – Parser class specification. Can be: - Simple class name (e.g., “DocxParser”) - looks in all2md.parsers.{format} - Fully qualified name (e.g., “myplugin.parsers.MyParser”) - Direct class reference (e.g., MyParserClass) - None for no parser

  • renderer_class (Union[str, type, None], optional) – Renderer class specification. Can be: - Simple class name (e.g., “DocxRenderer”) - looks in all2md.renderers.{format} - Fully qualified name (e.g., “myplugin.renderers.MyRenderer”) - Direct class reference (e.g., MyRendererClass) - None for no renderer

  • parser_required_packages (list[tuple[str, str, str]]) – Required packages for the parser as (install_name, import_name, version_spec) tuples. The install_name is the package name for pip install, import_name is the name used in Python import statements, and version_spec is the version requirement (can be empty string for no requirement). e.g., [(“pymupdf”, “fitz”, “>=1.26.4”), (“Pillow”, “PIL”, “>=9.0.0”)]

  • renderer_required_packages (list[tuple[str, str, str]]) – Required packages for the renderer as (install_name, import_name, version_spec) tuples. Same format as parser_required_packages. Empty list if no renderer or no special dependencies needed for rendering.

  • required_packages (list[tuple[str, str, str]]) – Combined list of all required packages (parser + renderer). This field is computed automatically and provided for backward compatibility.

  • optional_packages (list[tuple[str, str]]) – Optional packages that enhance functionality

  • import_error_message (str) – Custom error message for missing dependencies

  • parser_options_class (Union[str, type, None]) – Parser options class specification. Can be: - Simple class name (e.g., “PdfOptions”) - looks in all2md.options - Fully qualified name (e.g., “myplugin.options.MyOptions”) - Direct class reference (e.g., MyOptionsClass) - None for no parser options

  • renderer_options_class (Union[str, type, None]) – Renderer options class specification. Can be: - Simple class name (e.g., “MarkdownRendererOptions”) - looks in all2md.options - Fully qualified name (e.g., “myplugin.options.MyRendererOptions”) - Direct class reference (e.g., MyRendererOptionsClass) - None for no renderer options

  • description (str) – Human-readable description of the converter

  • priority (int) – Priority for format detection (higher = checked first)

format_name: str
extensions: list[str]
mime_types: list[str]
magic_bytes: list[tuple[bytes, int]]
content_detector: Callable[[bytes], bool] | None = None
content_detector_path: str | None = None
parser_class: str | type | None = None
renderer_class: str | type | None = None
parser_required_packages: list[tuple[str, str, str]]
renderer_required_packages: list[tuple[str, str, str]]
renders_as_string: bool = False
optional_packages: list[tuple[str, str]]
import_error_message: str = ''
parser_options_class: str | type | None = None
renderer_options_class: str | type | None = None
description: str = ''
priority: int = 0
property required_packages: list[tuple[str, str, str]]

Get combined list of all required packages for backward compatibility.

Returns:

Combined parser and renderer packages

Return type:

list[tuple[str, str, str]]

get_install_command(as_args: bool = False) → str | list[str]

Generate pip install command for required packages.

Parameters:

as_args (bool, default False) – Returns a list of str for subprocess if True

Returns:

Pip install command for all required packages

Return type:

str | list[str]

matches_extension(filename: str) → bool

Check if filename matches any supported extension.

Parameters:

filename (str) – Filename to check

Returns:

True if extension matches

Return type:

bool

matches_mime_type(mime_type: str) → bool

Check if MIME type matches this converter.

Parameters:

mime_type (str) – MIME type to check

Returns:

True if MIME type matches

Return type:

bool

matches_magic_bytes(content: bytes, max_check: int = 512) → bool

Check if content matches any magic byte patterns.

Parameters:

  • content (bytes) – File content to check

  • max_check (int) – Maximum bytes to check

Returns:

True if any magic byte pattern matches

Return type:

bool

resolve_content_detector() → Callable[[bytes], bool] | None

Return the content-detection callable, importing it lazily if needed.

Prefers a live content_detector callable when present (e.g. set directly by a plugin). Otherwise, if content_detector_path is set, the function is imported on first use and cached so subsequent calls are cheap. Returns None when this converter has no content detector.

This lazy resolution is what lets the converter manifest register detection metadata without importing the parser module: the detector module is only imported when an ambiguous extension or content-based detection actually requires running it.

Returns:

The content detector, or None if this converter has none.

Return type:

Callable[[bytes], bool] or None

get_required_packages_for_content(content: bytes | None = None, input_data: str | Path | IO[bytes] | bytes | None = None, operation: str = 'parse') → list[tuple[str, str, str]]

Get required packages for specific content, allowing context-aware dependency checking.

Some parsers or renderers may have different dependency requirements based on the actual content they’re processing. This method allows parsers/renderers to specify context-specific dependencies.

Parameters:

  • content (bytes, optional) – File content sample (may be partial) to analyze for dependency requirements

  • input_data (various types, optional) – Original input data (path, file object, or bytes) for more accurate detection. When provided, implementations can access the full file instead of relying on potentially truncated content samples.

  • operation (str, default="parse") – The operation type: “parse”, “render”, or “both”

Returns:

Required packages as (install_name, import_name, version_spec) tuples for this content

Return type:

list[tuple[str, str, str]]

get_parser_display_name() → str

Get friendly display name for the parser class.

Returns:

Display name for parser class

Return type:

str

get_renderer_display_name() → str

Get friendly display name for the renderer class.

Returns:

Display name for renderer class

Return type:

str

static normalize_class_spec(class_spec: str | type | None, default_module: str) → str | None

Normalize a class specification to a fully-qualified dotted path.

Mirrors the resolution rules used by converter_registry._load_class, producing the unambiguous string form used in the generated manifest:

  • None -> None

  • a class object -> "<module>.<qualname>"

  • a dotted string -> returned unchanged (already fully qualified)

  • a simple name -> "<default_module>.<name>"

Parameters:

  • class_spec (str, type, or None) – The class specification to normalize.

  • default_module (str) – Module path used to qualify a simple (dot-less) name, e.g. "all2md.options" or "all2md.parsers.markdown".

Returns:

Fully-qualified dotted path, or None if class_spec is None.

Return type:

str or None

get_converter_display_string() → str

Get combined display string showing both parser and renderer.

Returns:

Combined display string in format “Parser: X | Renderer: Y”

Return type:

str

__init__(format_name: str, extensions: list[str] = <factory>, mime_types: list[str] = <factory>, magic_bytes: list[tuple[bytes, int]] = <factory>, content_detector: ~typing.Callable[[bytes], bool] | None = None, content_detector_path: str | None = None, parser_class: str | type | None = None, renderer_class: str | type | None = None, parser_required_packages: list[tuple[str, str, str]] = <factory>, renderer_required_packages: list[tuple[str, str, str]] = <factory>, renders_as_string: bool = False, optional_packages: list[tuple[str, str]] = <factory>, import_error_message: str = '', parser_options_class: str | type | None = None, renderer_options_class: str | type | None = None, description: str = '', priority: int = 0) → None