html-to-markdown 1.0.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

html_to_markdown/__init__.py

@@ -1,3 +1,5 @@
 from html_to_markdown.processing import convert_to_markdown
 
-__all__ = ["convert_to_markdown"]
+from .legacy import Markdownify
+
+__all__ = ["Markdownify", "convert_to_markdown"]

html_to_markdown/__main__.py

@@ -1,131 +1,11 @@
-import argparse
 import sys
 
-from html_to_markdown import convert_to_markdown
-from html_to_markdown.constants import ASTERISK, ATX, ATX_CLOSED, BACKSLASH, SPACES, UNDERLINED, UNDERSCORE
-
-
-def cli(argv: list[str]) -> None:
-    """Command-line interface for html_to_markdown."""
-    parser = argparse.ArgumentParser(
-        prog="html_to_markdown",
-        description="Converts html to markdown.",
-    )
-
-    parser.add_argument(
-        "html",
-        nargs="?",
-        type=argparse.FileType("r"),
-        default=sys.stdin,
-        help="The html file to convert. Defaults to STDIN if not " "provided.",
-    )
-    parser.add_argument(
-        "-s",
-        "--strip",
-        nargs="*",
-        help="A list of tags to strip. This option can't be used with " "the --convert option.",
-    )
-    parser.add_argument(
-        "-c",
-        "--convert",
-        nargs="*",
-        help="A list of tags to convert. This option can't be used with " "the --strip option.",
-    )
-    parser.add_argument(
-        "-a",
-        "--autolinks",
-        action="store_true",
-        help="A boolean indicating whether the 'automatic link' style "
-        "should be used when a 'a' tag's contents match its href.",
-    )
-    parser.add_argument(
-        "--default-title",
-        action="store_false",
-        help="A boolean to enable setting the title of a link to its " "href, if no title is given.",
-    )
-    parser.add_argument(
-        "--heading-style",
-        default=UNDERLINED,
-        choices=(ATX, ATX_CLOSED, UNDERLINED),
-        help="Defines how headings should be converted.",
-    )
-    parser.add_argument(
-        "-b",
-        "--bullets",
-        default="*+-",
-        help="A string of bullet styles to use; the bullet will " "alternate based on nesting level.",
-    )
-    (
-        parser.add_argument(
-            "--strong-em-symbol",
-            default=ASTERISK,
-            choices=(ASTERISK, UNDERSCORE),
-            help="Use * or _ to convert strong and italics text",
-        ),
-    )
-    parser.add_argument("--sub-symbol", default="", help="Define the chars that surround '<sub>'.")
-    parser.add_argument("--sup-symbol", default="", help="Define the chars that surround '<sup>'.")
-    parser.add_argument(
-        "--newline-style",
-        default=SPACES,
-        choices=(SPACES, BACKSLASH),
-        help="Defines the style of <br> conversions: two spaces "
-        "or backslash at the and of the line thet should break.",
-    )
-    parser.add_argument(
-        "--code-language", default="", help="Defines the language that should be assumed for all " "'<pre>' sections."
-    )
-    parser.add_argument(
-        "--no-escape-asterisks",
-        dest="escape_asterisks",
-        action="store_false",
-        help="Do not escape '*' to '\\*' in text.",
-    )
-    parser.add_argument(
-        "--no-escape-underscores",
-        dest="escape_underscores",
-        action="store_false",
-        help="Do not escape '_' to '\\_' in text.",
-    )
-    parser.add_argument(
-        "-i",
-        "--keep-inline-images-in",
-        nargs="*",
-        help="Images are converted to their alt-text when the images are "
-        "located inside headlines or table cells. If some inline images "
-        "should be converted to markdown images instead, this option can "
-        "be set to a list of parent tags that should be allowed to "
-        "contain inline images.",
-    )
-    parser.add_argument(
-        "-w", "--wrap", action="store_true", help="Wrap all text paragraphs at --wrap-width characters."
-    )
-    parser.add_argument("--wrap-width", type=int, default=80)
-
-    args = parser.parse_args(argv)
-
-    result = convert_to_markdown(
-        args.html.read(),
-        strip=args.strip,
-        convert=args.convert,
-        autolinks=args.autolinks,
-        default_title=args.default_title,
-        heading_style=args.heading_style,
-        bullets=args.bullets,
-        strong_em_symbol=args.strong_em_symbol,
-        sub_symbol=args.sub_symbol,
-        sup_symbol=args.sup_symbol,
-        newline_style=args.newline_style,
-        code_language=args.code_language,
-        escape_asterisks=args.escape_asterisks,
-        escape_underscores=args.escape_underscores,
-        keep_inline_images_in=args.keep_inline_images_in,
-        wrap=args.wrap,
-        wrap_width=args.wrap_width,
-    )
-
-    print(result)  # noqa: T201
-
-
 if __name__ == "__main__":
