Web UI Widgets for showing Logs

This module contains additional predefined user interface widget (WebPageItems) classes for displaying data logs (i.e. time series of dynamic variables) in the web UI, either as a textual list or as a plotted chart. The time series data, incl. live updates, is fetched from interfaces, which implement the shc.data_logging.DataLogVariable interface. See Data Logging.

class shc.web.log_widgets.LogListWidget(interval: timedelta, data_spec: List[LogListDataSpec])

A WebPageItem showing a dynamically updated list of recent value changes from one or more DataLogVariables.

The different data logs are combined, such that all datapoints (value changes) are shown in a unified list, ordered by their timestamp.

Note: The aggregation method, interval and value formatting can be defined individually for each data log variable. Thus, these settings are defined via a list of LogListDataSpec tuples, each of them defining one data log source with its settings. The overall display interval of the widget (i.e. how far into the past log entries are displayed), is set for all data log variables together.

Usage example:

import datetime
from shc.web.data_logging import AggregationMethod
from shc.web.log_widgets import LogListWidget, LogListDataSpec
from shc.interfaces.in_memory_data_logging import InMemoryDataLogVariable

# create WebServer and WebPage
web_page = ...

# Example in-memory log variables for keeping timeseries for 2h
# They need to be connected to some subscribable objects for providing the values
room_temperature_log = InMemoryDataLogVariable(float, datetime.timedelta(hours=2))
heater_power_log = InMemoryDataLogVariable(bool, datetime.timedelta(hours=2))

# LogListWidget, showing interleaved average temperature every 5 minutes and all heater
# on/off events within last hour
web_page.add_item(
    LogListWidget(
        datetime.timedelta(hours=1),
        [
            LogListDataSpec(room_temperature_log,
                            format="{}°C",
                            aggregation=AggregationMethod.AVERAGE,
                            aggregation_interval=datetime.timedelta(minutes=5)),
            LogListDataSpec(heater_power_log, lambda v: "on" if v else "off"),
        ])
)

Parameters:

interval – The time interval boundary of the widget: All entries of the data logs from interval ago up to now are displayed.
data_spec – The list of data log sources and their individual display settings. See LogListDataSpec’s documentation for available fields.

class shc.web.log_widgets.LogListDataSpec(variable: DataLogVariable[T], format: Union[str, Markup, Callable[[Union[T, float]], Union[str, Markup]]] = '{}', color: str = '', aggregation: Optional[AggregationMethod] = None, aggregation_interval: Optional[timedelta] = None)

Specification of one data log source and the formatting of its datapoints within a LogListWidget

aggregation: Optional[AggregationMethod] = None: Aggregation method of this datalog or None to disable aggregation

aggregation_interval: Optional[timedelta] = None: If aggregation is not None: The time span/period of the single aggregation intervals and aggregated datapoints

color: str = '': A color name to highlight all rows belonging to this data log in the LogListWidget. Must be one of Fomantic-UIs’s color names.

format: Union[str, Markup, Callable[[Union[T, float]], Union[str, Markup]]] = '{}': Formatter function or format string to format the values

variable: DataLogVariable[T]: The DataLogVariable (i.e. logging database connector) to retrieve the recent datapoints and updates from

class shc.web.log_widgets.ChartWidget(interval: timedelta, data_spec: List[ChartDataSpec])

A WebPageItem showing a dynamically line plot from one or more DataLogVariables, using Chart.js

For each data log a single line is plotted, using a common x axis (time) and y axis (value). It is possible to combine different value types (float, int, bool – boolean values are converted to 0 and 1), as well as different aggregation methods and intervals. For example, you can show minimum, maximum and average aggregation of the same logging variable.

Note: The aggregation method, interval and value formatting can be defined individually for each plot line. Thus, these settings are defined via a list of ChartDataSpec tuples, each of them defining one data log source with its settings. The overall display interval of the widget (i.e. scaling of the x axis), is set for all data log variables together.

Usage example:

import datetime
from shc.web.data_logging import AggregationMethod
from shc.web.log_widgets import ChartWidget, ChartDataSpec
from shc.interfaces.in_memory_data_logging import InMemoryDataLogVariable

# create WebServer and WebPage
web_page = ...

# Example in-memory log variable for keeping timeseries for 2h
# Needs to be connected to some subscribable object for providing the values
room_temperature_log = InMemoryDataLogVariable(float, datetime.timedelta(hours=2))

# ChartWidget, showing a plot of the 15-minutes minimum, maximum and average of the room
# temperature within the last two hours.
web_page.add_item(
    ChartWidget(
        datetime.timedelta(hours=1),
        [
            ChartDataSpec(room_temperature_log,
                          label="Min",
                          aggregation=AggregationMethod.MINIMUM,
                          aggregation_interval=datetime.timedelta(minutes=15)),
            ChartDataSpec(room_temperature_log,
                          label="Max",
                          aggregation=AggregationMethod.MAXIMUM,
                          aggregation_interval=datetime.timedelta(minutes=15)),
            ChartDataSpec(room_temperature_log,
                          label="AVG",
                          aggregation=AggregationMethod.AVERAGE,
                          aggregation_interval=datetime.timedelta(minutes=15)),
        ])
)

Parameters:

interval – The time interval / x axis range of the widget. The x axis will cover this time interval and end at the current time (“now”).
data_spec – The list of data log sources and their individual display settings. See ChartDataSpec’s documentation for available fields.

class shc.web.log_widgets.ChartDataSpec(variable: DataLogVariable, label: str, color: Optional[Tuple[int, int, int]] = None, aggregation: Optional[AggregationMethod] = None, aggregation_interval: Optional[timedelta] = None, scale_factor: float = 1.0, unit_symbol: str = '', stack_group: Optional[str] = None, plot_style: ChartPlotStyle = ChartPlotStyle.AUTO, line_interpolation: ChartLineInterpolation = ChartLineInterpolation.AUTO)

Specification of one data log source and the formatting of its datapoints within a ChartWidget

aggregation: Optional[AggregationMethod] = None: Aggregation method of this datalog or None to disable aggregation

aggregation_interval: Optional[timedelta] = None: If aggregation is not None: The time span/period of the single aggregation intervals and aggregated datapoints

color: Optional[Tuple[int, int, int]] = None: An RGB color value for the plot line. If None, one of the five pre-defined colors will be used for each line

line_interpolation: ChartLineInterpolation = 'auto': Select different line interpolation styles (smoothed, linear, stepped)

plot_style: ChartPlotStyle = 'auto': Select different plot styles (area vs. line plot, dots on/off)

scale_factor: float = 1.0: Multiply all logged values by this factor before showing in the chart (e.g. for unit conversion purposes)

stack_group: Optional[str] = None: If not None, this data row will be stacked upon (values added to) previous data rows with the same stack_group

unit_symbol: str = '': Unit symbol to be shown after the value in the Chart tooltip

variable: DataLogVariable: The DataLogVariable (i.e. logging database connector) to retrieve the recent datapoints and updates from

class shc.web.log_widgets.ChartPlotStyle(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

AREA = 'area': An area plot without visible line but stronger colored filled area

AUTO = 'auto': Uses LINE_DOTS for aggregated values, otherwise LINE_FILLED

LINE = 'line': A simple line plot, no dots, no background filling

LINE_DOTS = 'line_dots': A line plot with dots, no background filling

LINE_FILLED = 'line_filled': A pretty line plot with slightly colored background area

class shc.web.log_widgets.ChartLineInterpolation(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

AUTO = 'auto': Uses SMOOTH for aggregated values, otherwise LINEAR

LINEAR = 'linear': Use linear interpolation (straight lines between data points)

SMOOTH = 'smooth': Use bezier line interpolation

STEP_AFTER = 'after': Use stepped graph with horizontal lines ending at each data point

STEP_BEFORE = 'before': Use stepped graph, beginning a horizontal line at each data point