HTML Utilities

The following are a number of utility functions used to generate the HTML log file produced by ShellLogger.

Various utilities for building the HTML log file.

shell_logger.html_utilities.append_html(*args, output)[source]

Append whatever is given to the output HTML file.

Parameters:

*args (Union[str, Iterator[str]]) – The argument(s) to write.
output (Path) – The HTML file to append to.

Return type:

None

shell_logger.html_utilities.child_logger_card(log)[source]

Generate a child logger card.

Create a card to go in the HTML log file containing everything pertaining to a child ShellLogger.

Parameters:: log (ShellLogger) – The child ShellLogger for which to generate the card.
Return type:: Iterator[str]
Returns:: A generator that will lazily yield the elements of the HTML for the card one at a time.

Todo

The type hinting for log is done in the docstring instead of the function signature, because to put it in the signature would create a circular dependency between shell_logger.py and html_utilities.py. This function needs to be reworked such that there’s no longer a dependency on ShellLogger.

shell_logger.html_utilities.child_logger_card_html(name, duration, *args)[source]

Generate the HTML for a child logger card.

Generate the HTML for a card corresponding to the child ShellLogger. The HTML elements are yielded one at a time to avoid loading all the data from the ShellLogger into memory at once.

Parameters:

name (str) – The name of the child ShellLogger.
duration (str) – The duration of the child ShellLogger.
*args (Union[Iterator[str], List[Iterator[str]]]) – A generator (or list of generators) to lazily yield string HTML elements for the contents of the child card.

Yields:

The header, followed by all the contents of the child ShellLogger, and then the footer.

Return type:

Iterator[str]

Todo

Should we replace the for loop with the one found in parent_logger_card_html()?

shell_logger.html_utilities.closing_html_text()[source]

Get the closing HTML tag.

Return type:: str
Returns:: A string with the closing HTML tag in it.

shell_logger.html_utilities.command_card(log, stream_dir)[source]

Generate a command card.

Create a card in the HTML log file containing the output of a command, along with all its corresponding data (environment information, trace output, memory/CPU/disk statistics, etc.).

Parameters:

log (dict) – An entry from the ShellLogger ‘s log book corresponding to a command that was run.
stream_dir (Path) – The stream directory containing the stdout, stderr, and trace output from the command.

Return type:

Iterator[str]

Returns:

A generator to lazily yield the elements of the command card one at a time.

shell_logger.html_utilities.command_card_html(log, *args)[source]

Generate the HTML for a command card.

Generate the HTML for a card corresponding to a command that was run. The HTML elements are yielded one at a time to avoid loading all the data into memory at once.

Parameters:

log (dict) – An entry from the ShellLogger ‘s log book corresponding to a command that was run.
*args (Iterator[Union[str, Iterable]]) – A generator that will yield all the elements to be included in the command card one at a time.

Yields:

The header, followed by all the contents of the command card, and then the footer.

Return type:

Iterator[str]

shell_logger.html_utilities.command_detail(cmd_id, name, value, *, hidden=False)[source]

Generate the HTML for a command detail.

Create the HTML snippet for a detail associated with a command that was run.

Parameters:

cmd_id (str) – The unique identifier associated with the command that was run.
name (str) – The name of the detail being recorded.
value (str) – The value of the detail being recorded.
hidden (bool) – Whether or not this detail should be hidden (collapsed) in the HTML by default.

Return type:

str

Returns:

The HTML snippet for this command detail.

shell_logger.html_utilities.command_detail_list(cmd_id, *args)[source]

Generate the list of command details.

Generate the HTML for a list of details associated with a command that was run.

Parameters:

cmd_id (str) – The unique identifier associated with the command that was run.
*args (Iterator[str]) – All of the details associated with a command that was run.

Yields:

The header, followed by each of the details associated with the command that was run, and then the footer.

Return type:

Iterator[str]

shell_logger.html_utilities.diagnostics_card(cmd_id, *args)[source]

Generate a diagnostics card.

Generate a card containing system diagnostic information associated with a command that was run.

Parameters:

cmd_id (str) – The unique identifier associated with the command that was run.
*args (Iterator[str]) – A generator to lazily yield all the diagnostic information, one piece at a time.

Yields:

The header, followed by each piece of diagnostic information, and then the footer.

Return type:

Iterator[str]

shell_logger.html_utilities.disk_time_series_plot(cmd_id, data_tuples, volume_name)[source]

Generate a time series plot of disk usage.

Create the HTML for a plot of the disk usage time series data for a particular volume.

Parameters:

cmd_id (str) – The unique identifier associated with the command that was run.
data_tuples (Tuple[float, float]) – A list of \(x\) and \(y\) locations.
volume_name (str) – The name of the disk volume who’s data is being plotted.

Return type:

