html-to-markdown 2.9.2__cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

html_to_markdown/__init__.py

@@ -0,0 +1,58 @@
+"""html-to-markdown: Convert HTML to Markdown using Rust backend.
+
+This package provides high-performance HTML to Markdown conversion
+powered by Rust with a clean Python API.
+
+V2 API (current):
+    from html_to_markdown import convert, ConversionOptions
+
+    options = ConversionOptions(heading_style="atx")
+    markdown = convert(html, options)
+
+V1 API (backward compatibility):
+    from html_to_markdown import convert_to_markdown
+
+    markdown = convert_to_markdown(html, heading_style="atx")
+"""
+
+from html_to_markdown.api import (
+    InlineImage,
+    InlineImageConfig,
+    InlineImageWarning,
+    OptionsHandle,
+    convert,
+    convert_with_handle,
+    convert_with_inline_images,
+    create_options_handle,
+)
+from html_to_markdown.exceptions import (
+    ConflictingOptionsError,
+    EmptyHtmlError,
+    HtmlToMarkdownError,
+    InvalidParserError,
+    MissingDependencyError,
+)
+from html_to_markdown.options import ConversionOptions, PreprocessingOptions
+from html_to_markdown.v1_compat import convert_to_markdown, markdownify
+
+__all__ = [
+    "ConflictingOptionsError",
+    "ConversionOptions",
+    "EmptyHtmlError",
+    "HtmlToMarkdownError",
+    "InlineImage",
+    "InlineImageConfig",
+    "InlineImageWarning",
+    "InvalidParserError",
+    "MissingDependencyError",
+    "OptionsHandle",
+    "PreprocessingOptions",
+    "convert",
+    "convert_to_markdown",
+    "convert_with_handle",
+    "convert_with_inline_images",
+    "create_options_handle",
+    "markdownify",
+]
+
+__version__ = "2.9.2"

html_to_markdown/__main__.py

@@ -0,0 +1,16 @@
+import sys
+
+from html_to_markdown.cli_proxy import main
+
+
+def cli() -> None:
+    try:
+        result = main(sys.argv[1:])
+        print(result, end="")  # noqa: T201
+    except (ValueError, FileNotFoundError) as e:
+        print(str(e), file=sys.stderr)  # noqa: T201
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    cli()

html_to_markdown/_html_to_markdown.pyi

@@ -0,0 +1,22 @@
+from typing import Any
+
+class PreprocessingOptions:
+    def __init__(self, *args: Any, **kwargs: Any) -> None: ...
+
+class ConversionOptions:
+    def __init__(self, *args: Any, **kwargs: Any) -> None: ...
+
+class InlineImageConfig:
+    def __init__(self, *args: Any, **kwargs: Any) -> None: ...
+
+class ConversionOptionsHandle:
+    def __init__(self, options: ConversionOptions | None = None) -> None: ...
+
+def convert(html: str, options: ConversionOptions | None = None) -> str: ...
+def convert_with_inline_images(
+    html: str,
+    options: ConversionOptions | None = None,
+    image_config: InlineImageConfig | None = None,
+) -> tuple[str, list[Any], list[Any]]: ...
+def create_options_handle(options: ConversionOptions | None = None) -> ConversionOptionsHandle: ...
+def convert_with_options_handle(html: str, handle: ConversionOptionsHandle) -> str: ...

html_to_markdown/api.py