-    cli(sys.argv[1:])
+    from html_to_markdown.cli import main
+
+    try:
+        result = main(sys.argv[1:])
+        print(result)  # noqa: T201
+    except ValueError as e:
+        print(str(e), file=sys.stderr)  # noqa: T201
+        sys.exit(1)

html_to_markdown/cli.py

@@ -0,0 +1,150 @@
+def main(argv: list[str]) -> str:
+    """Command-line entry point."""
+    from argparse import ArgumentParser, FileType
+    from sys import stdin
+
+    from html_to_markdown.constants import ASTERISK, ATX, ATX_CLOSED, BACKSLASH, SPACES, UNDERLINED, UNDERSCORE
+    from html_to_markdown.processing import convert_to_markdown
+
+    parser = ArgumentParser(
+        prog="html_to_markdown",
+        description="Converts HTML to Markdown.",
+    )
+
+    parser.add_argument(
+        "html",
+        nargs="?",
+        type=FileType("r"),
+        default=stdin,
+        help="The HTML file to convert. Defaults to STDIN if not provided.",
+    )
+
+    parser.add_argument(
+        "-s",
+        "--strip",
+        nargs="*",
+        help="A list of tags to strip from the conversion. Incompatible with the --convert option.",
+    )
+
+    parser.add_argument(
+        "-c",
+        "--convert",
+        nargs="*",
+        help="A list of HTML tags to explicitly convert. Incompatible with the --strip option.",
+    )
+
+    parser.add_argument(
+        "-a",
+        "--autolinks",
+        action="store_true",
+        help="Automatically convert anchor links where the content matches the href.",
+    )
+
+    parser.add_argument(
+        "--default-title",
+        action="store_false",
+        help="Use this flag to disable setting the link title to its href when no title is provided.",
+    )
+
+    parser.add_argument(
+        "--heading-style",
+        default=UNDERLINED,
+        choices=(ATX, ATX_CLOSED, UNDERLINED),
+        help="Defines the heading conversion style: 'atx', 'atx_closed', or 'underlined'. Defaults to 'underlined'.",
+    )
+
+    parser.add_argument(
+        "-b",
+        "--bullets",
+        default="*+-",
+        help="A string of bullet styles to use for list items. The style alternates based on nesting level. Defaults to '*+-'.",
+    )
+
+    parser.add_argument(
+        "--strong-em-symbol",
+        default=ASTERISK,
+        choices=(ASTERISK, UNDERSCORE),
+        help="Choose between '*' or '_' for strong and emphasized text. Defaults to '*'.",
+    )
+
+    parser.add_argument(
+        "--sub-symbol",
+        default="",
+        help="Define the characters used to surround <sub> text. Defaults to empty.",
+    )
+
+    parser.add_argument(
+        "--sup-symbol",
+        default="",
+        help="Define the characters used to surround <sup> text. Defaults to empty.",
+    )
+
+    parser.add_argument(
+        "--newline-style",
+        default=SPACES,
+        choices=(SPACES, BACKSLASH),
+        help="Specify the <br> conversion style: two spaces (default) or a backslash at the end of the line.",
+    )
+
+    parser.add_argument(
+        "--code-language",
+        default="",
+        help="Specify the default language for code blocks inside <pre> tags. Defaults to empty.",
+    )
+
+    parser.add_argument(
+        "--no-escape-asterisks",
+        dest="escape_asterisks",
+        action="store_false",
+        help="Disable escaping of '*' characters in text to '\\*'.",
+    )
+
+    parser.add_argument(
+        "--no-escape-underscores",
+        dest="escape_underscores",
+        action="store_false",
+        help="Disable escaping of '_' characters in text to '\\_'.",
+    )
+
+    parser.add_argument(
+        "-i",
+        "--keep-inline-images-in",
+        nargs="*",
+        help="Specify parent tags where inline images should be preserved as images, rather than converted to alt-text. Defaults to None.",
+    )
+
+    parser.add_argument(
+        "-w",
+        "--wrap",
+        action="store_true",
+        help="Enable word wrapping for paragraphs at --wrap-width characters.",
+    )
+
+    parser.add_argument(
+        "--wrap-width",
+        type=int,
+        default=80,
+        help="The number of characters at which text paragraphs should wrap. Defaults to 80.",
+    )
+
+    args = parser.parse_args(argv)
+
+    return convert_to_markdown(
+        args.html.read(),
+        strip=args.strip,
+        convert=args.convert,
+        autolinks=args.autolinks,
+        default_title=args.default_title,
+        heading_style=args.heading_style,
+        bullets=args.bullets,
+        strong_em_symbol=args.strong_em_symbol,
+        sub_symbol=args.sub_symbol,
+        sup_symbol=args.sup_symbol,
+        newline_style=args.newline_style,
+        code_language=args.code_language,
+        escape_asterisks=args.escape_asterisks,
+        escape_underscores=args.escape_underscores,
+        keep_inline_images_in=args.keep_inline_images_in,
+        wrap=args.wrap,
+        wrap_width=args.wrap_width,
+    )

html_to_markdown/constants.py

