html-to-markdown 1.9.0__py3-none-any.whl → 1.10.0__py3-none-any.whl

html_to_markdown/__main__.py

@@ -4,7 +4,6 @@ from html_to_markdown.cli import main
 
 
 def cli() -> None:
-    """Main CLI entrypoint."""
     try:
         result = main(sys.argv[1:])
         print(result)  # noqa: T201

html_to_markdown/cli.py

@@ -10,15 +10,16 @@ from html_to_markdown.constants import (
     SPACES,
     UNDERLINED,
     UNDERSCORE,
+    WHITESPACE_NORMALIZED,
+    WHITESPACE_STRICT,
 )
 from html_to_markdown.processing import convert_to_markdown
 
 
 def main(argv: list[str]) -> str:
-    """Command-line entry point."""
     parser = ArgumentParser(
         prog="html_to_markdown",
-        description="Converts HTML to Markdown.",
+        description="Convert HTML to Markdown with comprehensive customization options.",
     )
 
     parser.add_argument(
@@ -33,188 +34,243 @@ def main(argv: list[str]) -> str:
         "-s",
         "--strip",
         nargs="*",
-        help="A list of tags to strip from the conversion. Incompatible with the --convert option.",
+        help="HTML tags to remove from output. Incompatible with --convert.",
     )
 
     parser.add_argument(
         "-c",
         "--convert",
         nargs="*",
-        help="A list of HTML tags to explicitly convert. Incompatible with the --strip option.",
+        help="HTML tags to convert (only these will be processed). Incompatible with --strip.",
     )
 
     parser.add_argument(
         "-a",
         "--autolinks",
         action="store_true",
-        help="Automatically convert anchor links where the content matches the href.",
+        help="Convert URLs to automatic links when text matches href.",
     )
 
     parser.add_argument(
         "--default-title",
         action="store_true",
-        help="Set the link title to its href when no title is provided.",
+        help="Use href as link title 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'.",
+        help="Header style: 'atx' (#), 'atx_closed' (# #), or 'underlined' (===). Default: 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 '*+-'.",
+        help="Characters for bullet points, alternates by nesting level. Default: '*+-'.",
     )
 
     parser.add_argument(
         "--strong-em-symbol",
         default=ASTERISK,
         choices=(ASTERISK, UNDERSCORE),
-        help="Choose between '*' or '_' for strong and emphasized text. Defaults to '*'.",
+        help="Symbol for bold/italic text: '*' or '_'. Default: '*'.",
     )
 
     parser.add_argument(
         "--sub-symbol",
         default="",
-        help="Define the characters used to surround <sub> text. Defaults to empty.",
+        help="Characters to surround subscript text. Default: none.",
     )
 
     parser.add_argument(
         "--sup-symbol",
         default="",
-        help="Define the characters used to surround <sup> text. Defaults to empty.",
+        help="Characters to surround superscript text. Default: none.",
     )
 
     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.",
+        help="Line break style: 'spaces' (two spaces) or 'backslash' (\\). Default: spaces.",
     )
 
     parser.add_argument(
         "--code-language",
         default="",
-        help="Specify the default language for code blocks inside <pre> tags. Defaults to empty.",
+        help="Default language for code blocks. Default: none.",
     )
 
     parser.add_argument(
         "--no-escape-asterisks",
         dest="escape_asterisks",
         action="store_false",
-        help="Disable escaping of '*' characters in text to '\\*'.",
+        help="Don't escape asterisk (*) characters.",
     )
 
     parser.add_argument(
         "--no-escape-underscores",
         dest="escape_underscores",
         action="store_false",
-        help="Disable escaping of '_' characters in text to '\\_'.",
+        help="Don't escape underscore (_) characters.",
     )
 
     parser.add_argument(
         "--no-escape-misc",
         dest="escape_misc",
         action="store_false",
-        help="Disable escaping of miscellaneous characters to prevent conflicts in Markdown.",
+        help="Don't escape other special Markdown characters.",
     )
 
     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.",
+        help="Parent tags where images remain inline (not converted to alt-text).",
     )
 
