Skip to content

Home Information - Your home, your data, organized.

Python
8.4 KB
Raw Blame
from typing import Dict, List

from hi.apps.common.singleton import Singleton

from .base_models import SimEntityDefinition, SimEntityFields, SimState
from .enums import ServiceFaultMode
from .sim_entity import SimEntity


class ServiceSimulator( Singleton ):
    """
    Defining a ServiceSimulator

    - Each simulator should subclass this in a file named "simulator.py" in
      its app directory.

    - The simulator's app directory should be located in the "simulator/services"
      subdirectory.

    - The ServiceSimulatorManager will auto-discovery all simulators with a
      simulator.py file in that services directopry.

    - The simulator should also define a urls.py and views.py file with the
      needed API endpoints.

    - The urls.py will also be auto-discovered by logic in the
      simulator/urls.py file

    Responsibilities

    - A simulator must provide a list of SimEntityDefinition instances via
      overriding the sim_entity_definition_list() method.  This tells the
      simulator the available types of simulator entities that are
      available to be defined, what extra custrom fields it needs and the
      list of SimState types the entity contains.

    - SimState instances is what the simulator UI shows as manually
      adjustable.  The API views of the simulator should convert those
      entities and current state values into the proper API responses.

    - The ServiceSimulatorManager is responsible for creating SimEntity instances
      and for updating the values of then SimState instances.

    - SimEntity definitions are persisted in the database with DbSimEntity,
      but ther SimState definitions and values are not persisted. e.g., A
      simulator server restart will lose any current SimState values.

    - The ServiceSimulatorManager also supports defining and switching between
      different simulation profiles, each with its own set of SimEntity
      definitions.  The individual simulator subclasses do not need to be
      aware of this as the ServiceSimulatorManager creates a new simulator
      subclass instance for each profile.

    """
    
    def __init_singleton__( self ):
        # Set BEFORE initialize() so that a SimProfile switch — which
        # re-invokes initialize() to reload entity instances — does NOT
        # reset the operator-selected fault mode.
        self._fault_mode = ServiceFaultMode.default()
        self.initialize()
        return

    @property
    def id(self) -> str:
        """ A unique identifier for referencing this simulator implementation. """
        raise NotImplementedError('Subclasses must override this method.')

    @property
    def url_path_segment(self) -> str:
        """
        The URL segment under which this simulator's routes are mounted by
        src/hi/simulator/services/urls.py:discover_service_urls() — derived
        from the services-app directory name (e.g., 'homebox' for the
        simulator at hi.simulator.services.homebox.simulator). Note this
        can differ from `id` (e.g., id='hb' but url_path_segment='homebox').
        """
        return self.__class__.__module__.split('.')[-2]

    @property
    def module_key(self) -> str:
        """The simulator's pluggable module key — its Django AppConfig
        name (e.g. ``hi.simulator.services.hass``). Used as the
        ``SimProfile.module_key`` foreign reference so each service
        simulator has its own independent profile space."""
        return '.'.join( self.__class__.__module__.split('.')[:-1] )

    @property
    def integration_urls(self) -> List[ tuple ]:
        """
        URL path(s) operators paste into the main app's integration
        settings to point at this simulator. Each entry is a tuple of
        (label, path) where ``path`` is appended to ``<scheme>://<host>/``.
        Default empty; subclasses opt in by overriding.
        """
        return []

    @property
    def fault_mode(self) -> ServiceFaultMode:
        return self._fault_mode

    def set_fault_mode( self, fault_mode : ServiceFaultMode ):
        self._fault_mode = fault_mode
        return

    @property
    def extras_template_name(self) -> str:
        """Optional template path included in the simulator's
        service-page toolbar for simulator-specific controls
        (e.g., HomeBox's API-version toggle). Return None to skip
        the include; the default is no extras."""
        return None

    @property
    def extras_context(self) -> Dict:
        """Extra context the ``extras_template_name`` template
        needs beyond the standard service-page variables. Default
        empty; override when the extras pane has dynamic choices
        or other simulator-specific data to expose. Implementations
        should avoid keys that collide with the standard service-
        page context (``simulator``, ``profile_list``, etc.) since
        the caller merges this dict via ``dict.update``."""
        return {}

    @property
    def label(self) -> str:
        """ A human-friendly label for this simulatior. """
        raise NotImplementedError('Subclasses must override this method.')

    def sim_entity_definition_list(self) -> List[ SimEntityDefinition ]:
        """
        A return a list of SimEntity subclasses that define the different types
        of entities that can be define for the simulator.
        """
        raise NotImplementedError('Subclasses must override this method.')        

    @property
    def sim_entities(self) -> List[ SimEntity ]:
        sim_entity_list = [ x for x in self._sim_entity_map.values() ]
        sim_entity_list.sort( key = lambda item : item.name )
        return sim_entity_list

    def get_sim_entity_by_id( self, sim_entity_id : int ) -> SimEntity:
        if sim_entity_id not in self._sim_entity_map:
            raise KeyError( f'No simulator ewntity found with id = {sim_entity_id}' )
        return self._sim_entity_map.get( sim_entity_id )
        
    def initialize( self ):
        """
        The ServiceSimulatorManager stores, hydrates and defines the set of existing
        SimEntity instances a simulator will use.  This initialization will
        occur at start up and if/when the simulation profile changes
        (requiring a new list of SimEntity instances).
        """
        self._sim_entity_map : Dict[ id, SimEntity ] = dict()
        return

    def post_load_hook( self ):
        """Called once by the ServiceSimulatorManager after a profile
        load has finished hydrating ``self._sim_entity_map`` from the
        database. Subclasses override this to ensure required default
        entities exist for the freshly-loaded profile — e.g. a
        singleton "server" entity that should be present in every
        profile. Default is a no-op.

        Implementations may call back into the manager (e.g. via
        ``add_sim_entity``) and so must NOT be called while the
        manager's data lock is held.
        """
        return
    
    def validate_new_sim_entity_fields( self, new_sim_entity_fields : SimEntityFields ):
        """
        Subclasses should override this if there are additional validation
        checks needed before adding a SimEntity. This is called
        before persisting the data so can raise SimEntityValidationError if
        there are any validation issue.
        """
        return
        
    def validate_updated_sim_entity( self, updated_sim_entity : SimEntity ):
        """
        Subclasses should override this if there are additional validation
        checks needed before updating a SimEntity. This is called
        before persisting the data so can raise SimEntityValidationError if
        there are any validation issue.
        """
        return
        
    def add_sim_entity( self, sim_entity : SimEntity ):
        previous_sim_entity = self._sim_entity_map.get( sim_entity.id )
        if previous_sim_entity:
            sim_entity.copy_state_values( previous_sim_entity )
        self._sim_entity_map[sim_entity.id] = sim_entity
        return

    def remove_sim_entity_by_id( self, sim_entity_id : int ):
        del self._sim_entity_map[sim_entity_id]
        return

    def set_sim_state( self,
                       sim_entity_id  : int,
                       sim_state_id   : str,
                       value_str      : str ) -> SimState:
        sim_entity = self.get_sim_entity_by_id( sim_entity_id = sim_entity_id )
        return sim_entity.set_sim_state(
            sim_state_id = sim_state_id,
            value_str = value_str,
        )