@@ -0,0 +1,151 @@
+"""High-level Python API backed by the Rust core."""
+
+from __future__ import annotations
+
+from typing import Literal, TypedDict, cast
+
+import html_to_markdown._html_to_markdown as _rust
+from html_to_markdown._html_to_markdown import (
+    ConversionOptionsHandle as OptionsHandle,
+)
+from html_to_markdown._html_to_markdown import (
+    InlineImageConfig,
+)
+from html_to_markdown.options import ConversionOptions, PreprocessingOptions
+
+
+class InlineImage(TypedDict):
+    """Inline image extracted during conversion."""
+
+    data: bytes
+    format: str
+    filename: str | None
+    description: str | None
+    dimensions: tuple[int, int] | None
+    source: Literal["img_data_uri", "svg_element"]
+    attributes: dict[str, str]
+
+
+class InlineImageWarning(TypedDict):
+    """Warning produced during inline image extraction."""
+
+    index: int
+    message: str
+
+
+def _to_rust_preprocessing(options: PreprocessingOptions) -> _rust.PreprocessingOptions:
+    return _rust.PreprocessingOptions(
+        enabled=options.enabled,
+        preset=options.preset,
+        remove_navigation=options.remove_navigation,
+        remove_forms=options.remove_forms,
+    )
+
+
+def _to_rust_options(
+    options: ConversionOptions,
+    preprocessing: PreprocessingOptions,
+) -> _rust.ConversionOptions:
+    return _rust.ConversionOptions(
+        heading_style=options.heading_style,
+        list_indent_type=options.list_indent_type,
+        list_indent_width=options.list_indent_width,
+        bullets=options.bullets,
+        strong_em_symbol=options.strong_em_symbol,
+        escape_asterisks=options.escape_asterisks,
+        escape_underscores=options.escape_underscores,
+        escape_misc=options.escape_misc,
+        escape_ascii=options.escape_ascii,
+        code_language=options.code_language,
+        autolinks=options.autolinks,
+        default_title=options.default_title,
+        br_in_tables=options.br_in_tables,
+        hocr_spatial_tables=options.hocr_spatial_tables,
+        highlight_style=options.highlight_style,
+        extract_metadata=options.extract_metadata,
+        whitespace_mode=options.whitespace_mode,
+        strip_newlines=options.strip_newlines,
+        wrap=options.wrap,
+        wrap_width=options.wrap_width,
+        convert_as_inline=options.convert_as_inline,
+        sub_symbol=options.sub_symbol,
+        sup_symbol=options.sup_symbol,
+        newline_style=options.newline_style,
+        code_block_style=options.code_block_style,
+        keep_inline_images_in=list(options.keep_inline_images_in) if options.keep_inline_images_in else [],
+        preprocessing=_to_rust_preprocessing(preprocessing),
+        encoding=options.encoding,
+        debug=options.debug,
+        strip_tags=list(options.strip_tags) if options.strip_tags else [],
+        preserve_tags=list(options.preserve_tags) if options.preserve_tags else [],
+    )
+
+
+def convert(
+    html: str,
+    options: ConversionOptions | None = None,
+    preprocessing: PreprocessingOptions | None = None,
+) -> str:
+    """Convert HTML to Markdown using the Rust backend."""
+    if options is None and preprocessing is None:
+        return _rust.convert(html, None)
+
+    if options is None:
+        options = ConversionOptions()
+    if preprocessing is None:
+        preprocessing = PreprocessingOptions()
+
+    rust_options = _to_rust_options(options, preprocessing)
+    return _rust.convert(html, rust_options)
+
+
+def convert_with_inline_images(
+    html: str,
+    options: ConversionOptions | None = None,
+    preprocessing: PreprocessingOptions | None = None,
+    image_config: InlineImageConfig | None = None,
+) -> tuple[str, list[InlineImage], list[InlineImageWarning]]:
+    """Convert HTML and extract inline images."""
+    if options is None:
+        options = ConversionOptions()
+    if preprocessing is None:
+        preprocessing = PreprocessingOptions()
+    if image_config is None:
+        image_config = InlineImageConfig()
+
+    rust_options = _to_rust_options(options, preprocessing)
+    markdown, images, warnings = cast(
+        "tuple[str, list[InlineImage], list[InlineImageWarning]]",
+        _rust.convert_with_inline_images(html, rust_options, image_config),
+    )
+    return markdown, list(images), list(warnings)
+
+
+def create_options_handle(
+    options: ConversionOptions | None = None,
+    preprocessing: PreprocessingOptions | None = None,
+) -> OptionsHandle:
+    """Create a reusable ConversionOptions handle backed by Rust."""
+    if options is None:
+        options = ConversionOptions()
+    if preprocessing is None:
+        preprocessing = PreprocessingOptions()
+    rust_options = _to_rust_options(options, preprocessing)
+    return _rust.create_options_handle(rust_options)
+
+
+def convert_with_handle(html: str, handle: OptionsHandle) -> str:
+    """Convert HTML using a pre-parsed ConversionOptions handle."""
+    return _rust.convert_with_options_handle(html, handle)
+
+
+__all__ = [
+    "InlineImage",
+    "InlineImageConfig",
+    "InlineImageWarning",
+    "OptionsHandle",
+    "convert",
+    "convert_with_handle",
+    "convert_with_inline_images",
+    "create_options_handle",
+]

html_to_markdown/cli.py

@@ -0,0 +1,3 @@
+from html_to_markdown.cli_proxy import main
+
+__all__ = ["main"]

html_to_markdown/cli_proxy.py

