hdhelpers 0.0.1__py3-none-any.whl

hdhelpers/__init__.py

@@ -0,0 +1,47 @@
+from hdhelpers.exceptions import ComponentException, HelperException, InsufficientPlottingData
+from hdhelpers.helper_functions import (
+    _get_display_name,
+    _get_end_timestamp,
+    _get_start_timestamp,
+    _get_unit,
+    _pad_end,
+    _pad_start,
+    _to_datetime,
+)
+from hdhelpers.plot_target_settings import (
+    PlotTargetSettings,
+    PlotTargetStyle,
+    StatusColors,
+    get_plot_target_settings,
+)
+from hdhelpers.user_functions import (
+    get_and_pad_start_and_end_timestamp,
+    get_colors_from_plot_target_settings,
+    get_locale_from_plot_target_settings,
+    get_y_axis_label,
+    modify_timezone,
+    plotly_fig_to_json_dict,
+)
+
+__all__ = [
+    "ComponentException",
+    "HelperException",
+    "InsufficientPlottingData",
+    "PlotTargetSettings",
+    "PlotTargetStyle",
+    "StatusColors",
+    "_get_display_name",
+    "_get_end_timestamp",
+    "_get_start_timestamp",
+    "_get_unit",
+    "_pad_end",
+    "_pad_start",
+    "_to_datetime",
+    "get_and_pad_start_and_end_timestamp",
+    "get_colors_from_plot_target_settings",
+    "get_locale_from_plot_target_settings",
+    "get_plot_target_settings",
+    "get_y_axis_label",
+    "modify_timezone",
+    "plotly_fig_to_json_dict",
+]

hdhelpers/exceptions.py

