html-to-markdown 2.1.2__cp310-abi3-macosx_11_0_arm64.whl → 2.3.0__cp310-abi3-macosx_11_0_arm64.whl

html_to_markdown/__init__.py

@@ -39,4 +39,4 @@ __all__ = [
     "markdownify",
 ]
 
-__version__ = "2.1.1"
+__version__ = "2.3.0"

html_to_markdown/_rust.pyi

@@ -11,6 +11,7 @@ class ConversionOptions:
     autolinks: bool
     default_title: bool
     br_in_tables: bool
+    hocr_spatial_tables: bool
     highlight_style: str
     extract_metadata: bool
     whitespace_mode: str
@@ -39,6 +40,7 @@ class ConversionOptions:
         autolinks: bool = True,
         default_title: bool = False,
         br_in_tables: bool = False,
+        hocr_spatial_tables: bool = True,
         highlight_style: str = "double-equal",
         extract_metadata: bool = True,
         whitespace_mode: str = "normalized",

html_to_markdown/api.py

@@ -51,6 +51,7 @@ def convert(
         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,

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/options.py

@@ -71,6 +71,9 @@ class ConversionOptions:
     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."""
 

html_to_markdown/v1_compat.py

@@ -120,8 +120,11 @@ def convert_to_markdown(
     if custom_converters is not None:
         raise NotImplementedError("custom_converters is not yet implemented in v2")
     if not hocr_extract_tables:
-        raise NotImplementedError(
-            "hocr_extract_tables toggle was removed in v2. hOCR tables are always reconstructed when detected."
+        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(
@@ -146,6 +149,7 @@ def convert_to_markdown(
         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]

{html_to_markdown-2.1.2.dist-info → html_to_markdown-2.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: html-to-markdown
-Version: 2.1.2
+Version: 2.3.0
 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.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+html_to_markdown-2.3.0.data/scripts/html-to-markdown,sha256=Pq5ne6u45stGE7uabdTs-zMJ9iyVNur55DEqWpxEnqA,3817824
+html_to_markdown-2.3.0.dist-info/RECORD,,
+html_to_markdown-2.3.0.dist-info/WHEEL,sha256=HtAbUhtjhH1WdiDuIy2CapdoAiKCwe6bij_Tlxr1lEg,131
+html_to_markdown-2.3.0.dist-info/METADATA,sha256=tt8NYBDARFjWP7kXkCDuiBOGqhMVNoC-h3yv93qbG5Y,8811
+html_to_markdown-2.3.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=yo-M4pugwmV5qNdpeq3Hm1So_4JLPilqkYjV1O9mWSQ,3668288
+html_to_markdown/__init__.py,sha256=f-xST7KCaVMfqGiTcwAdWDRdYOOLmsXF3Ivgpn5MR70,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=8Byrnok5-WkDWToaUeMcKi1xVr62PhZKygHymdrSfFE,3682
+html_to_markdown/__main__.py,sha256=3Ic_EbOt2h6W88q084pkz5IKU6iY5z_woBygH6u9aw0,327
+html_to_markdown/bin/html-to-markdown,sha256=Pq5ne6u45stGE7uabdTs-zMJ9iyVNur55DEqWpxEnqA,3817824

html_to_markdown-2.1.2.dist-info/RECORD

@@ -1,17 +0,0 @@
-html_to_markdown-2.1.2.data/scripts/html-to-markdown,sha256=7PFfHn91sQQL-AWpzh5gBRz0xVbizJBLYQs4izr24yc,3784640
-html_to_markdown-2.1.2.dist-info/RECORD,,
-html_to_markdown-2.1.2.dist-info/WHEEL,sha256=HtAbUhtjhH1WdiDuIy2CapdoAiKCwe6bij_Tlxr1lEg,131
-html_to_markdown-2.1.2.dist-info/METADATA,sha256=W-yMCoN32dNA4ggXeZLY1RazbepXMmuE2yNVxkmUizQ,7071
-html_to_markdown-2.1.2.dist-info/licenses/LICENSE,sha256=oQvPC-0UWvfg0WaeUBe11OJMtX60An-TW1ev_oaAA0k,1086
-html_to_markdown/options.py,sha256=oV-_GFEKuL3RBu27RD1AhVruEh-bNuY3c8ATRbzcos0,4802
-html_to_markdown/_html_to_markdown.abi3.so,sha256=igb9iD5dR4jf2qpiaLG0IYvNz_gzQ7d0yx5ofdNK6Sg,3618704
-html_to_markdown/__init__.py,sha256=-HSsEKPPjp08ksh9aZi3xwdTE9-kNvplMlG2npMPVuI,1149
-html_to_markdown/api.py,sha256=HuM6RZg064VxrTvwcY-OmraS-hsGM9Bt1tIaM0_w7F8,2727
-html_to_markdown/_rust.pyi,sha256=An3Wlvedlr_2XgzqmXulLi5AzMx3HTqOJWH11M5cgcY,2026
-html_to_markdown/v1_compat.py,sha256=VQq1wv8OedkESpCFaUpaSUBh6vJNkByylVUbY6EPIZ8,7856
-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=7PFfHn91sQQL-AWpzh5gBRz0xVbizJBLYQs4izr24yc,3784640