@@ -0,0 +1,142 @@
+import subprocess
+import sys
+import warnings
+from pathlib import Path
+
+from html_to_markdown.exceptions import RedundantV1FlagError, RemovedV1FlagError
+
+
+def find_cli_binary() -> Path:
+    """Find the html-to-markdown CLI binary in expected locations.
+
+    Returns:
+        Path to the CLI binary.
+
+    Raises:
+        FileNotFoundError: If the binary cannot be found.
+    """
+    binary_name = "html-to-markdown.exe" if sys.platform == "win32" else "html-to-markdown"
+
+    module_dir = Path(__file__).resolve().parent
+    parent_dirs = list(module_dir.parents)
+
+    search_roots = []
+    for parent in parent_dirs:
+        candidate = parent / "target" / "release" / binary_name
+        search_roots.append(candidate)
+
+    possible_locations = [
+        *search_roots,
+        module_dir / "bin" / binary_name,
+        module_dir / binary_name,
+    ]
+
+    for location in possible_locations:
+        if location.exists() and location.is_file():
+            return location
+
+    msg = "html-to-markdown CLI binary not found. Please install or build the package."
+    raise FileNotFoundError(msg)
+
+
+def translate_v1_args_to_v2(argv: list[str]) -> list[str]:
+    """Translate v1 CLI arguments to v2 format.
+
+    Args:
+        argv: List of command-line arguments.
+
+    Returns:
+        Translated list of arguments compatible with v2.
+
+    Raises:
+        RemovedV1FlagError: If a v1 flag has been removed in v2.
+    """
+    translated = []
+    i = 0
+    while i < len(argv):
+        arg = argv[i]
+
+        if arg in ("--strip", "--convert"):
+            raise RemovedV1FlagError(
+                flag=arg,
+                reason=f"{arg} option has been removed in v2.",
+                migration="Remove this flag from your command. The feature is no longer available.",
+            )
+
+        if arg in (
+            "--no-escape-asterisks",
+            "--no-escape-underscores",
+            "--no-escape-misc",
+            "--no-wrap",
+            "--no-autolinks",
+            "--no-extract-metadata",
+        ):
+            warnings.warn(
+                f"'{arg}' is deprecated and redundant in v2. "
+                f"These options are now disabled by default. Remove this flag.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        elif arg == "--preprocess-html":
+            warnings.warn(
+                "'--preprocess-html' is deprecated. Use '--preprocess' instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            translated.append("--preprocess")
+
+        elif arg in (
+            "--escape-asterisks",
+            "--escape-underscores",
+            "--escape-misc",
+            "--autolinks",
+            "--extract-metadata",
+            "--wrap",
+        ):
+            translated.append(arg)
+
+        else:
+            translated.append(arg)
+
+        i += 1
+
+    return translated
+
+
+def main(argv: list[str]) -> str:
+    """Execute the CLI proxy.
+
+    Translates v1 arguments to v2 and invokes the native Rust CLI binary.
+
+    Args:
+        argv: Command-line arguments.
+
+    Returns:
+        Stdout from the CLI binary.
+    """
+    cli_binary = find_cli_binary()
+
+    try:
+        translated_args = translate_v1_args_to_v2(argv)
+    except (RemovedV1FlagError, RedundantV1FlagError) as e:
+        sys.stderr.write(f"\n❌ Error: {e.flag}\n\n")
+        sys.stderr.write(f"   {e.reason}\n\n")
+        sys.stderr.write(f"   💡 {e.migration}\n\n")
+        sys.exit(1)
+    except ValueError as e:
+        sys.stderr.write(f"Error: {e}\n")
+        sys.exit(1)
+
+    result = subprocess.run(  # noqa: S603
+        [str(cli_binary), *translated_args],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+    if result.returncode != 0:
+        sys.stderr.write(result.stderr)
+        sys.exit(result.returncode)
+
+    return result.stdout

html_to_markdown/exceptions.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+
+class HtmlToMarkdownError(Exception):
+    """Base exception for all html-to-markdown errors."""
+
+
+class MissingDependencyError(HtmlToMarkdownError):
+    """Raised when a required dependency is not installed."""
+
+    def __init__(self, dependency: str, install_command: str | None = None) -> None:
+        self.dependency = dependency
+        self.install_command = install_command
+
+        message = f"{dependency} is not installed."
+        if install_command:
+            message += f" Install with: {install_command}"
+
+        super().__init__(message)
+
+
+class InvalidParserError(HtmlToMarkdownError):
+    """Raised when an invalid parser is specified."""
+
+    def __init__(self, parser: str, available_parsers: list[str]) -> None:
+        self.parser = parser
+        self.available_parsers = available_parsers
+
+        message = f"Invalid parser '{parser}'. Available parsers: {', '.join(available_parsers)}"
+        super().__init__(message)
+
+
+class EmptyHtmlError(HtmlToMarkdownError):
+    """Raised when input HTML is empty."""
+
+    def __init__(self) -> None:
+        super().__init__("The input HTML is empty.")
+
+
+class ConflictingOptionsError(HtmlToMarkdownError):
+    """Raised when conflicting configuration options are specified."""
+
+    def __init__(self, option1: str, option2: str) -> None:
+        self.option1 = option1
+        self.option2 = option2
+
+        super().__init__(f"Only one of '{option1}' and '{option2}' can be specified.")
+
+
+class InvalidEncodingError(HtmlToMarkdownError):
+    """Raised when an invalid character encoding is specified."""
+
+    def __init__(self, encoding: str) -> None:
+        super().__init__(f"The specified encoding ({encoding}) is not valid.")
+
+
+class UnsupportedV1FeatureError(HtmlToMarkdownError):
+    """Raised when a v1 feature is not supported in v2."""
+
+    def __init__(self, flag: str, reason: str, migration: str) -> None:
+        self.flag = flag
+        self.reason = reason
+        self.migration = migration
+        message = f"'{flag}' is not supported in v2.\n\nReason: {reason}\n\nMigration: {migration}"
+        super().__init__(message)
+
+
+class RemovedV1FlagError(UnsupportedV1FeatureError):
+    """Raised when a v1 flag has been removed in v2."""
+
+
+class RedundantV1FlagError(UnsupportedV1FeatureError):
+    """Raised when a v1 flag is redundant in v2."""

html_to_markdown/options.py

@@ -0,0 +1,144 @@
+"""Configuration options for HTML to Markdown conversion.
+
+This module provides dataclass-based configuration for the v2 API.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass
+class ConversionOptions:
+    """Main conversion configuration.
+
+    This class groups all conversion-related options together, replacing
+    the large number of keyword arguments in the v1 API.
+
+    Example:
+        >>> options = ConversionOptions(
+        ...     heading_style="atx",
+        ...     list_indent_width=2,
+        ...     escape_asterisks=True,
+        ... )
+        >>> from html_to_markdown import convert
+        >>> markdown = convert("<h1>Title</h1>", options)
+    """
+
+    heading_style: Literal["underlined", "atx", "atx_closed"] = "atx"
+    """Style for headings: 'atx' (#) is CommonMark default, 'underlined' (===), or 'atx_closed' (# #)."""
+
+    list_indent_type: Literal["spaces", "tabs"] = "spaces"
+    """Type of indentation for lists."""
+
+    list_indent_width: int = 2
+    """Number of spaces for list indentation (CommonMark uses 2 spaces, ignored if list_indent_type='tabs')."""
+
+    bullets: str = "-*+"
+    """Characters to use for unordered list bullets (cycles through -, *, + for nested levels). CommonMark compliant."""
+
+    strong_em_symbol: Literal["*", "_"] = "*"
+    """Symbol for strong/emphasis formatting."""
+
+    escape_asterisks: bool = False
+    """Escape asterisk characters in text to prevent accidental formatting. Default False for minimal escaping (CommonMark)."""
+
+    escape_underscores: bool = False
+    """Escape underscore characters in text to prevent accidental formatting. Default False for minimal escaping (CommonMark)."""
+
+    escape_misc: bool = False
+    """Escape miscellaneous Markdown characters. Default False for minimal escaping (CommonMark)."""
+
+    escape_ascii: bool = False
+    """Escape all ASCII punctuation (for CommonMark spec compliance tests). Disabled by default for minimal escaping."""
+
+    code_language: str = ""
+    """Default language for code blocks."""
+
+    encoding: str = "utf-8"
+    """Character encoding expected for the HTML input."""
+
+    autolinks: bool = True
+    """Convert bare URLs to automatic links."""
+
+    default_title: bool = False
+    """Add a default title if none exists."""
+
+    keep_inline_images_in: set[str] | None = None
+    """Parent tag names where images should remain inline."""
+
+    br_in_tables: bool = False
+    """Use <br> tags for line breaks in table cells instead of spaces."""
+
+    hocr_spatial_tables: bool = True
+    """Reconstruct tables in hOCR documents using spatial heuristics."""
+
+    highlight_style: Literal["double-equal", "html", "bold"] = "double-equal"
+    """Style for highlighting <mark> elements."""
+
+    extract_metadata: bool = True
+    """Extract metadata from HTML head and include as comment."""
+
+    whitespace_mode: Literal["normalized", "strict"] = "normalized"
+    """How to handle whitespace: 'normalized' or 'strict'."""
+
+    strip_newlines: bool = False
+    """Remove newlines from HTML before processing."""
+
+    wrap: bool = False
+    """Enable text wrapping."""
+
+    wrap_width: int = 80
+    """Column width for text wrapping."""
+
+    strip_tags: set[str] | None = None
+    """HTML tags to strip from output (output only text content, no markdown conversion)."""
+
+    preserve_tags: set[str] | None = None
+    """HTML tags to preserve as-is in the output (keep original HTML). Useful for complex elements like tables."""
+
+    convert_as_inline: bool = False
+    """Treat block elements as inline during conversion."""
+
+    sub_symbol: str = ""
+    """Symbol for subscript text."""
+
+    sup_symbol: str = ""
+    """Symbol for superscript text."""
+
+    newline_style: Literal["spaces", "backslash"] = "spaces"
+    """Style for newlines: 'spaces' (two trailing spaces, CommonMark default) or 'backslash' (\\). Both are equally CommonMark compliant."""
+
+    code_block_style: Literal["indented", "backticks", "tildes"] = "backticks"
+    """Style for code blocks: 'backticks' (```, better whitespace preservation), 'indented' (4 spaces), or 'tildes' (~~~). All are CommonMark compliant."""
+
+    debug: bool = False
+    """Enable debug mode with diagnostic warnings about unhandled elements and hOCR processing."""
+
+
+@dataclass
+class PreprocessingOptions:
+    """HTML preprocessing configuration.
+
+    Controls how HTML is cleaned and preprocessed before conversion.
+
+    Example:
+        >>> options = PreprocessingOptions(
+        ...     enabled=True,
+        ...     preset="aggressive",
+        ...     remove_navigation=True,
+        ... )
+    """
+
+    enabled: bool = True
+    """Whether to enable HTML preprocessing (enabled by default for robust handling of malformed HTML)."""
+
+    preset: Literal["minimal", "standard", "aggressive"] = "standard"
+    """Preprocessing aggressiveness level."""
+
+    remove_navigation: bool = True
+    """Remove navigation elements during preprocessing."""
+
+    remove_forms: bool = True
+    """Remove form elements during preprocessing."""

html_to_markdown/v1_compat.py

@@ -0,0 +1,192 @@
+"""V1 API compatibility layer.
+
+Provides backward compatibility for the v1 convert_to_markdown API
+by translating v1 kwargs to v2 ConversionOptions and PreprocessingOptions.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+from html_to_markdown import ConversionOptions, PreprocessingOptions
+from html_to_markdown import convert as convert_v2
+
+DEPRECATION_MESSAGE = (
+    "The v1 compatibility layer is deprecated and will be removed in v3.0. "
+    "Use html_to_markdown.convert() with ConversionOptions instead."
+)
+
+
+def _warn_deprecated(api_name: str, *, stacklevel: int = 2) -> None:
+    warnings.warn(f"{api_name} is deprecated. {DEPRECATION_MESSAGE}", DeprecationWarning, stacklevel=stacklevel)
+
+
+def convert_to_markdown(
+    html: str,
+    *,
+    heading_style: str = "underlined",
+    list_indent_type: str = "spaces",
+    list_indent_width: int = 4,
+    bullets: str = "*+-",
+    strong_em_symbol: str = "*",
+    escape_asterisks: bool = True,
+    escape_underscores: bool = True,
+    escape_misc: bool = True,
+    code_language: str = "",
+    autolinks: bool = True,
+    default_title: bool = False,
+    br_in_tables: bool = False,
+    hocr_extract_tables: bool = True,
+    hocr_table_column_threshold: int = 50,
+    hocr_table_row_threshold_ratio: float = 0.5,
+    highlight_style: str = "double-equal",
+    extract_metadata: bool = True,
+    whitespace_mode: str = "normalized",
+    strip_newlines: bool = False,
+    wrap: bool = False,
+    wrap_width: int = 80,
+    convert_as_inline: bool = False,
+    sub_symbol: str = "",
+    sup_symbol: str = "",
+    newline_style: str = "spaces",
+    keep_inline_images_in: set[str] | None = None,
+    preprocess: bool = False,
+    preprocessing_preset: str = "standard",
+    remove_navigation: bool = True,
+    remove_forms: bool = True,
+    source_encoding: str = "utf-8",
+    code_language_callback: object | None = None,
+    strip: list[str] | None = None,
+    convert: list[str] | None = None,
+    custom_converters: dict[str, object] | None = None,
+) -> str:
+    """Convert HTML to Markdown (v1 compatibility API).
+
+    This function provides backward compatibility with the v1 API by translating
+    v1-style keyword arguments to v2 ConversionOptions and PreprocessingOptions.
+
+    Args:
+        html: HTML string to convert.
+        heading_style: Style for headings (default: "underlined" for v1 compatibility).
+        list_indent_type: Type of indentation for lists.
+        list_indent_width: Number of spaces for list indentation (v1 default: 4).
+        bullets: Characters to use for unordered list bullets.
+        strong_em_symbol: Symbol for strong/emphasis formatting.
+        escape_asterisks: Escape asterisk characters (v1 default: True).
+        escape_underscores: Escape underscore characters (v1 default: True).
+        escape_misc: Escape miscellaneous Markdown characters (v1 default: True).
+        code_language: Default language for code blocks.
+        autolinks: Convert bare URLs to automatic links.
+        default_title: Add a default title if none exists.
+        br_in_tables: Use <br> tags for line breaks in table cells.
+        hocr_extract_tables: Deprecated - always True in v2.
+        hocr_table_column_threshold: Deprecated - uses built-in heuristics in v2.
+        hocr_table_row_threshold_ratio: Deprecated - uses built-in heuristics in v2.
+        highlight_style: Style for highlighting <mark> elements.
+        extract_metadata: Extract metadata from HTML head.
+        whitespace_mode: How to handle whitespace.
+        strip_newlines: Remove newlines from HTML before processing.
+        wrap: Enable text wrapping.
+        wrap_width: Column width for text wrapping.
+        convert_as_inline: Treat block elements as inline.
+        sub_symbol: Symbol for subscript text.
+        sup_symbol: Symbol for superscript text.
+        newline_style: Style for newlines.
+        keep_inline_images_in: Parent tag names where images should remain inline.
+        preprocess: Enable HTML preprocessing.
+        preprocessing_preset: Preprocessing aggressiveness level.
+        remove_navigation: Remove navigation elements during preprocessing.
+        remove_forms: Remove form elements during preprocessing.
+        source_encoding: Character encoding expected for the HTML input.
+        code_language_callback: Deprecated - not supported in v2.
+        strip: HTML tags to strip from output.
+        convert: Deprecated - not supported in v2.
+        custom_converters: Deprecated - not yet implemented in v2.
+
+    Returns:
+        Converted Markdown string.
+
+    Raises:
+        NotImplementedError: If deprecated v1 features are used.
+
+    .. deprecated:: 2.0
+        Use :func:`html_to_markdown.convert` with :class:`ConversionOptions` instead.
+        The v1 API is provided for backward compatibility only.
+    """
+    _warn_deprecated("convert_to_markdown()", stacklevel=2)
+
+    if code_language_callback is not None:
+        raise NotImplementedError(
+            "code_language_callback was removed in v2. Use the code_language option to set a default language."
+        )
+    if convert is not None:
+        raise NotImplementedError("convert option was removed in v2. All supported tags are converted by default.")
+    if custom_converters is not None:
+        raise NotImplementedError("custom_converters is not yet implemented in v2")
+    if not hocr_extract_tables:
+        warnings.warn(
+            "hocr_extract_tables is deprecated and will be removed in a future release. "
+            "Use ConversionOptions(hocr_spatial_tables=False) to disable spatial table reconstruction.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+    if hocr_table_column_threshold != 50 or hocr_table_row_threshold_ratio != 0.5:
+        raise NotImplementedError(
+            "hOCR table threshold overrides were removed in v2. Table reconstruction now uses built-in heuristics."
+        )
+
+    # ~keep: v1 used indented code blocks by default, but switched to backticks when a language was set
+    # This maintains v1 behavior for backward compatibility
+    code_block_style = "backticks" if code_language else "indented"
+
+    options = ConversionOptions(
+        heading_style=heading_style,  # type: ignore[arg-type]
+        list_indent_type=list_indent_type,  # type: ignore[arg-type]
+        list_indent_width=list_indent_width,
+        bullets=bullets,
+        strong_em_symbol=strong_em_symbol,  # type: ignore[arg-type]
+        escape_asterisks=escape_asterisks,
+        escape_underscores=escape_underscores,
+        escape_misc=escape_misc,
+        code_block_style=code_block_style,  # type: ignore[arg-type]
+        code_language=code_language,
+        autolinks=autolinks,
+        default_title=default_title,
+        br_in_tables=br_in_tables,
+        hocr_spatial_tables=hocr_extract_tables,
+        highlight_style=highlight_style,  # type: ignore[arg-type]
+        extract_metadata=extract_metadata,
+        whitespace_mode=whitespace_mode,  # type: ignore[arg-type]
+        strip_newlines=strip_newlines,
+        wrap=wrap,
+        wrap_width=wrap_width,
+        convert_as_inline=convert_as_inline,
+        sub_symbol=sub_symbol,
+        sup_symbol=sup_symbol,
+        newline_style=newline_style,  # type: ignore[arg-type]
+        keep_inline_images_in=keep_inline_images_in,
+        strip_tags=set(strip) if strip else None,
+    )
+
+    preprocessing = PreprocessingOptions(
+        enabled=preprocess,
+        preset=preprocessing_preset,  # type: ignore[arg-type]
+        remove_navigation=remove_navigation,
+        remove_forms=remove_forms,
+    )
+
+    options.encoding = source_encoding
+    return convert_v2(html, options, preprocessing)
+
+
+def markdownify(*args: object, **kwargs: object) -> str:
+    """Alias for convert_to_markdown (deprecated).
+
+    .. deprecated:: 2.0
+        Use html_to_markdown.convert() instead.
+    """
+    _warn_deprecated("markdownify()", stacklevel=2)
+    return convert_to_markdown(*args, **kwargs)  # type: ignore[arg-type]
+
+
+__all__ = ["convert_to_markdown", "markdownify"]

html_to_markdown-2.9.2.dist-info/METADATA

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: html-to-markdown
+Version: 2.9.2
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Typing :: Typed
+License-File: LICENSE
+Summary: High-performance HTML to Markdown converter powered by Rust with a clean Python API
+Keywords: cli-tool,converter,html,html2markdown,html5,markdown,markup,parser,rust,text-processing
+Home-Page: https://github.com/Goldziher/html-to-markdown
+Author-email: Na'aman Hirschfeld <nhirschfeld@gmail.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/Goldziher/html-to-markdown/releases
+Project-URL: Homepage, https://github.com/Goldziher/html-to-markdown
+Project-URL: Issues, https://github.com/Goldziher/html-to-markdown/issues
+Project-URL: Repository, https://github.com/Goldziher/html-to-markdown.git
+
+# html-to-markdown
+
+High-performance HTML to Markdown converter with a clean Python API (powered by a Rust core). The same engine also drives the Node.js, Ruby, PHP, and WebAssembly bindings, so rendered Markdown stays identical across runtimes. Wheels are published for Linux, macOS, and Windows.
+
+[![Crates.io](https://img.shields.io/crates/v/html-to-markdown.svg)](https://crates.io/crates/html-to-markdown)
+[![npm (node)](https://badge.fury.io/js/html-to-markdown-node.svg)](https://www.npmjs.com/package/html-to-markdown-node)
+[![npm (wasm)](https://badge.fury.io/js/html-to-markdown-wasm.svg)](https://www.npmjs.com/package/html-to-markdown-wasm)
+[![PyPI](https://badge.fury.io/py/html-to-markdown.svg)](https://pypi.org/project/html-to-markdown/)
+[![Packagist](https://img.shields.io/packagist/v/goldziher/html-to-markdown.svg)](https://packagist.org/packages/goldziher/html-to-markdown)
+[![RubyGems](https://badge.fury.io/rb/html-to-markdown.svg)](https://rubygems.org/gems/html-to-markdown)
+[![Hex.pm](https://img.shields.io/hexpm/v/html_to_markdown.svg)](https://hex.pm/packages/html_to_markdown)
+[![NuGet](https://img.shields.io/nuget/v/Goldziher.HtmlToMarkdown.svg)](https://www.nuget.org/packages/Goldziher.HtmlToMarkdown/)
+[![Maven Central](https://img.shields.io/maven-central/v/io.github.goldziher/html-to-markdown.svg)](https://central.sonatype.com/artifact/io.github.goldziher/html-to-markdown)
+[![Go Reference](https://pkg.go.dev/badge/github.com/Goldziher/html-to-markdown/packages/go/htmltomarkdown.svg)](https://pkg.go.dev/github.com/Goldziher/html-to-markdown/packages/go/htmltomarkdown)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Goldziher/html-to-markdown/blob/main/LICENSE)
+[![Discord](https://img.shields.io/badge/Discord-Join%20our%20community-7289da)](https://discord.gg/pXxagNK2zN)
+
+## Installation
+
+```bash
+pip install html-to-markdown
+```
+
+## Performance Snapshot
+
+Apple M4 • Real Wikipedia documents • `convert()` (Python)
+
+| Document            | Size  | Latency | Throughput | Docs/sec |
+| ------------------- | ----- | ------- | ---------- | -------- |
+| Lists (Timeline)    | 129KB | 0.62ms  | 208 MB/s   | 1,613    |
+| Tables (Countries)  | 360KB | 2.02ms  | 178 MB/s   | 495      |
+| Mixed (Python wiki) | 656KB | 4.56ms  | 144 MB/s   | 219      |
+
+> V1 averaged ~2.5 MB/s (Python/BeautifulSoup). V2's Rust engine delivers 60–80× higher throughput.
+
+### Benchmark Fixtures (Apple M4)
+
+Pulled directly from `tools/runtime-bench` (`task bench:bindings -- --language python`) so they stay in lockstep with the Rust core:
+
+| Document               | Size   | ops/sec (Python) |
+| ---------------------- | ------ | ---------------- |
+| Lists (Timeline)       | 129 KB | 1,405            |
+| Tables (Countries)     | 360 KB | 352              |
+| Medium (Python)        | 657 KB | 158              |
+| Large (Rust)           | 567 KB | 183              |
+| Small (Intro)          | 463 KB | 223              |
+| hOCR German PDF        | 44 KB  | 2,991            |
+| hOCR Invoice           | 4 KB   | 23,500           |
+| hOCR Embedded Tables   | 37 KB  | 3,464            |
+
+> Re-run locally with `task bench:bindings -- --language python --output tmp.json` to compare against CI history.
+
+## Quick Start
+
+```python
+from html_to_markdown import convert
+
+html = """
+<h1>Welcome</h1>
+<p>This is <strong>fast</strong> Rust-powered conversion!</p>
+<ul>
+    <li>Blazing fast</li>
+    <li>Type safe</li>
+    <li>Easy to use</li>
+</ul>
+"""
+
+markdown = convert(html)
+print(markdown)
+```
+
+## Configuration (v2 API)
+
+```python
+from html_to_markdown import ConversionOptions, convert
+
+options = ConversionOptions(
+    heading_style="atx",
+    list_indent_width=2,
+    bullets="*+-",
+)
+options.escape_asterisks = True
+options.code_language = "python"
+options.extract_metadata = True
+
+markdown = convert(html, options)
+```
+
+### Reusing Parsed Options
+
+Avoid re-parsing the same option dictionaries inside hot loops by building a reusable handle:
+
+```python
+from html_to_markdown import ConversionOptions, convert_with_handle, create_options_handle
+
+handle = create_options_handle(ConversionOptions(hocr_spatial_tables=False))
+
+for html in documents:
+    markdown = convert_with_handle(html, handle)
+```
+
+### HTML Preprocessing
+
+```python
+from html_to_markdown import ConversionOptions, PreprocessingOptions, convert
+
+options = ConversionOptions(
+    ...
+)
+
+preprocessing = PreprocessingOptions(
+    enabled=True,
+    preset="aggressive",
+)
+
+markdown = convert(scraped_html, options, preprocessing)
+```
+
+### Inline Image Extraction
+
+```python
+from html_to_markdown import InlineImageConfig, convert_with_inline_images
+
+markdown, inline_images, warnings = convert_with_inline_images(
+    '<p><img src="data:image/png;base64,...==" alt="Pixel" width="1" height="1"></p>',
+    image_config=InlineImageConfig(max_decoded_size_bytes=1024, infer_dimensions=True),
+)
+
+if inline_images:
+    first = inline_images[0]
+    print(first["format"], first["dimensions"], first["attributes"])  # e.g. "png", (1, 1), {"width": "1"}
+```
+
+Each inline image is returned as a typed dictionary (`bytes` payload, metadata, and relevant HTML attributes). Warnings are human-readable skip reasons.
+
+### hOCR (HTML OCR) Support
+
+```python
+from html_to_markdown import ConversionOptions, convert
+
+# Default: emit structured Markdown directly
+markdown = convert(hocr_html)
+
+# hOCR documents are detected automatically; tables are reconstructed without extra configuration.
+markdown = convert(hocr_html)
+```
+
+## CLI (same engine)
+
+```bash
+pipx install html-to-markdown  # or: pip install html-to-markdown
+
+html-to-markdown page.html > page.md
+cat page.html | html-to-markdown --heading-style atx > page.md
+```
+
+## API Surface
+
+### `ConversionOptions`
+
+Key fields (see docstring for full matrix):
+
+- `heading_style`: `"underlined" | "atx" | "atx_closed"`
+- `list_indent_width`: spaces per indent level (default 2)
+- `bullets`: cycle of bullet characters (`"*+-"`)
+- `strong_em_symbol`: `"*"` or `"_"`
+- `code_language`: default fenced code block language
+- `wrap`, `wrap_width`: wrap Markdown output
+- `strip_tags`: remove specific HTML tags
+- `preprocessing`: `PreprocessingOptions`
+- `encoding`: input character encoding (informational)
+
+### `PreprocessingOptions`
+
+- `enabled`: enable HTML sanitisation (default: `True` since v2.4.2 for robust malformed HTML handling)
+- `preset`: `"minimal" | "standard" | "aggressive"` (default: `"standard"`)
+- `remove_navigation`: remove navigation elements (default: `True`)
+- `remove_forms`: remove form elements (default: `True`)
+
+**Note:** As of v2.4.2, preprocessing is enabled by default to ensure robust handling of malformed HTML (e.g., bare angle brackets like `1<2` in content). Set `enabled=False` if you need minimal preprocessing.
+
+### `InlineImageConfig`
+
+- `max_decoded_size_bytes`: reject larger payloads
+- `filename_prefix`: generated name prefix (`embedded_image` default)
+- `capture_svg`: collect inline `<svg>` (default `True`)
+- `infer_dimensions`: decode raster images to obtain dimensions (default `False`)
+
+## Performance: V2 vs V1 Compatibility Layer
+
+### ⚠️ Important: Always Use V2 API
+
+The v2 API (`convert()`) is **strongly recommended** for all code. The v1 compatibility layer adds significant overhead and should only be used for gradual migration:
+
+```python
+# ✅ RECOMMENDED - V2 Direct API (Fast)
+from html_to_markdown import convert, ConversionOptions
+
+markdown = convert(html)  # Simple conversion - FAST
+markdown = convert(html, ConversionOptions(heading_style="atx"))  # With options - FAST
+
+# ❌ AVOID - V1 Compatibility Layer (Slow)
+from html_to_markdown import convert_to_markdown
+
+markdown = convert_to_markdown(html, heading_style="atx")  # Adds 77% overhead
+```
+
+### Performance Comparison
+
+Benchmarked on Apple M4 with 25-paragraph HTML document:
+
+| API                      | ops/sec          | Relative Performance | Recommendation      |
+| ------------------------ | ---------------- | -------------------- | ------------------- |
+| **V2 API** (`convert()`) | **129,822**      | baseline             | ✅ **Use this**     |
+| **V1 Compat Layer**      | **67,673**       | **77% slower**       | ⚠️ Migration only   |
+| **CLI**                  | **150-210 MB/s** | Fastest              | ✅ Batch processing |
+
+The v1 compatibility layer creates extra Python objects and performs additional conversions, significantly impacting performance.
+
+### When to Use Each
+
+- **V2 API (`convert()`)**: All new code, production systems, performance-critical applications ← **Use this**
+- **V1 Compat (`convert_to_markdown()`)**: Only for gradual migration from legacy codebases
+- **CLI (`html-to-markdown`)**: Batch processing, shell scripts, maximum throughput
+
+## v1 Compatibility
+
+A compatibility layer is provided to ease migration from v1.x:
+
+- **Compat shim**: `html_to_markdown.v1_compat` exposes `convert_to_markdown`, `convert_to_markdown_stream`, and `markdownify`. Keyword mappings are listed in the [changelog](https://github.com/Goldziher/html-to-markdown/blob/main/CHANGELOG.md#v200).
+- **⚠️ Performance warning**: These compatibility functions add 77% overhead. Migrate to v2 API as soon as possible.
+- **CLI**: The Rust CLI replaces the old Python script. New flags are documented via `html-to-markdown --help`.
+- **Removed options**: `code_language_callback`, `strip`, and streaming APIs were removed; use `ConversionOptions`, `PreprocessingOptions`, and the inline-image helpers instead.
+
+## Links
+
+- GitHub: [https://github.com/Goldziher/html-to-markdown](https://github.com/Goldziher/html-to-markdown)
+- Discord: [https://discord.gg/pXxagNK2zN](https://discord.gg/pXxagNK2zN)
+- Kreuzberg ecosystem: [https://kreuzberg.dev](https://kreuzberg.dev)
+
+## License
+
+MIT License – see [LICENSE](https://github.com/Goldziher/html-to-markdown/blob/main/LICENSE).
+
+## Support
+
+If you find this library useful, consider [sponsoring the project](https://github.com/sponsors/Goldziher).
+

html_to_markdown-2.9.2.dist-info/RECORD

@@ -0,0 +1,17 @@
+html_to_markdown/__init__.py,sha256=aX-YIWAK87DqmkDOx8qMuCLbXqOHbm6sckMk5pWZOIs,1506
+html_to_markdown/__main__.py,sha256=3Ic_EbOt2h6W88q084pkz5IKU6iY5z_woBygH6u9aw0,327
+html_to_markdown/_html_to_markdown.abi3.so,sha256=xdq0A3NaCuMVknVykYmO_WwH2S50gXN5Z1rNl9gKKM4,4401816
+html_to_markdown/_html_to_markdown.pyi,sha256=ke8_jd35wwoSDj5KX1YM5Sj_y_tD7qn4GLgVG4RwZ1E,856
+html_to_markdown/api.py,sha256=EDn838XWA5LSKSFhgtVHc2fqn5rzhsnCAMybPlTooak,5090
+html_to_markdown/cli.py,sha256=Rn-s3FZPea1jgCJtDzH_TFvOEiA_uZFVfgjhr6xyL_g,64
+html_to_markdown/cli_proxy.py,sha256=HPYKH5Mf5OUvkbEQISJvAkxrbjWKxE5GokA44HoQ6z8,3858
+html_to_markdown/exceptions.py,sha256=aTASOzbywgfqOYjlw18ZkOWSxKff4EbUbmMua_73TGA,2370
+html_to_markdown/options.py,sha256=vImRfeHAeyAy0Lnt6cTPHGbj7mTdw8AEUgo19u7MAA0,5080
+html_to_markdown/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+html_to_markdown/v1_compat.py,sha256=nZN8hVd3u4vacbfyLsPMIGqSmJENZgx1Ya0SpqVLi-g,8061
+html_to_markdown/bin/html-to-markdown,sha256=mhumOD3LUj2YdrVOOEj8Q9H9yU2uKIwCrffBWMgqx1Y,4514832
+html_to_markdown-2.9.2.data/scripts/html-to-markdown,sha256=mhumOD3LUj2YdrVOOEj8Q9H9yU2uKIwCrffBWMgqx1Y,4514832
+html_to_markdown-2.9.2.dist-info/METADATA,sha256=yW-foX4ejruLx3NxZQN4qZJww9UKN1EL6GXp53aarUI,11697
+html_to_markdown-2.9.2.dist-info/WHEEL,sha256=GZ8Bj1_F3gyOkAjh92uwv3D10I5SM_VZJkuZVDmniNg,146
+html_to_markdown-2.9.2.dist-info/RECORD,,
+html_to_markdown-2.9.2.dist-info/licenses/LICENSE,sha256=oQvPC-0UWvfg0WaeUBe11OJMtX60An-TW1ev_oaAA0k,1086

html_to_markdown-2.9.2.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: maturin (1.10.2)
+Root-Is-Purelib: false
+Tag: cp310-abi3-manylinux_2_17_x86_64
+Tag: cp310-abi3-manylinux2014_x86_64
+

html_to_markdown-2.9.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright 2024-2025 Na'aman Hirschfeld
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.