-    parser.add_argument(
-        "-w",
-        "--wrap",
-        action="store_true",
-        help="Enable word wrapping for paragraphs at --wrap-width characters.",
-    )
+    parser.add_argument("-w", "--wrap", action="store_true", help="Enable text wrapping 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.",
+        help="Column width for text wrapping. Default: 80.",
     )
 
     parser.add_argument(
         "--strip-newlines",
         action="store_true",
-        help="Remove newlines from HTML input before processing. This helps flatten janky output from HTML with unnecessary line breaks.",
+        help="Remove newlines from HTML input (helps with messy HTML formatting).",
     )
 
     parser.add_argument(
         "--convert-as-inline",
         action="store_true",
-        help="Treat the content as inline elements (no block elements like paragraphs).",
+        help="Treat all content as inline elements (no paragraph breaks).",
     )
 
     parser.add_argument(
         "--no-extract-metadata",
         dest="extract_metadata",
         action="store_false",
-        help="Disable extraction of document metadata (title, meta tags) as a comment header.",
+        help="Don't extract metadata (title, meta tags) as comment header.",
     )
 
     parser.add_argument(
         "--highlight-style",
         default=DOUBLE_EQUAL,
         choices=("double-equal", "html", "bold"),
-        help="Style to use for highlighted text (mark elements). Defaults to 'double-equal'.",
+        help="Highlighting style: 'double-equal' (==), 'html' (<mark>), or 'bold' (**). Default: double-equal.",
     )
 
     parser.add_argument(
         "--stream-processing",
         action="store_true",
-        help="Use streaming processing for large documents to reduce memory usage.",
+        help="Process large documents in chunks to reduce memory usage.",
     )
 
     parser.add_argument(
         "--chunk-size",
         type=int,
         default=1024,
-        help="Size of chunks when using streaming processing. Defaults to 1024 characters.",
+        help="Chunk size for streaming processing. Default: 1024 characters.",
+    )
+
+    parser.add_argument("--show-progress", action="store_true", help="Show progress bar for large documents.")
+
+    parser.add_argument(
+        "--parser",
+        choices=("html.parser", "lxml", "html5lib"),
+        help="HTML parser: 'lxml', 'html.parser', or 'html5lib'. Default: auto-detect.",
+    )
+
+    parser.add_argument(
+        "--list-indent-type",
+        default="spaces",
+        choices=("spaces", "tabs"),
+        help="List indentation: 'spaces' or 'tabs'. Default: spaces.",
+    )
+
+    parser.add_argument(
+        "--list-indent-width",
+        type=int,
+        default=4,
+        help="Spaces per list indent level (use 2 for Discord/Slack). Default: 4.",
     )
 
     parser.add_argument(
-        "--show-progress",
+        "--whitespace-mode",
+        default=WHITESPACE_NORMALIZED,
+        choices=(WHITESPACE_NORMALIZED, WHITESPACE_STRICT),
+        help="Whitespace handling: 'normalized' (clean) or 'strict' (preserve). Default: normalized.",
+    )
+
+    parser.add_argument(
+        "--preprocess-html",
         action="store_true",
-        help="Show progress information when processing large documents.",
+        help="Clean messy HTML (removes navigation, ads, forms, etc).",
+    )
+
+    parser.add_argument(
+        "--preprocessing-preset",
+        default="standard",
+        choices=("minimal", "standard", "aggressive"),
+        help="Cleaning level: 'minimal', 'standard', or 'aggressive'. Default: standard.",
+    )
+
+    parser.add_argument(
+        "--no-remove-forms",
+        dest="remove_forms",
+        action="store_false",
+        help="Keep form elements when preprocessing (normally removed).",
+    )
+
+    parser.add_argument(
+        "--no-remove-navigation",
+        dest="remove_navigation",
+        action="store_false",
+        help="Keep navigation elements when preprocessing (normally removed).",
     )
 
     args = parser.parse_args(argv)
 
     base_args = {
-        "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,
+        "convert": args.convert,
+        "convert_as_inline": args.convert_as_inline,
+        "default_title": args.default_title,
         "escape_asterisks": args.escape_asterisks,
-        "escape_underscores": args.escape_underscores,
         "escape_misc": args.escape_misc,
+        "escape_underscores": args.escape_underscores,
+        "extract_metadata": args.extract_metadata,
+        "heading_style": args.heading_style,
+        "highlight_style": args.highlight_style,
         "keep_inline_images_in": args.keep_inline_images_in,
+        "list_indent_type": args.list_indent_type,
+        "list_indent_width": args.list_indent_width,
+        "newline_style": args.newline_style,
+        "preprocess_html": args.preprocess_html,
+        "preprocessing_preset": args.preprocessing_preset,
+        "remove_forms": args.remove_forms,
+        "remove_navigation": args.remove_navigation,
+        "strip": args.strip,
+        "strip_newlines": args.strip_newlines,
+        "strong_em_symbol": args.strong_em_symbol,
+        "sub_symbol": args.sub_symbol,
+        "sup_symbol": args.sup_symbol,
+        "whitespace_mode": args.whitespace_mode,
         "wrap": args.wrap,
         "wrap_width": args.wrap_width,
-        "strip_newlines": args.strip_newlines,
-        "convert_as_inline": args.convert_as_inline,
-        "extract_metadata": args.extract_metadata,
-        "highlight_style": args.highlight_style,
     }
 
+    if args.parser:
+        base_args["parser"] = args.parser
+
     if args.stream_processing:
         base_args["stream_processing"] = True
         base_args["chunk_size"] = args.chunk_size

html_to_markdown/constants.py

@@ -17,3 +17,6 @@ UNDERLINED: Final = "underlined"
 SPACES: Final = "spaces"
 UNDERSCORE: Final = "_"
 DOUBLE_EQUAL: Final = "double-equal"
+
+WHITESPACE_NORMALIZED: Final = "normalized"
+WHITESPACE_STRICT: Final = "strict"