Home Information - Your home, your data, organized.
Python
"""
Event-system models.
Lifecycle note (Issue #288): EventDefinition is integration-attached
(inherits IntegrationDetailsModel). Integration-owned rows
(``integration_id IS NOT NULL``) are cleaned up at the integration
disconnect / sync-removal boundary by
``hi.integrations.event_definition_operations.EventDefinitionOperations``,
not by a generalized "EntityState delete cascades to parent" rule.
User-owned rows are not touched by integration cleanup; the existing
``on_delete=CASCADE`` on ``EventClause.entity_state`` and
``ControlAction.controller`` continues to apply, which can leave a
user-owned EventDefinition silently semantically changed (clauseless,
or with reduced clauses) — that broader UX is deferred to a separate
redesign.
"""
from django.db import models
from hi.apps.alert.enums import AlarmLevel
from hi.apps.control.models import Controller
from hi.apps.entity.models import EntityState
from hi.apps.security.enums import SecurityLevel
from hi.integrations.models import IntegrationDetailsModel
from .enums import EventClauseOperator, EventType
class EventDefinition( IntegrationDetailsModel ):
name = models.CharField(
'Name',
max_length = 64,
)
event_type_str = models.CharField(
'Match Type',
max_length = 32,
null = False, blank = False,
)
# For multi-clause event definitions, the span in which all clauses
# need to satisfied.
#
event_window_secs = models.PositiveIntegerField(
'Match Window Secs',
)
# Rate limits how many events will be generated for this
# EventDefinition by ensuring at least this time elapsed before a new
# event would be generated.
#
dedupe_window_secs = models.PositiveIntegerField(
'Dedupe Window Secs',
)
enabled = models.BooleanField(
default = True,
)
created_datetime = models.DateTimeField(
'Created',
auto_now_add = True,
blank = True,
)
updated_datetime = models.DateTimeField(
'Updated',
auto_now = True,
blank = True,
)
class Meta:
verbose_name = 'Rule'
verbose_name_plural = 'Rules'
@property
def event_type(self):
return EventType.from_name_safe( self.event_type_str )
@event_type.setter
def event_type( self, event_type : EventType ):
self.event_type_str = str(event_type)
return
class EventClause( models.Model ):
event_definition = models.ForeignKey(
EventDefinition,
related_name = 'event_clauses',
verbose_name = 'Rule',
on_delete = models.CASCADE,
)
entity_state = models.ForeignKey(
EntityState,
related_name = '+',
verbose_name = 'Item State',
on_delete = models.CASCADE,
)
value = models.CharField(
'Value',
max_length = 255
)
# How ``value`` is compared against the live wire reading.
# Default ``'EQ'`` keeps every pre-threshold clause matching by
# exact string equality (the historical behavior). Numeric
# operators (LT / LTE / GT / GTE) enable threshold-based alarms
# on continuous EntityStateTypes such as BATTERY_LEVEL.
value_operator_str = models.CharField(
'Operator',
max_length = 8,
default = str(EventClauseOperator.default()),
null = False, blank = False,
)
created_datetime = models.DateTimeField(
'Created',
auto_now_add = True,
blank = True,
)
updated_datetime = models.DateTimeField(
'Updated',
auto_now = True,
blank = True,
)
class Meta:
verbose_name = 'Rule Condition'
verbose_name_plural = 'Rule Conditions'
IN_VALUE_DELIMITER = ','
@property
def value_operator(self) -> EventClauseOperator:
return EventClauseOperator.from_name_safe( self.value_operator_str )
@value_operator.setter
def value_operator( self, value_operator : EventClauseOperator ):
self.value_operator_str = str(value_operator)
return
def in_value_members(self) -> set:
"""Members of the comma-delimited ``value`` used by the IN
operator. Returns an empty set when ``value`` is empty or
only contains delimiters / whitespace."""
return {
m.strip() for m in ( self.value or '' ).split(
self.IN_VALUE_DELIMITER,
)
if m.strip()
}
@classmethod
def serialize_in_members(cls, values) -> str:
"""Inverse of :meth:`in_value_members` — joins an iterable of
member strings into the comma-delimited storage shape.
Whitespace-tolerant, deduplicated, sorted for determinism."""
return cls.IN_VALUE_DELIMITER.join( sorted({
v.strip() for v in ( values or [] ) if v and v.strip()
}))
class AlarmAction( models.Model ):
event_definition = models.ForeignKey(
EventDefinition,
related_name = 'alarm_actions',
verbose_name = 'Rule',
on_delete = models.CASCADE,
)
security_level_str = models.CharField(
'Security Level',
max_length = 32,
null = False, blank = False,
)
alarm_level_str = models.CharField(
'Alarm Level',
max_length = 32,
null = False, blank = False,
)
alarm_lifetime_secs = models.PositiveIntegerField(
'Lifetime Secs',
)
created_datetime = models.DateTimeField(
'Created',
auto_now_add = True,
blank = True,
)
updated_datetime = models.DateTimeField(
'Updated',
auto_now = True,
blank = True,
)
class Meta:
verbose_name = 'Alarm Actions'
verbose_name_plural = 'Alarm Actions'
@property
def security_level(self):
return SecurityLevel.from_name_safe( self.security_level_str )
@security_level.setter
def security_level( self, security_level : SecurityLevel ):
self.security_level_str = str(security_level)
return
@property
def alarm_level(self):
return AlarmLevel.from_name_safe( self.alarm_level_str )
@alarm_level.setter
def alarm_level( self, alarm_level : AlarmLevel ):
self.alarm_level_str = str(alarm_level)
return
class ControlAction( models.Model ):
event_definition = models.ForeignKey(
EventDefinition,
related_name = 'control_actions',
verbose_name = 'Rule',
on_delete = models.CASCADE,
)
controller = models.ForeignKey(
Controller,
related_name = 'control_actions',
verbose_name = 'Controller',
on_delete = models.CASCADE,
)
value = models.CharField(
'Value',
max_length = 255
)
created_datetime = models.DateTimeField(
'Created',
auto_now_add = True,
blank = True,
)
updated_datetime = models.DateTimeField(
'Updated',
auto_now = True,
blank = True,
)
class Meta:
verbose_name = 'Control Action'
verbose_name_plural = 'Control Actions'
class EventHistory( models.Model ):
event_definition = models.ForeignKey(
EventDefinition,
related_name = 'history',
verbose_name = 'Rule',
on_delete = models.CASCADE,
)
event_datetime = models.DateTimeField(
'Timestamp',
db_index = True,
)
class Meta:
verbose_name = 'Rule Match'
verbose_name_plural = 'Rule Matches'
ordering = [ '-event_datetime' ]