Iterator[str]

Returns:

A HTML snippet for a plot of the given data.

Todo

Should we combine this with time_series_plot()?

shell_logger.html_utilities.embed_html(resource)[source]

Embed the contents of a file in the HTML.

Get a HTML resource from a file for the sake of embedding it into the HTML header.

Parameters:: resource (str) – The name of a HTML file to embed.
Return type:: str
Returns:: The contents of the file.

Todo

Why do we use pkgutil.get_data() instead of a simple read().

shell_logger.html_utilities.embed_script(resource)[source]

Embed a script in the HTML.

Wrap the given resource in an appropriate <script>...</script> block for embedding in the HTML header.

Parameters:: resource (str) – The name of a script file to embed.
Return type:: str
Returns:: A string containing the <script>...</script> block.

shell_logger.html_utilities.embed_style(resource)[source]

Embed a style in the HTML.

Wrap the given resource in an appropriate <style>...</style> block for embedding in the HTML header.

Parameters:: resource (str) – The name of a style file to embed.
Return type:: str
Returns:: A string containing the <style>...</style> block.

Todo

Should we combine this with embed_script() and embed_html()?

shell_logger.html_utilities.fixed_width(text)[source]

Convert the text to a fixed-width font.

Wrap the given text in a <pre><code>...</code></pre> block such that it displays in a fixed-width font.

Parameters:: text (str) – The text to wrap.
Return type:: str
Returns:: The <pre><code>...</code></pre> block.

shell_logger.html_utilities.flatten(element)[source]

Turn a tree of lists into a flat iterable of strings.

Parameters:: element (Union[str, bytes, Iterable]) – An element of a tree.
Yields:: The string representation of the given element.
Return type:: Iterator[str]

shell_logger.html_utilities.get_human_time(milliseconds)[source]

Get a human-readable date/time.

Parameters:: milliseconds (float) – The number of milliseconds since epoch.
Return type:: str
Returns:: A string representation of the date and time.

shell_logger.html_utilities.html_encode(text)[source]

Replace special characters with their HTML encodings.

Parameters:: text (str) – The text to encode.
Return type:: str
Returns:: The encoded text.

shell_logger.html_utilities.html_header()[source]

Get the HTML header, complete with embedded styles and scripts.

Return type:: str
Returns:: A string with the <head>...</head> contents.

shell_logger.html_utilities.html_message_card(log)[source]

Generate the HTML for a message card.

Generate the HTML for a card corresponding to a message to only be included in the HTML log file (e.g., not printed to stdout as well).

Parameters:: log (dict) – An entry from the ShellLogger ‘s log book corresponding to a message.
Yields:: The header, followed by the contents of the message card, and then the footer.
Return type:: Iterator[str]

shell_logger.html_utilities.load_template(template)[source]

Load a template HTML file.

Parameters:: template (str) – The file name to load.
Return type:: str
Returns:: A string containing the contents of the file.

Todo

Should we combine this with embed_html()?

shell_logger.html_utilities.message_card(log)[source]

Generate a message card.

Generate the HTML for a card corresponding to a message to be both printed to stdout and included in the HTML log file.

Parameters:: log (dict) – An entry from the ShellLogger ‘s log book corresponding to a message.
Yields:: The header, followed by the contents of the message card, and then the footer.
Return type:: Iterator[str]

shell_logger.html_utilities.nested_simplenamespace_to_dict(namespace)[source]

Convert a SimpleNamespace to a dict.

Convert a SimpleNamespace, which may include nested namespaces, iterables, and mappings, to a dict containing the equivalent items.

Parameters:: namespace (Union[str, bytes, tuple, Mapping, Iterable, SimpleNamespace]) – The given namespace to convert, or some nested element therein.
Return type:: Union[str, bytes, tuple, dict, list]
Returns:: Recursively returns a base Python type equivalent of whatever was given.

shell_logger.html_utilities.opening_html_text()[source]

Get the opening HTML text.

Return type:: str
Returns:: A string containing the first line of the HTML document through </head>.

shell_logger.html_utilities.output_block(output, name, cmd_id)[source]

Generate an output block.

Given the output from a command, generate the HTML equivalent for inclusion in the log file.

Parameters:

output (Union[Path, str]) – The output from a command.
name (str) – The name (title) of the output block.
cmd_id (str) – The unique identifier associated with the command that was run.

Yields:

The HTML equivalent of each line of the output in turn.

Return type:

Iterator[str]

shell_logger.html_utilities.output_block_card(title, output, cmd_id, *, collapsed=True)[source]

Generate an output block card.

Given the output from a command, generate a corresponding HTML card for inclusion in the log file.

Parameters:

