html-to-markdown 2.2.0__cp310-abi3-macosx_11_0_arm64.whl → 2.3.3__cp310-abi3-macosx_11_0_arm64.whl

html_to_markdown/__init__.py

@@ -15,7 +15,13 @@ V1 API (backward compatibility):
     markdown = convert_to_markdown(html, heading_style="atx")
 """
 
-from html_to_markdown.api import convert
+from html_to_markdown.api import (
+    InlineImage,
+    InlineImageConfig,
+    InlineImageWarning,
+    convert,
+    convert_with_inline_images,
+)
 from html_to_markdown.exceptions import (
     ConflictingOptionsError,
     EmptyHtmlError,
@@ -31,12 +37,16 @@ __all__ = [
     "ConversionOptions",
     "EmptyHtmlError",
     "HtmlToMarkdownError",
+    "InlineImage",
+    "InlineImageConfig",
+    "InlineImageWarning",
     "InvalidParserError",
     "MissingDependencyError",
     "PreprocessingOptions",
     "convert",
     "convert_to_markdown",
+    "convert_with_inline_images",
     "markdownify",
 ]
 
-__version__ = "2.2.0"
+__version__ = "2.3.3"

html_to_markdown/api.py

@@ -6,38 +6,52 @@ using the Rust backend for conversion.
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING, Literal, TypedDict, cast
+
 import html_to_markdown._html_to_markdown as _rust  # type: ignore[import-not-found]
 from html_to_markdown.options import ConversionOptions, PreprocessingOptions
 
+if TYPE_CHECKING:
+    from html_to_markdown._html_to_markdown import InlineImageConfig
+else:
+    InlineImageConfig = _rust.InlineImageConfig  # type: ignore[misc, assignment]
 
-def convert(
-    html: str,
-    options: ConversionOptions | None = None,
-    preprocessing: PreprocessingOptions | None = None,
-) -> str:
-    """Convert HTML to Markdown using the Rust backend.
 
-    Args:
-        html: HTML string to convert.
-        options: Conversion configuration options (defaults to ConversionOptions()).
-        preprocessing: HTML preprocessing options (defaults to 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]
 
-    Returns:
-        Converted Markdown string.
-    """
-    if options is None:
-        options = ConversionOptions()
-    if preprocessing is None:
-        preprocessing = PreprocessingOptions()
 
-    rust_preprocessing = _rust.PreprocessingOptions(
-        enabled=preprocessing.enabled,
-        preset=preprocessing.preset,
-        remove_navigation=preprocessing.remove_navigation,
-        remove_forms=preprocessing.remove_forms,
+class InlineImageWarning(TypedDict):
+    """Warning produced during inline image extraction."""
+
+    index: int
+    message: str
+
+
+def _to_rust_preprocessing(options: PreprocessingOptions) -> _rust.PreprocessingOptions:
+    """Convert high-level preprocessing options to the Rust bindings."""
+    return _rust.PreprocessingOptions(
+        enabled=options.enabled,
+        preset=options.preset,
+        remove_navigation=options.remove_navigation,
+        remove_forms=options.remove_forms,
     )
 
-    rust_options = _rust.ConversionOptions(
+
+def _to_rust_options(
+    options: ConversionOptions,
+    preprocessing: PreprocessingOptions,
+) -> _rust.ConversionOptions:
+    """Convert high-level conversion options to the Rust bindings."""
+    return _rust.ConversionOptions(
         heading_style=options.heading_style,
         list_indent_type=options.list_indent_type,
         list_indent_width=options.list_indent_width,
@@ -64,11 +78,66 @@ def convert(
         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=rust_preprocessing,
+        preprocessing=_to_rust_preprocessing(preprocessing),
         encoding=options.encoding,
         debug=options.debug,
         strip_tags=list(options.strip_tags) if options.strip_tags else [],
     )
 
-    result: str = _rust.convert(html, rust_options)
-    return result
+
+def convert(
+    html: str,
+    options: ConversionOptions | None = None,
+    preprocessing: PreprocessingOptions | None = None,
+) -> str:
+    """Convert HTML to Markdown using the Rust backend.
+
+    Args:
+        html: HTML string to convert.
+        options: Conversion configuration options (defaults to ConversionOptions()).
+        preprocessing: HTML preprocessing options (defaults to PreprocessingOptions()).
+
+    Returns:
+        Converted Markdown string.
+    """
+    if options is None:
+        options = ConversionOptions()
+    if preprocessing is None:
+        preprocessing = PreprocessingOptions()
+
+    rust_options = _to_rust_options(options, preprocessing)
+    return cast("str", _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.
+
+    Returns Markdown along with extracted inline images and any warnings.
+    """
+    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)
+
+
+__all__ = [
+    "InlineImage",
+    "InlineImageConfig",
+    "InlineImageWarning",
+    "convert",
+    "convert_with_inline_images",
+]

