scistag.vislog.visual_log_builder.VisualLogBuilder¶

class VisualLogBuilder(log)[source]¶

Bases: object

Defines an interface to all major log writing functions for the creation of a VisualLog document.

Can be overwritten to be provided as callback target for dynamic documentation creation.

Parameters: log (VisualLog) – The log to which the content shall be added.

Methods

`add`	Adds the provided content to the log.
`br`	Inserts a simple line break
`build`	Builds the whole page including header, footers and other sugar.
`build_body`	Is called when the body of the log shall be build or rebuild.
`build_footer`	Called to build the page's footer and after the body
`build_header`	Called to build the page's header and before the body
`clear`	Clears the whole log (excluding headers and footers)
`clip_logs`	Clips the logging files (e.g.
`code`	Adds code to the log
`critical`	Logs a critical error
`debug`	Logs an info text
`df`	Adds a dataframe to the log
`embed`	Embeds another VisualLog's content into this one
`error`	Logs an info text
`evaluate`	Runs a piece of code and returns it's output
`figure`	Adds a figure to the log
`get_hashed_filename`	Returns a hashed filename for name to be store it with a fixed size on disk
`get_temp_path`	Returns the temporary file path.
`hr`	Adds a horizontal rule to the document
`html`	Adds a html section.
`info`	Logs an info text
`link`	Adds a hyperlink to the log
`log`	Adds a log text to the log
`log_dict`	Logs a dictionary or a list.
`log_list`	Logs a list (just for convenience), forwards to log_dict.
`log_statistics`	Adds statistics about the VisualLog as table to the log
`log_timestamp`	Logs a timestamp to the log
`md`	Adds a markdown section.
`np`	Adds a numpy matrix or vector to the log
`page_break`	Inserts a page break
`pyplot`	Opens a matplotlib context to add a figure directly to the plot.
`reserve_unique_name`	Reserves a unique name within the log, e.g.
`sub`	Adds a sub title to the log
`sub_test`	Adds a subtest section to the log
`sub_x3`	Adds a subtitle to the log
`sub_x4`	Adds a subtitle to the log
`text`	Adds a text to the log
`title`	Adds a title to the log
`warning`	Logs an info text

Attributes

`__dict__`
`__doc__`
`__module__`
`__weakref__`	list of weak references to the object (if defined)
`max_fig_size`	The maximum figure size in pixels
`target_log`	The main logging target
`forward_targets`	List of logs to which all rendering commands shall be forwarded
`test`	Helper class for adding regression tests to the log.
`image`	Helper object for adding images to the log
`table`	Helper class for adding tables to the log.

_add_html(html_code)[source]¶

The HTML code to add

Parameters: html_code (str) – The html code
Returns: True if txt logging is enabled

_add_md(md_code, no_break=False)[source]¶

The markdown code to add

Parameters

md_code (str) – The markdown code
no_break (bool) – If defined no line break will be added

Returns

True if txt logging is enabled

_add_txt(txt_code, console=True, md=False)[source]¶

Adds text code to the txt / console log

Parameters

txt_code (str) – The text to add
console (bool) – Defines if the text shall also be added ot the console’s log (as it’s mostly identical). True by default.
md (bool) – Defines if the text shall be added to markdown as well

Returns

True if txt logging is enabled

static _encode_html(text)[source]¶

Escaped text to html compatible text

Parameters: text (str) – The original unicode text
Return type: str
Returns: The escaped text

static _html_linebreaks(text)[source]¶

Replaces linebreaks through html linebreaks

Parameters: text (str) – The original text
Return type: str
Returns: The text with html linebreaks

_log_advanced(text, level)[source]¶

Detects tables and other objects in a log and pretty prints the tables while keeping the other log data intact

Parameters

text – The log text
level (LogLevel) – The log level

add(content)[source]¶

Adds the provided content to the log.

Supports a large variety of types. All supported types can also easily be embedded into tables and divs via the provided add_row and add_col methods.

Parameters: content (Union[str, float, int, bool, ndarray, DataFrame, Series, list, dict, Image, Figure]) – The data to be logged
Return type: VisualLogBuilder
Returns: The builder

br()[source]¶

Inserts a simple line break

Return type: VisualLogBuilder
Returns: The builder

build()[source]¶

Builds the whole page including header, footers and other sugar.

Only overwrite this if you really want to do a more complex customization.

build_body()[source]¶

Is called when the body of the log shall be build or rebuild.

This is usually the function you want to override to implement your own page builder.

build_footer()[source]¶: Called to build the page’s footer and after the body

build_header()[source]¶: Called to build the page’s header and before the body

clear()[source]¶: Clears the whole log (excluding headers and footers)

clip_logs()[source]¶: Clips the logging files (e.g. if they are limited in length)

code(code)[source]¶

Adds code to the log

Parameters: code (str) – The code to execute
Return type: VisualLogBuilder
Returns: The builder

critical(*args, **kwargs)[source]¶

Logs a critical error

Parameters

args – The elements to log. Will be separated by space.
kwargs – Keyword arguments

Return type

VisualLogBuilder

debug(*args, **kwargs)[source]¶

Logs an info text

Parameters

args – The elements to log. Will be separated by space.
kwargs – Keyword arguments

Return type

VisualLogBuilder

df(df, name=None, index=True)[source]¶

Adds a dataframe to the log

Parameters

name (str | None) – The dataframe’s name
df (pd.DataFrame) – The data frame
index (bool) – Defines if the index shall be printed

embed(log)[source]¶

Embeds another VisualLog’s content into this one

Parameters: log (VisualLog) – The source log

error(*args, **kwargs)[source]¶

Logs an info text

Parameters

args – The elements to log. Will be separated by space.
kwargs – Keyword arguments

Return type

VisualLogBuilder

evaluate(code, log_code=True)[source]¶

Runs a piece of code and returns it’s output

Parameters

code (str) – The code to execute
log_code (bool) – Defines if the code shall be added to the log

Return type

Any

Returns

The returned data (if any)

figure(figure, name=None, alt_text=None, _out_image_data=None)[source]¶

Adds a figure to the log

Parameters

name (str | None) – The figure’s name
figure (plt.Figure | plt.Axes | Figure | Plot) – The figure to log
alt_text (str | None) – An alternative text to display if the figure can not be displayed.
_out_image_data (io.IOBase | None) – Receives the image data if provided (for debugging and assertion purposes)

static get_hashed_filename(name)[source]¶

Returns a hashed filename for name to be store it with a fixed size on disk

Parameters: name – The file’s name
Returns: The hash name to be used as filename

get_temp_path(relative=None)[source]¶

Returns the temporary file path. The data will be wiped upon the call of finalize.

Parameters: relative (str | None) – A relative path which can be passed and automatically gets concatenated.
Return type: str
Returns: The path or combined path

hr()[source]¶

Adds a horizontal rule to the document

Return type: VisualLogBuilder
Returns: The builder

html(code)[source]¶

Adds a html section. (only to targets supporting html)

Parameters: code (str) – The html code to parse
Return type: VisualLogBuilder

info(*args, **kwargs)[source]¶

Logs an info text

Parameters

args – The elements to log. Will be separated by space.
kwargs – Keyword arguments

Return type

VisualLogBuilder

link(text, link)[source]¶

Adds a hyperlink to the log

Parameters

text (str) – The text to add to the log
link (str) – The link target

Return type

VisualLogBuilder

Returns

The builder

log(*args, level=LogLevel.INFO, detect_objects=False, space=' ')[source]¶

Adds a log text to the log

Parameters

args (Any) – The text arguments to add to the log
level (LogLevel | str) – The importance / category of the log entry
detect_objects (bool) – Defines if special objects such as tables shall be detected and printed beautiful
space (str) – The character or text to be used for spaces

Returns

log_dict(dict_or_list)[source]¶

Logs a dictionary or a list.

The data needs to be JSON compatible so can contain further nested diotionaries, lists, floats, booleans or integers but no more complex types.

Parameters: dict_or_list (dict | list) – The dictionary or list

log_list(list_data)[source]¶

Logs a list (just for convenience), forwards to log_dict.

The data needs to be JSON compatible so can contain further nested diotionaries, lists, floats, booleans or integers but no more complex types.

Parameters: list_data (list) – The list to log

log_statistics()[source]¶: Adds statistics about the VisualLog as table to the log

log_timestamp(prefix='', postfix='')[source]¶

Logs a timestamp to the log

Parameters

prefix (str) – The text before the timestamp
postfix (str) – The text after the timestamp

Returns

md(text, exclude_targets=None)[source]¶

Adds a markdown section.

Requires the Markdown package to be installed.

Parameters

text (str) – The text to parse
exclude_targets (set[str] | None) – Defines the target to exclude

Return type

VisualLogBuilder

Returns

The builder

np(data, digits=2)[source]¶

Adds a numpy matrix or vector to the log

Parameters

data (ndarray) – The data frame
digits – The number of digits with which the numbers shall be formatted.

page_break()[source]¶

Inserts a page break

Return type: VisualLogBuilder
Returns: The builder

pyplot()[source]¶

Opens a matplotlib context to add a figure directly to the plot.

Also takes care off that no other thread is using matplotlib so you can safely plot using this function and matplotlib from multiple threads at once.

Return type: PyPlotLogContext

reserve_unique_name(name)[source]¶

Reserves a unique name within the log, e.g. to store an object to a unique file.

Parameters: name (str) – The desired name
Returns: The effective name with which the data shall be stored

sub(text, level=2)[source]¶

Adds a sub title to the log

Parameters

text (str) – The text to add to the log
level (int) – The title level (0..5)

Return type

VisualLogBuilder

Returns

The builder

sub_test(text)[source]¶

Adds a subtest section to the log

Parameters: text (str) – The text to add to the log
Return type: VisualLogBuilder
Returns: The builder

sub_x3(text)[source]¶

Adds a subtitle to the log

Parameters: text (str) – The text to add to the log
Return type: VisualLogBuilder
Returns: The builder

sub_x4(text)[source]¶

Adds a subtitle to the log

Parameters: text (str) – The text to add to the log
Return type: VisualLogBuilder
Returns: The builder

text(text)[source]¶

Adds a text to the log

Parameters: text (str) – The text to add to the log
Return type: VisualLogBuilder
Returns: The builder

title(text)[source]¶

Adds a title to the log

Parameters: text (str) – The title’s text
Return type: VisualLogBuilder
Returns: The builder

warning(*args, **kwargs)[source]¶

Logs an info text

Parameters

args – The elements to log. Will be separated by space.
kwargs – Keyword arguments

Return type

VisualLogBuilder

forward_targets: dict[str, scistag.vislog.visual_log_builder.VisualLogBuilder]¶: List of logs to which all rendering commands shall be forwarded

image¶

Helper object for adding images to the log

Can also be called directly to add a simple image to the log.

property max_fig_size: Size2D¶

The maximum figure size in pixels

Return type: Size2D

table¶

Helper class for adding tables to the log.

Can also be called directly to add a simple table to the log.

target_log: VisualLog¶: The main logging target

test¶: Helper class for adding regression tests to the log.