html-to-markdown 1.2.1__tar.gz → 1.3.0__tar.gz

{html_to_markdown-1.2.1 → html_to_markdown-1.3.0}/PKG-INFO

@@ -1,11 +1,10 @@
 Metadata-Version: 2.4
 Name: html-to-markdown
-Version: 1.2.1
+Version: 1.3.0
 Summary: Convert HTML to markdown
-Project-URL: homepage, https://github.com/Goldziher/html-to-markdown
 Author-email: Na'aman Hirschfeld <nhirschfeld@gmail.com>
 License: MIT
-License-File: LICENSE
+Project-URL: homepage, https://github.com/Goldziher/html-to-markdown
 Keywords: converter,html,markdown,text-extraction,text-processing
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -23,8 +22,10 @@ Classifier: Topic :: Text Processing :: Markup :: Markdown
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.9
-Requires-Dist: beautifulsoup4>=4.12.3
 Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: beautifulsoup4>=4.12.3
+Dynamic: license-file
 
 # html-to-markdown
 
@@ -116,6 +117,26 @@ markdown = convert_to_markdown(
 )
 ```
 
+### Custom Converters
+
+You can provide your own conversion functions for specific HTML tags:
+
+```python
+from bs4.element import Tag
+from html_to_markdown import convert_to_markdown
+
+# Define a custom converter for the <b> tag
+def custom_bold_converter(*, tag: Tag, text: str, **kwargs) -> str:
+    return f"IMPORTANT: {text}"
+
+html = "<p>This is a <b>bold statement</b>.</p>"
+markdown = convert_to_markdown(html, custom_converters={"b": custom_bold_converter})
+print(markdown)
+# Output: This is a IMPORTANT: bold statement.
+```
+
+Custom converters take precedence over the built-in converters and can be used alongside other configuration options.
+
 ### Configuration Options
 
 | Option               | Type | Default        | Description                                            |
@@ -189,6 +210,7 @@ Full list of configuration options:
 - `wrap`: Enable text wrapping
 - `wrap_width`: Width for text wrapping
 - `convert_as_inline`: Treat content as inline elements
+- `custom_converters`: A mapping of HTML tag names to custom converter functions
 
 ## Contribution
 

{html_to_markdown-1.2.1 → html_to_markdown-1.3.0}/README.md

@@ -88,6 +88,26 @@ markdown = convert_to_markdown(
 )
 ```
 
+### Custom Converters
+
+You can provide your own conversion functions for specific HTML tags:
+
+```python
+from bs4.element import Tag
+from html_to_markdown import convert_to_markdown
+
+# Define a custom converter for the <b> tag
+def custom_bold_converter(*, tag: Tag, text: str, **kwargs) -> str:
+    return f"IMPORTANT: {text}"
+
+html = "<p>This is a <b>bold statement</b>.</p>"
+markdown = convert_to_markdown(html, custom_converters={"b": custom_bold_converter})
+print(markdown)
+# Output: This is a IMPORTANT: bold statement.
+```
+
+Custom converters take precedence over the built-in converters and can be used alongside other configuration options.
+
 ### Configuration Options
 
 | Option               | Type | Default        | Description                                            |
@@ -161,6 +181,7 @@ Full list of configuration options:
 - `wrap`: Enable text wrapping
 - `wrap_width`: Width for text wrapping
 - `convert_as_inline`: Treat content as inline elements
+- `custom_converters`: A mapping of HTML tag names to custom converter functions
 
 ## Contribution
 

{html_to_markdown-1.2.1 → html_to_markdown-1.3.0}/html_to_markdown/converters.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
-from collections.abc import Iterable, Mapping
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
 from functools import partial
 from inspect import getfullargspec
 from textwrap import fill
@@ -55,7 +58,8 @@ SupportedElements = Literal[
     "kbd",
 ]
 
-ConvertersMap = Mapping[SupportedElements, Callable[[str, Tag], str]]
+Converter = Callable[[str, Tag], str]
+ConvertersMap = dict[SupportedElements, Converter]
 
 T = TypeVar("T")
 

{html_to_markdown-1.2.1 → html_to_markdown-1.3.0}/html_to_markdown/processing.py

@@ -1,5 +1,9 @@
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
 from itertools import chain
 from typing import TYPE_CHECKING, Any, Callable, Literal, cast
 