@@ -0,0 +1,50 @@
+from typing import Any
+
+
+class ComponentException(Exception):
+    """Exception to re-raise exceptions with error code raised in the component code."""
+
+    __is_hetida_designer_exception__ = True
+
+    def __init__(
+        self,
+        *args: Any,
+        error_code: int | str = "",
+        extra_information: dict | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if not isinstance(error_code, int | str):
+            raise ValueError("The ComponentException.error_code must be int or string!")
+        self.error_code = error_code
+        self.extra_information = extra_information
+        super().__init__(*args, **kwargs)
+
+
+class HelperException(Exception):
+    """Exception to re-raise exceptions with error code raised in the code of the hdhelpers
+    package."""
+
+    __is_hetida_designer_exception__ = True
+
+    def __init__(
+        self,
+        *args: Any,
+        error_code: int | str = "",
+        extra_information: dict | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if not isinstance(error_code, int | str):
+            raise ValueError("The HelperException.error_code must be int or string!")
+        self.error_code = error_code
+        self.extra_information = extra_information
+        super().__init__(*args, **kwargs)
+
+
+class InsufficientPlottingData(ComponentException):
+    """A plot component has insufficient data to generate a meaningful plot
+
+    This exception class should be used when custom plots generated by hetida
+    designer are integrated in other frontends. This allows the frontend to
+    handle the case of e.g. no data to show in a sensible way, surpressing an
+    empty plot and showing an adequate message instead.
+    """

hdhelpers/helper_functions.py

@@ -0,0 +1,178 @@
+import logging
+from datetime import datetime
+from typing import Any
+
+import pandas as pd
+from pandas.tseries.frequencies import to_offset
+
+from hdhelpers.exceptions import HelperException
+from hdhelpers.plot_target_settings import get_plot_target_settings
+
+logger = logging.getLogger(__name__)
+
+
+def _convert_to_optional_timezone(object_to_convert: Any, to_timezone: str | None) -> Any:
+    """Convert object_to_convert to to_timezone if not None,
+    or to its own timezone if aware
+    or to UTC otherwise"""
+    if to_timezone is None:
+        if object_to_convert.tz is None:
+            return object_to_convert.tz_localize("UTC")
+        return object_to_convert
+    if object_to_convert.tz is None:
+        return object_to_convert.tz_localize(to_timezone)
+    return object_to_convert.tz_convert(to_timezone)
+
+
+def _get_display_name(series: pd.Series, default_title: str = "") -> str:
+    """Get name for y-axis label from metadata
+
+    Tries to get the name from series.attrs according to the conventions of thehetida platform.
+    If such metadata doesn't exist, the default_title is returned instead.
+    """
+    try:
+        title = (
+            series.attrs.get("single_metric_metadata", {})
+            .get("structured_metadata", {})
+            .get("metric", {})["short_display_name"]
+        )
+        if not isinstance(title, str):
+            raise HelperException("Expected short_display_name to be a string, but it is not!")
+    except (KeyError, HelperException) as exc:
+        msg = (
+            'Expected attrs["single_metric_metadata"]["structured_metadata"]["metric"]',
+            '["short_display_name"] but got incorrect keys',
+        )
+        logger.warning(msg=msg, exc_info=exc)
+        title = default_title
+    return title
+
+
+def _get_unit(series: pd.Series, default_unit: str = "") -> str:
+    """Get unit for y-axis label from metadata
+
+    Tries to get the unit from series.attrs according to the conventions of thehetida platform.
+    If such metadata doesn't exist, the default_unit is returned instead.
+    """
+    try:
+        unit = (
+            series.attrs.get("single_metric_metadata", {})
+            .get("structured_metadata", {})
+            .get("metric", {})["unit"]
+        )
+        if not isinstance(unit, str):
+            raise HelperException("Expected unit to be a string, but it is not!")
+    except (KeyError, HelperException) as exc:
+        msg = 'Expected attrs["single_metric_metadata"]["structured_metadata"]["metric"]["unit"'
+        "] but got incorrect keys"
+        logger.warning(msg=msg, exc_info=exc)
+        unit = default_unit
+    return unit
+
+
+def _pad_start(timestamp: pd.Timestamp, padding: str | None) -> pd.Timestamp:
+    """Subtracts padding from the timestamp
+
+    That padding has to be formatted to be compatible with pandas.tseries.frequencies.to_offset().
+    """
+    if padding is None:
+        return timestamp
+    try:
+        return timestamp - to_offset(padding)
+    except ValueError as exc:
+        raise HelperException(
+            f"{padding} as padding value is an invalid frequency. "
+            "Use something compatible with pandas.tseries.frequencies.to_offset()"
+        ) from exc
+
+
+def _pad_end(timestamp: pd.Timestamp, padding: str | None) -> pd.Timestamp:
+    """Adds padding to the timestamp
+
+    That padding has to be formatted to be compatible with pandas.tseries.frequencies.to_offset().
+    """
+    if padding is None:
+        return timestamp
+    try:
+        return timestamp + to_offset(padding)
+    except ValueError as exc:
+        raise HelperException(
+            f"{padding} as padding value is an invalid frequency. "
+            "Use something compatible with pandas.tseries.frequencies.to_offset()"
+        ) from exc
+
+
+def _get_start_timestamp(
+    series: pd.Series, timestamp: datetime | str | None
+) -> pd.Timestamp | None:
+    """Get the start timestamp  hierarchically
+
+    Will check for an explicit input timestamp first, then check PlotTargetSettings, then the series
+    metadata, and if both are None, will take the first series entry as start timestamp.
+    If the series is also empty, None is returned.
+    """
+    if timestamp is not None:
+        return _to_datetime(timestamp)
+
+    plot_target_settings = get_plot_target_settings()
+
+    timestamp = plot_target_settings.datetime_x_axes_range_start
+
+    if timestamp is None:
+        key = "ref_interval_start_timestamp"
+        try:
+            timestamp = series.attrs.get("single_metric_dataset_metadata", {})[key]
+        except KeyError as exc:
+            msg = f"""Expected key structure not found:
+             attrs["single_metric_dataset_metadata"]["{key}"]"""
+            logger.warning(msg=msg, exc_info=exc)
+            if len(series) > 0:
+                timestamp = series.index[0]
+
+    return _to_datetime(timestamp)
+
+
+def _get_end_timestamp(series: pd.Series, timestamp: datetime | str | None) -> pd.Timestamp | None:
+    """Get the end timestamp hierarchically
+
+    Will check for an explicit input timestamp first, then check PlotTargetSettings, then the series
+    metadata, and if both are None, will take the last series entry as end timestamp.
+    If the series is also empty, None is returned.
+    """
+    if timestamp is not None:
+        return _to_datetime(timestamp)
+
+    plot_target_settings = get_plot_target_settings()
+
+    timestamp = plot_target_settings.datetime_x_axes_range_end
+
+    if timestamp is None:
+        key = "ref_interval_end_timestamp"
+        try:
+            timestamp = series.attrs.get("single_metric_dataset_metadata", {})[key]
+        except KeyError as exc:
+            msg = f"""Expected key structure not found:
+             attrs["single_metric_dataset_metadata"]["{key}"]"""
+            logger.warning(msg=msg, exc_info=exc)
+            if len(series) > 0:
+                timestamp = series.index[-1]
+
+    return _to_datetime(timestamp)
+
+
+def _to_datetime(timestamp: datetime | str | int | None) -> pd.Timestamp | None:
+    """Turn datetime string or integer into a pandas timestamp
+
+    Integer values are interpreted as epoch in seconds.
+    String values are accepted in any format compatible with pd.to_datetime
+    and interpreted in seconds.
+    The timezone is set to utc in both cases, other timezones can be set via modify_timezone."""
+    if timestamp is None:
+        return None
+    if isinstance(timestamp, int):
+        timestamp = pd.to_datetime(timestamp, unit="s", utc=True)
+    elif isinstance(timestamp, str | datetime):
+        timestamp = pd.to_datetime(timestamp, utc=True)
+    else:
+        raise HelperException("Unexpected timestamp type, please use str or int!")
+    return timestamp

hdhelpers/plot_target_settings.py

@@ -0,0 +1,112 @@
+import datetime
+import logging
+
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+
+class StatusColors(BaseModel):
+    """Collection of status-related colors
+
+    Unlike the other colors in PlotTargetSettings, these colors do not have a predefined use.
+    Instead they should be used contextually, e.g. when displaying the sensor status of an asset.
+    """
+
+    success_color: str | None = Field(
+        None, description="Color of markers that signal success as a hexcode"
+    )
+    error_color: str | None = Field(
+        None, description="Color of markers that signal errors as a hexcode"
+    )
+    warn_color: str | None = Field(
+        None, description="Color of markers that signal warnings as a hexcode"
+    )
+    info_color: str | None = Field(
+        None, description="Color of markers that signal informativeness as a hexcode"
+    )
+
+
+class PlotTargetStyle(BaseModel):
+    axes_label_color: str | None = Field(
+        None, description="Color of the tick labels of all axes as a hex code"
+    )
+    background_color: str | None = Field(
+        None, description="Color of the panel background as a hex code"
+    )
+    grid_color: str | None = Field(
+        None, description="Color of the grid as a hex code that may be drawn into the background"
+    )
+    line_colors: list[str] | None = Field(
+        None,
+        description="""List of colors to be used for plot traces.
+            Will be set as colorway by plotly_fig_to_json_dict,
+            so the colors are only applied where no explicit trace color is set""",
+    )
+    status_colors: StatusColors = Field(
+        StatusColors(),  # type: ignore
+        description="Has the properties success_color, error_color, warn_color, info_color",
+    )
+
+
+class PlotTargetSettings(BaseModel):
+    """Settings that plot components can/should use
+
+    Some Plotly settings like locale or the timezone of timestamps must be set
+    by Python and cannot easily be set by plotly.js in a frontend.
+
+    They can be provided to execution endpoints as part of the ExecByIdBase payload,
+    are made accessible to components using the execution context.
+
+    hdhelpers provides helper functions to access them at runtime.
+    """
+
+    plot_target_timezone: str | None = Field(
+        None,
+        description="""The timezone plot components should use for datetime axes etc.
+             Usually via
+             s.index=pd.to_datetime(s.index, utc=True).tz_convert(plot_target_timezone)""",
+        examples=["Europe/Berlin"],
+    )
+    plot_target_locale: str | None = Field(
+        None,
+        description="""Locale to set for plots, e.g. to write weekdays in the user's language.
+             This has to be set in the config of the plotly figure dict and the plotly.js
+             must have the associated plotly local scripts loaded.""",
+    )
+    plot_target_style: PlotTargetStyle = Field(
+        PlotTargetStyle(),  # type: ignore
+        description="Colors to use in the plot",
+    )
+    datetime_tick_format: str | None = Field(
+        None, description="Tickformat to use for datetime axes", examples=["%H:%M<br>%d.%m.%Y"]
+    )
+    datetime_x_axes_range_start: datetime.datetime | None = Field(
+        None, description="datetime range start which plots should set as x axis range"
+    )
+
+    datetime_x_axes_range_end: datetime.datetime | None = Field(
+        None, description="datetime range end which plots should set as x axis range"
+    )
+
+
+def get_plot_target_settings() -> PlotTargetSettings:
+    """Obtain plot settings from runtime execution context.
+
+    If hetdesrun is not importable or this context field is not set,
+    return default values.
+    """
+    try:
+        from hetdesrun.runtime.context import (  # type: ignore  # noqa: PLC0415
+            get_runtime_exec_context,
+        )
+
+        plot_target_settings = get_runtime_exec_context().plot_target_settings
+        if not isinstance(plot_target_settings, PlotTargetSettings):
+            raise TypeError("plot_target_settings must be instance of PlotTargetSettings")
+
+        return plot_target_settings
+    except (ImportError, TypeError):
+        logger.warning("Could not load runtime exec context, import failed! Switch to defaults.")
+        # return defaults if hetdesrun is not available as import
+        return PlotTargetSettings()  # type: ignore

hdhelpers/user_functions.py

@@ -0,0 +1,348 @@
+import json
+import logging
+from datetime import datetime
+from typing import Any
+from warnings import warn
+
+import pandas as pd
+import pytz
+from plotly.graph_objects import Figure  # type: ignore
+from plotly.utils import PlotlyJSONEncoder  # type: ignore
+
+from hdhelpers.exceptions import HelperException
+from hdhelpers.helper_functions import (
+    _convert_to_optional_timezone,
+    _get_display_name,
+    _get_end_timestamp,
+    _get_start_timestamp,
+    _get_unit,
+    _pad_end,
+    _pad_start,
+)
+from hdhelpers.plot_target_settings import PlotTargetStyle, get_plot_target_settings
+
+logger = logging.getLogger(__name__)
+
+
+def get_colors_from_plot_target_settings() -> PlotTargetStyle:
+    """Get thematically coherent colors for customizing plots
+
+    Most color uses are already covered by the default settings of plotly_fig_to_json_dict().
+    They are still included here in case coloring other plot elements in the same color is desired.
+    Each color is given as a hex code, line_colors is a list of such, as specified in
+    PlotTargetStyle.
+    """
+    plot_target_settings = get_plot_target_settings()
+
+    return plot_target_settings.plot_target_style
+
+
+def get_locale_from_plot_target_settings() -> str | None:
+    """Get language for customizing text elements in plots
+
+    Axis ticks are already covered by the default settings of plotly_fig_to_json_dict().
+    The language of custom text elements should be adjusted to the locale.
+    """
+    plot_target_settings = get_plot_target_settings()
+
+    return plot_target_settings.plot_target_locale
+
+
+def get_y_axis_label(series: pd.Series, default_title: str = "", default_unit: str = "") -> str:
+    """Get full y-axis label from metadata
+
+    Combines the title and unit provided by _get_display_name and _get_unit.
+    """
+    title = _get_display_name(series, default_title)
+    unit = _get_unit(series, default_unit)
+    if len(unit) > 0:
+        title = f"{title} [{unit}]"
+    return title
+
+
+def get_and_pad_start_and_end_timestamp(
+    series: pd.Series,
+    timezone: str | None = None,
+    start: datetime | str | None = None,
+    start_padding: str | None = None,
+    end: datetime | str | None = None,
+    end_padding: str | None = None,
+) -> tuple[pd.Timestamp, pd.Timestamp]:
+    """Get time period displayed on the x-axis
+
+    Retrieves the start and end timestamps, prioritizing the explicit "start" and "end" parameters
+    over the metadata of "series" and using the first and last index of the series if neither is
+    given. If a padding is given, the respective timestamp is adjusted. That padding has to be
+    formatted to be compatible with pandas.tseries.frequencies.to_offset().
+    """
+    # Get start and end
+    start = _get_start_timestamp(series, start)
+    end = _get_end_timestamp(series, end)
+
+    if start is None:
+        raise HelperException("No start timestamp found!")
+    start_timestamp = start
+    if end is None:
+        raise HelperException("No end timestamp found!")
+    end_timestamp = end
+
+    # Convert timezone
+    if timezone is not None:
+        start_with_timezone = modify_timezone(start_timestamp, timezone)
+        end_with_timezone = modify_timezone(end_timestamp, timezone)
+    else:
+        start_with_timezone = start_timestamp
+        end_with_timezone = end_timestamp
+
+    # Optionally add padding
+    start_padded = _pad_start(start_with_timezone, start_padding)
+    end_padded = _pad_end(end_with_timezone, end_padding)
+
+    return start_padded, end_padded
+
+
+def modify_timezone[T: (pd.Timestamp, pd.Series, pd.DataFrame)](  # noqa: PLR0912
+    object_to_convert: T,
+    to_timezone: str | None = None,
+    column_name: str | None = None,
+    column_names: list[str] | None = None,
+    convert_index: bool = True,
+) -> T:
+    """Modifies timestamps to a certain timezone
+
+    Keyword arguments:
+    object_to_convert -- pd.Timestamp, pd.Series or pd.DataFrame where timezone is modified
+    to_timezone -- timezone to convert to, e.g. for German time use Europe/Berlin.
+    See possible timezone strings in pandas tz_convert method or pytz all_timezones list.
+    column_name -- column_name to apply, default is index as pd.Series have timestamps in index
+    """
+    if not isinstance(object_to_convert, pd.Timestamp | pd.Series | pd.DataFrame):
+        raise TypeError(
+            f"object_to_convert is {type(object_to_convert)} not pd.Series | pd.DataFrame"
+        )
+    if column_names is None:
+        column_names = []
+
+    try:
+        if to_timezone is None:
+            plot_target_settings = get_plot_target_settings()
+            if plot_target_settings.plot_target_timezone is not None:
+                to_timezone = plot_target_settings.plot_target_timezone
+
+        if isinstance(object_to_convert, pd.Timestamp):
+            return _convert_to_optional_timezone(object_to_convert, to_timezone)
+
+        if isinstance(object_to_convert, pd.Series):
+            new_object = object_to_convert.to_frame(name=object_to_convert.name)
+        else:
+            new_object = object_to_convert.copy(deep=True)
+
+        # Both column_name branches exist purely for backwards compatibility,
+        # only convert_index should stay.
+        if column_name is None and convert_index:
+            new_object.index = _convert_to_optional_timezone(
+                pd.to_datetime(new_object.index), to_timezone
+            )
+        if column_name is not None:
+            warn(
+                """The parameter 'column_name' will soon be deprecated in favor of
+                the more flexible 'columns_names'""",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            new_object[column_name] = _convert_to_optional_timezone(
+                pd.to_datetime(new_object[column_name]).dt, to_timezone
+            )
+            column_names.append(column_name)
+
+        if len(column_names) == 0:
+            if isinstance(object_to_convert, pd.Series):
+                new_object.index = _convert_to_optional_timezone(
+                    pd.to_datetime(new_object.index), to_timezone
+                )
+                msg = f"Converted index to datetime starting with {object_to_convert.index[0]}"
+                logger.debug(msg=msg)
+            elif isinstance(new_object, pd.DataFrame) and "timestamp" in new_object.columns:
+                new_object["timestamp"] = _convert_to_optional_timezone(
+                    pd.to_datetime(new_object["timestamp"]).dt, to_timezone
+                )
+                msg = f"""Converted column "timestamp" to datetime starting with
+                {object_to_convert["timestamp"][0]}"""
+                logger.debug(msg=msg)
+        if len(column_names) > 0:
+            for column in column_names:
+                new_object[column] = _convert_to_optional_timezone(
+                    pd.to_datetime(new_object[column]).dt, to_timezone
+                )
+
+        if not isinstance(object_to_convert, pd.Series):
+            new_object.attrs = object_to_convert.attrs
+            return new_object
+
+        series_object = pd.Series(
+            new_object[object_to_convert.name],
+            index=new_object.index,
+            name=object_to_convert.name,
+        )
+        series_object.attrs = object_to_convert.attrs
+
+        return series_object
+
+    except pytz.exceptions.UnknownTimeZoneError as exc:
+        possible_timezone = pytz.all_timezones
+        raise ValueError(f"""Timezone not known, please choose from {possible_timezone}""") from exc
+    except (AttributeError, pytz.exceptions.NonExistentTimeError) as exc:
+        raise TypeError("Entries to convert do not contain valid timestamps") from exc
+    except KeyError as exc:
+        exc.add_note(f"Column name {column_name} not in object_to_convert")
+        raise
+
+
+def plotly_fig_to_json_dict(  # noqa: PLR0912, PLR0915
+    fig: Figure,
+    add_config_settings: bool = True,
+    hide_legend: bool | None = None,
+    hide_x_title: bool | None = None,
+    remove_plotly_bar: bool | None = None,
+    remove_plotly_icon: bool = True,
+    update_x_axes_tickformat: bool | None = None,
+    use_default_standoff: bool = False,
+    use_minimum_margin: bool = True,
+    use_muplot_axes_color: bool | None = None,
+    use_muplot_grid: bool | None = None,
+    use_muplot_line_and_markers: bool | None = None,
+    use_platform_background: bool | None = None,
+    use_platform_colorway: bool = True,
+    use_platform_defaults: bool = True,
+    use_simple_white_template: bool = True,
+) -> Any:
+    """Turn Plotly figure into a Python dict-like object
+
+    This function can be used in visualization components to obtain the
+    correct plotly json-like object from a Plotly Figure object.
+
+    Additionally, this function has a dozen boolean parameters that can be
+    set to standardize certain aspects of the plot styling in accordance
+    with the hetida platform.
+
+    See visualization components from the accompanying base components for
+    examples on usage.
+    """
+    if use_platform_defaults:
+        if hide_legend is None:
+            hide_legend = True
+        if hide_x_title is None:
+            hide_x_title = True
+        if remove_plotly_bar is None:
+            remove_plotly_bar = True
+        if update_x_axes_tickformat is None:
+            update_x_axes_tickformat = True
+        if use_default_standoff is None:
+            use_default_standoff = True
+        if use_muplot_axes_color is None:
+            use_muplot_axes_color = True
+        if use_muplot_grid is None:
+            use_muplot_grid = True
+        if use_muplot_line_and_markers is None:
+            use_muplot_line_and_markers = True
+        if use_platform_background is None:
+            use_platform_background = True
+    else:
+        if hide_legend is None:
+            hide_legend = False
+        if hide_x_title is None:
+            hide_x_title = False
+        if remove_plotly_bar is None:
+            remove_plotly_bar = False
+        if update_x_axes_tickformat is None:
+            update_x_axes_tickformat = False
+        if use_default_standoff is None:
+            use_default_standoff = False
+        if use_muplot_axes_color is None:
+            use_muplot_axes_color = False
+        if use_muplot_grid is None:
+            use_muplot_grid = False
+        if use_muplot_line_and_markers is None:
+            use_muplot_line_and_markers = False
+        if use_platform_background is None:
+            use_platform_background = False
+
+    plot_target_settings = get_plot_target_settings()
+
+    if use_platform_colorway and plot_target_settings.plot_target_style.line_colors is not None:
+        fig.update_layout(colorway=plot_target_settings.plot_target_style.line_colors)
+
+    if use_simple_white_template:
+        fig.update_layout({"template": "simple_white"})
+
+    if (
+        use_platform_background
+        and plot_target_settings.plot_target_style.background_color is not None
+    ):
+        fig.update_layout(
+            {
+                "paper_bgcolor": plot_target_settings.plot_target_style.background_color,
+                "plot_bgcolor": "rgba(0,0,0,0)",
+            }
+        )
+
+    if hide_legend:
+        fig.update_layout(showlegend=False)
+
+    if hide_x_title:
+        fig.update_xaxes(title_text="")
+
+    if update_x_axes_tickformat and plot_target_settings.datetime_tick_format is not None:
+        fig.update_xaxes(tickformat=plot_target_settings.datetime_tick_format)
+
+    if (
+        use_muplot_axes_color
+        and plot_target_settings.plot_target_style.axes_label_color is not None
+    ):
+        fig.update_xaxes(color=plot_target_settings.plot_target_style.axes_label_color)
+        fig.update_yaxes(color=plot_target_settings.plot_target_style.axes_label_color)
+
+    if use_default_standoff:
+        fig.update_yaxes(title_standoff=5)
+
+    if use_muplot_line_and_markers:
+        fig.update_traces(
+            {
+                "marker": {"size": 3},
+                "line": {"width": 1},
+                "mode": "lines+markers",
+                "marker_symbol": "circle",
+            }
+        )
+
+    if use_minimum_margin:
+        fig.update_layout(
+            {"margin": {"autoexpand": True, "l": 0, "r": 0, "b": 0, "t": 0, "pad": 0}}
+        )
+
+    if use_muplot_grid and plot_target_settings.plot_target_style.grid_color is not None:
+        grid_dict = {
+            "showgrid": True,
+            "gridcolor": plot_target_settings.plot_target_style.grid_color,
+            "zeroline": True,
+            "zerolinecolor": plot_target_settings.plot_target_style.grid_color,
+        }
+        fig.update_layout({"xaxis": grid_dict, "yaxis": grid_dict})
+
+    fig_dict_obj = fig.to_plotly_json()
+    if not "config" in fig_dict_obj:
+        fig_dict_obj["config"] = {}
+
+    if add_config_settings and plot_target_settings.plot_target_locale is not None:
+        fig_dict_obj["config"]["locale"] = plot_target_settings.plot_target_locale
+
+    if remove_plotly_bar:
+        fig_dict_obj["config"]["displayModeBar"] = False
+
+    if remove_plotly_icon:
+        fig_dict_obj["config"]["displaylogo"] = False
+
+    # possibly quite inefficient (multiple serialisation / deserialization) but
+    # guarantees that the PlotlyJSONEncoder is used and so the resulting Json
+    # should be definitely compatible with the plotly javascript library:
+    return json.loads(json.dumps(fig_dict_obj, cls=PlotlyJSONEncoder))

hdhelpers-0.0.1.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: hdhelpers
+Version: 0.0.1
+Summary: Streamlines plotting and timezone handling in hetida designer components
+Project-URL: homepage, https://fuseki.com/data-science/hetida-designer/
+Project-URL: documentation, https://github.com/hetida/hetida-designer/tree/release/docs
+Project-URL: repository, https://github.com/hetida/hetida-designer
+Author-email: Christoph Dingel <cdingel@fuseki.com>, Steffen Wittkamp <swittkamp@fuseki.com>
+License:  The MIT License (MIT)
+        
+        Copyright © 2025 fuseki GmbH
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.13
+Requires-Dist: pandas<3,>=2
+Requires-Dist: plotly<7,>=6
+Requires-Dist: pydantic<3,>=2
+Description-Content-Type: text/markdown
+
+# hdhelpers
+## What is hdhelpers?
+hdhelpers is a package designed for and included in the standard installation of the [hetida designer](https://github.com/hetida/hetida-designer).
+
+It contains functions that streamline plotting components, especially those that are used in the [hetida platform](https://hetida.io/), by
+* accessing series metadata that complies with the hetida platform metadata scheme
+* accessing metadata that the hetida platform writes into the hetida designer's `plot_target_settings` context variable 
+* adjusting the timezone of timestamps, series, and dataframes
+* providing toggleable standardized styling options and json serialization for plotly plots
+
+## Getting Started with hdhelpers
+Since the intended use of the hdhelpers package is as a part of the hetida designer, it is highly recommended to follow the [hetida designer setup guide](https://github.com/hetida/hetida-designer/blob/release/README.md#getting-started-with-hetida-designer).
+
+For a specific example of how to use hdhelpers functionality in a hetida designer component, see [Example](#example).
+
+## Developing for hdhelpers
+In the development of this package, [uv](https://docs.astral.sh/uv/) was used for setting up a virtual environnment, managing dependencies, building and publishing the package. Though its use is not technically required, the following instructions assume that you use uv, too.
+
+### Setting up a Development Environment
+First, move to the `runtime/hdhelpers` subdirectory, which contains the hdhelpers package.
+
+Create a virtual environment with `uv venv`, which you can then find in the `.venv` subdirectory. There, uv installs all dependencies defined in `pyproject.toml`.
+
+All uv commands that need a python environment will use `.venv`, so you should use it for your development, too.
+
+Finally, in case you need to add a new dependency, do so via `uv add <new_dependency>`. That way, uv finds versions of all dependencies that are compatible with each other.
+
+### Deploying Your Code
+Once you are done writing your code, including unit tests, use `./run check` to see if your code quality is sufficient.
+
+Before you build the package, , then set an appropriate [version number](https://packaging.python.org/en/latest/discussions/versioning/#semantic-versioning) in `pyproject.toml`.
+
+To build the package and delete any files that are currently in the `dist` subdirectory, execute `rm -r dist && uv build`. [Hatchling](https://pypi.org/project/hatchling/), the build backend specified in `pyproject.toml`, will build a new sdist and wheel in the `dist` subdirectory.
+
+The hetida designer docker compose dev setup installs hdhelpers from [TestPyPI](https://packaging.python.org/en/latest/guides/using-testpypi/) using the following command in the `Dockerfile-runtime`:
+```
+RUN pip install -U --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ hdhelpers
+```
+**Note: TestPyPI occasionally deletes projects to free up disk space. If your hetida designer docker compose dev setup cannot find hdhelpers, make sure the project is still on TestPyPI before following other debugging approaches!**
+
+To publish the build from the `dist` subdirectory to TestPyPI, use `uv publish --index testpypi`. To do so, you need a TestPyPI account with a token to enter in the command line as password following the username "\_\_token__".
+
+Next time your hetida designer docker compose dev setup builds the runtime container, it will install the hdhelpers version that you just deployed.
+
+## <a name="example"></a> Example
+Let's say we want to plot the following timeseries in a style that looks good on a hetida platform dashboard.
+```
+{
+    "__hd_wrapped_data_object__":"SERIES",
+    "__metadata__": {
+        "single_metric_metadata": {
+            "ref_interval_end_timestamp":"2020-01-01T08:17:00.000Z",
+            "ref_interval_start_timestamp": "2020-01-01T08:10:00.000Z",
+            "structured_metadata": {
+                "metric": {
+                    "short_display_name": "Water Level",
+                    "unit": "cm"
+                }
+            }
+        }
+    },    "__data__": {
+        "2020-01-01T08:10:00.000Z": 1,
+        "2020-01-01T08:15:00.000Z": 2,
+        "2020-01-01T08:16:00.000Z": 3,
+        "2020-01-01T08:17:00.000Z": 4
+    }
+}
+```
+Our component code might look like this:
+```
+from hdhelpers import get_and_pad_start_and_end_timestamp, get_title_with_unit, modify_timezone, plotly_fig_to_json_dict
+import plotly.graph_objects as go
+...
+def main(*, series, timezone):
+    # entrypoint function for this component
+    # ***** DO NOT EDIT LINES ABOVE *****
+    # write your function code here.
+    series = modify_timezone(series, timezone)
+
+    fig = go.Figure([go.Scatter(x=series.index, y=series.values)])
+
+    start, end = get_and_pad_start_and_end_timestamp(series=series, timezone=timezone, start_padding='5s', end_padding='5s')
+    fig.update_xaxes(range=(start, end))
+
+    full_title = get_title_with_unit(series=series, default_title="Level")
+    fig.update_layout(yaxis_title=full_title)
+
+    return {"plot": plotly_fig_to_json_dict(fig=fig, use_platform_defaults=True)}
+```
+First, we use `modify_timezone` to set the timezone. Setting it to a string containing "plot_target", like "plot_target_timezone" or "plot_target_settings", will use the dashboard's timezone, but throw an exception if no such timezone is defined. Therefore, we might want to enter the timezone as a component input parameter with a default value of "plot_target_timezone", so it can be set to another value when the component is executed outside of the hetida platform.
+
+With the timezone-corrected data in place, we turn it into a plotly scatter plot called `fig`, that we can then style to our liking.
+
+Now, we use `get_and_pad_start_and_end_timestamp` for precise control over the x-axis range. We do not set `start` and `end` because we want to parse them from the series metadata. The timezone of the axis and that of the data should be the same, so we pass it to the function as `timezone` just like we did with `modify_timezone`. We also set a padding, so the markers of the first and last data point are not cut in half by the edge of the plot. With start and end parsed, we can update `fig`'s x-axis range.
+
+Next, we use `get_title_with_unit` so our y-axis can be labeled with the series metadata. With the above input series, title and unit will be parsed from the series metadata, but in case the component is ever run without series metadata, we provide a `default_title`, but we leave the `default_unit` at its empty default value. Then, we update `fig` with our title.
+
+Lastly, we use `plotly_fig_to_json_dict` to apply standardized stylings of our choice and serialize the plotly figure into a json dict. We set `use_platform_defaults` to True to switch on all the styling options at once, as detailed in [Styling Flags](#flags).
+
+As a result we get the following plot:
+
+![hdhelpers example plot](./../../docs/assets/hdhelpers_example_plot.png)
+
+### <a name="flags"></a> Styling Flags
+`use_platform_defaults=True` sets the following flags to `True`, which are by default `False`:
+* `hide_legend` sets the plotly layout parameter `showlegend=False` to hide the plot's legend
+* `hide_x_title` sets the plotly xaxes parameter `title_text=''` to hide the x-axis title
+* `update_x_axes_tickformat` sets the plotly xaxes parameter `tickformat` to the `datetime_tick_format` property the hetida platform writes into the hetida designer's `plot_target_settings` context variable (unless the property is `None`)
+* `use_default_standoff` sets the plotly yaxes parameter `title_standoff=5`
+* `use_muplot_axes_color` sets the plotly xaxes and yaxes parameter `color` to the `axes_label_color` property the hetida platform writes into the hetida designer's `plot_target_settings` context variable (unless the property is `None`)
+* `use_muplot_grid` makes the plotly grid visible and colors it in according to the `grid_color` property the hetida platform writes into the hetida designer's `plot_target_settings` context variable (unless the property is `None`)
+* `use_muplot_line_and_markers` sets the plotly traces to the following style, which matches the hetida platform's µplots:
+```
+{
+    "marker": {"size": 3},
+    "line": {"width": 1},
+    "mode": "lines+markers",
+    "marker_symbol": "circle",
+}
+```
+* `use_platform_background` sets the plotly layout parameter `paper_bgcolor` to the `background_color` property the hetida platform writes into the hetida designer's `plot_target_settings` context variable (unless the property is `None`) and it sets `plot_bgcolor=rgba(0,0,0,0)` so the "paper background" is visible through the "plot background"
+
+`plotly_fig_to_json_dict` has five more boolean parameters:
+* `add_config_settings` sets the plotly figure's locale to the `plot_target_locale` property the hetida platform writes into the hetida designer's `plot_target_settings` context variable (unless the property is `None`)
+* `remove_plotly_bar` sets the plotly figure's `displayModeBar` setting to `False` to remove the plotly bar from the plot
+* `remove_plotly_icon` sets the plotly figure's `displaylogo` setting to `False` to remove the plotly logo from the plot
+* `use_minimum_margin` sets the plotly layout parameter `margin={"autoexpand": True, "l": 0, "r": 0, "b": 0, "t": 0, "pad": 0}` to minimize the plot's margins
+* `use_simple_white_template` sets the plotly layout parameter `template=simple_white`
+
+Beyond that, there is one more thing `plotly_fig_to_json_dict` does: It sets the `colorway` to the `line_colors` in `plot_target_settings` (unless they are `None`). This cannot be turned off because the colorway is automatically overwritten by any explicitly set line color, so it being "always on" does not hinder plot customization.

hdhelpers-0.0.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+hdhelpers/__init__.py,sha256=h7Qovh2RU6Xlijn_ZPAIzu47uuTiZ_Uqy-WV123DKDA,1208
+hdhelpers/exceptions.py,sha256=OCkqwt3-V00zWGVZQX89VcANr3_-JICNJIVS6h3mVOQ,1695
+hdhelpers/helper_functions.py,sha256=KX5z-fkj9iNG5qu1PDnFlVWa82A-Ql-k5o805rxc7EU,6667
+hdhelpers/plot_target_settings.py,sha256=w8zh4TIdNZAeHSkbHA4RJtto8Giq0o8i1uDVpw-AvWg,4353
+hdhelpers/user_functions.py,sha256=Lns9dY_N5Yhy2_lP8GOpQAYp3q2aOsq0VCNo4tWXn7o,13332
+hdhelpers-0.0.1.dist-info/METADATA,sha256=lRxBrZzpxoQU_w8p3V_sYimbSrGdHxAb_GY6-iIG31s,11921
+hdhelpers-0.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+hdhelpers-0.0.1.dist-info/licenses/LICENSE,sha256=0czzBa9jPwpQLIqxOZk0zcQfAudLJBH-_4IRjEAr0zU,1086
+hdhelpers-0.0.1.dist-info/RECORD,,

hdhelpers-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hdhelpers-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,9 @@
+ The MIT License (MIT)
+
+Copyright © 2025 fuseki GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.