blebox-uniapi 2.5.5__tar.gz → 2.5.6__tar.gz

{blebox_uniapi-2.5.5 → blebox_uniapi-2.5.6}/CONTRIBUTING.rst

@@ -122,7 +122,11 @@ Make sure all your changes are committed (including an entry in HISTORY.rst).
 Then run::
 
 $ bump2version patch # possible: major / minor / patch
-$ git push
-$ git push --tags
-
-Travis will then deploy to PyPI if tests pass.
+$ git push --follow-tags
+
+bump2version bumps the version in setup.py, blebox_uniapi/__init__.py and
+setup.cfg, commits the change and creates a matching git tag (e.g. v2.6.0).
+Pushing the tag triggers the "Publish to PyPI" GitHub Actions workflow
+(.github/workflows/release.yml), which first runs lint + tests, then builds and
+uploads to PyPI via Trusted Publishing (OIDC) from the blebox/blebox_uniapi repo.
+The publish step only runs if the tests pass.

{blebox_uniapi-2.5.5 → blebox_uniapi-2.5.6}/MANIFEST.in

@@ -1,4 +1,3 @@
-include AUTHORS.rst
 include CONTRIBUTING.rst
 include HISTORY.rst
 include LICENSE

{blebox_uniapi-2.5.5 → blebox_uniapi-2.5.6}/PKG-INFO

@@ -1,22 +1,36 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: blebox_uniapi
-Version: 2.5.5
+Version: 2.5.6
 Summary: Python API for accessing BleBox smart home devices
 Home-page: https://github.com/blebox/blebox_uniapi
 Author: BleBox
 Author-email: opensource@blebox.eu
 License: Apache Software License 2.0
 Keywords: blebox_uniapi
-Platform: UNKNOWN
 Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Natural Language :: English
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
 Requires-Python: >=3.9
 Description-Content-Type: text/x-rst
 License-File: LICENSE
+Requires-Dist: aiohttp>=3
+Requires-Dist: jmespath>1.0.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 ====================
 BleBox Python UniAPI
@@ -227,5 +241,3 @@ History
 ------------------
 
 * First release on PyPI.
-
-

{blebox_uniapi-2.5.5 → blebox_uniapi-2.5.6}/blebox_uniapi/__init__.py

@@ -2,4 +2,4 @@
 
 __author__ = """BleBox"""
 __email__ = "opensource@blebox.eu"
-__version__ = "2.5.5"
+__version__ = "2.5.6"

{blebox_uniapi-2.5.5 → blebox_uniapi-2.5.6}/blebox_uniapi/box.py

@@ -111,6 +111,7 @@ class Box:
 
         self._data_path = config["api_path"]
         self._type = type
+        self._product = product
         self._unique_id = unique_id
         self._name = name
         self._address = address
@@ -212,6 +213,11 @@ class Box:
     def type(self) -> str:
         return self._type
 
+    @property
+    def product(self) -> str:
+        """Product name for informational purpose only - do not use it in any application logic."""
+        return self._product
+
     @property
     def unique_id(self) -> Any:
         return self._unique_id

{blebox_uniapi-2.5.5 → blebox_uniapi-2.5.6}/blebox_uniapi/box_types.py

@@ -1,3 +1,4 @@
+from .button import GateBoxSecondOutput, TvLift
 from .cover import Gate, GateBox, GateBoxB, Shutter
 from typing import Union, Any
 
@@ -50,9 +51,8 @@ BOX_TYPE_CONF: dict[str, dict[int, dict[str, Any]]] = {
                 "set": lambda command: ("GET", f"/s/c/{command}")
             },  # dictionary with interaction methods
             "buttons": [
-                "tvLift",
-                {"lift": ""},
-            ],  # key used to set platform, list elements used in cls init, e.g. [<alias>, {"path": "state_value"}]
+                ["tvLift", {}, TvLift],
+            ],  # key used to set platform, list elements used in cls init, e.g. [<alias>, {"path": "state_value"}, <optional type class>]
         }
     },
     # airSensor
