ENH/TST: format html helper + explicit html tests

klauer · klauer · commit 54632b9d9b3d · 2025-12-03T08:07:41.000-08:00
diff --git a/blark/format.py b/blark/format.py
@@ -8,8 +8,7 @@
 import sys
 from typing import Any, List, Optional, Tuple, Union
 
-from blark import output
-
+from . import output
 from . import transform as tf
 from .output import OutputBlock
 from .parse import ParseResult
diff --git a/blark/html.py b/blark/html.py
@@ -212,3 +212,38 @@ def _register():
     register_output_handler("html", HtmlWriter.save)
     register_output_handler(".htm", HtmlWriter.save)
     register_output_handler(".html", HtmlWriter.save)
+
+
+def format_file_as_html(
+    input_filename: pathlib.Path | str,
+    *,
+    header: str = "<html><body>",
+    footer: str = "</body></html>",
+) -> str:
+    """
+    Helper for formatting a file as HTML.
+
+    Parameters
+    ----------
+    input_filename : pathlib.Path or str
+        The source code filename. Any supported by `blark.parse`.
+    header : str, optional
+        HTML header to include in the output.
+        Defaults to html and body opening tags.
+    footer : str, optional
+        HTML footer to include in the output.
+        Defaults to html and body closing tags.
+
+    Note
+    ----
+    Users would typically format a file through blark's CLI by way of
+    `blark format --output-format html`.
+    """
+    from .format import get_reformatted_code_blocks
+    from .parse import parse
+
+    input_filename = pathlib.Path(input_filename)
+    results = parse(input_filename)
+    blocks = get_reformatted_code_blocks(list(results), filename=input_filename)
+    body = HtmlWriter.save(user=None, source_filename=input_filename, parts=blocks)
+    return "".join((header, body, footer))
diff --git a/blark/tests/test_html.py b/blark/tests/test_html.py
@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import os
+import pathlib
+
+import pytest
+
+from ..html import format_file_as_html
+from . import conftest
+
+parse_filenames = conftest.twincat_pou_filenames + conftest.structured_text_filenames
+
+
+@pytest.fixture(params=parse_filenames)
+def input_filename(request) -> pathlib.Path:
+    if not os.path.exists(request.param):
+        pytest.skip(f"File missing: {request.param}")
+    return pathlib.Path(request.param)
+
+
+def test_format_html(input_filename: pathlib.Path) -> None:
+    print(format_file_as_html(input_filename))