@@ -12,7 +16,7 @@ from html_to_markdown.constants import (
     html_heading_re,
     whitespace_re,
 )
-from html_to_markdown.converters import ConvertersMap, create_converters_map
+from html_to_markdown.converters import Converter, ConvertersMap, SupportedElements, create_converters_map
 from html_to_markdown.utils import escape
 
 if TYPE_CHECKING:
@@ -189,6 +193,8 @@ def convert_to_markdown(
     code_language: str = "",
     code_language_callback: Callable[[Any], str] | None = None,
     convert: str | Iterable[str] | None = None,
+    convert_as_inline: bool = False,
+    custom_converters: Mapping[SupportedElements, Converter] | None = None,
     default_title: bool = False,
     escape_asterisks: bool = True,
     escape_misc: bool = True,
@@ -202,7 +208,6 @@ def convert_to_markdown(
     sup_symbol: str = "",
     wrap: bool = False,
     wrap_width: int = 80,
-    convert_as_inline: bool = False,
 ) -> str:
     """Convert HTML to Markdown.
 
@@ -213,6 +218,8 @@ def convert_to_markdown(
         code_language: Default language identifier for fenced code blocks. Defaults to an empty string.
         code_language_callback: Function to dynamically determine the language for code blocks.
         convert: A list of tag names to convert to Markdown. If None, all supported tags are converted.
+        convert_as_inline: Treat the content as inline elements (no block elements like paragraphs). Defaults to False.
+        custom_converters: A mapping of custom converters for specific HTML tags. Defaults to None.
         default_title: Use the default title when converting certain elements (e.g., links). Defaults to False.
         escape_asterisks: Escape asterisks (*) to prevent unintended Markdown formatting. Defaults to True.
         escape_misc: Escape miscellaneous characters to prevent conflicts in Markdown. Defaults to True.
@@ -226,7 +233,6 @@ def convert_to_markdown(
         sup_symbol: Custom symbol for superscript text. Defaults to an empty string.
         wrap: Wrap text to the specified width. Defaults to False.
         wrap_width: The number of characters at which to wrap text. Defaults to 80.
-        convert_as_inline: Treat the content as inline elements (no block elements like paragraphs). Defaults to False.
 
     Raises:
         ValueError: If both 'strip' and 'convert' are specified, or when the input HTML is empty.
@@ -260,6 +266,8 @@ def convert_to_markdown(
         wrap=wrap,
         wrap_width=wrap_width,
     )
+    if custom_converters:
+        converters_map.update(cast("ConvertersMap", custom_converters))
 
     return _process_tag(
         source,

html_to_markdown-1.3.0/html_to_markdown.egg-info/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: html-to-markdown
+Version: 1.3.0
+Summary: Convert HTML to markdown
+Author-email: Na'aman Hirschfeld <nhirschfeld@gmail.com>
+License: MIT
+Project-URL: homepage, https://github.com/Goldziher/html-to-markdown
+Keywords: converter,html,markdown,text-extraction,text-processing
+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.9
+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: Topic :: Text Processing
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: beautifulsoup4>=4.12.3
+Dynamic: license-file
+
+# html-to-markdown
+
+A modern, fully typed Python library for converting HTML to Markdown. This library is a completely rewritten fork
+of [markdownify](https://pypi.org/project/markdownify/) with a modernized codebase, strict type safety and support for
+Python 3.9+.
+
+## Features
+
+- Full type safety with strict MyPy adherence
+- Functional API design
+- Extensive test coverage
+- Configurable conversion options
+- CLI tool for easy conversions
+- Support for pre-configured BeautifulSoup instances
+- Strict semver versioning
+
+## Installation
+
+```shell
+pip install html-to-markdown
+```
+
+## Quick Start
+
+Convert HTML to Markdown with a single function call:
+
+```python
+from html_to_markdown import convert_to_markdown
+
+html = """
+<article>
+    <h1>Welcome</h1>
+    <p>This is a <strong>sample</strong> with a <a href="https://example.com">link</a>.</p>
+    <ul>
+        <li>Item 1</li>
+        <li>Item 2</li>
+    </ul>
+</article>
+"""
+
+markdown = convert_to_markdown(html)
+print(markdown)
+```
+
+Output:
+
+```markdown
+# Welcome
+
+This is a **sample** with a [link](https://example.com).
+
+* Item 1
+* Item 2
+```
+
+### Working with BeautifulSoup
+
+If you need more control over HTML parsing, you can pass a pre-configured BeautifulSoup instance:
+
+```python
+from bs4 import BeautifulSoup
+from html_to_markdown import convert_to_markdown
+
+# Configure BeautifulSoup with your preferred parser
+soup = BeautifulSoup(html, "lxml")  # Note: lxml requires additional installation
+markdown = convert_to_markdown(soup)
+```
+
+## Advanced Usage
+
+### Customizing Conversion Options
+
+The library offers extensive customization through various options:
+
+```python
+from html_to_markdown import convert_to_markdown
+
+html = "<div>Your content here...</div>"
+markdown = convert_to_markdown(
+    html,
+    heading_style="atx",  # Use # style headers
+    strong_em_symbol="*",  # Use * for bold/italic
+    bullets="*+-",  # Define bullet point characters
+    wrap=True,  # Enable text wrapping
+    wrap_width=100,  # Set wrap width
+    escape_asterisks=True,  # Escape * characters
+    code_language="python",  # Default code block language
+)
+```
+
+### Custom Converters
+
+You can provide your own conversion functions for specific HTML tags:
+
+```python
+from bs4.element import Tag
+from html_to_markdown import convert_to_markdown
+
+# Define a custom converter for the <b> tag
+def custom_bold_converter(*, tag: Tag, text: str, **kwargs) -> str:
+    return f"IMPORTANT: {text}"
+
+html = "<p>This is a <b>bold statement</b>.</p>"
+markdown = convert_to_markdown(html, custom_converters={"b": custom_bold_converter})
+print(markdown)
+# Output: This is a IMPORTANT: bold statement.
+```
+
+Custom converters take precedence over the built-in converters and can be used alongside other configuration options.
+
+### Configuration Options
+
+| Option               | Type | Default        | Description                                            |
+| -------------------- | ---- | -------------- | ------------------------------------------------------ |
+| `autolinks`          | bool | `True`         | Auto-convert URLs to Markdown links                    |
+| `bullets`            | str  | `'*+-'`        | Characters to use for bullet points                    |
+| `code_language`      | str  | `''`           | Default language for code blocks                       |
+| `heading_style`      | str  | `'underlined'` | Header style (`'underlined'`, `'atx'`, `'atx_closed'`) |
+| `escape_asterisks`   | bool | `True`         | Escape * characters                                    |
+| `escape_underscores` | bool | `True`         | Escape _ characters                                    |
+| `wrap`               | bool | `False`        | Enable text wrapping                                   |
+| `wrap_width`         | int  | `80`           | Text wrap width                                        |
+
+For a complete list of options, see the [Configuration](#configuration) section below.
+
+## CLI Usage
+
+Convert HTML files directly from the command line:
+
+```shell
+# Convert a file
+html_to_markdown input.html > output.md
+
+# Process stdin
+cat input.html | html_to_markdown > output.md
+
+# Use custom options
+html_to_markdown --heading-style atx --wrap --wrap-width 100 input.html > output.md
+```
+
+View all available options:
+
+```shell
+html_to_markdown --help
+```
+
+## Migration from Markdownify
+
+For existing projects using Markdownify, a compatibility layer is provided:
+
+```python
+# Old code
+from markdownify import markdownify as md
+
+# New code - works the same way
+from html_to_markdown import markdownify as md
+```
+
+The `markdownify` function is an alias for `convert_to_markdown` and provides identical functionality.
+
+## Configuration
+
+Full list of configuration options:
+
+- `autolinks`: Convert valid URLs to Markdown links automatically
+- `bullets`: Characters to use for bullet points in lists
+- `code_language`: Default language for fenced code blocks
+- `code_language_callback`: Function to determine code block language
+- `convert`: List of HTML tags to convert (None = all supported tags)
+- `default_title`: Use default titles for elements like links
+- `escape_asterisks`: Escape * characters
+- `escape_misc`: Escape miscellaneous Markdown characters
+- `escape_underscores`: Escape _ characters
+- `heading_style`: Header style (underlined/atx/atx_closed)
+- `keep_inline_images_in`: Tags where inline images should be kept
+- `newline_style`: Style for handling newlines (spaces/backslash)
+- `strip`: Tags to remove from output
+- `strong_em_symbol`: Symbol for strong/emphasized text (\* or \_)
+- `sub_symbol`: Symbol for subscript text
+- `sup_symbol`: Symbol for superscript text
+- `wrap`: Enable text wrapping
+- `wrap_width`: Width for text wrapping
+- `convert_as_inline`: Treat content as inline elements
+- `custom_converters`: A mapping of HTML tag names to custom converter functions
+
+## Contribution
+
+This library is open to contribution. Feel free to open issues or submit PRs. Its better to discuss issues before
+submitting PRs to avoid disappointment.
+
+### Local Development
+
+1. Clone the repo
+
+1. Install the system dependencies
+
+1. Install the full dependencies with `uv sync`
+
+1. Install the pre-commit hooks with:
+
+    ```shell
+    pre-commit install && pre-commit install --hook-type commit-msg
+    ```
+
+1. Make your changes and submit a PR
+
+## License
+
+This library uses the MIT license.
+
+## Acknowledgments
+
+Special thanks to the original [markdownify](https://pypi.org/project/markdownify/) project creators and contributors.

html_to_markdown-1.3.0/html_to_markdown.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+html_to_markdown/__init__.py
+html_to_markdown/__main__.py
+html_to_markdown/cli.py
+html_to_markdown/constants.py
+html_to_markdown/converters.py
+html_to_markdown/processing.py
+html_to_markdown/py.typed
+html_to_markdown/utils.py
+html_to_markdown.egg-info/PKG-INFO
+html_to_markdown.egg-info/SOURCES.txt
+html_to_markdown.egg-info/dependency_links.txt
+html_to_markdown.egg-info/requires.txt
+html_to_markdown.egg-info/top_level.txt

html_to_markdown-1.3.0/html_to_markdown.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

html_to_markdown-1.3.0/html_to_markdown.egg-info/requires.txt

@@ -0,0 +1 @@
+beautifulsoup4>=4.12.3

html_to_markdown-1.3.0/html_to_markdown.egg-info/top_level.txt

@@ -0,0 +1 @@
+html_to_markdown

{html_to_markdown-1.2.1 → html_to_markdown-1.3.0}/pyproject.toml

@@ -1,11 +1,11 @@
 [build-system]
-build-backend = "hatchling.build"
+build-backend = "setuptools.build_meta"
 
-requires = [ "hatchling" ]
+requires = [ "setuptools>=78.1" ]
 
 [project]
 name = "html-to-markdown"
-version = "1.2.1"
+version = "1.3.0"
 description = "Convert HTML to markdown"
 readme = "README.md"
 keywords = [ "converter", "html", "markdown", "text-extraction", "text-processing" ]
@@ -42,20 +42,23 @@ dev = [
   "mypy>=1.14.1",
   "pre-commit>=4.1",
   "pytest>=8.3.4",
-  "pytest-cov>=6",
+  "pytest-cov>=6.1",
   "pytest-mock>=3.14",
   "ruff>=0.9.3",
   "types-beautifulsoup4>=4.12.0.20241020",
+  "uv-bump",
 ]
 
+[tool.setuptools.packages.find]
+include = [ "html_to_markdown" ]
+
+[tool.setuptools.package-data]
+html_to_markdown = [ "py.typed" ]
+
 [tool.hatch.build]
 skip-excluded-dirs = true
 
-[tool.hatch.build.targets.sdist]
-only-include = [ "html_to_markdown" ]
-
-[tool.hatch.build.targets.wheel]
-only-include = [ "html_to_markdown" ]
+scripts.html_to_markdown = "html_to_markdown.__main__:cli"
 
 [tool.ruff]
 target-version = "py39"
@@ -113,3 +116,6 @@ disallow_untyped_decorators = false
 
 [tool.uv]
 default-groups = [ "dev" ]
+
+[tool.uv.sources]
+uv-bump = { git = "https://github.com/Goldziher/uv-bump" }

html_to_markdown-1.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

html_to_markdown-1.2.1/.gitignore

@@ -1,22 +0,0 @@
-*$py.class
-*.iml
-*.log
-*.py[cod]
-.coverage
-.env
-.idea/
-.run/
-.mypy_cache/
-.pdm-build/
-.pdm-python
-.pdm.toml
-.pytest_cache/
-.python-version
-.ruff_cache/
-.tox/
-.venv/
-.vscode/
-__pycache__/
-__pypackages__/
-coverage.xml
-dist/