conson-xp 1.1.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

xp/models/protocol/conbus_protocol.py

@@ -1,3 +1,5 @@
+"""Conbus protocol event models."""
+
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Union
@@ -15,7 +17,11 @@ if TYPE_CHECKING:
 
 
 class ConnectionMadeEvent(BaseEvent):
-    """Event dispatched when TCP connection is established"""
+    """Event dispatched when TCP connection is established.
+
+    Attributes:
+        protocol: Reference to the TelegramProtocol instance.
+    """
 
     protocol: TelegramProtocol = Field(
         description="Reference to the TelegramProtocol instance"
@@ -23,12 +29,25 @@ class ConnectionMadeEvent(BaseEvent):
 
 
 class ConnectionFailedEvent(BaseEvent):
-    """Event dispatched when TCP connection fails"""
+    """Event dispatched when TCP connection fails.
+
+    Attributes:
+        reason: Failure reason.
+    """
 
     reason: str = Field(description="Failure reason")
 
 
 class SendWriteConfigEvent(BaseEvent):
+    """Event for sending write config commands.
+
+    Attributes:
+        serial_number: Serial number.
+        output_number: Output number.
+        datapoint_type: Datapoint type.
+        value: Set brightness value.
+    """
+
     serial_number: str = Field(description="Serial number")
     output_number: int = Field(description="Output number")
     datapoint_type: DataPointType = Field(description="Datapoint type")
@@ -36,25 +55,58 @@ class SendWriteConfigEvent(BaseEvent):
 
 
 class SendActionEvent(BaseEvent):
+    """Event for sending action commands.
+
+    Attributes:
+        serial_number: Serial number of the light bulb set.
+        output_number: Output number of the light bulb set.
+        value: Set light bulb On or Off (True/False).
+    """
+
     serial_number: str = Field(description="Serial number of the light bulb set")
     output_number: int = Field(description="Output number of the light bulb set")
     value: bool = Field(description="Set light bulb On or Off (True/False)")
 
 
 class DatapointEvent(BaseEvent):
+    """Base event for datapoint operations.
+
+    Attributes:
+        serial_number: Serial number of the light bulb set.
+        datapoint_type: Datapoint type.
+    """
+
     serial_number: str = Field(description="Serial number of the light bulb set")
     datapoint_type: DataPointType = Field(description="Datapoint type")
 
 
 class OutputStateReceivedEvent(DatapointEvent):
+    """Event when output state is received.
+
+    Attributes:
+        data_value: Data value.
+    """
+
     data_value: str = Field(description="Data value")
 
 
 class LightLevelReceivedEvent(DatapointEvent):
+    """Event when light level is received.
+
+    Attributes:
+        data_value: Data value.
+    """
+
     data_value: str = Field(description="Data value")
 
 
 class ReadDatapointEvent(DatapointEvent):
+    """Event to read datapoint.
+
+    Attributes:
+        refresh_cache: If True, force cache invalidation and fresh protocol query.
+    """
+
     refresh_cache: bool = Field(
         default=False,
         description="If True, force cache invalidation and fresh protocol query",
@@ -62,13 +114,20 @@ class ReadDatapointEvent(DatapointEvent):
 
 
 class ReadDatapointFromProtocolEvent(DatapointEvent):
-    """Internal event for cache service to forward to protocol when cache misses"""
+    """Internal event for cache service to forward to protocol when cache misses."""
 
     pass
 
 
 class ModuleEvent(BaseEvent):
-    """Event dispatched when light bulb set is on"""
+    """Event dispatched when light bulb set is on.
+
+    Attributes:
+        serial_number: Serial number of the light bulb set.
+        output_number: Output number of the light bulb set.
+        module: ConsonModuleConfig of the light bulb set.
+        accessory: HomekitAccessoryConfig of the light bulb set.
+    """
 
     serial_number: str = Field(description="Serial number of the light bulb set")
     output_number: int = Field(description="Output number of the light bulb set")
@@ -81,73 +140,111 @@ class ModuleEvent(BaseEvent):
 
 
 class LightBulbSetOnEvent(ModuleEvent):
-    """Event dispatched when light bulb set is on"""
+    """Event dispatched when light bulb set is on.
+
+    Attributes:
+        value: On or Off the light bulb set.
+    """
 
     value: bool = Field(description="On or Off the light bulb set")
 
 
 class LightBulbGetOnEvent(ModuleEvent, BaseEvent[bool]):
-    """Event dispatched when light bulb set is on"""
+    """Event dispatched when getting light bulb on state."""
 
     pass
 
 
 class OutletSetOnEvent(ModuleEvent):
-    """Event dispatched when outlet set is on"""
+    """Event dispatched when outlet set is on.
+
+    Attributes:
+        value: On or Off the light bulb set.
+    """
 
     value: bool = Field(description="On or Off the light bulb set")
 
 
 class OutletGetOnEvent(ModuleEvent):
-    """Event dispatched when outlet set is on"""
+    """Event dispatched when getting outlet on state."""
 
     pass
 
 
 class OutletGetInUseEvent(ModuleEvent):
-    """Event dispatched when outlet set is on"""
+    """Event dispatched when getting outlet in-use state."""
 
     pass
 
 
 class OutletSetInUseEvent(ModuleEvent, BaseEvent[bool]):
-    """Event dispatched when outlet set is on"""
+    """Event dispatched when outlet set is on.
+
+    Attributes:
+        value: On or Off the light bulb set.
+    """
 
     value: bool = Field(description="On or Off the light bulb set")
 
 
 class DimmingLightSetOnEvent(ModuleEvent):
-    """Event dispatched when dimming light set is on"""
+    """Event dispatched when dimming light set is on.
+
+    Attributes:
+        value: On or Off the light bulb set.
+        brightness: Brightness of the light bulb set.
+    """
 
     value: bool = Field(description="On or Off the light bulb set")
     brightness: int = Field(description="Brightness of the light bulb set")
 
 
 class DimmingLightGetOnEvent(ModuleEvent):
-    """Event dispatched when dimming light set is on"""
+    """Event dispatched when getting dimming light on state."""
 
     pass
 
 
 class DimmingLightSetBrightnessEvent(ModuleEvent):
-    """Event dispatched when dimming light set is on"""
+    """Event dispatched when dimming light set is on.
+
+    Attributes:
+        brightness: Level of brightness of the dimming light.
+    """
 
     brightness: int = Field(description="Level of brightness of the dimming light")
 
 
 class DimmingLightGetBrightnessEvent(ModuleEvent):
-    """Event dispatched when dimming light set is on"""
+    """Event dispatched when getting dimming light brightness."""
 
     pass
 
 
 class ConnectionLostEvent(BaseEvent):
-    """Event dispatched when TCP connection is lost"""
+    """Event dispatched when TCP connection is lost.
+
+    Attributes:
+        reason: Disconnection reason.
+    """
 
     reason: str = Field(description="Disconnection reason")
 
 
 class TelegramEvent(BaseEvent):
+    """Event for telegram operations.
+
+    Attributes:
+        protocol: TelegramProtocol instance.
+        frame: Frame <S0123450001F02D12FK>.
+        telegram: Telegram S0123450001F02D12FK.
+        payload: Payload S0123450001F02D12.
+        telegram_type: Telegram type S.
+        serial_number: Serial number 0123450001 or empty.
+        checksum: Checksum FK.
+        checksum_valid: Checksum valid true or false.
+    """
+
     protocol: Union[TelegramProtocol, ConbusProtocol] = Field(
         description="TelegramProtocol instance"
     )
@@ -163,7 +260,14 @@ class TelegramEvent(BaseEvent):
 
 
 class ModuleStateChangedEvent(BaseEvent):
-    """Event dispatched when a module's state changes (from event telegram)"""
+    """Event dispatched when a module's state changes (from event telegram).
+
+    Attributes:
+        module_type_code: Module type code from event telegram.
+        link_number: Link number from event telegram.
+        input_number: Input number that triggered the event.
+        telegram_event_type: Event type (M=press, B=release).
+    """
 
     module_type_code: int = Field(description="Module type code from event telegram")
     link_number: int = Field(description="Link number from event telegram")
@@ -172,27 +276,32 @@ class ModuleStateChangedEvent(BaseEvent):
 
 
 class EventTelegramReceivedEvent(TelegramEvent):
-    """Event telegram received"""
+    """Event telegram received."""
 
     pass
 
 
 class ModuleDiscoveredEvent(TelegramEvent):
-    """Event dispatched when module is discovered"""
+    """Event dispatched when module is discovered."""
 
     pass
 
 
 class TelegramReceivedEvent(TelegramEvent):
-    """Event dispatched when a telegram frame is received"""
+    """Event dispatched when a telegram frame is received."""
 
     pass
 
 
 class InvalidTelegramReceivedEvent(BaseEvent):
-    """Event dispatched when an invalid telegram frame is received"""
+    """Event dispatched when an invalid telegram frame is received.
+
+    Attributes:
+        protocol: TelegramProtocol instance.
+        frame: Frame <S0123450001F02D12FK>.
+        error: Error with the received telegram.
+    """
 
     protocol: TelegramProtocol = Field(description="TelegramProtocol instance")
     frame: str = Field(description="Frame <S0123450001F02D12FK>")
     error: str = Field(description="Error with the received telegram")
-    pass

xp/models/telegram/__init__.py

@@ -0,0 +1 @@
+"""Telegram models for console bus communication."""

xp/models/telegram/action_type.py

@@ -1,16 +1,30 @@
+"""Action type enumeration for XP24 telegrams."""
+
 from enum import Enum
 from typing import Optional
 
 
 class ActionType(Enum):
-    """Action types for XP24 telegrams"""
+    """Action types for XP24 telegrams.
+
+    Attributes:
+        OFF_PRESS: Make action (activate relay).
+        ON_RELEASE: Break action (deactivate relay).
+    """
 
     OFF_PRESS = "AA"  # Make action (activate relay)
     ON_RELEASE = "AB"  # Break action (deactivate relay)
 
     @classmethod
     def from_code(cls, code: str) -> Optional["ActionType"]:
-        """Get ActionType from code string"""
+        """Get ActionType from code string.
+
+        Args:
+            code: Action code string.
+
+        Returns:
+            ActionType instance if found, None otherwise.
+        """
         for action in cls:
             if action.value == code:
                 return action

xp/models/telegram/datapoint_type.py

@@ -1,9 +1,36 @@
+"""Datapoint type enumeration for system telegrams."""
+
 from enum import Enum
 from typing import Optional
 
 
 class DataPointType(str, Enum):
-    """Data point types for system telegrams"""
+    """Data point types for system telegrams.
+
+    Attributes:
+        MODULE_TYPE: Module type (XP24, XP33, etc).
+        HW_VERSION: Hardware version information.
+        SW_VERSION: Software version information.
+        SERIAL_NUMBER: Serial number.
+        LINK_NUMBER: Link number.
+        MODULE_NUMBER: Module number.
+        SYSTEM_TYPE: System type.
+        MODULE_TYPE_CODE: Module type code.
+        MODULE_TYPE_ID: Module type ID.
+        MODULE_STATE: Module state.
+        MODULE_ERROR_CODE: Status query data point.
+        MODULE_INPUT_STATE: Module input state.
+        MODULE_OUTPUT_STATE: Channel states (XP33).
+        MODULE_FW_CRC: Module firmware CRC.
+        MODULE_ACTION_TABLE_CRC: Module action table CRC.
+        MODULE_LIGHT_LEVEL: Module light level.
+        MODULE_OPERATING_HOURS: Module operating hours.
+        MODULE_ENERGY_LEVEL: Current data point.
+        TEMPERATURE: Temperature data point.
+        SW_TOP_VERSION: Software top version.
+        VOLTAGE: Voltage data point.
+        AUTO_REPORT_STATUS: Auto report status.
+    """
 
     MODULE_TYPE = "00"  # Module type (XP24, XP33, ..)
     HW_VERSION = "01"  # Hardware version information
@@ -41,7 +68,14 @@ class DataPointType(str, Enum):
 
     @classmethod
     def from_code(cls, code: str) -> Optional["DataPointType"]:
-        """Get DataPointType from code string"""
+        """Get DataPointType from code string.
+
+        Args:
+            code: Datapoint type code string.
+
+        Returns:
+            DataPointType instance if found, None otherwise.
+        """
         for dp_type in cls:
             if dp_type.value == code:
                 return dp_type

xp/models/telegram/event_telegram.py

@@ -1,3 +1,5 @@
+"""Event telegram model for console bus communication."""
+
 from dataclasses import dataclass
 from datetime import datetime
 from typing import Any, Optional
@@ -11,14 +13,23 @@ from xp.models.telegram.telegram_type import TelegramType
 
 @dataclass
 class EventTelegram(Telegram):
-    """
-    Represents a parsed event telegram from the console bus.
+    r"""Represent a parsed event telegram from the console bus.
 
     Format: <[EO]{module_type}L{link_number}I{input_number}{event_type}{checksum}>
-    Examples:
 
-        \b
+    Examples:
         <E14L00I02MAK>
+
+    Attributes:
+        event_telegram_type: Event telegram type (E or O).
+        module_type: Module type code.
+        link_number: Link number.
+        input_number: Input number.
+        event_type: Type of event (press or release).
+        module_info: Module type information if found.
+        input_type: Input type based on input number.
+        is_button_press: True if this is a button press event.
+        is_button_release: True if this is a button release event.
     """
 
     event_telegram_type: str = "E"  # E or O
@@ -28,18 +39,27 @@ class EventTelegram(Telegram):
     event_type: Optional[EventType] = None
 
     def __post_init__(self) -> None:
+        """Initialize timestamp and telegram type."""
         if self.timestamp is None:
             self.timestamp = datetime.now()
         self.telegram_type = TelegramType.EVENT
 
     @property
     def module_info(self) -> Optional[ModuleType]:
-        """Get module type information for this telegram"""
+        """Get module type information for this telegram.
+
+        Returns:
+            ModuleType instance if found, None otherwise.
+        """
         return ModuleType.from_code(self.module_type)
 
     @property
     def input_type(self) -> InputType:
-        """Determines the input type based on input number"""
+        """Determines the input type based on input number.
+
+        Returns:
+            InputType enum value.
+        """
         if 0 <= self.input_number <= 9:
             return InputType.PUSH_BUTTON
         elif 10 <= self.input_number <= 89:
@@ -51,16 +71,28 @@ class EventTelegram(Telegram):
 
     @property
     def is_button_press(self) -> bool:
-        """True if this is a button press event"""
+        """True if this is a button press event.
+
+        Returns:
+            True if event is a button press, False otherwise.
+        """
         return self.event_type == EventType.BUTTON_PRESS
 
     @property
     def is_button_release(self) -> bool:
-        """True if this is a button release event"""
+        """True if this is a button release event.
+
+        Returns:
+            True if event is a button release, False otherwise.
+        """
         return self.event_type == EventType.BUTTON_RELEASE
 
     def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for JSON serialization"""
+        """Convert to dictionary for JSON serialization.
+
+        Returns:
+            Dictionary representation of the event telegram.
+        """
         result: dict[str, Any] = {
             "module_type": self.module_type,
             "link_number": self.link_number,
@@ -90,7 +122,11 @@ class EventTelegram(Telegram):
         return result
 
     def __str__(self) -> str:
-        """Human-readable string representation"""
+        """Human-readable string representation.
+
+        Returns:
+            Formatted string representation.
+        """
         event_desc = "pressed" if self.is_button_press else "released"
 
         # Include module name if available

xp/models/telegram/event_type.py

@@ -1,8 +1,15 @@
+"""Event type enumeration for telegram events."""
+
 from enum import Enum
 
 
 class EventType(Enum):
-    """Event types for telegraph events"""
+    """Event types for telegraph events.
+
+    Attributes:
+        BUTTON_PRESS: Button make (press) event.
+        BUTTON_RELEASE: Button break (release) event.
+    """
 
     BUTTON_PRESS = "M"  # Make
     BUTTON_RELEASE = "B"  # Break

xp/models/telegram/input_action_type.py

@@ -1,10 +1,42 @@
-"""Input action types for XP24 module based on Feature-Action-Table.md"""
+"""Input action types for XP24 module based on Feature-Action-Table.md."""
 
 from enum import IntEnum
 
 
 class InputActionType(IntEnum):
-    """Input action types for XP24 module (based on Feature-Action-Table.md)"""
+    """Input action types for XP24 module (based on Feature-Action-Table.md).
+
+    Attributes:
+        VOID: No action.
+        TURNON: Turn on action.
+        TURNOFF: Turn off action.
+        TOGGLE: Toggle action.
+        BLOCK: Block action.
+        AUXRELAY: Auxiliary relay action.
+        MUTUALEX: Mutual exclusion action.
+        LEVELUP: Level up action.
+        LEVELDOWN: Level down action.
+        LEVELINC: Level increment action.
+        LEVELDEC: Level decrement action.
+        LEVELSET: Level set action.
+        FADETIME: Fade time action.
+        SCENESET: Scene set action.
+        SCENENEXT: Scene next action.
+        SCENEPREV: Scene previous action.
+        CTRLMETHOD: Control method action.
+        RETURNDATA: Return data action.
+        DELAYEDON: Delayed on action.
+        EVENTTIMER1: Event timer 1 action.
+        EVENTTIMER2: Event timer 2 action.
+        EVENTTIMER3: Event timer 3 action.
+        EVENTTIMER4: Event timer 4 action.
+        STEPCTRL: Step control action.
+        STEPCTRLUP: Step control up action.
+        STEPCTRLDOWN: Step control down action.
+        LEVELSETINTERN: Level set internal action.
+        FADE: Fade action.
+        LEARN: Learn action.
+    """
 
     VOID = 0
     TURNON = 1

xp/models/telegram/input_type.py

@@ -1,8 +1,16 @@
+"""Input type enumeration based on input number ranges."""
+
 from enum import Enum
 
 
 class InputType(Enum):
-    """Input types based on input number ranges"""
+    """Input types based on input number ranges.
+
+    Attributes:
+        PUSH_BUTTON: Push button input (range 00-09).
+        IR_REMOTE: IR remote input (range 10-89).
+        PROXIMITY_SENSOR: Proximity sensor input (input 90).
+    """
 
     PUSH_BUTTON = "push_button"  # Input 00-09
     IR_REMOTE = "ir_remote"  # Input 10-89