@@ -2,17 +2,17 @@ from __future__ import annotations
 
 import re
 from re import Pattern
-from typing import Final, Literal
+from typing import Final
 
 convert_heading_re: Final[Pattern[str]] = re.compile(r"convert_h(\d+)")
 line_beginning_re: Final[Pattern[str]] = re.compile(r"^", re.MULTILINE)
 whitespace_re: Final[Pattern[str]] = re.compile(r"[\t ]+")
 html_heading_re: Final[Pattern[str]] = re.compile(r"h[1-6]")
 
-ASTERISK: Final[Literal["*"]] = "*"
-ATX: Final[Literal["atx"]] = "atx"
-ATX_CLOSED: Final[Literal["atx_closed"]] = "atx_closed"
-BACKSLASH: Final[Literal["backslash"]] = "backslash"
-UNDERLINED: Final[Literal["underlined"]] = "underlined"
-SPACES: Final[Literal["spaces"]] = "spaces"
-UNDERSCORE: Final[Literal["_"]] = "_"
+ASTERISK: Final = "*"
+ATX: Final = "atx"
+ATX_CLOSED: Final = "atx_closed"
+BACKSLASH: Final = "backslash"
+UNDERLINED: Final = "underlined"
+SPACES: Final = "spaces"
+UNDERSCORE: Final = "_"

html_to_markdown/converters.py

@@ -55,17 +55,19 @@ SupportedElements = Literal[
     "kbd",
 ]
 
-ConvertsMap = Mapping[SupportedElements, Callable[[str, Tag], str]]
+ConvertersMap = Mapping[SupportedElements, Callable[[str, Tag], str]]
 
 T = TypeVar("T")
 
 
 def _create_inline_converter(markup_prefix: str) -> Callable[[Tag, str], str]:
-    """This abstracts all simple inline tags like b, em, del, ...
-    Returns a function that wraps the chomped text in a pair of the string
-    that is returned by markup_fn, with '/' inserted in the string used after
-    the text if it looks like an HTML tag. markup_fn is necessary to allow for
-    references to self.strong_em_symbol etc.
+    """Create an inline converter for a markup pattern or tag.
+
+    Args:
+        markup_prefix: The markup prefix to insert.
+
+    Returns:
+        A function that can be used to convert HTML to Markdown.
     """
 
     def implementation(*, tag: Tag, text: str) -> str:
@@ -147,9 +149,9 @@ def _convert_hn(
 
 
 def _convert_img(*, tag: Tag, convert_as_inline: bool, keep_inline_images_in: Iterable[str] | None) -> str:
-    alt = tag.attrs.get("alt", None) or ""
-    src = tag.attrs.get("src", None) or ""
-    title = tag.attrs.get("title", None) or ""
+    alt = tag.attrs.get("alt", "")
+    src = tag.attrs.get("src", "")
+    title = tag.attrs.get("title", "")
     title_part = ' "{}"'.format(title.replace('"', r"\"")) if title else ""
     parent_name = tag.parent.name if tag.parent else ""
     if convert_as_inline and parent_name not in (keep_inline_images_in or []):
@@ -295,7 +297,7 @@ def create_converters_map(
     sup_symbol: str,
     wrap: bool,
     wrap_width: int,
-) -> ConvertsMap:
+) -> ConvertersMap:
     """Create a mapping of HTML elements to their corresponding conversion functions.
 
     Args:

html_to_markdown/legacy.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from html_to_markdown.constants import ASTERISK, SPACES, UNDERLINED
+from html_to_markdown.converters import create_converters_map
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
+
+    from bs4 import Tag
+
+
+def _create_legacy_class(
+    autolinks: bool,
+    bullets: str,
+    code_language: str,
+    code_language_callback: Callable[[Tag], str] | None,
+    default_title: bool,
+    heading_style: Literal["atx", "atx_closed", "underlined"],
+    keep_inline_images_in: Iterable[str] | None,
+    newline_style: str,
+    strong_em_symbol: str,
+    sub_symbol: str,
+    sup_symbol: str,
+    wrap: bool,
+    wrap_width: int,
+) -> type:
+    """Create a legacy class for Markdownify.
+
+    Deprecated: Use the new hooks api instead.
+
+    Args:
+        autolinks: Whether to convert URLs into links.
+        bullets: The bullet characters to use for unordered lists.
+        code_language: The default code language to use.
+        code_language_callback: A callback to get the code language.
+        default_title: Whether to use the URL as the title for links.
+        heading_style: The style of headings.
+        keep_inline_images_in: The tags to keep inline images in.
+        newline_style: The style of newlines.
+        strong_em_symbol: The symbol to use for strong and emphasis text.
+        sub_symbol: The symbol to use for subscript text.
+        sup_symbol: The symbol to use for superscript text.
+        wrap: Whether to wrap text.
+        wrap_width: The width to wrap text at.
+
+    Returns:
+        A class that can be used to convert HTML to Markdown.
+    """
+    return type(
+        "Markdownify",
+        (),
+        {
+            k.removeprefix("_"): v
+            for k, v in create_converters_map(
+                autolinks=autolinks,
+                bullets=bullets,
+                code_language=code_language,
+                code_language_callback=code_language_callback,
+                default_title=default_title,
+                heading_style=heading_style,
+                keep_inline_images_in=keep_inline_images_in,
+                newline_style=newline_style,
+                strong_em_symbol=strong_em_symbol,
+                sub_symbol=sub_symbol,
+                sup_symbol=sup_symbol,
+                wrap=wrap,
+                wrap_width=wrap_width,
+            ).items()
+        },
+    )
+
+
+Markdownify = _create_legacy_class(
+    autolinks=True,
+    bullets="*+-",
+    code_language="",
+    code_language_callback=None,
+    default_title=False,
+    heading_style=UNDERLINED,
+    keep_inline_images_in=None,
+    newline_style=SPACES,
+    strong_em_symbol=ASTERISK,
+    sub_symbol="",
+    sup_symbol="",
+    wrap=False,
+    wrap_width=80,
+)

