dashboard

Generic container dashboard.

To configure a container dashboard: attach DashboardConf metadata to MetadorContainer nodes.

To show a container dashboard: create a Dashboard instance.

NodeWidgetPair module-attribute

NodeWidgetPair = Tuple[MetadorNode, WidgetConf]

A container node paired up with a widget configuration.

NodeWidgetRow module-attribute

NodeWidgetRow = List[NodeWidgetPair]

Sorted list of NodeWidgetPairs.

Ordered first by descending priority, then by ascending node path.

DashboardPriority

Bases: int, Inclusive

Dashboard priority of a widget.

Source code in src/metador_core/widget/dashboard.py

class DashboardPriority(int, Inclusive, low=1, high=10):
    """Dashboard priority of a widget."""

DashboardGroup

Bases: int, Inclusive

Dashboard group of a widget.

Source code in src/metador_core/widget/dashboard.py

class DashboardGroup(int, Inclusive, low=1):
    """Dashboard group of a widget."""

WidgetConf

Bases: MetadataSchema

Configuration of a widget in the dashboard.

Source code in src/metador_core/widget/dashboard.py

class WidgetConf(MetadataSchema):
    """Configuration of a widget in the dashboard."""

    priority: Optional[DashboardPriority] = DashboardPriority(1)
    """Priority of the widget (1-10), higher priority nodes are shown first."""

    group: Optional[DashboardGroup]
    """Dashboard group of the widget.

    Groups are presented in ascending order.
    Widgets are ordered by priority within a group.
    All widgets in a group are shown in a single row.

    Widgets without an assigned group come last.
    """

    # ----

    schema_name: Optional[NonEmptyStr]
    """Name of schema of an metadata object at the current node that is to be visualized.

    If not given, any suitable will be selected if possible.
    """

    schema_version: Optional[SemVerTuple]
    """Version of schema to be used.

    If not given, any suitable will be selected if possible.
    """

    widget_name: Optional[str]
    """Name of widget to be used.

    If not given, any suitable will be selected if possible.
    """

    widget_version: Optional[SemVerTuple]
    """Version of widget to be used.

    If not given, any suitable will be selected if possible.
    """

priority class-attribute instance-attribute

priority: Optional[DashboardPriority] = DashboardPriority(1)

Priority of the widget (1-10), higher priority nodes are shown first.

group instance-attribute

group: Optional[DashboardGroup]

Dashboard group of the widget.

Groups are presented in ascending order. Widgets are ordered by priority within a group. All widgets in a group are shown in a single row.

Widgets without an assigned group come last.

schema_name instance-attribute

schema_name: Optional[NonEmptyStr]

Name of schema of an metadata object at the current node that is to be visualized.

If not given, any suitable will be selected if possible.

schema_version instance-attribute

schema_version: Optional[SemVerTuple]

Version of schema to be used.

If not given, any suitable will be selected if possible.

widget_name instance-attribute

widget_name: Optional[str]

Name of widget to be used.

If not given, any suitable will be selected if possible.

widget_version instance-attribute

widget_version: Optional[SemVerTuple]

Version of widget to be used.

If not given, any suitable will be selected if possible.

DashboardConf

Bases: MetadataSchema

Schema describing dashboard configuration for a node in a container.

Instantiating without passing a list of widget configurations will return an instance that will show an arbitrary suitable widget, i.e. is equivalent to DashboardConf.show()

Source code in src/metador_core/widget/dashboard.py

class DashboardConf(MetadataSchema):
    """Schema describing dashboard configuration for a node in a container.

    Instantiating without passing a list of widget configurations will
    return an instance that will show an arbitrary suitable widget, i.e.
    is equivalent to `DashboardConf.show()`
    """

    class Plugin:
        name = "core.dashboard"
        version = (0, 1, 0)

    widgets: List[WidgetConf] = [WidgetConf()]
    """Widgets to present for this node in the dashboard.

    If left empty, will try present any widget usable for this node.
    """

    @staticmethod
    def widget(**kwargs) -> WidgetConf:
        """Construct a dashboard widget configuration (see `WidgetConf`)."""
        # for convenience
        return WidgetConf(**kwargs)

    @classmethod
    def show(cls, _arg: List[WidgetConf] = None, **kwargs):
        """Construct a dashboard configuration for the widget(s) of one container node.

        For one widget, pass the widget config (if any) as keyword arguments,
        e.g.  `DashboardConf.show(group=1)`.

        For multiple widgets, create widget configurations with `widget(...)`,
        and pass them to `show`, e.g.:
        `DashboardConf.show([DashboardConf.widget(), DashboardConf.widget(group=2)])`.
        """
        if _arg and kwargs:
            msg = "Pass widget config arguments or list of widget configs - not both!"
            raise ValueError(msg)

        if _arg is None:
            # kwargs have config for a singleton widget
            widgets = [cls.widget(**kwargs)]
        else:
            # multiple widgets, preconfigured
            widgets = list(_arg)
        return cls(widgets=widgets)

