pdstools.utils.report_utils._html¶

HTML post-processing: CSS inlining, zip bundling, error scanning.

Attributes¶

`_LINK_STYLESHEET_RE`
`_HREF_ATTR_RE`

Functions¶

`_inline_css`(→ int)	Inline relative CSS `<link>` tags in an HTML file.
`generate_zipped_report`(output_filename, folder_to_zip)	Generate a zipped archive of a directory.
`bundle_quarto_resources`(→ pathlib.Path)	Bundle a Quarto-rendered file with its resources folder into a zip.
`check_report_for_errors`(→ list[str])	Check generated report HTML for error indicators.

Module Contents¶

_LINK_STYLESHEET_RE¶

_HREF_ATTR_RE¶

_inline_css(html_path: pathlib.Path, base_dir: pathlib.Path) → int¶

Inline relative CSS <link> tags in an HTML file.

Replaces each <link rel="stylesheet" href="..."> whose href is a relative path with an inline <style> block containing the CSS text. Absolute URLs (http://, https://, //) are left untouched. Missing files are logged as warnings and left alone.

Parameters:

html_path (Path) – HTML file to patch in-place.
base_dir (Path) – Directory used to resolve relative href values.

Returns:

Number of CSS files successfully inlined.

Return type:

int

generate_zipped_report(output_filename: str, folder_to_zip: str)¶

Generate a zipped archive of a directory.

This is a general-purpose utility function that can compress any directory into a zip archive. While named for report generation, it works with any directory structure.

Parameters:

output_filename (str) – Name of the output file (extension will be replaced with .zip)
folder_to_zip (str) – Path to the directory to be compressed

Return type:

None

Raises:

FileNotFoundError – If the folder to zip does not exist or is not a directory

Examples

>>> generate_zipped_report("my_archive.zip", "/path/to/directory")
>>> generate_zipped_report("report_2023", "/tmp/report_output")

bundle_quarto_resources(output_path: pathlib.Path) → pathlib.Path¶

Bundle a Quarto-rendered file with its resources folder into a zip.

When Quarto renders an HTML report without embed-resources, it emits the HTML alongside a <basename>_files/ directory containing the JavaScript and CSS assets the report needs. This helper detects that pattern and wraps both into a single <basename>.zip archive so the report can be distributed and unpacked as one unit.

If no companion resources folder exists next to output_path (e.g. the report was fully embedded, or the format doesn’t produce resources), the function is a no-op and returns output_path unchanged.

Parameters:: output_path (Path) – Path to the rendered report file (typically an HTML file). The companion resources folder is expected at <output_path stem>_files in the same directory.
Returns:: Path to the zip archive when bundling occurred, otherwise the original output_path.
Return type:: Path

check_report_for_errors(html_path: str | pathlib.Path) → list[str]¶

Check generated report HTML for error indicators.

Scans the HTML file for error patterns that indicate plot rendering failures or exceptions during report generation. These errors are typically hidden in collapsed callout sections but should be caught in testing.

Parameters:: html_path (str or Path) – Path to the HTML file to check
Returns:: List of error descriptions found (empty if no errors)
Return type:: list[str]
Raises:: FileNotFoundError – If the HTML file does not exist

Examples

>>> from pdstools.utils.report_utils import check_report_for_errors
>>> errors = check_report_for_errors("HealthCheck.html")
>>> if errors:
...     print(f"Found {len(errors)} error(s):")
...     for error in errors:
...         print(f"  - {error}")