title (str) – The title for the output block.
output (Union[Path, str]) – The output from a command.
cmd_id (str) – The unique identifier associated with the command that was run.
collapsed (bool) – Whether or not the output block should be collapsed by default in the HTML log file.

Yields:

The header, followed by each line of the output, and then the footer.

Return type:

Iterator[str]

shell_logger.html_utilities.output_block_html(lines, name, cmd_id)[source]

Generate the HTML for an output block.

Given the output of a command, generate its HTML equivalent for inclusion in the log file.

Parameters:

lines (Union[TextIO, str]) – The lines of output.
name (str) – The name (title) for this output block.
cmd_id (str) – The unique identifier associated with the command that was run.

Yields:

The header, followed by the HTML corresponding to each line of output, and then the footer.

Return type:

Iterator[str]

shell_logger.html_utilities.output_line_html(line, line_no)[source]

Generate the HTML for a line of output.

Given a line of output from a command, along with the corresponding line number, create the HTML equivalent to be included in the log file.

Parameters:

line (str) – A line of output.
line_no (int) – The corresponding line number.

Return type:

str

Returns:

The corresponding HTML snippet.

shell_logger.html_utilities.parent_logger_card_html(name, *args)[source]

Generate the HTML for a parent logger card.

Generate the HTML for the card corresponding to the parent ShellLogger. The HTML elements are yielded one at a time to avoid loading all the data from the ShellLogger into memory at once.

Parameters:

name (str) – The name of the ShellLogger.
*args (List[Iterator[str]]) – A list of generators to lazily yield string HTML elements for the contents of the parent card.

Yields:

The header, followed by all the contents of the ShellLogger, and then the footer.

Return type:

Iterator[str]

shell_logger.html_utilities.sgr_24bit_color_to_html(sgr_params)[source]

Convert 24-bit SGR colors to HTML.

Convert a 24-bit Select Graphic Rendition (SGR) code to valid HTML/CSS.

Parameters:: sgr_params (List[str]) – The SGR codes to convert.
Return type:: str
Returns:: A HTML span with the appropriate CSS style.

shell_logger.html_utilities.sgr_4bit_color_and_style_to_html(sgr)[source]

Convert from Select Graphic Rendition (SGR) codes to CSS styles.

Parameters:: sgr (str) – The SGR code specified.
Return type:: str
Returns:: A HTML span with the corresponding CSS style definition.

shell_logger.html_utilities.sgr_8bit_color_to_html(sgr_params)[source]

Convert 8-bit SGR colors to HTML.

Convert an 8-bit Select Graphic Rendition (SGR) code to valid HTML/CSS.

Parameters:: sgr_params (List[str]) – The SGR codes to convert.
Return type:: str
Returns:: A HTML span with the appropriate CSS style.

shell_logger.html_utilities.sgr_to_html(text)[source]

Convert SGR to HTML.

Translate Select Graphic Rendition (SGR, a.k.a. ANSI escape codes) to valid HTML/CSS.

Parameters:: text (str) – The input text.
Return type:: str
Returns:: The same text, with the escape codes translated to HTML/CSS.

shell_logger.html_utilities.split_template(template, split_at, **kwargs)[source]

Subdivide a HTML template.

Take a templated HTML snippet and split it into a header and footer, meaning everything that comes before and after the line containing split_at. Also determine the indentation for the content that will be inserted between the header and footer.

Example

If the following snippet is template and split_at is child_body, then the header is lines 1-6, the footer is lines 8-9, and the indent is eight spaces.

<details class="child-logger">
    <summary>
        <h6 class="child-logger-heading">{name}</h6>
        <span class="duration"> (Duration: {duration})</span>
    </summary>
    <div class="child-logger-body">
        {child_body}
    </div>
</details>

Parameters:

template (str) – A templated HTML snippet.
split_at (str) – A substring used to split the template into before and after chunks.
**kwargs – Additional keyword arguments used to replace keywords in the template.

Return type:

Tuple[str, str, str]

Returns:

The header, indent, and footer.

shell_logger.html_utilities.stat_chart_card(labels, data, title, identifier)[source]

Create the HTML for a two-dimensional plot.

Parameters:

labels (List[str]) – The \(x\) values.
data (List[float]) – The \(y\) values.
title (str) – The title for the plot.
identifier (str) – A unique identifier for the chart.

Yields:

A HTML snippet for the chart with all the details filled in.

Return type:

Iterator[str]

shell_logger.html_utilities.time_series_plot(cmd_id, data_tuples, series_title)[source]

Create the HTML for a plot of time series data.

Parameters:

cmd_id (str) – The unique identifier associated with the command that was run.
data_tuples (List[Tuple[float, float]]) – A list of \(x\) and \(y\) locations.
series_title (str) – The title of the plot.

Return type:

Iterator[str]

Returns:

A HTML snippet for a plot of the given data.