widgets class-attribute instance-attribute

widgets: List[WidgetConf] = [WidgetConf()]

Widgets to present for this node in the dashboard.

If left empty, will try present any widget usable for this node.

widget staticmethod

widget(**kwargs) -> WidgetConf

Construct a dashboard widget configuration (see WidgetConf).

Source code in src/metador_core/widget/dashboard.py

@staticmethod
def widget(**kwargs) -> WidgetConf:
    """Construct a dashboard widget configuration (see `WidgetConf`)."""
    # for convenience
    return WidgetConf(**kwargs)

show classmethod

show(_arg: List[WidgetConf] = None, **kwargs)

Construct a dashboard configuration for the widget(s) of one container node.

For one widget, pass the widget config (if any) as keyword arguments, e.g. DashboardConf.show(group=1).

For multiple widgets, create widget configurations with widget(...), and pass them to show, e.g.: DashboardConf.show([DashboardConf.widget(), DashboardConf.widget(group=2)]).

Source code in src/metador_core/widget/dashboard.py

@classmethod
def show(cls, _arg: List[WidgetConf] = None, **kwargs):
    """Construct a dashboard configuration for the widget(s) of one container node.

    For one widget, pass the widget config (if any) as keyword arguments,
    e.g.  `DashboardConf.show(group=1)`.

    For multiple widgets, create widget configurations with `widget(...)`,
    and pass them to `show`, e.g.:
    `DashboardConf.show([DashboardConf.widget(), DashboardConf.widget(group=2)])`.
    """
    if _arg and kwargs:
        msg = "Pass widget config arguments or list of widget configs - not both!"
        raise ValueError(msg)

    if _arg is None:
        # kwargs have config for a singleton widget
        widgets = [cls.widget(**kwargs)]
    else:
        # multiple widgets, preconfigured
        widgets = list(_arg)
    return cls(widgets=widgets)

Dashboard

The dashboard presents a view of all marked nodes in a container.

To be included in the dashboard, a node must be marked by a DashboardConf object configuring at least one widget for that node.

Note that the Dashboard needs * either a widget server to be passed (embedding in a website), * or the container is wrapped by metador_core.widget.jupyter.Previewable (notebook mode)

Source code in src/metador_core/widget/dashboard.py