html_to_markdown/cli_proxy.py

@@ -97,7 +97,7 @@ def translate_v1_args_to_v2(argv: list[str]) -> list[str]:
 
 
 def main(argv: list[str]) -> str:
-    """Main entry point for the CLI proxy.
+    """Execute the CLI proxy.
 
     Translates v1 arguments to v2 and invokes the native Rust CLI binary.
 

{html_to_markdown-2.2.0.dist-info → html_to_markdown-2.3.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: html-to-markdown
-Version: 2.2.0
+Version: 2.3.3
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -52,11 +52,11 @@ 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      |
+| 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.
+> V1 averaged ~2.5 MB/s (Python/BeautifulSoup). V2's Rust engine delivers 60–80× higher throughput.
 
 ## Quick Start
 
@@ -173,11 +173,50 @@ Key fields (see docstring for full matrix):
 - `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
 
-- **Performance**: V1 averaged ~2.5 MB/s; V2 sustains 150–210 MB/s with identical Markdown output.
-- **Compat shim**: `html_to_markdown.v1_compat` exposes `convert_to_markdown`, `convert_to_markdown_stream`, and `markdownify` to ease migration. Keyword mappings are listed in the [changelog](CHANGELOG.md#v200).
-- **CLI**: The Rust CLI replaces the Python script. New flags are documented via `html-to-markdown --help`.
+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](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

html_to_markdown-2.3.3.dist-info/RECORD

@@ -0,0 +1,17 @@
+html_to_markdown-2.3.3.dist-info/RECORD,,
+html_to_markdown-2.3.3.dist-info/WHEEL,sha256=HtAbUhtjhH1WdiDuIy2CapdoAiKCwe6bij_Tlxr1lEg,131
+html_to_markdown-2.3.3.dist-info/METADATA,sha256=oyNmsZG9JQEEaxycvu3C6Xlj7ZnuzUoYW_A3U2c7P4c,8811
+html_to_markdown-2.3.3.dist-info/licenses/LICENSE,sha256=oQvPC-0UWvfg0WaeUBe11OJMtX60An-TW1ev_oaAA0k,1086
+html_to_markdown-2.3.3.data/scripts/html-to-markdown,sha256=Xba9k0_dGOyIhO3rVoVPjxZ3H1Mig9cwNGwSJ6tkcZA,3834352
+html_to_markdown/options.py,sha256=N1orEtzXiqgV88Y7eqRjw3ilxDi7N97FBkBa79hdfzo,4913
+html_to_markdown/_html_to_markdown.abi3.so,sha256=_4-WXBZHE5NikMeg37k9Eh5mXc0mD2pzk25_qLWwJls,3668304
+html_to_markdown/__init__.py,sha256=QjyTIjeujelR5cVDnq8xE6e-ADD8pwijntK4wFEl4rE,1358
+html_to_markdown/api.py,sha256=sXezV2iZb42s-za0hWWHFhihKjaMo6j_tx7e-0EyQPg,4860
+html_to_markdown/_rust.pyi,sha256=pi6C_qAdB81qUlC89Dy1ZKC1JrpdnqVce-caJx3ekPA,2098
+html_to_markdown/v1_compat.py,sha256=5DZA-fPMqZ5hYiA43rFaOAqshLS8MScbBnivDXuvQII,8034
+html_to_markdown/cli.py,sha256=Rn-s3FZPea1jgCJtDzH_TFvOEiA_uZFVfgjhr6xyL_g,64
+html_to_markdown/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+html_to_markdown/exceptions.py,sha256=aTASOzbywgfqOYjlw18ZkOWSxKff4EbUbmMua_73TGA,2370
+html_to_markdown/cli_proxy.py,sha256=8Byrnok5-WkDWToaUeMcKi1xVr62PhZKygHymdrSfFE,3682
+html_to_markdown/__main__.py,sha256=3Ic_EbOt2h6W88q084pkz5IKU6iY5z_woBygH6u9aw0,327
+html_to_markdown/bin/html-to-markdown,sha256=Xba9k0_dGOyIhO3rVoVPjxZ3H1Mig9cwNGwSJ6tkcZA,3834352

html_to_markdown-2.2.0.dist-info/RECORD

@@ -1,17 +0,0 @@
-html_to_markdown-2.2.0.data/scripts/html-to-markdown,sha256=_jgp22NNhPsmx9MgSb11wrTWiYpwnzZ7qZtpdXrudls,3817824
-html_to_markdown-2.2.0.dist-info/RECORD,,
-html_to_markdown-2.2.0.dist-info/WHEEL,sha256=HtAbUhtjhH1WdiDuIy2CapdoAiKCwe6bij_Tlxr1lEg,131
-html_to_markdown-2.2.0.dist-info/METADATA,sha256=v8jDHZrq6_Vuwry7Dn3e8r9QlAZDj3-8kU_mFrSA9og,7071
-html_to_markdown-2.2.0.dist-info/licenses/LICENSE,sha256=oQvPC-0UWvfg0WaeUBe11OJMtX60An-TW1ev_oaAA0k,1086
-html_to_markdown/options.py,sha256=N1orEtzXiqgV88Y7eqRjw3ilxDi7N97FBkBa79hdfzo,4913
-html_to_markdown/_html_to_markdown.abi3.so,sha256=xI0Wr26xhNoPGzlrlngo49vWvg61X_4d0xdMd9de8Rk,3668288
-html_to_markdown/__init__.py,sha256=QZ314Edod-PD-v5CvRtJ-Lw7lqXqHP6o36UtyzUQrg8,1149
-html_to_markdown/api.py,sha256=f0jhD003p8Kz5jHe0BdaKN8Uh9mvGDo2Sl9eNw06VAY,2784
-html_to_markdown/_rust.pyi,sha256=pi6C_qAdB81qUlC89Dy1ZKC1JrpdnqVce-caJx3ekPA,2098
-html_to_markdown/v1_compat.py,sha256=5DZA-fPMqZ5hYiA43rFaOAqshLS8MScbBnivDXuvQII,8034
-html_to_markdown/cli.py,sha256=Rn-s3FZPea1jgCJtDzH_TFvOEiA_uZFVfgjhr6xyL_g,64
-html_to_markdown/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-html_to_markdown/exceptions.py,sha256=aTASOzbywgfqOYjlw18ZkOWSxKff4EbUbmMua_73TGA,2370
-html_to_markdown/cli_proxy.py,sha256=MbDRZdmQMCDI9cruy1vifc__FsjNPRdvBXKFU9GaAZE,3695
-html_to_markdown/__main__.py,sha256=3Ic_EbOt2h6W88q084pkz5IKU6iY5z_woBygH6u9aw0,327
-html_to_markdown/bin/html-to-markdown,sha256=_jgp22NNhPsmx9MgSb11wrTWiYpwnzZ7qZtpdXrudls,3817824