HtmlLog – Reference Guide

Source code

Class HtmlLog

    An HTML logger to file, plus optional plain-text printing to standard output
    TODO:   maybe rename "HtmlLogger" or "ReportMaker"
            Add feature to create a Table of Contents
    
nameargumentsreturns
configcls, filename=None, namestem=None, mode=None, css=None, js=None, use_D3=False, Vue_lib=FalseNone
        It can only be called once in a run.
        If desired, it can be done explicitly - and should be done so if the Class defaults need to be changed;
        if not done explicitly, it'll be done automatically if calling any method in this library.

        Roughly, the counterpart of basicConfig in the default Python logger

        # ARGUMENTS OPTIONALLY USED TO CHANGE THE CLASS DEFAULTS
        :param filename:    Name for the log file (if using just 1 file), or basename (if using multiple log files);
                                EXAMPLES: "log.htm" or "reports/log1.htm"

        :param namestem:    EXPERIMENTAL, not yet in use.  A filename, or full/relative path, without a suffix;
                                ".log.htm" will automatically get added

        :param mode:        Must be one of:
                                "append"    - if the log file exists, append to it; otherwise, create it (AVOID if using Vue)
                                "overwrite" - if the log file exists, first clear it; otherwise, create it
                                "multiple"  - each run's output should go into a separate file (consecutively numbered)

        # ARGUMENTS OPTIONALLY USED TO PASS STYLING/JAVASCRIPT/GRAPHING PARAMETER
        :param css:         String, or list of strings, with name(s) of CSS files to include
        :param js:          String, or list of strings, with name(s) of extra JavaScript files to include
        :param use_D3:      Flag indicating whether D3 will be used.  If True,
                                https://d3js.org/d3.v7.min.js will be included
        :param Vue_lib:     Full name of js file that contains the desired version of the Vue library.
                                NOTE: at present, use of Vue isn't compatible with the "append" mode

        :return:            None
        
nameargumentsreturns
writecls, msg: str, plain="", also_print=ALSO_PRINT, indent = 0, blanks_before = 0, newline = True, blanks_after = 0, style = None, style_par = None

        :param msg:             A string (possibly with HTML markup - but NOT recommended),
                                or object that can be sent as input to the str() function,
                                to be sent out to the log, and possibly also printed
                                (newline automatically added by default)

        ALL THE FOLLOWING ARGUMENTS ARE OPTIONAL
        :param plain:           A plain-text version (possibly blank) of the `msg` argument.
                                If an empty string, then the value in the `msg` argument is used,
                                after stripping off any HTML that might be present
        :param also_print:      Only applicable if `plain` is blank.
                                Flag indicating whether to also print an HTML-stripped version of msg

        :param indent:          Integer indicating the number of blank spaces (or HTML left indent) to prefix to the message being output

        :param blanks_before:   Number of blank lines to precede the output with
        :param newline:         Flag indicating whether the output should be terminated by a newline (a 
in the HTML version) :param blanks_after: Number of blank lines to place after the output :param style: Name of a function (or list/tuple of function names) to apply to the message string prior to sending it to HTML logs. Example: HtmlLog.bold , or [HtmlLog.italic, HtmlLog.red] :param style_par: :return:
nameargumentsreturns
new_runclsNone
        If the HTML log is cumulative, annotate it with a prominent header line (with a timestamp),
        to indicate the start of a new run (to easily distinguish this run from earlier ones.)
        Typically done early on in a run.

        :return:    None
        
nameargumentsreturns
separatorcls, caption = "", also_print=ALSO_PRINTNone
        Append to the appropriate logs a separator line and an optional caption

        :param caption:     Optional caption string after the separator line
        :param also_print:  Flag indicating whether to also print a text version
        :return:            None
        
nameargumentsreturns
blank_linecls, n_blanks = 1None
        Append the specified number of blank lines to the logs

        :param n_blanks:    Desired number of blank lines
        :return:            None
        
nameargumentsreturns
export_plot_D3cls, data, svg_id, js_file, js_func, D3_tag="svg"None
        Append to the log the HTML needed to produce a D3-based plot

        :param data:
        :param svg_id:
        :param js_file:
        :param js_func:
        :param D3_tag:  The tag of the container that D3 reaches into.
                        Typically, "svg" or "div"
        :return:        None
        
nameargumentsreturns
export_plot_Vuecls, data: dict, component_name: str, component_file: strNone
        Append to the log the HTML needed to produce a Vue-based plot

        :param data:            A python dictionary of data to pass to the Vue component
        :param component_name:  A string with the name of the existing Vue.js component to use.
                                        EXAMPLE: "vue_curves_4" (assuming that a js file with such a component exists)
        :param component_file:  A string with the name of the .js file containing the needed Vue component above

        :return:        None
        
