Skip to content

Home Information - Your home, your data, organized.

Python
8.0 KB
Raw Blame
import logging
from dataclasses import dataclass, field
from typing import Any, Dict, List, Set

from hi.apps.entity.enums import DisplayContext, EntityStateRole, EntityType
from hi.apps.entity.state_panel_base import EntityStatePanel
from hi.apps.entity.state_panel_registry import EntityStatePanelRegistry
from hi.apps.monitor.display_data import EntityDisplayData, EntityStateDisplayData


logger = logging.getLogger( __name__ )


@dataclass
class PanelResolution:
    panel  : EntityStatePanel
    extras : Set[ EntityStateRole ] = field( default_factory = set )
    trace  : List[ str ]            = field( default_factory = list )


@dataclass
class EntityStatePanelData:
    """An entity prepared for rendering through the panel framework in a
    specific display context. Produced by
    ``StatePanelDispatcher.build_state_panel_data``; consumed identically
    by both the entity status modal and the collection card wrappers.

    ``panel_context`` carries the panel-template variables (filtered to
    declared roles for typed panels, unfiltered for fallback panels).
    ``extras_state_data_list`` is the framework-managed projection of
    roles outside the panel's declared set; the modal extras section
    renders it."""

    entity_display_data    : EntityDisplayData
    panel_template         : str
    panel_context          : Dict[ str, Any ]
    extras_state_data_list : List[ EntityStateDisplayData ] = field( default_factory = list )
    trace                  : List[ str ]                    = field( default_factory = list )

    # Forwarded for template ergonomics — templates read
    # ``state_panel_data.entity`` etc. without descending through
    # ``entity_display_data``.
    @property
    def entity(self):
        return self.entity_display_data.entity

    @property
    def display_category(self):
        return self.entity_display_data.display_category

    @property
    def display_only_svg_icon_item(self):
        return self.entity_display_data.display_only_svg_icon_item

    @property
    def entity_for_video(self):
        return self.entity_display_data.entity_for_video


class StatePanelDispatcher:

    @classmethod
    def build_state_panel_data(
            cls,
            entity_display_data : EntityDisplayData,
            display_context     : DisplayContext,
            debug               : bool = False,
    ) -> EntityStatePanelData:
        resolution = cls.resolve_panel_for(
            entity_display_data, display_context, debug = debug,
        )
        panel = resolution.panel

        if panel.entity_type is None:
            # Fallback panels see every state; nothing is "extras."
            state_list = entity_display_data.state_status_data_list
            by_role = entity_display_data.state_status_data_by_role
            extras_list : List[ EntityStateDisplayData ] = []
        else:
            declared = panel.required_roles | panel.optional_roles
            state_list, by_role = entity_display_data.filter_to_roles( declared )
            extras_list = [
                d for d in entity_display_data.state_status_data_list
                if d.entity_state.entity_state_role in resolution.extras
            ]

        panel_context : Dict[ str, Any ] = {
            'entity'                     : entity_display_data.entity,
            'entity_status_data'         : entity_display_data,
            'state_status_data_list'     : state_list,
            'state_status_data_by_role'  : by_role,
            'entity_for_video'           : entity_display_data.entity_for_video,
            'display_only_svg_icon_item' : entity_display_data.display_only_svg_icon_item,
            'display_category'           : entity_display_data.display_category,
        }
        # Resolve the panel's declared role-data template aliases against
        # the (filtered) by-role map. Absent optional roles resolve to
        # ``None`` so templates can ``{% if alias %}``-guard them.
        for alias, role in panel.role_data_template_aliases.items():
            panel_context[ alias ] = by_role.get( role.name.lower() )
        return EntityStatePanelData(
            entity_display_data    = entity_display_data,
            panel_template         = panel.template_name,
            panel_context          = panel_context,
            extras_state_data_list = extras_list,
            trace                  = resolution.trace,
        )

    @classmethod
    def resolve_panel_for(
            cls,
            entity_display_data : EntityDisplayData,
            display_context     : DisplayContext,
            debug               : bool = False,
    ) -> PanelResolution:
        return cls.resolve_panel(
            entity_type     = entity_display_data.entity.entity_type,
            display_context = display_context,
            present_roles   = entity_display_data.present_roles,
            debug           = debug,
        )

    @classmethod
    def resolve_panel(
            cls,
            entity_type     : EntityType,
            display_context : DisplayContext,
            present_roles   : Set[ EntityStateRole ],
            debug           : bool = False,
    ) -> PanelResolution:
        """Choose the panel for ``(entity_type, display_context, present_roles)``.
        Type-specific panels win over fallback panels; among either group,
        lower ``priority`` wins, with ``name`` as the alphabetical tiebreaker.
        Raises ``RuntimeError`` if no fallback panel covers the context.

        The trace is only built when ``debug`` is True or DEBUG-level
        logging is enabled — the production hot path (one dispatch per
        collection card) skips the trace string formatting entirely."""

        want_trace = debug or logger.isEnabledFor( logging.DEBUG )
        all_panels = EntityStatePanelRegistry().all_panels()
        trace : List[ str ] = []
        if want_trace:
            trace.append(
                f'entity_type={entity_type.name} '
                f'display_context={display_context.name} '
                f'present_roles=[{",".join(sorted(r.name for r in present_roles))}]'
            )

        typed = sorted(
            (
                p for p in all_panels
                if p.entity_type == entity_type
                and display_context in p.display_contexts
                and p.required_roles.issubset( present_roles )
            ),
            key = lambda p: ( p.priority, p.name ),
        )
        if typed:
            chosen = typed[ 0 ]
            if want_trace:
                trace.append(
                    'typed candidates: '
                    + ', '.join( f'{p.name}#{p.priority}' for p in typed )
                    + f' -> {chosen.name}'
                )
            return cls._build_resolution( chosen, present_roles, trace, want_trace )

        fallbacks = sorted(
            (
                p for p in all_panels
                if p.entity_type is None
                and display_context in p.display_contexts
            ),
            key = lambda p: ( p.priority, p.name ),
        )
        if not fallbacks:
            if want_trace:
                trace.append( f'no fallback registered for {display_context.name}' )
            raise RuntimeError(
                f'No fallback panel registered for display_context={display_context.name}'
            )
        chosen = fallbacks[ 0 ]
        if want_trace:
            trace.append(
                'fallback candidates: '
                + ', '.join( f'{p.name}#{p.priority}' for p in fallbacks )
                + f' -> {chosen.name}'
            )
        return cls._build_resolution( chosen, present_roles, trace, want_trace )

    @classmethod
    def _build_resolution( cls, panel, present_roles, trace, want_trace ):
        extras = present_roles - ( panel.required_roles | panel.optional_roles )
        if want_trace and extras:
            trace.append( 'extras: ' + ','.join( sorted( r.name for r in extras ) ) )
        resolution = PanelResolution( panel = panel, extras = extras, trace = trace )
        if want_trace and trace:
            logger.debug( 'Panel resolution:\n  ' + '\n  '.join( trace ) )
        return resolution