class Dashboard:
    """The dashboard presents a view of all marked nodes in a container.

    To be included in the dashboard, a node must be marked by a `DashboardConf`
    object configuring at least one widget for that node.


    Note that the `Dashboard` needs
    * either a widget server to be passed (embedding in a website),
    * or the container is wrapped by `metador_core.widget.jupyter.Previewable` (notebook mode)
    """

    def __init__(
        self,
        container: MetadorContainer,
        *,
        server: WidgetServer = None,
        container_id: Optional[str] = None,
    ):
        """Return instance of a dashboard.

        Args:
            container: Actual Metador container that is open and readable
            server: `WidgetServer` to use for the widgets (default: standalone server / Jupyter mode)
            container_id: Container id usable with the server to get this container (default: container UUID)
        """
        self._container: MetadorContainer = container
        self._server = server
        self._container_id: str = container_id

        # figure out what schemas to show and what widgets to use and collect
        ws: List[NodeWidgetPair] = []
        for node in self._container.metador.query(DashboardConf):
            dbmeta = node.meta.get(DashboardConf)
            restr_node = node.restrict(read_only=True, local_only=True)
            for wmeta in dbmeta.widgets:
                ws.append((restr_node, self._resolve_node(node, wmeta)))

        grps, ungrp = sorted_widgets(ws)
        self._groups = grps
        self._ungrouped = ungrp

    def _resolve_node(self, node: MetadorNode, wmeta: WidgetConf) -> WidgetConf:
        """Check and resolve widget dashboard metadata for a node."""
        wmeta = wmeta.copy()  # use copy, abandon original

        s_ref: PluginRef = _resolve_schema(node, wmeta)
        wmeta.schema_name = s_ref.name
        wmeta.schema_version = s_ref.version

        w_ref: PluginRef = _resolve_widget(
            node, s_ref, wmeta.widget_name, wmeta.widget_version
        )
        wmeta.widget_name = w_ref.name
        wmeta.widget_version = w_ref.version

        return wmeta

    def show(self) -> Viewable:
        """Instantiate widgets for container and return resulting dashboard."""
        # Outermost element: The Dashboard is a column of widget groups
        db = pn.FlexBox(
            flex_direction="column",
            justify_content="space-evenly",
            align_content="space-evenly",
            align_items="center",
            sizing_mode="scale_both",
        )

        # add each widget group within individual, flexibly-wrapping rows
        for idx, widget_group in enumerate(self._groups.values()):
            db.append(
                get_grp_row(
                    idx=idx,
                    widget_group=widget_group,
                    divider=False,  # does not work offline with panel >= 1.0?
                    server=self._server,
                    container_id=self._container_id,
                )
            )

        # dump remaining ungrouped widgets into a separate flexibly-wrapping row
        ungrp_exist = len(self._ungrouped) != 0
        if ungrp_exist:
            db.append(
                get_grp_row(
                    widget_group=self._ungrouped,
                    server=self._server,
                    container_id=self._container_id,
                )
            )
        return db

__init__

__init__(
    container: MetadorContainer,
    *,
    server: WidgetServer = None,
    container_id: Optional[str] = None
)

Return instance of a dashboard.

Parameters:

Name	Type	Description	Default
container	MetadorContainer	Actual Metador container that is open and readable	required
server	WidgetServer	WidgetServer to use for the widgets (default: standalone server / Jupyter mode)	None
container_id	Optional[str]	Container id usable with the server to get this container (default: container UUID)	None

Source code in src/metador_core/widget/dashboard.py

def __init__(
    self,
    container: MetadorContainer,
    *,
    server: WidgetServer = None,
    container_id: Optional[str] = None,
):
    """Return instance of a dashboard.

    Args:
        container: Actual Metador container that is open and readable
        server: `WidgetServer` to use for the widgets (default: standalone server / Jupyter mode)
        container_id: Container id usable with the server to get this container (default: container UUID)
    """
    self._container: MetadorContainer = container
    self._server = server
    self._container_id: str = container_id

    # figure out what schemas to show and what widgets to use and collect
    ws: List[NodeWidgetPair] = []
    for node in self._container.metador.query(DashboardConf):
        dbmeta = node.meta.get(DashboardConf)
        restr_node = node.restrict(read_only=True, local_only=True)
        for wmeta in dbmeta.widgets:
            ws.append((restr_node, self._resolve_node(node, wmeta)))

    grps, ungrp = sorted_widgets(ws)
    self._groups = grps
    self._ungrouped = ungrp

show

show() -> Viewable

Instantiate widgets for container and return resulting dashboard.

Source code in src/metador_core/widget/dashboard.py

def show(self) -> Viewable:
    """Instantiate widgets for container and return resulting dashboard."""
    # Outermost element: The Dashboard is a column of widget groups
    db = pn.FlexBox(
        flex_direction="column",
        justify_content="space-evenly",
        align_content="space-evenly",
        align_items="center",
        sizing_mode="scale_both",
    )

    # add each widget group within individual, flexibly-wrapping rows
    for idx, widget_group in enumerate(self._groups.values()):
        db.append(
            get_grp_row(
                idx=idx,
                widget_group=widget_group,
                divider=False,  # does not work offline with panel >= 1.0?
                server=self._server,
                container_id=self._container_id,
            )
        )

    # dump remaining ungrouped widgets into a separate flexibly-wrapping row
    ungrp_exist = len(self._ungrouped) != 0
    if ungrp_exist:
        db.append(
            get_grp_row(
                widget_group=self._ungrouped,
                server=self._server,
                container_id=self._container_id,
            )
        )
    return db

sorted_widgets

sorted_widgets(
    widgets: Iterable[NodeWidgetPair],
) -> Tuple[Dict[int, NodeWidgetRow], NodeWidgetRow]