nameargumentsreturns
_pass_propsdata: dictstr
        Prepare a string that goes inside the Vue component call

        :param data:    A python dictionary of data for the component
        :return:        A string that goes inside the Vue component call
        
nameargumentsreturns
_convert_datadata: dictstr
        From a Python dictionary, prepare a string that goes inside the "data:" section of the Vue element instantiation,
        and therefore needs to be valid JavaScript.

        EXAMPLE:  { "outer_radius": 200, "width": True, "a": [1, 'yes', "no"] , "b": {"x": 8, "y": False}, "c": "it's \"almost\" true" }
            returns the string:
            '''outer_radius_json: 200,\nwidth_json: true,\na_json: [1, "yes", "no"],\nb_json: {"x": 8, "y": false},\nc_json: "it's \\"almost\\" true"'''
            which prints out as [left indent added for readability]:

                outer_radius_json: 200,
                width_json: true,
                a_json: [1, "yes", "no"],
                b_json: {"x": 8, "y": false},
                c_json: "it's \"almost\" true"

        Notice the "_json" suffix added to the keys  (TODO: maybe this suffix could be ditched...)

        :param data:    A python dictionary
        :return:        A string that goes inside the "data:" section of the Vue element instantiation
        
nameargumentsreturns
bolds: strstr

nameargumentsreturns
italics: strstr

nameargumentsreturns
h1s: strstr

nameargumentsreturns
h2s: strstr

nameargumentsreturns
h3s: strstr

nameargumentsreturns
grays: strstr

nameargumentsreturns
reds: strstr

nameargumentsreturns
greens: strstr

nameargumentsreturns
blues: strstr

nameargumentsreturns
colors: str, color_valuestr

nameargumentsreturns
reverses: strstr

nameargumentsreturns
html_indentindent: intstr
        Compose and return a SPAN html element to create a left indentation
        by the specified value (expressed in "ch" units)

        :param indent:  In "ch" units (the width of the zero character "0")
        :return:        A string with the HTML code for the formatted element
        
nameargumentsreturns
linkname: str, url: str, new_window=Truestr

        :param name:
        :param url:
        :param new_window:
        :return:
        
nameargumentsreturns
button_posttext: str, url: str, post_data: strstr

        :param text:
        :param url:
        :param post_data: TODO: it currently cannot have double quotes
        :return:
        
nameargumentsreturns
_external_js_filecls, filename: str, defer=False
        Write into the log file the necessary HTML code to include
        the given JavaScript file

        :param filename:
        :param defer:
        :return:
        
nameargumentsreturns
_write_to_filecls, msg: str, blanks_before = 0, newline = False, blanks_after = 0None
        Write the given message (containing text and/or HTML code) into the file managed with
        the File Handler stored in the class property "file_handler"

        :param msg:             String to write to the designated log file
        :param blanks_before:   Number of blank lines ("
\n") to precede the output with :param newline: Flag indicating whether the output should be terminated by an HTML newline ("
\n") :param blanks_after: Number of blank lines ("
\n") to place after the output :return: None
nameargumentsreturns
_write_to_consolecls, msg: str, blanks_before = 0, newline = True, blanks_after = 0None
        Print out (to the standard output) the given message

        :param msg:             Plain-text string to print out to the standard output
        :param blanks_before:   Number of blank lines to precede the output with
        :param newline:         Flag indicating whether the output should be terminated by a newline
        :param blanks_after:    Number of blank lines to place after the output
        :return:                None
        
nameargumentsreturns
closecls
        Useful in case of ongoing file lock the prevents its deletion
        (for example, if the file was opened in JupyterLab)
        
nameargumentsreturns
_html_commentcls, comment: str, newline_before = TrueNone
        Write to the log, an HTML comment (useful for readability), on a separate line

        :param comment:         String with the body of the comment.  EXAMPLE: "Start of data table"
        :param newline_before:
        :return:                None
        
nameargumentsreturns
strip_htmlcls, html_strstr
        A light-duty HTML stripper that preserves newlines.
        EXAMPLE:    "An important list:
A
B" results in "An important list:\nA\nB" :param html_str: :return:
nameargumentsreturns
_next_available_filenamecls, filename_stem: strstr
        Given a particular file name (referred to as "stem", because we'll be suffixing a numeric index),
        locate the first index such that no file with that name is present in the same directory as the original file.

        EXAMPLES:
            given "test.htm", it might return "test1.htm" or "test23.htm"
            given "/my_path/test.htm", it might return "/my_path/test1.htm" or "/my_path/test34.htm"
            given "myfile", it might return "myfile1" or "myfile8"

        :param filename_stem:   A filename with or without a path.  If no path is given, the current directory is understood

        :return:                The modified filename, with either a numeric index or "_overflow" added at the end
                                (file suffices such as ".htm" aren't modified if present)