@@ -135,11 +135,15 @@ BOX_TYPE_CONF: dict[str, dict[int, dict[str, Any]]] = {
                     {
                         "position": "gate.currentPos",
                         "gate_type": "gate.gateType",
+                        "extra_button_type": "gate.extraButtonType",
                     },
                     "gatebox",
                     GateBoxB,
                 ]
             ],
+            "buttons": [
+                ["second_output", {}, GateBoxSecondOutput],
+            ],
         },
     },
     # gateController

blebox_uniapi-2.5.6/blebox_uniapi/button.py

@@ -0,0 +1,141 @@
+from .cover import GateBoxControlType, GateBoxExtraButtonType
+from .feature import Feature
+from typing import TYPE_CHECKING, Any, Optional, Type
+
+from enum import Enum, auto
+
+if TYPE_CHECKING:
+    from .box import Box
+
+TV_LIFT_CONTROL_TYPES_API = {
+    0: {"1": "open_or_stop", "2": "close_or_stop"},
+    1: {"1": "up_or_stop", "2": "down_or_stop"},
+    2: {"1": "up_or_stop", "2": "down_or_stop"},
+    3: {"1": "up_or_stop", "2": "down_or_stop"},
+    4: {"1": "open_or_stop", "2": "close_or_stop", "3": "to_fav"},
+}
+
+
+class ControlType(Enum):
+    UP = auto()
+    DOWN = auto()
+    FAVORITE = auto()
+    OPEN = auto()
+    CLOSE = auto()
+
+
+class Buttons:
+    """Buttons defines how a product derives its buttons from extended state."""
+
+    @staticmethod
+    def many_from_extended_state(
+        button_cls: Type["Button"],
+        product: "Box",
+        alias: str,
+        methods: dict,
+        extended_state: dict,
+    ) -> list["Button"]:
+        raise NotImplementedError  # pragma: no cover
+
+
+class TvLift(Buttons):
+    @staticmethod
+    def many_from_extended_state(
+        button_cls: Type["Button"],
+        product: "Box",
+        alias: str,
+        methods: dict,
+        extended_state: dict,
+    ) -> list["Button"]:
+        control_type = extended_state.get("tvLift", {}).get("controlType")
+        endpoints = TV_LIFT_CONTROL_TYPES_API.get(control_type, {})
+        return [
+            button_cls(product, f"{alias}_{endpoint}", methods, endpoint)
+            for endpoint in endpoints.values()
+        ]
+
+
+class GateBoxSecondOutput(Buttons):
+    """GateBoxSecondOutput exposes the gateBox extra button output as a button.
+
+    WALK_IN and OTHER share one button name because what the output does is a
+    device setting the user can change at any time, not a hardware trait.
+    """
+
+    @staticmethod
+    def many_from_extended_state(
+        button_cls: Type["Button"],
+        product: "Box",
+        alias: str,
+        methods: dict,
+        extended_state: dict,
+    ) -> list["Button"]:
+        gate = extended_state.get("gate", {})
+        if gate.get("extraButtonType") not in (
+            GateBoxExtraButtonType.WALK_IN,
+            GateBoxExtraButtonType.OTHER,
+        ):
+            return []
+
+        # Api levels below 20230102 report no mode and cannot be wired that way.
+        if gate.get("openCloseMode") == GateBoxControlType.OPEN_CLOSE:
+            return []
+
+        return [button_cls(product, alias, methods, "second_output", "secondary")]
+
+
+class Button(Feature):
+    def __init__(
+        self,
+        product: "Box",
+        alias: str,
+        methods: dict,
+        query_string: str,
+        api_command: str = "set",
+    ) -> None:
+        super().__init__(product, alias, methods)
+        self._device_class = "UPDATE"
+        self._query_string: str = query_string
+        self._api_command: str = api_command
+
+    @classmethod
+    def many_from_config(
+        cls, product: "Box", box_type_config: list, extended_state: Any
+    ) -> list["Button"]:
+        if not isinstance(extended_state, dict):
+            return []
+
+        features: list[Button] = []
+        for alias, methods, buttons in box_type_config:
+            features.extend(
+                buttons.many_from_extended_state(
+                    cls, product, alias, methods, extended_state
+                )
+            )
+        return features
+
+    async def set(self) -> None:
+        await self.async_api_command(self._api_command, self.query_string)
+
+    def after_update(self) -> None:
+        pass
+
+    @property
+    def control_type(self) -> Optional[ControlType]:
+        """Return icon for endpoint."""
+        if "up" in self.query_string:
+            return ControlType.UP
+        elif "down" in self.query_string:
+            return ControlType.DOWN
+        elif "fav" in self.query_string:
+            return ControlType.FAVORITE
+        elif "open" in self.query_string:
+            return ControlType.OPEN
+        elif "close" in self.query_string:
+            return ControlType.CLOSE
+        else:
+            return None
+
+    @property
+    def query_string(self) -> str:
+        return self._query_string