html_to_markdown/processing.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from itertools import chain
 from typing import TYPE_CHECKING, Any, Callable, Literal, cast
 
 from bs4 import BeautifulSoup, Comment, Doctype, NavigableString, Tag
@@ -11,7 +12,7 @@ from html_to_markdown.constants import (
     html_heading_re,
     whitespace_re,
 )
-from html_to_markdown.converters import ConvertsMap, create_converters_map
+from html_to_markdown.converters import ConvertersMap, create_converters_map
 from html_to_markdown.utils import escape
 
 if TYPE_CHECKING:
@@ -76,48 +77,21 @@ def _is_nested_tag(el: PageElement) -> bool:
 
 def _process_tag(
     tag: Tag,
+    converters_map: ConvertersMap,
     *,
-    autolinks: bool,
-    bullets: str,
-    code_language: str,
-    code_language_callback: Callable[[Any], str] | None,
-    convert: Iterable[str] | None,
+    convert: set[str] | None,
     convert_as_inline: bool = False,
-    converters_map: ConvertsMap | None = None,
-    default_title: bool,
     escape_asterisks: bool,
     escape_misc: bool,
     escape_underscores: bool,
-    heading_style: Literal["atx", "atx_closed", "underlined"],
-    keep_inline_images_in: Iterable[str] | None,
-    newline_style: str,
-    strip: Iterable[str] | None,
-    strong_em_symbol: str,
-    sub_symbol: str,
-    sup_symbol: str,
-    wrap: bool,
-    wrap_width: int,
+    strip: set[str] | None,
 ) -> str:
-    if converters_map is None:
-        converters_map = create_converters_map(
-            autolinks=autolinks,
-            bullets=bullets,
-            code_language=code_language,
-            code_language_callback=code_language_callback,
-            default_title=default_title,
-            heading_style=heading_style,
-            keep_inline_images_in=keep_inline_images_in,
-            newline_style=newline_style,
-            strong_em_symbol=strong_em_symbol,
-            sub_symbol=sub_symbol,
-            sup_symbol=sup_symbol,
-            wrap=wrap,
-            wrap_width=wrap_width,
-        )
-
+    should_convert_tag = _should_convert_tag(tag_name=tag.name, strip=strip, convert=convert)
+    tag_name: SupportedTag | None = cast(SupportedTag, tag.name.lower()) if tag.name.lower() in converters_map else None
     text = ""
+
     is_heading = html_heading_re.match(tag.name) is not None
-    is_cell = tag.name in {"td", "th"}
+    is_cell = tag_name in {"td", "th"}
     convert_children_as_inline = convert_as_inline or is_heading or is_cell
 
     if _is_nested_tag(tag):
@@ -141,32 +115,17 @@ def _process_tag(
             )
         elif isinstance(el, Tag):
             text += _process_tag(
-                tag=el,
+                el,
+                converters_map,
                 convert_as_inline=convert_children_as_inline,
-                strip=strip,
                 convert=convert,
-                escape_misc=escape_misc,
                 escape_asterisks=escape_asterisks,
+                escape_misc=escape_misc,
                 escape_underscores=escape_underscores,
-                converters_map=converters_map,
-                autolinks=autolinks,
-                bullets=bullets,
-                code_language=code_language,
-                code_language_callback=code_language_callback,
-                default_title=default_title,
-                heading_style=heading_style,
-                keep_inline_images_in=keep_inline_images_in,
-                newline_style=newline_style,
-                strong_em_symbol=strong_em_symbol,
-                sub_symbol=sub_symbol,
-                sup_symbol=sup_symbol,
-                wrap=wrap,
-                wrap_width=wrap_width,
+                strip=strip,
             )
 
-    tag_name: SupportedTag | None = cast(SupportedTag, tag.name.lower()) if tag.name.lower() in converters_map else None
-
-    if tag_name and _should_convert_tag(tag_name=tag.name, strip=strip, convert=convert):
+    if tag_name and should_convert_tag:
         return converters_map[tag_name](  # type: ignore[call-arg]
             tag=tag, text=text, convert_as_inline=convert_as_inline
         )
