ucapi-framework 1.8.3__tar.gz → 1.9.0b1__tar.gz

{ucapi_framework-1.8.3 → ucapi_framework-1.9.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucapi-framework
-Version: 1.8.3
+Version: 1.9.0b1
 Summary: ucapi framework that provides core functionality for building integrations.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{ucapi_framework-1.8.3 → ucapi_framework-1.9.0b1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ucapi-framework"
-version = "1.8.3"
+version = "1.9.0b1"
 description = "ucapi framework that provides core functionality for building integrations."
 readme = "README.md"
 requires-python = ">=3.11"

ucapi_framework-1.9.0b1/tests/test_button_entity.py

@@ -0,0 +1,154 @@
+"""Tests for ButtonEntity with built-in state management."""
+
+import pytest
+from unittest.mock import MagicMock
+from ucapi import button
+from ucapi_framework import ButtonEntity
+
+
+class TestButtonEntity:
+    """Test ButtonEntity state management."""
+
+    @pytest.fixture
+    def mock_api(self):
+        """Create a mock API for testing."""
+        api = MagicMock()
+        api.configured_entities.get.return_value = MagicMock(
+            attributes={button.Attributes.STATE: button.States.AVAILABLE}
+        )
+        return api
+
+    @pytest.fixture
+    def entity(self, mock_api):
+        """Create a ButtonEntity for testing."""
+        entity = ButtonEntity(
+            "button.test",
+            "Test Button",
+        )
+        entity._api = mock_api  # noqa: SLF001
+        return entity
+
+    def test_initial_state(self, entity):
+        """Test initial state from constructor attributes."""
+        assert entity.state == button.States.AVAILABLE
+
+    def test_initial_state_always_available(self, mock_api):
+        """Test that button always initializes STATE to AVAILABLE (ucapi hardcodes this)."""
+        entity = ButtonEntity(
+            "button.unset",
+            "Unset Button",
+        )
+        entity._api = mock_api  # noqa: SLF001
+        # ucapi.button.Button hardcodes {Attributes.STATE: States.AVAILABLE} in __init__
+        assert entity.state == button.States.AVAILABLE
+
+    def test_set_state_with_update(self, entity, mock_api):
+        """Test set_state() calls entity.update() by default."""
+        entity.set_state(button.States.UNAVAILABLE, update=True)
+
+        # Verify internal state was updated
+        assert entity.state == button.States.UNAVAILABLE
+
+        # Verify update was called
+        assert mock_api.configured_entities.update_attributes.called
+        call_args = mock_api.configured_entities.update_attributes.call_args
+        entity_id, attributes = call_args[0]
+        assert entity_id == "button.test"
+        assert button.Attributes.STATE in attributes
+        assert attributes[button.Attributes.STATE] == button.States.UNAVAILABLE
+
+    def test_set_state_without_update(self, entity, mock_api):
+        """Test set_state(update=False) does not call entity.update()."""
+        entity.set_state(button.States.UNAVAILABLE, update=False)
+
+        # Verify internal state was updated
+        assert entity.state == button.States.UNAVAILABLE
+
+        # Verify update was NOT called
+        assert not mock_api.configured_entities.update_attributes.called
+
+    def test_set_state_available(self, entity, mock_api):
+        """Test transitioning back to AVAILABLE."""
+        entity.set_state(button.States.UNAVAILABLE, update=False)
+        assert entity.state == button.States.UNAVAILABLE
+
+        entity.set_state(button.States.AVAILABLE, update=False)
+        assert entity.state == button.States.AVAILABLE
+
+    def test_set_state_none_does_not_update_remote(self, entity, mock_api):
+        """Test set_state(None) stores None but update filter strips it."""
+        # set_state(None) writes None into attributes dict
+        entity.set_state(None, update=True)
+
+        # Internal state stores None
+        assert entity.state is None
+
+        # The update should have been called but the None filter in
+        # update_attributes strips the None value — so update_attributes
+        # is called with an empty dict (or not called if filter removes all)
+        # Either way, the Remote should not receive a None value
+        if mock_api.configured_entities.update_attributes.called:
+            call_args = mock_api.configured_entities.update_attributes.call_args
+            _, attributes = call_args[0]
+            assert button.Attributes.STATE not in attributes
+
+    def test_property_getter_is_read_only(self, entity):
+        """Test that the state property cannot be set directly."""
+        with pytest.raises(AttributeError):
+            entity.state = button.States.AVAILABLE  # type: ignore[misc]
+
+    def test_only_one_attribute(self, entity, mock_api):
+        """Test that Button only has the STATE attribute."""
+        entity.set_state(button.States.UNAVAILABLE, update=True)
+
+        call_args = mock_api.configured_entities.update_attributes.call_args
+        _, attributes = call_args[0]
+        # Should only contain STATE
+        assert list(attributes.keys()) == [button.Attributes.STATE]
+
+
+class TestButtonEntityInheritance:
+    """Test that ButtonEntity can be subclassed and overridden."""
+
+    def test_custom_set_state(self):
+        """Test that set_state can be overridden."""
+
+        class CustomButton(ButtonEntity):
+            def __init__(self):
+                super().__init__(
+                    "button.custom",
+                    "Custom Button",
+                )
+                self.custom_set_state_called = False
+
+            def set_state(self, value, *, update=True):
+                """Override set_state to add custom logic."""
+                self.custom_set_state_called = True
+                super().set_state(value, update=update)
+
+        entity = CustomButton()
+        entity._api = MagicMock()  # noqa: SLF001
+        entity._api.configured_entities.get.return_value = entity  # noqa: SLF001
+
+        entity.set_state(button.States.AVAILABLE, update=False)
+        assert entity.custom_set_state_called is True
+        assert entity.state == button.States.AVAILABLE
+
+    def test_custom_property_getter(self):
+        """Test that the state property getter can be overridden."""
+
+        class CustomButton(ButtonEntity):
+            def __init__(self):
+                super().__init__(
+                    "button.custom",
+                    "Custom Button",
+                )
+
+            @property
+            def state(self):
+                """Override state getter to always return AVAILABLE."""
+                return button.States.AVAILABLE
+
+        entity = CustomButton()
+        # Property override always returns AVAILABLE
+        assert entity.state == button.States.AVAILABLE

ucapi_framework-1.9.0b1/tests/test_climate_entity.py

@@ -0,0 +1,230 @@
+"""Tests for ClimateEntity with built-in state management."""
+
+import pytest
+from unittest.mock import MagicMock
+from ucapi import climate
+from ucapi_framework import ClimateEntity
+
+
+class TestClimateEntity:
+    """Test ClimateEntity state management."""
+
+    @pytest.fixture
+    def mock_api(self):
+        """Create a mock API for testing."""
+        api = MagicMock()
+        api.configured_entities.get.return_value = MagicMock(
+            attributes={climate.Attributes.STATE: climate.States.OFF}
+        )
+        return api
+
+    @pytest.fixture
+    def entity(self, mock_api):
+        """Create a ClimateEntity for testing."""
+        entity = ClimateEntity(
+            "climate.test",
+            "Test Thermostat",
+            features=[climate.Features.ON_OFF, climate.Features.HEAT],
+            attributes={climate.Attributes.STATE: climate.States.OFF},
+        )
+        entity._api = mock_api  # noqa: SLF001
+        return entity
+
+    def test_initial_state(self, entity):
+        """Test initial state from constructor attributes."""
+        assert entity.state == climate.States.OFF
+        assert entity.current_temperature is None
+        assert entity.target_temperature is None
+        assert entity.target_temperature_high is None
+        assert entity.target_temperature_low is None
+        assert entity.fan_mode is None
+
+    def test_set_state_with_update(self, entity, mock_api):
+        """Test set_state() calls entity.update() by default."""
+        entity.set_state(climate.States.HEAT, update=True)
+
+        assert entity.state == climate.States.HEAT
+
+        assert mock_api.configured_entities.update_attributes.called
+        call_args = mock_api.configured_entities.update_attributes.call_args
+        entity_id, attributes = call_args[0]
+        assert entity_id == "climate.test"
+        assert climate.Attributes.STATE in attributes
+        assert attributes[climate.Attributes.STATE] == climate.States.HEAT
+
+    def test_set_state_without_update(self, entity, mock_api):
+        """Test set_state(update=False) does not call entity.update()."""
+        entity.set_state(climate.States.COOL, update=False)
+
+        assert entity.state == climate.States.COOL
+        assert not mock_api.configured_entities.update_attributes.called
+
+    def test_set_current_temperature(self, entity, mock_api):
+        """Test set_current_temperature() updates state and calls update."""
+        entity.set_current_temperature(22.5, update=True)
+
+        assert entity.current_temperature == 22.5
+        assert mock_api.configured_entities.update_attributes.called
+
+    def test_set_current_temperature_without_update(self, entity, mock_api):
+        """Test set_current_temperature(update=False) does not call update."""
+        entity.set_current_temperature(22.5, update=False)
+
+        assert entity.current_temperature == 22.5
+        assert not mock_api.configured_entities.update_attributes.called
+
+    def test_set_target_temperature(self, entity, mock_api):
+        """Test set_target_temperature() updates state and calls update."""
+        entity.set_target_temperature(21.0, update=True)
+
+        assert entity.target_temperature == 21.0
+        assert mock_api.configured_entities.update_attributes.called
+
+    def test_set_target_temperature_without_update(self, entity, mock_api):
+        """Test set_target_temperature(update=False) does not call update."""
+        entity.set_target_temperature(21.0, update=False)
+
+        assert entity.target_temperature == 21.0
+        assert not mock_api.configured_entities.update_attributes.called
+
+    def test_set_target_temperature_high(self, entity, mock_api):
+        """Test set_target_temperature_high() updates state and calls update."""
+        entity.set_target_temperature_high(25.0, update=True)
+
+        assert entity.target_temperature_high == 25.0
+        assert mock_api.configured_entities.update_attributes.called
+
+    def test_set_target_temperature_low(self, entity, mock_api):
+        """Test set_target_temperature_low() updates state and calls update."""
+        entity.set_target_temperature_low(18.0, update=True)
+
+        assert entity.target_temperature_low == 18.0
+        assert mock_api.configured_entities.update_attributes.called
+
+    def test_set_fan_mode(self, entity, mock_api):
+        """Test set_fan_mode() updates state and calls update."""
+        entity.set_fan_mode("AUTO", update=True)
+
+        assert entity.fan_mode == "AUTO"
+        assert mock_api.configured_entities.update_attributes.called
+
+    def test_set_fan_mode_without_update(self, entity, mock_api):
+        """Test set_fan_mode(update=False) does not call update."""
+        entity.set_fan_mode("HIGH", update=False)
+
+        assert entity.fan_mode == "HIGH"
+        assert not mock_api.configured_entities.update_attributes.called
+
+    def test_set_attributes_bulk_update(self, entity, mock_api):
+        """Test set_attributes() updates multiple attributes with single update call."""
+        entity.set_attributes(
+            state=climate.States.HEAT,
+            current_temperature=20.5,
+            target_temperature=22.0,
+            fan_mode="AUTO",
+            update=True,
+        )
+
+        assert entity.state == climate.States.HEAT
+        assert entity.current_temperature == 20.5
+        assert entity.target_temperature == 22.0
+        assert entity.fan_mode == "AUTO"
+
+        # Verify update was called only once
+        assert mock_api.configured_entities.update_attributes.call_count == 1
+
+        call_args = mock_api.configured_entities.update_attributes.call_args
+        entity_id, attributes = call_args[0]
+        assert entity_id == "climate.test"
+        assert len(attributes) == 4
+        assert attributes[climate.Attributes.STATE] == climate.States.HEAT
+        assert attributes[climate.Attributes.CURRENT_TEMPERATURE] == 20.5
+        assert attributes[climate.Attributes.TARGET_TEMPERATURE] == 22.0
+        assert attributes[climate.Attributes.FAN_MODE] == "AUTO"
+
+    def test_set_attributes_without_update(self, entity, mock_api):
+        """Test set_attributes(update=False) does not call entity.update()."""
+        entity.set_attributes(
+            state=climate.States.COOL,
+            target_temperature=19.0,
+            update=False,
+        )
+
+        assert entity.state == climate.States.COOL
+        assert entity.target_temperature == 19.0
+        assert not mock_api.configured_entities.update_attributes.called
+
+    def test_set_attributes_ignores_none_values(self, entity, mock_api):
+        """Test set_attributes() ignores None values."""
+        entity.set_attributes(
+            state=climate.States.HEAT, current_temperature=None, update=True
+        )
+
+        assert entity.state == climate.States.HEAT
+        assert entity.current_temperature is None
+
+        call_args = mock_api.configured_entities.update_attributes.call_args
+        entity_id, attributes = call_args[0]
+        assert len(attributes) == 1
+        assert climate.Attributes.STATE in attributes
+
+    def test_set_attributes_all_six(self, entity, mock_api):
+        """Test setting all six climate attributes at once."""
+        entity.set_attributes(
+            state=climate.States.HEAT_COOL,
+            current_temperature=21.0,
+            target_temperature=22.0,
+            target_temperature_high=25.0,
+            target_temperature_low=18.0,
+            fan_mode="AUTO",
+            update=True,
+        )
+
+        assert entity.state == climate.States.HEAT_COOL
+        assert entity.current_temperature == 21.0
+        assert entity.target_temperature == 22.0
+        assert entity.target_temperature_high == 25.0
+        assert entity.target_temperature_low == 18.0
+        assert entity.fan_mode == "AUTO"
+
+        assert mock_api.configured_entities.update_attributes.call_count == 1
+
+    def test_property_getters_are_read_only(self, entity):
+        """Test that property getters cannot be set directly."""
+        with pytest.raises(AttributeError):
+            entity.state = climate.States.HEAT  # type: ignore[misc]
+
+        with pytest.raises(AttributeError):
+            entity.current_temperature = 20.0  # type: ignore[misc]
+
+        with pytest.raises(AttributeError):
+            entity.target_temperature = 21.0  # type: ignore[misc]
+
+
+class TestClimateEntityInheritance:
+    """Test that ClimateEntity can be subclassed and overridden."""
+
+    def test_custom_set_state(self):
+        """Test that set_state can be overridden."""
+
+        class CustomClimate(ClimateEntity):
+            def __init__(self):
+                super().__init__(
+                    "climate.custom",
+                    "Custom Thermostat",
+                    features=[],
+                    attributes={},
+                )
+                self.custom_called = False
+
+            def set_state(self, value, *, update=True):
+                self.custom_called = True
+                super().set_state(value, update=update)
+
+        entity = CustomClimate()
+        entity._api = MagicMock()  # noqa: SLF001
+        entity._api.configured_entities.get.return_value = entity  # noqa: SLF001
+
+        entity.set_state(climate.States.COOL, update=False)
+        assert entity.custom_called is True
+        assert entity.state == climate.States.COOL

ucapi_framework-1.9.0b1/tests/test_cover_entity.py

@@ -0,0 +1,228 @@
+"""Tests for CoverEntity with built-in state management."""
+
+import pytest
+from unittest.mock import MagicMock
+from ucapi import cover
+from ucapi_framework import CoverEntity
+
+
+class TestCoverEntity:
+    """Test CoverEntity state management."""
+
+    @pytest.fixture
+    def mock_api(self):
+        """Create a mock API for testing."""
+        api = MagicMock()
+        api.configured_entities.get.return_value = MagicMock(
+            attributes={cover.Attributes.STATE: cover.States.CLOSED}
+        )
+        return api
+
+    @pytest.fixture
+    def entity(self, mock_api):
+        """Create a CoverEntity for testing."""
+        entity = CoverEntity(
+            "cover.test",
+            "Test Cover",
+            features=[cover.Features.OPEN, cover.Features.CLOSE],
+            attributes={cover.Attributes.STATE: cover.States.CLOSED},
+        )
+        entity._api = mock_api  # noqa: SLF001
+        return entity
+
+    def test_initial_state(self, entity):
+        """Test initial state from constructor attributes."""
+        # State was set to CLOSED in constructor
+        assert entity.state == cover.States.CLOSED
+        # These were not set, so should be None
+        assert entity.position is None
+        assert entity.tilt_position is None
+
+    def test_set_state_with_update(self, entity, mock_api):
+        """Test set_state() calls entity.update() by default."""
+        entity.set_state(cover.States.OPEN, update=True)
+
+        # Verify internal state was updated
+        assert entity.state == cover.States.OPEN
+
+        # Verify update was called
+        assert mock_api.configured_entities.update_attributes.called
+        call_args = mock_api.configured_entities.update_attributes.call_args
+        entity_id, attributes = call_args[0]
+        assert entity_id == "cover.test"
+        assert cover.Attributes.STATE in attributes
+        assert attributes[cover.Attributes.STATE] == cover.States.OPEN
+
+    def test_set_state_without_update(self, entity, mock_api):
+        """Test set_state(update=False) does not call entity.update()."""
+        entity.set_state(cover.States.OPEN, update=False)
+
+        # Verify internal state was updated
+        assert entity.state == cover.States.OPEN
+
+        # Verify update was NOT called
+        assert not mock_api.configured_entities.update_attributes.called
+
+    def test_set_state_transitions(self, entity, mock_api):
+        """Test all valid state transitions."""
+        for state in [
+            cover.States.OPENING,
+            cover.States.OPEN,
+            cover.States.CLOSING,
+            cover.States.CLOSED,
+            cover.States.UNKNOWN,
+            cover.States.UNAVAILABLE,
+        ]:
+            entity.set_state(state, update=False)
+            assert entity.state == state
+
+    def test_set_position(self, entity, mock_api):
+        """Test set_position() updates state and calls update."""
+        entity.set_position(75, update=True)
+
+        assert entity.position == 75
+        assert mock_api.configured_entities.update_attributes.called
+
+    def test_set_position_without_update(self, entity, mock_api):
+        """Test set_position(update=False) does not call entity.update()."""
+        entity.set_position(75, update=False)
+
+        assert entity.position == 75
+        assert not mock_api.configured_entities.update_attributes.called
+
+    def test_set_tilt_position(self, entity, mock_api):
+        """Test set_tilt_position() updates state and calls update."""
+        entity.set_tilt_position(45, update=True)
+
+        assert entity.tilt_position == 45
+        assert mock_api.configured_entities.update_attributes.called
+
+    def test_set_tilt_position_without_update(self, entity, mock_api):
+        """Test set_tilt_position(update=False) does not call entity.update()."""
+        entity.set_tilt_position(45, update=False)
+
+        assert entity.tilt_position == 45
+        assert not mock_api.configured_entities.update_attributes.called
+
+    def test_set_attributes_bulk_update(self, entity, mock_api):
+        """Test set_attributes() updates multiple attributes with single update call."""
+        entity.set_attributes(
+            state=cover.States.OPEN,
+            position=100,
+            tilt_position=50,
+            update=True,
+        )
+
+        # Verify all internal state was updated
+        assert entity.state == cover.States.OPEN
+        assert entity.position == 100
+        assert entity.tilt_position == 50
+
+        # Verify update was called only once
+        assert mock_api.configured_entities.update_attributes.call_count == 1
+
+        # Verify all attributes were included in the update
+        call_args = mock_api.configured_entities.update_attributes.call_args
+        entity_id, attributes = call_args[0]
+        assert entity_id == "cover.test"
+        assert len(attributes) == 3
+        assert attributes[cover.Attributes.STATE] == cover.States.OPEN
+        assert attributes[cover.Attributes.POSITION] == 100
+        assert attributes[cover.Attributes.TILT_POSITION] == 50
+
+    def test_set_attributes_without_update(self, entity, mock_api):
+        """Test set_attributes(update=False) does not call entity.update()."""
+        entity.set_attributes(state=cover.States.OPEN, position=100, update=False)
+
+        # Verify internal state was updated
+        assert entity.state == cover.States.OPEN
+        assert entity.position == 100
+
+        # Verify update was NOT called
+        assert not mock_api.configured_entities.update_attributes.called
+
+    def test_set_attributes_ignores_none_values(self, entity, mock_api):
+        """Test set_attributes() ignores None values."""
+        entity.set_attributes(state=cover.States.OPEN, position=None, update=True)
+
+        # Only state should be in internal storage
+        assert entity.state == cover.States.OPEN
+        assert entity.position is None
+
+        # Verify only state was included in update
+        call_args = mock_api.configured_entities.update_attributes.call_args
+        entity_id, attributes = call_args[0]
+        assert len(attributes) == 1
+        assert cover.Attributes.STATE in attributes
+
+    def test_property_getters_are_read_only(self, entity):
+        """Test that property getters cannot be set directly."""
+        with pytest.raises(AttributeError):
+            entity.state = cover.States.OPEN  # type: ignore[misc]
+
+    def test_all_cover_attributes(self, entity, mock_api):
+        """Test setting all cover attributes."""
+        entity.set_attributes(
+            state=cover.States.OPEN,
+            position=100,
+            tilt_position=0,
+            update=True,
+        )
+
+        assert entity.state == cover.States.OPEN
+        assert entity.position == 100
+        assert entity.tilt_position == 0
+
+        # Verify single update call
+        assert mock_api.configured_entities.update_attributes.call_count == 1
+
+
+class TestCoverEntityInheritance:
+    """Test that CoverEntity can be subclassed and overridden."""
+
+    def test_custom_set_state(self):
+        """Test that set_state can be overridden."""
+
+        class CustomCover(CoverEntity):
+            def __init__(self):
+                super().__init__(
+                    "cover.custom",
+                    "Custom Cover",
+                    features=[],
+                    attributes={},
+                )
+                self.custom_set_state_called = False
+
+            def set_state(self, value, *, update=True):
+                """Override set_state to add custom logic."""
+                self.custom_set_state_called = True
+                super().set_state(value, update=update)
+
+        entity = CustomCover()
+        entity._api = MagicMock()  # noqa: SLF001
+        entity._api.configured_entities.get.return_value = entity  # noqa: SLF001
+
+        entity.set_state(cover.States.OPEN, update=False)
+        assert entity.custom_set_state_called is True
+        assert entity.state == cover.States.OPEN
+
+    def test_custom_property_getter(self):
+        """Test that property getters can be overridden."""
+
+        class CustomCover(CoverEntity):
+            def __init__(self):
+                super().__init__(
+                    "cover.custom",
+                    "Custom Cover",
+                    features=[],
+                    attributes={},
+                )
+
+            @property
+            def state(self):
+                """Override state getter to always return OPEN."""
+                return cover.States.OPEN
+
+        entity = CustomCover()
+        # Even if internal state is None, getter returns OPEN
+        assert entity.state == cover.States.OPEN