Overview

Interface for Report Output class.

It declares all the methods that have to be implemented by ReportOutput engine. Report Output operates on the concept of document to which components are added sequentially. Because of that, the add_ methods don't return anything, but instead they are modifying internal document object.

It has the following implications:

Calling the same method twice will add the same component twice to the report document.
The order in which we add components to the report maters.
We cannot return to the previous components to modify them, so we must have all needed data before we create it.

Document might be a different object type depending on the implementation, but usually it is a sequence of object that represents components in the document.

Each report output implements an .export() method that exports the content of report output to a file, that can be considered a report document artifact. For example, Word Report Output produces .docx file when .export() method is called on it.

`add_text(text, style=TextStyle.DEFAULT, dictionary=None, **kwargs)` `abstractmethod`

Adds text paragraph to the report document.

text is a string and style is an identifier of style that is applied to it. Style's nature depends on the implementation details, e.g. for Word Document it is a name of style, while for Dash / HTML it's a name of class defined in CSS.

This method supports a subset of Markdown formatting in provided text string. Following elements are supported:

Empty line adds a new paragraph.
Hashes (#) at the beginning of the line adds heading. Number of hashes indicates a heading level and the text after the hashes is a heading text. Example:
```
self.add_text("## Report Overview\nThis a report overview text")
```
is an equivalent of
```
self.add_heading(text="Report Overview", level=2)
self.add_text(text="This is a report overview")
```

Pattern [TEXT](URL) adds a hyperlink with TEXT that points to URL. Example:

self.add_text("Visit [ABB website](https://new.abb.com) now.")

is an equivalent of:

self.add_text(text="Visit ")
self.add_hyperlink(text="ABB website", url="https://new.abb.com")
self.add_text(text=" now.")

Any occurrence of {{VARIABLE}} will be replaced by the string that comes from provided dictionary keyword argument. Example:
```
d = dict(temperature=42.0)
self.add_text("Current motor temperature is {{temperature}} °C", dictionary=d)
```
will add to the report following string: "Current motor temperature is 42.0 °C"

Parameters:

Name	Type	Description	Default
`text`	`str`	Input text	required
`style`	`TextStyle`	Identifier of a text that will be applied to the text	`DEFAULT`
`dictionary`	`Optional[Dict]`	Dictionary that would be used to replace Variables located in input text.	`None`

`add_hyperlink(text, url, **kwargs)` `abstractmethod`

Adds hyperlink to the report document.

Hyperlink object can link the report reader to external url or to the another section of the report.

Parameters:

Name	Type	Description	Default
`text`	`str`	Text of the Hyperlink	required
`url`	`str`	URL that the hyperlink points to	required

`add_heading(text, level, **kwargs)` `abstractmethod`

Adds heading to the report document.

Each heading has text and level, where text is what the heading says and level is how bold it is. Levels is an integer from range <1;6>. The lower the number is the more important the heading is. That corresponds to the HTML concept of H tags.

Parameters:

Name	Type	Description	Default
`text`	`str`	Text of the heading	required
`level`	`int`	Level of the heading. Integer from 1 to 6	required

`add_page_break(**kwargs)` `abstractmethod`

Adds page break to the report document.

For some implementation it might be invisible since they don't support the concept of the page, but it is always stored in the report document, so it can be reused when the report is converted to different output type.

`add_toc(**kwargs)` `abstractmethod`

Adds automatic Table of Content to the report document.

Due to the nature of how the document is modified, and the fact that the ToC is usually added at the beginning of the report and then followed by the content, it has to be an interactive field, that will be rendered when the report file is opened.

`add_table(table_data, style=TableStyle.DEFAULT, column_widths=None, **kwargs)` `abstractmethod`

Adds table to the report document.

Input data should be provided as sequence of rows, where row is a sequence of cells and cells is either as simple string or a TableCell object that carries extra formatting information. Only 2-D structures with constant number of rows and columns are allowed. Merging can be achieved by using a special cell values TableCell.MERGE_LEFT and TableCell.MERGE_ABOVE.

Parameters:

Name	Type	Description	Default
`table_data`	`TableData`	Sequence rows, where row is a sequence of cells. Cell might be a simple string or a TableCell object, that also carries the information about cell formatting.	required
`style`	`TableStyle`	TableStyle, Identifier of a style that will be applied to created table	`DEFAULT`
`column_widths`	`Sequence[float]`	Sequence of column widths as percents. They should sum up to 100%. If not provided, each implementation will figure out the best widths based on provided data.	`None`

`add_table_legend(legend_cells, **kwargs)` `abstractmethod`

Adds a color-based legend table to the report document.

It expects a sequence of LegendCell objects as an input. Each LegendCell object defines a title, color and description. Legend can be used to explain color encoding of a table. Widths of legend cells are automatically calculated. Based on the required space, legend is adjusted to the right or takes all the row space.

Parameters:

Name	Type	Description	Default
`legend_cells`	`Sequence[LegendCell]`	Sequence of LegendCell objects.	required

`add_picture(picture, width=100.0, **kwargs)`

Adds a single static picture to the report document. It is based on the .add_pictures() method and simply adds a sequence of one picture to a row with default width of 100 percent.

Refer to .add_pictures() method documentation for more details.

Parameters:

Name	Type	Description	Default
`picture`	`Union[str, bytes]`	Picture data provided either as a bytes sequence or string.	required
`width`	`float`	Width of the picture to be added in percents of document width. If not provided, then the full width (100%) is used.	`100.0`

`add_pictures(pictures, widths=None, **kwargs)` `abstractmethod`

Adds a sequence of static pictures to a single row in the report document.

Each picture should be provided either as a sequence of bytes or as a path to the picture file.

Parameters:

Name	Type	Description	Default
`pictures`	`Sequence[Union[Path, str, bytes]]`	Sequence of picture data provided either as a bytes sequence or picture file path.	required
`widths`	`Sequence[float]`	Optional sequence of pictures widths. They should sum up to 100%. If not provided, each implementation will figure out the best widths based on provided data.	`None`

`add_figure(figure, width=100.0, **kwargs)`

Adds a single Plotly figure to the report document.

It is based on the .add_figures() method and simply adds a sequence of one figure to a row with default width of 100 percent.

Refer to .add_figures() method documentation for more details.

Parameters:

Name	Type	Description	Default
`figure`	`Figure`	Plotly figure object.	required
`width`	`float`	Width of the figure to be added in percents of document width. If not provided, then the full width (100%) is used.	`100.0`

`add_figures(figures, widths=None, **kwargs)` `abstractmethod`

Adds a sequence of Plotly figures to a single row in the report document.

Depending on the implementation it might be added as an interactive object (Dash Reports) or as a static picture rendered from original figure (Word Reports).

Parameters:

Name	Type	Description	Default
`figures`	`Sequence[Figure]`	Sequence of Plotly figure objects data provided either as a bytes sequence or string.	required
`widths`	`Optional[Sequence[float]]`	Optional sequence of pictures widths. They should sum up to 100%. If not provided, each implementation will figure out the best widths based on provided data.	`None`

`column_section(no_of_columns=2)` `abstractmethod`

Creates a context in which the Report Output works in column layout.

Number of columns is defined no_of_columns parameter. Components can be added to the document the same way as you would do for a standard (single column) layout, but within the context you have a next_column() function available that can move you to the next column. When the context is finished the basic layout is restored (single column).

Example of usage:

ro = ReportOutput()
with ro.column_section(3) as next_column:  # 'next_column' is the name of the function that jumps to next column
    # We start from the first column (counting from the left)
    # and we work with ReportOutput the same way as usual
    ro.add_text("Text in first column")
    next_column()  # move the context to the next column (second)
    ro.add_heading("Heading in the middle", level=2)
    ro.add_text("Text in second column")
    next_column()  # move the context to the next column (third, last)
    ro.add_text("Text in third column")
    next_column()  # there were only three columns in this context, so this will do nothing

Parameters:

Name	Type	Description	Default
`no_of_columns`	`int`	Number of columns to be created for the section bounded by the column context manager.	`2`

Returns:

Type	Description
`None`	A function that will move the report output "cursor" to the next column in the created context.
`None`	This function should be called each time when you are finished with adding content to the current column,
`None`	and you want to move to the next column. If you call it while being in the last column, nothing will happen,
`None`	and the "cursor" will remain in the same (last) column.

`export(filepath, **kwargs)` `abstractmethod`

Exports a report document to a file path provided in the filepath argument.

Parameters:

Name	Type	Description	Default
`filepath`	`Union[str, Path]`	Path to the export file	required

Interface extension

Following methods are a part of interface, but it's not mandatory to implement them. That is why they don't have the @abstractmethod decorator.

It only makes sense to implement them in the interactive reports, so currently only Dash reports does so. If there is any data preparation involved in the report generation logic, it might be beneficial to wrap the whole section with .is_interactive if statement, so it is executed only for interactive reports.

Example

   if ro.is_interactive:
      data = heavy_data_processing()
      ro.add_audio_player(audio_data=data)

Interface for Report Output class.

It declares all the methods that have to be implemented by ReportOutput engine. Report Output operates on the concept of document to which components are added sequentially. Because of that, the add_ methods don't return anything, but instead they are modifying internal document object.

It has the following implications:

Calling the same method twice will add the same component twice to the report document.
The order in which we add components to the report maters.
We cannot return to the previous components to modify them, so we must have all needed data before we create it.

Document might be a different object type depending on the implementation, but usually it is a sequence of object that represents components in the document.

Each report output implements an .export() method that exports the content of report output to a file, that can be considered a report document artifact. For example, Word Report Output produces .docx file when .export() method is called on it.

`add_slider(initial_value, button_text, **kwargs)`

Adds a button to the report document that opens an extra window with a slider that allow the report reader to adjust some values that affect the report content.

It can only be implemented for the interactive report output types, but the results of the content modification caused by the slider can be saved, and therefore seen in the static report after the conversion process.

Currently, only Dash Report Output implements it.

Parameters:

Name	Type	Description	Default
`initial_value`	`float`	Initial value of the slider	required
`button_text`	`str`	Text on the button that opens the slider window	required

`add_comment_box(**kwargs)`

Adds an interactive field to the report document where a report reader can add his/hers comments.

It can only be implemented for the interactive report output types, but the comment text added by the reader can be saved and rendered as a highlighted paragraph in the static report after the conversion process.

Currently, only Dash Report Output implements it.

`add_audio_player(audio_data, **kwargs)`

Adds an audio player to the report document.

It takes any sequence of bytes that can be interpreted as sound wave, and creates HTML Audio element with based on this data.

It is only implemented for Dash Reports, and it is neglected in the conversion process.

Parameters:

Name	Type	Description	Default
`audio_data`	`bytes`	Sequence of bytes that can be interpreted as a sound wave.	required

Overview

add_text(text, style=TextStyle.DEFAULT, dictionary=None, **kwargs) abstractmethod

add_hyperlink(text, url, **kwargs) abstractmethod

add_heading(text, level, **kwargs) abstractmethod

add_page_break(**kwargs) abstractmethod

add_toc(**kwargs) abstractmethod

add_table(table_data, style=TableStyle.DEFAULT, column_widths=None, **kwargs) abstractmethod

add_table_legend(legend_cells, **kwargs) abstractmethod

add_picture(picture, width=100.0, **kwargs)

add_pictures(pictures, widths=None, **kwargs) abstractmethod

add_figure(figure, width=100.0, **kwargs)

add_figures(figures, widths=None, **kwargs) abstractmethod

column_section(no_of_columns=2) abstractmethod

export(filepath, **kwargs) abstractmethod

Interface extension

add_slider(initial_value, button_text, **kwargs)

add_comment_box(**kwargs)

add_audio_player(audio_data, **kwargs)

`add_text(text, style=TextStyle.DEFAULT, dictionary=None, **kwargs)` `abstractmethod`

`add_hyperlink(text, url, **kwargs)` `abstractmethod`

`add_heading(text, level, **kwargs)` `abstractmethod`

`add_page_break(**kwargs)` `abstractmethod`

`add_toc(**kwargs)` `abstractmethod`

`add_table(table_data, style=TableStyle.DEFAULT, column_widths=None, **kwargs)` `abstractmethod`

`add_table_legend(legend_cells, **kwargs)` `abstractmethod`

`add_picture(picture, width=100.0, **kwargs)`

`add_pictures(pictures, widths=None, **kwargs)` `abstractmethod`

`add_figure(figure, width=100.0, **kwargs)`

`add_figures(figures, widths=None, **kwargs)` `abstractmethod`

`column_section(no_of_columns=2)` `abstractmethod`

`export(filepath, **kwargs)` `abstractmethod`

`add_slider(initial_value, button_text, **kwargs)`

`add_comment_box(**kwargs)`

`add_audio_player(audio_data, **kwargs)`