@@ -209,7 +168,7 @@ def _process_text(
     return text
 
 
-def _should_convert_tag(*, tag_name: str, strip: Iterable[str] | None, convert: Iterable[str] | None) -> bool:
+def _should_convert_tag(*, tag_name: str, strip: set[str] | None, convert: set[str] | None) -> bool:
     if strip is not None:
         return tag_name not in strip
     if convert is not None:
@@ -217,15 +176,22 @@ def _should_convert_tag(*, tag_name: str, strip: Iterable[str] | None, convert:
     return True
 
 
+def _as_optional_set(value: str | Iterable[str] | None) -> set[str] | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return set(",".split(value))
+    return {*chain(*[v.split(",") for v in value])}
+
+
 def convert_to_markdown(
-    html: str,
+    source: str | BeautifulSoup,
     *,
-    soup: BeautifulSoup | None = None,
     autolinks: bool = True,
     bullets: str = "*+-",
     code_language: str = "",
     code_language_callback: Callable[[Any], str] | None = None,
-    convert: Iterable[str] | None = None,
+    convert: str | Iterable[str] | None = None,
     default_title: bool = False,
     escape_asterisks: bool = True,
     escape_misc: bool = True,
@@ -233,7 +199,7 @@ def convert_to_markdown(
     heading_style: Literal["underlined", "atx", "atx_closed"] = UNDERLINED,
     keep_inline_images_in: Iterable[str] | None = None,
     newline_style: Literal["spaces", "backslash"] = SPACES,
-    strip: Iterable[str] | None = None,
+    strip: str | Iterable[str] | None = None,
     strong_em_symbol: Literal["*", "_"] = ASTERISK,
     sub_symbol: str = "",
     sup_symbol: str = "",
@@ -244,55 +210,67 @@ def convert_to_markdown(
     """Convert HTML to Markdown.
 
     Args:
-        html: The HTML to convert.
-        soup: The BeautifulSoup object to convert.
-        autolinks: Whether to convert links to Markdown.
-        bullets: The bullet characters to use for unordered lists.
-        code_language: The default code language to use.
-        code_language_callback: A callback function to determine the code language.
-        convert: The HTML elements to convert.
-        default_title: Whether to use the default title.
-        escape_asterisks: Whether to escape asterisks.
-        escape_misc: Whether to escape miscellaneous characters.
-        escape_underscores: Whether to escape underscores.
-        heading_style: The style to use for headings.
-        keep_inline_images_in: The tags to keep inline images in.
-        newline_style: The style to use for newlines.
-        strip: The HTML elements to strip.
-        strong_em_symbol: The symbol to use for strong and emphasis.
-        sub_symbol: The symbol to use for subscript.
-        sup_symbol: The symbol to use for superscript.
-        wrap: Whether to wrap text.
-        wrap_width: The width to wrap text at.
-        convert_as_inline: Whether to convert elements as inline.
+        source: An HTML document or a an initialized instance of BeautifulSoup.
+        autolinks: Automatically convert valid URLs into Markdown links. Defaults to True.
+        bullets: A string of characters to use for bullet points in lists. Defaults to '*+-'.
+        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.
+        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.
+        escape_underscores: Escape underscores (_) to prevent unintended italic formatting. Defaults to True.
+        heading_style: The style to use for Markdown headings. Defaults to "underlined".
+        keep_inline_images_in: Tags in which inline images should be preserved. Defaults to None.
+        newline_style: Style for handling newlines in text content. Defaults to "spaces".
+        strip: Tags to strip from the output. Defaults to None.
+        strong_em_symbol: Symbol to use for strong/emphasized text. Defaults to "*".
+        sub_symbol: Custom symbol for subscript text. Defaults to an empty string.
+        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.
 
     Returns:
-        The Markdown.
+        str: A string of Markdown-formatted text converted from the given HTML.
     """
-    if soup is None:
+    if isinstance(source, str):
         from bs4 import BeautifulSoup
 
-        soup = BeautifulSoup(html, "html.parser")
+        if "".join(source.split("\n")):
+            source = BeautifulSoup(source, "html.parser")
+        else:
+            raise ValueError("The input HTML is empty.")
 
-    return _process_tag(
+    if strip is not None and convert is not None:
+        raise ValueError("Only one of 'strip' and 'convert' can be specified.")
+
+    converters_map = create_converters_map(
         autolinks=autolinks,
         bullets=bullets,
         code_language=code_language,
         code_language_callback=code_language_callback,
-        convert=convert,
-        convert_as_inline=convert_as_inline,
         default_title=default_title,
-        escape_asterisks=escape_asterisks,
-        escape_misc=escape_misc,
-        escape_underscores=escape_underscores,
         heading_style=heading_style,
         keep_inline_images_in=keep_inline_images_in,
         newline_style=newline_style,
-        strip=strip,
         strong_em_symbol=strong_em_symbol,
         sub_symbol=sub_symbol,
         sup_symbol=sup_symbol,
-        tag=soup,
         wrap=wrap,
         wrap_width=wrap_width,
     )
+
+    return _process_tag(
+        source,
+        converters_map,
+        convert=_as_optional_set(convert),
+        convert_as_inline=convert_as_inline,
+        escape_asterisks=escape_asterisks,
+        escape_misc=escape_misc,
+        escape_underscores=escape_underscores,
+        strip=_as_optional_set(strip),
+    )

html_to_markdown-1.2.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: html-to-markdown
+Version: 1.2.0
+Summary: Convert HTML to markdown
+Author-email: Na'aman Hirschfeld <nhirschfeld@gmail.com>
+License: MIT
+License-File: LICENSE
+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
+Requires-Dist: beautifulsoup4>=4.12.3
+Description-Content-Type: text/markdown
+
+# html_to_markdown
+
+This library is a refactored and modernized fork of [markdownify](https://pypi.org/project/markdownify/), supporting
+Python 3.9 and above.
+
+### Differences with the Markdownify
+
+- The refactored codebase uses a strict functional approach - no classes are involved.
+- There is full typing with strict MyPy strict adherence and a py.typed file included.
+- The `convert_to_markdown` function allows passing a pre-configured instance of `BeautifulSoup` instead of html.
+- This library releases follows standard semver. Its version v1.0.0 was branched from markdownify's v0.13.1, at which
+  point versioning is no longer aligned.
+
+## Installation
+
+```shell
+pip install html_to_markdown
+```
+
+## Usage
+
+Convert an string HTML to Markdown:
+
+```python
+from html_to_markdown import convert_to_markdown
+
+convert_to_markdown('<b>Yay</b> <a href="http://github.com">GitHub</a>')  # > '**Yay** [GitHub](http://github.com)'
+```
+
+Or pass a pre-configured instance of `BeautifulSoup`:
+
+```python
+from bs4 import BeautifulSoup
+from html_to_markdown import convert_to_markdown
+
+soup = BeautifulSoup('<b>Yay</b> <a href="http://github.com">GitHub</a>', 'lxml')  # lxml requires an extra dependency.
+
+convert_to_markdown(soup)  # > '**Yay** [GitHub](http://github.com)'
+```
+
+### Options
+
+The `convert_to_markdown` function accepts the following kwargs:
+
+- autolinks (bool): Automatically convert valid URLs into Markdown links. Defaults to True.
+- bullets (str): A string of characters to use for bullet points in lists. Defaults to '\*+-'.
+- code_language (str): Default language identifier for fenced code blocks. Defaults to an empty string.
+- code_language_callback (Callable[[Any], str] | None): Function to dynamically determine the language for code blocks.
+- convert (Iterable[str] | None): A list of tag names to convert to Markdown. If None, all supported tags are converted.
+- default_title (bool): Use the default title when converting certain elements (e.g., links). Defaults to False.
+- escape_asterisks (bool): Escape asterisks (\*) to prevent unintended Markdown formatting. Defaults to True.
+- escape_misc (bool): Escape miscellaneous characters to prevent conflicts in Markdown. Defaults to True.
+- escape*underscores (bool): Escape underscores (*) to prevent unintended italic formatting. Defaults to True.
+- heading_style (Literal["underlined", "atx", "atx_closed"]): The style to use for Markdown headings. Defaults to "
+  underlined".
+- keep_inline_images_in (Iterable[str] | None): Tags in which inline images should be preserved. Defaults to None.
+- newline_style (Literal["spaces", "backslash"]): Style for handling newlines in text content. Defaults to "spaces".
+- strip (Iterable[str] | None): Tags to strip from the output. Defaults to None.
+- strong*em_symbol (Literal["\*", "*"]): Symbol to use for strong/emphasized text. Defaults to "\*".
+- sub_symbol (str): Custom symbol for subscript text. Defaults to an empty string.
+- sup_symbol (str): Custom symbol for superscript text. Defaults to an empty string.
+- wrap (bool): Wrap text to the specified width. Defaults to False.
+- wrap_width (int): The number of characters at which to wrap text. Defaults to 80.
+- convert_as_inline (bool): Treat the content as inline elements (no block elements like paragraphs). Defaults to False.
+
+## CLI
+
+For compatibility with the original markdownify, a CLI is provided. Use `html_to_markdown example.html > example.md` or
+pipe input from stdin:
+
+```shell
+cat example.html | html_to_markdown > example.md
+```
+
+Use `html_to_markdown -h` to see all available options. They are the same as listed above and take the same arguments.

html_to_markdown-1.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+html_to_markdown/__init__.py,sha256=cXm4YOyrAp2HKHMDfnVA5e75zg6wdqpyXugjBYvBMFc,143
+html_to_markdown/__main__.py,sha256=u5xevySlT5eIGyLUaethdDQIKJygaKnc3F2sHWoz75g,264
+html_to_markdown/cli.py,sha256=HVnzmcyrYwah_yWhZ87mZcG0VgnKYp6y89fJh2R-Rlw,4532
+html_to_markdown/constants.py,sha256=Usk67k18tuRovJpKDsiEXdgH20KgqI9KOnK4Fbx-M5c,547
+html_to_markdown/converters.py,sha256=hW4RqAbgx0tdTzfUSvAGQg1OgQUmHL1cekZtJLFq_Ns,12080
+html_to_markdown/legacy.py,sha256=vL-MVKPXOue-JJafXFtmGcVIPylwmPOly0CELTSzWRQ,2773
+html_to_markdown/processing.py,sha256=L1wZwUm7WA8wN4GA5zjCStwACb-8S2scQZPbzeHgdY8,8951
+html_to_markdown/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+html_to_markdown/utils.py,sha256=HJUDej5HSpXRtYv-OkCyD0hwnPnVfQCwY6rBRlIOt9s,1989
+html_to_markdown-1.2.0.dist-info/METADATA,sha256=Dg2ZibNWNW_GyszXG2bxT-oOtOJc8iryVxlLn38eMww,4709
+html_to_markdown-1.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+html_to_markdown-1.2.0.dist-info/licenses/LICENSE,sha256=06BS7zd6oPCrbzAqrThGFboRlbssgBsqDJGqKyZW2Og,1117
+html_to_markdown-1.2.0.dist-info/RECORD,,

{html_to_markdown-1.0.0.dist-info → html_to_markdown-1.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.25.0
+Generator: hatchling 1.27.0
 Root-Is-Purelib: true
 Tag: py3-none-any

html_to_markdown-1.0.0.dist-info/METADATA

@@ -1,194 +0,0 @@
-Metadata-Version: 2.3
-Name: html-to-markdown
-Version: 1.0.0
-Summary: Convert HTML to markdown
-Author-email: Na'aman Hirschfeld <nhirschfeld@gmail.com>
-License: MIT
-License-File: LICENSE
-Keywords: beautifulsoup,converter,html,markdown,text-processing
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-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
-Requires-Dist: beautifulsoup4>=4.12.3
-Description-Content-Type: text/markdown
-
-# html_to_markdown
-
-This library is a refactored and modernized fork of [markdownify](https://pypi.org/project/markdownify/), supporting
-Python 3.9 and offering strong typing.
-
-### Differences from the Markdownify
-
-- The refactored codebase uses a strict functional approach - no classes are involved.
-- There is full typing with strict MyPy adherence in place.
-- The `convert_to_markdown` allows passing a pre-configured instance of `Beautifulsoup`.
-- This library releases follows standard semver. Its version v1.0.0 was branched from markdownify's v0.13.1, at which
-  point versioning is no longer aligned.
-
-## Installation
-
-```shell
-pip install html_to_markdown
-```
-
-## Usage
-
-Convert some HTML to Markdown:
-
-```python
-from html_to_markdown import convert_to_markdown
-
-convert_to_markdown('<b>Yay</b> <a href="http://github.com">GitHub</a>')  # > '**Yay** [GitHub](http://github.com)'
-```
-
-Specify tags to exclude:
-
-```python
-from html_to_markdown import convert_to_markdown
-
-convert_to_markdown('<b>Yay</b> <a href="http://github.com">GitHub</a>', strip=['a'])  # > '**Yay** GitHub'
-```
-
-\...or specify the tags you want to include:
-
-```python
-from html_to_markdown import convert_to_markdown
-
-convert_to_markdown('<b>Yay</b> <a href="http://github.com">GitHub</a>', convert=['b'])  # > '**Yay** GitHub'
-```
-
-# Options
-
-html_to_markdown supports the following options:
-
-strip
-
-:   A list of tags to strip. This option can\'t be used with the
-`convert` option.
-
-convert
-
-:   A list of tags to convert. This option can\'t be used with the
-`strip` option.
-
-autolinks
-
-:   A boolean indicating whether the \"automatic link\" style should be
-used when a `a` tag\'s contents match its href. Defaults to `True`.
-
-default_title
-
-:   A boolean to enable setting the title of a link to its href, if no
-title is given. Defaults to `False`.
-
-heading_style
-
-:   Defines how headings should be converted. Accepted values are `ATX`,
-`ATX_CLOSED`, `SETEXT`, and `UNDERLINED` (which is an alias for
-`SETEXT`). Defaults to `UNDERLINED`.
-
-bullets
-
-:   An iterable (string, list, or tuple) of bullet styles to be used. If
-the iterable only contains one item, it will be used regardless of
-how deeply lists are nested. Otherwise, the bullet will alternate
-based on nesting level. Defaults to `'*+-'`.
-
-strong_em_symbol
-
-:   In markdown, both `*` and `_` are used to encode **strong** or
-*emphasized* texts. Either of these symbols can be chosen by the
-options `ASTERISK` (default) or `UNDERSCORE` respectively.
-
-sub_symbol, sup_symbol
-
-:   Define the chars that surround `<sub>` and `<sup>` text. Defaults to
-an empty string, because this is non-standard behavior. Could be
-something like `~` and `^` to result in `~sub~` and `^sup^`. If the
-value starts with `<` and ends with `>`, it is treated as an HTML
-tag and a `/` is inserted after the `<` in the string used after the
-text; this allows specifying `<sub>` to use raw HTML in the output
-for subscripts, for example.
-
-newline_style
-
-:   Defines the style of marking linebreaks (`<br>`) in markdown. The
-default value `SPACES` of this option will adopt the usual two
-spaces and a newline, while `BACKSLASH` will convert a linebreak to
-`\\n` (a backslash and a newline). While the latter convention is
-non-standard, it is commonly preferred and supported by a lot of
-interpreters.
-
-code_language
-
-:   Defines the language that should be assumed for all `<pre>`
-sections. Useful, if all code on a page is in the same programming
-language and should be annotated with ``[python]{.title-ref}[ or
-similar. Defaults to ]{.title-ref}[\'\']{.title-ref}\` (empty
-string) and can be any string.
-
-code_language_callback
-
-:   When the HTML code contains `pre` tags that in some way provide the
-code language, for example as class, this callback can be used to
-extract the language from the tag and prefix it to the converted
-`pre` tag. The callback gets one single argument, an BeautifylSoup
-object, and returns a string containing the code language, or
-`None`. An example to use the class name as code language could be:
-
-        def callback(el):
-            return el['class'][0] if el.has_attr('class') else None
-
-    Defaults to `None`.
-
-escape_asterisks
-
-:   If set to `False`, do not escape `*` to `\*` in text. Defaults to
-`True`.
-
-escape_underscores
-
-:   If set to `False`, do not escape `_` to `\_` in text. Defaults to
-`True`.
-
-escape_misc
-
-:   If set to `False`, do not escape miscellaneous punctuation
-characters that sometimes have Markdown significance in text.
-Defaults to `True`.
-
-keep_inline_images_in
-
-:   Images are converted to their alt-text when the images are located
-inside headlines or table cells. If some inline images should be
-converted to markdown images instead, this option can be set to a
-list of parent tags that should be allowed to contain inline images,
-for example `['td']`. Defaults to an empty list.
-
-wrap, wrap_width
-
-:   If `wrap` is set to `True`, all text paragraphs are wrapped at
-`wrap_width` characters. Defaults to `False` and `80`. Use with
-`newline_style=BACKSLASH` to keep line breaks in paragraphs.
-
-Options may be specified as kwargs to the `html_to_markdown` function, or as
-a nested `Options` class in `MarkdownConverter` subclasses.
-
-# CLI
-
-Use `html_to_markdown example.html > example.md` or pipe input from stdin
-(`cat example.html | html_to_markdown > example.md`). Call `html_to_markdown -h`
-to see all available options. They are the same as listed above and take
-the same arguments.

html_to_markdown-1.0.0.dist-info/RECORD

@@ -1,12 +0,0 @@
-html_to_markdown/__init__.py,sha256=_WXeqic-7b6hvidTXkPQwAfLa4YOEAEP-mOUXjx_25k,95
-html_to_markdown/__main__.py,sha256=Wll22XKFmiNSIpdbGzC75b5_Unc3HYOTA6oXA414Tl8,4412
-html_to_markdown/constants.py,sha256=vUjffZ0vFq56jbXF5bBNzomfJwgsp0TWqdUzhkp6bks,687
-html_to_markdown/converters.py,sha256=q1wpzsYl-FRR9qbB983gAkem_-7mgYZ7hOgziofjIDM,12238
-html_to_markdown/processing.py,sha256=9l3zq_kdyvU0TnTk5g4uuYI6Jbu1gY7NQ11u3IBKyFU,9029
-html_to_markdown/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-html_to_markdown/utils.py,sha256=HJUDej5HSpXRtYv-OkCyD0hwnPnVfQCwY6rBRlIOt9s,1989
-html_to_markdown-1.0.0.dist-info/METADATA,sha256=0MObULuhTHiyvVcytDBN_liafpyFjgp5brgoWQYEglA,6478
-html_to_markdown-1.0.0.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
-html_to_markdown-1.0.0.dist-info/entry_points.txt,sha256=jhMqXDYvIyzQDLKjCn4xCyzCCbAMl94tzQx_HiG5Qi0,67
-html_to_markdown-1.0.0.dist-info/licenses/LICENSE,sha256=06BS7zd6oPCrbzAqrThGFboRlbssgBsqDJGqKyZW2Og,1117
-html_to_markdown-1.0.0.dist-info/RECORD,,

html_to_markdown-1.0.0.dist-info/entry_points.txt

@@ -1,2 +0,0 @@
-[console_scripts]
-html_to_markdown = html_to_markdown.__main__:cli