Return widgets in groups, ordered by priority and node path.

Returns tuple with dict of groups and a remainder of ungrouped widgets.

Source code in src/metador_core/widget/dashboard.py

def sorted_widgets(
    widgets: Iterable[NodeWidgetPair],
) -> Tuple[Dict[int, NodeWidgetRow], NodeWidgetRow]:
    """Return widgets in groups, ordered by priority and node path.

    Returns tuple with dict of groups and a remainder of ungrouped widgets.
    """

    def nwp_group(tup: NodeWidgetPair) -> int:
        return tup[1].group or 0

    def nwp_prio(tup: NodeWidgetPair) -> int:
        return -tup[1].priority or 0  # in descending order of priority

    def sorted_group(ws: Iterable[NodeWidgetPair]) -> NodeWidgetRow:
        """Sort first on priority, and for same priority on container node."""
        return list(sorted(sorted(ws, key=lambda x: x[0].name), key=nwp_prio))

    # dict, sorted in ascending group order (but ungrouped are 0)
    ret = dict(
        sorted(
            {
                k: sorted_group(v)
                for k, v in groupby(sorted(widgets, key=nwp_group), key=nwp_group)
            }.items()
        )
    )
    ungrp = ret.pop(0, [])  # separate out the ungrouped (were mapped to 0)
    return ret, ungrp

get_grp_label

get_grp_label(idx)

Create and return a styled group label.

Source code in src/metador_core/widget/dashboard.py

def get_grp_label(idx):
    """Create and return a styled group label."""
    return pn.pane.Str(
        f"Group {idx+1}" if idx is not None else "Ungrouped resources",
        style={
            "font-size": "15px",
            "font-weight": "bold",
            "text-decoration": "underline",
        },
    )

add_widgets

add_widgets(
    w_grp,
    ui_grp,
    *,
    server=None,
    container_id: Optional[str] = None
)

Instantiate and add widget to the flexibly wrapping row that handles the entire group.

Source code in src/metador_core/widget/dashboard.py

def add_widgets(w_grp, ui_grp, *, server=None, container_id: Optional[str] = None):
    """Instantiate and add widget to the flexibly wrapping row that handles the entire group."""
    w_width, w_height = 500, 500  # max size of a widget tile, arbitrarily set
    for node, wmeta in w_grp:
        w_cls = widgets.get(wmeta.widget_name, wmeta.widget_version)
        label = pn.pane.Str(f"{node.name}:")

        # instantiating the appropriate widget
        w_obj = w_cls(
            node,
            wmeta.schema_name,
            wmeta.schema_version,
            server=server,
            container_id=container_id,
            # reset max widget of a widget tile,  only if it is for a pdf, text or video file
            max_width=700
            if "pdf" in wmeta.widget_name
            or "text" in wmeta.widget_name
            or "video" in wmeta.widget_name
            else w_width,
            # reset max height of a widget tile, only if it is for a text file
            max_height=700 if "text" in wmeta.widget_name else w_height,
        )

        # adding the new widget to the given row
        ui_grp.append(
            pn.Column(
                label,
                w_obj.show(),
                sizing_mode="scale_both",
                scroll=False
                if "image" in wmeta.widget_name or "pdf" in wmeta.widget_name
                else True,
            )
        )
    return ui_grp

get_grp_row

get_grp_row(
    *,
    idx=None,
    widget_group=None,
    divider=False,
    server=None,
    container_id: Optional[str] = None
)

Create a flexible and wrapping row for all widgets within a single group.

Source code in src/metador_core/widget/dashboard.py

def get_grp_row(
    *,
    idx=None,
    widget_group=None,
    divider=False,
    server=None,
    container_id: Optional[str] = None,
):
    """Create a flexible and wrapping row for all widgets within a single group."""
    return pn.FlexBox(
        get_grp_label(idx=idx),
        add_widgets(
            widget_group,
            pn.FlexBox(
                flex_direction="row",
                justify_content="space-evenly",
                align_content="space-evenly",
                align_items="center",
                sizing_mode="scale_both",
            ),
            server=server,
            container_id=container_id,
        ),
        pn.layout.Divider(margin=(100, 0, 20, 0)) if divider else None,
        flex_direction="column",
        justify_content="space-evenly",
        align_content="space-evenly",
        align_items="center",
        sizing_mode="scale_both",
    )