{blebox_uniapi-2.5.5 → blebox_uniapi-2.5.6}/blebox_uniapi/cover.py

@@ -65,6 +65,19 @@ class GateBoxControlType(IntEnum):
     OPEN_CLOSE = 2
 
 
+class GateBoxExtraButtonType(IntEnum):
+    """GateBoxExtraButtonType defines gateBox extra button semantics.
+
+    Only meaningful outside OPEN_CLOSE mode, which takes the extra button output
+    for the close action and leaves this field unused.
+    """
+
+    DISABLED = 0
+    STOP = 1
+    WALK_IN = 2
+    OTHER = 3
+
+
 class GateBoxGateType(IntEnum):
     """GateBoxGateType defines possible gate/cover types reported by gateBox"""
 
@@ -305,7 +318,7 @@ class GateBox(Gate):
         if button_type is None:
             return False
 
-        return button_type == 1
+        return button_type == GateBoxExtraButtonType.STOP
 
 
 class GateBoxB(GateBox):
@@ -328,9 +341,23 @@ class GateBoxB(GateBox):
         return raw_value("position")
 
     def read_has_stop(self, alias: str, raw_value: Any, product: "Box") -> bool:
+        if product.last_data is None:
+            return False
+
         # note: if control type is unknown we assume it is not open/close
         #       and has the stop feature via secondary button command.
-        return self._control_type != GateBoxControlType.OPEN_CLOSE
+        if self._control_type == GateBoxControlType.OPEN_CLOSE:
+            return False
+
+        # stop_command issues the same secondary command as the second_output button.
+        extra_button_type = raw_value("extra_button_type")
+        if extra_button_type in (
+            GateBoxExtraButtonType.WALK_IN,
+            GateBoxExtraButtonType.OTHER,
+        ):
+            return False
+
+        return True
 
     def read_cover_type(
         self, alias: str, raw_value: Any, product: "Box"

{blebox_uniapi-2.5.5 → blebox_uniapi-2.5.6}/blebox_uniapi/error.py

@@ -39,7 +39,6 @@ class UnsupportedBoxVersion(BoxError):
     pass
 
 
-
 class BadFieldExceedsMax(BoxError):
     def __init__(self, dev_name: str, field: str, value: int, max_value: int):
         self._dev_name = dev_name
@@ -103,7 +102,6 @@ class BadFieldNotRGBW(BoxError):
         return f"{self._dev_name}.{self._field} is {self._value} which is not a rgbw string"
 
 
-
 # misc errors
 
 

{blebox_uniapi-2.5.5 → blebox_uniapi-2.5.6}/blebox_uniapi/session.py

@@ -98,7 +98,7 @@ class ApiHost:
         try:
             return await self.async_request(path, self._session.get)
         except Exception as ex:
-            logger.error(f"EXCEPTION DURING API CALL: {ex}")
+            logger.debug(f"EXCEPTION DURING API CALL: {ex}")
             raise ex
 
     async def async_api_get_ota(self, path: str) -> Optional[dict]:
@@ -107,7 +107,7 @@ class ApiHost:
                 path, self._session.get, allow_ota_check_response=True
             )
         except Exception as ex:
-            logger.error(f"EXCEPTION DURING API CALL: {ex}")
+            logger.debug(f"EXCEPTION DURING API CALL: {ex}")
             raise ex
 
     async def async_api_post(

{blebox_uniapi-2.5.5 → blebox_uniapi-2.5.6}/blebox_uniapi.egg-info/PKG-INFO

@@ -1,22 +1,36 @@
-Metadata-Version: 2.1
-Name: blebox-uniapi
-Version: 2.5.5
+Metadata-Version: 2.4
+Name: blebox_uniapi
+Version: 2.5.6
 Summary: Python API for accessing BleBox smart home devices
 Home-page: https://github.com/blebox/blebox_uniapi
 Author: BleBox
 Author-email: opensource@blebox.eu
 License: Apache Software License 2.0
 Keywords: blebox_uniapi
-Platform: UNKNOWN
 Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Natural Language :: English
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
 Requires-Python: >=3.9
 Description-Content-Type: text/x-rst
 License-File: LICENSE
+Requires-Dist: aiohttp>=3
+Requires-Dist: jmespath>1.0.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 ====================
 BleBox Python UniAPI
@@ -227,5 +241,3 @@ History
 ------------------
 
 * First release on PyPI.
-
-

{blebox_uniapi-2.5.5 → blebox_uniapi-2.5.6}/blebox_uniapi.egg-info/SOURCES.txt

@@ -35,4 +35,16 @@ docs/index.rst
 docs/installation.rst
 docs/make.bat
 docs/readme.rst
-docs/usage.rst
+docs/usage.rst
+tests/test_box.py
+tests/test_box_types.py
+tests/test_button.py
+tests/test_climate.py
+tests/test_cover.py
+tests/test_light.py
+tests/test_light_unit.py
+tests/test_sensor.py
+tests/test_session.py
+tests/test_switch.py
+tests/test_unknown.py
+tests/test_update.py

{blebox_uniapi-2.5.5 → blebox_uniapi-2.5.6}/setup.cfg

@@ -1,7 +1,8 @@
 [bumpversion]
-current_version = 2.5.5
+current_version = 2.5.6
 commit = True
 tag = True
+tag_name = v{new_version}
 
 [bumpversion:file:setup.py]
 search = version="{current_version}"

{blebox_uniapi-2.5.5 → blebox_uniapi-2.5.6}/setup.py

@@ -23,7 +23,7 @@ test_requirements = [
 ]
 
 setup(
-    version="2.5.5",
+    version="2.5.6",
     author="BleBox",
     author_email="opensource@blebox.eu",
     python_requires=">=3.9",
@@ -34,6 +34,7 @@ setup(
         "Natural Language :: English",
         "Programming Language :: Python :: 3.9",
         "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
     ],
     description="Python API for accessing BleBox smart home devices",
     install_requires=requirements,

blebox_uniapi-2.5.6/tests/test_box.py

@@ -0,0 +1,236 @@
+import pytest
+from unittest import mock
+from unittest.mock import AsyncMock, patch
+from blebox_uniapi.box import Box
+from blebox_uniapi import error
+from blebox_uniapi.jfollow import follow
+
+pytestmark = pytest.mark.asyncio
+
+
+@pytest.fixture
+def mock_session():
+    return mock.MagicMock(host="172.1.2.3", port=80)
+
+
+@pytest.fixture
+def sample_data():
+    return {
+        "id": "abcd1234ef",
+        "type": "airSensor",
+        "deviceName": "foobar",
+        "fv": "1.23",
+        "hv": "4.56",
+        "apiLevel": "20180403",
+    }
+
+
+@pytest.fixture
+def config(sample_data):
+    return Box._match_device_config(sample_data)
+
+
+async def test_without_type(mock_session, sample_data, config):
+    del sample_data["type"]
+
+    with pytest.raises(error.UnsupportedBoxResponse, match="has no type"):
+        Box(mock_session, sample_data, config, None)
+
+
+async def test_with_unknown_type(mock_session, sample_data):
+    sample_data["type"] = "unknownBox"
+
+    with pytest.raises(error.UnsupportedBoxResponse, match="not a supported type"):
+        Box._match_device_config(sample_data)
+
+
+async def test_without_name(mock_session, sample_data, config):
+    del sample_data["deviceName"]
+
+    with pytest.raises(error.UnsupportedBoxResponse, match="has no name"):
+        Box(mock_session, sample_data, config, None)
+
+
+async def test_without_firmware_version(mock_session, sample_data, config):
+    del sample_data["fv"]
+
+    with pytest.raises(error.UnsupportedBoxResponse, match="has no firmware version"):
+        Box(mock_session, sample_data, config, None)
+
+
+async def test_without_hardware_version(mock_session, sample_data, config):
+    del sample_data["hv"]
+
+    with pytest.raises(error.UnsupportedBoxResponse, match="has no hardware version"):
+        Box(mock_session, sample_data, config, None)
+
+
+async def test_without_api_level(mock_session, sample_data, config):
+    del sample_data["apiLevel"]
+
+    with pytest.raises(error.UnsupportedBoxVersion, match=r"unsupported version"):
+        Box._match_device_config(sample_data)
+
+
+async def test_json_path_extraction(mock_session, sample_data, config):
+    # note: follow is thin wrapper over jmespath so there's no real reason to test it.
+    # However, this tests makes sure we understand the syntax and know how it works.
+    # We can also use it as a canary for any unexpected change in syntax that may come
+    # in newer version.
+
+    # succesfull extraction
+    assert follow(["foo"], "[0]") == "foo"
+    assert follow([{"foo": "3", "value": 4}], "[?foo=='3'].value") == [4]
+
+    # "dud" extraction
+    assert follow([{"foo": "ab", "value": 4}], "[?foo=='bc'].value") == []
+    assert follow([{"value": 4}], "[1].value") is None
+    assert follow({"value": 4}, "foo") is None
+    assert follow({"foo": [4]}, "[?bar==`0`].value") is None
+
+
+async def test_missing_device_id(mock_session, sample_data, config):
+    del sample_data["id"]
+    with pytest.raises(error.UnsupportedBoxResponse, match="has no id"):
+        Box(mock_session, sample_data, config, None)
+
+
+# Add more test cases for other missing fields (type, name, versions, etc.)
+
+
+async def test_invalid_init(mock_session, sample_data, config):
+    with mock.patch(
+        "blebox_uniapi.sensor.SensorFactory.many_from_config",
+        spec_set=True,
+        autospec=True,
+    ) as mock_sensor:
+        mock_sensor.side_effect = KeyError
+        with pytest.raises(
+            error.UnsupportedBoxResponse, match=r"Failed to initialize:"
+        ):
+            Box(mock_session, sample_data, config, None)
+
+
+async def test_properties(mock_session, sample_data, config):
+    box = Box(mock_session, sample_data, config, None)
+    assert box.name == "foobar"
+    assert box.last_data is None
+    assert box.type == "airSensor"
+    assert box.model == "airSensor"
+    assert box.product == "airSensor"
+    assert box.unique_id == "abcd1234ef"
+    assert box.firmware_version == "1.23"
+    assert box.hardware_version == "4.56"
+    assert box.brand == "BleBox"
+    assert box.api_version == 20180403
+    assert box.address == "172.1.2.3:80"
+
+
+async def test_field_validations(mock_session, sample_data, config):
+    box = Box(mock_session, sample_data, config, None)
+
+    with pytest.raises(
+        error.BadFieldExceedsMax,
+        match=r"foobar.field1 is 123 which exceeds max \(100\)",
+    ):
+        box.check_int_range(123, "field1", 100, 0)
+
+    with pytest.raises(
+        error.BadFieldLessThanMin,
+        match=r"foobar.field1 is 123 which is less than minimum \(200\)",
+    ):
+        box.check_int_range(123, "field1", 300, 200)
+
+    with pytest.raises(error.BadFieldMissing, match=r"foobar.field1 is missing"):
+        box.check_int(None, "field1", 300, 200)
+
+    with pytest.raises(
+        error.BadFieldNotANumber, match=r"foobar.field1 is '123' which is not a number"
+    ):
+        box.check_int("123", "field1", 300, 200)
+
+    with pytest.raises(error.BadFieldMissing, match=r"foobar.field1 is missing"):
+        box.check_hex_str(None, "field1", 300, 200)
+
+    with pytest.raises(
+        error.BadFieldNotAString, match=r"foobar.field1 is 123 which is not a string"
+    ):
+        box.check_hex_str(123, "field1", 300, 200)
+
+    with pytest.raises(error.BadFieldMissing, match=r"foobar.field1 is missing"):
+        box.check_rgbw(None, "field1")
+
+    with pytest.raises(
+        error.BadFieldNotAString, match=r"foobar.field1 is 123 which is not a string"
+    ):
+        box.check_rgbw(123, "field1")
+
+    with pytest.raises(
+        error.BadFieldNotRGBW, match=r"foobar.field1 is 123 which is not a rgbw string"
+    ):
+        box.check_rgbw("123", "field1")
+
+
+async def test_available_firmware_version_none(mock_session, sample_data, config):
+    box = Box(mock_session, sample_data, config, None)
+    assert box.available_firmware_version is None
+
+
+async def test_available_firmware_version_set(mock_session, sample_data, config):
+    sample_data["availableFv"] = "2.0"
+    box = Box(mock_session, sample_data, config, None)
+    assert box.available_firmware_version == "2.0"
+
+
+async def test_async_ota_update_calls_session(mock_session, sample_data, config):
+    box = Box(mock_session, sample_data, config, None)
+    mock_session.async_api_get = AsyncMock(return_value=None)
+    await box.async_ota_update()
+    mock_session.async_api_get.assert_called_once_with("/api/ota/update")
+
+
+async def test_async_ota_check_updates_firmware_versions(
+    mock_session, sample_data, config
+):
+    box = Box(mock_session, sample_data, config, None)
+    mock_session.async_api_get_ota = AsyncMock(return_value=None)
+    mock_session.async_api_get = AsyncMock(
+        return_value={"availableFv": "2.0", "fv": "1.5"}
+    )
+    with patch("asyncio.sleep", new=AsyncMock()):
+        await box.async_ota_check()
+    assert box.available_firmware_version == "2.0"
+    assert box.firmware_version == "1.5"
+
+
+async def test_async_ota_check_unwraps_device_key(mock_session, sample_data, config):
+    box = Box(mock_session, sample_data, config, None)
+    mock_session.async_api_get_ota = AsyncMock(return_value=None)
+    mock_session.async_api_get = AsyncMock(
+        return_value={"device": {"availableFv": "3.0", "fv": "2.5"}}
+    )
+    with patch("asyncio.sleep", new=AsyncMock()):
+        await box.async_ota_check()
+    assert box.available_firmware_version == "3.0"
+
+
+async def test_async_ota_check_raises_on_none_info_response(
+    mock_session, sample_data, config
+):
+    box = Box(mock_session, sample_data, config, None)
+    mock_session.async_api_get_ota = AsyncMock(return_value=None)
+    mock_session.async_api_get = AsyncMock(return_value=None)
+    with patch("asyncio.sleep", new=AsyncMock()):
+        with pytest.raises(error.UnsupportedBoxResponse):
+            await box.async_ota_check()
+
+
+async def test_async_ota_check_returns_silently_when_no_available_fv(
+    mock_session, sample_data, config
+):
+    box = Box(mock_session, sample_data, config, None)
+    mock_session.async_api_get_ota = AsyncMock(return_value=None)
+    mock_session.async_api_get = AsyncMock(return_value={"fv": "1.0"})
+    with patch("asyncio.sleep", new=AsyncMock()):
+        await box.async_ota_check()
+    assert box.available_firmware_version is None