Refactor pysmartthings to be more typesafe

.pre-commit-config.yaml

@@ -72,6 +72,8 @@ repos:
         types: [text]
         exclude: ^poetry\.lock$
         entry: poetry run codespell
+        args:
+          - --ignore-words-list=unx
       - id: detect-private-key
         name: 🕵️  Detect Private Keys
         language: system

pyproject.toml

@@ -30,6 +30,8 @@ packages = [
 python = "^3.11"
 aiohttp = ">=3.0.0"
 yarl = ">=1.6.0"
+mashumaro = "^3.11"
+orjson = "^3.9.10"
 
 [tool.poetry.group.dev.dependencies]
 codespell = "2.4.1"
@@ -44,6 +46,15 @@ pre-commit = "4.1.0"
 pre-commit-hooks = "5.0.0"
 yamllint = "1.35.1"
 ruff = "0.9.5"
+syrupy = "^4.8.1"
+aioresponses = "^0.7.8"
+
+[tool.poetry.group.cli]
+optional = true
+
+[tool.poetry.group.cli.dependencies]
+treelib = "^1.7.0"
+pyperclip = "^1.9.0"
 
 [tool.poetry.urls]
 "Bug Tracker" = "https://github.com/pySmartThings/pysmartthings/issues"
@@ -120,6 +131,7 @@ asyncio_mode = "auto"
 ignore = [
   "ANN401", # Opinioated warning on disallowing dynamically typed expressions
   "DTZ005",
+  "ERA001",
   "PLR0913",
   "TRY003",
   "FBT002",

script/__init__.py

@@ -0,0 +1 @@
+"""Script module."""

script/process_device_status.py

@@ -0,0 +1,90 @@
+"""Process the device status JSON file to generate a tree of a device status."""
+
+import json
+from pathlib import Path
+import re
+import sys
+
+from treelib import Tree
+
+from pysmartthings.models import CAPABILITY_ATTRIBUTES, Attribute, Capability
+
+
+def main() -> int:  # noqa: PLR0912
+    """Run the script."""
+    if len(sys.argv) != 2:
+        print("Usage: python process_device_status.py <filename>")
+        return 1
+    filename = sys.argv[1]
+    print(f"Processing {filename}")
+    with Path(filename).open(encoding="utf-8") as file:
+        data = json.load(file)
+    components = data["components"]
+    tree = Tree()
+    found_capabilities = {}
+    found_attributes = {}
+    missing_attribute_mapping = {}
+    tree.create_node(filename, "root")
+    for component_name, capabilities in components.items():  # pylint: disable=too-many-nested-blocks
+        tree.create_node(component_name, component_name, parent="root")
+        for capability_name, attributes in capabilities.items():
+            if capability_name not in Capability:
+                found_capabilities[capability_name] = (
+                    re.sub(r"(?<!^)(?=[A-Z])", "_", capability_name)
+                    .upper()
+                    .replace(".", "_")
+                    .replace("SAMSUNGCE", "SAMSUNG_CE")
+                )
+                missing_attribute_mapping[capability_name] = []
+            tree.create_node(
+                capability_name,
+                f"{component_name}-{capability_name}",
+                parent=component_name,
+            )
+            for attribute in attributes:
+                attribute_name: str
+                if attribute not in Attribute:
+                    found_attributes[attribute] = attribute_name = re.sub(
+                        r"(?<!^)(?=[A-Z])", "_", attribute
+                    ).upper()
+                else:
+                    attribute_name = Attribute(attribute).name
+                attribute_name = f"Attribute.{attribute_name}"
+                if capability_name in CAPABILITY_ATTRIBUTES:
+                    if attribute not in CAPABILITY_ATTRIBUTES[capability_name]:
+                        if capability_name not in missing_attribute_mapping:
+                            missing_attribute_mapping[capability_name] = []
+                        if (
+                            attribute_name
+                            not in missing_attribute_mapping[capability_name]
+                        ):
+                            missing_attribute_mapping[capability_name].append(
+                                attribute_name
+                            )
+                else:
+                    if capability_name not in missing_attribute_mapping:
+                        missing_attribute_mapping[capability_name] = []
+                    if attribute_name not in missing_attribute_mapping[capability_name]:
+                        missing_attribute_mapping[capability_name].append(
+                            attribute_name
+                        )
+                tree.create_node(
+                    attribute,
+                    f"{component_name}-{capability_name}-{attribute}",
+                    parent=f"{component_name}-{capability_name}",
+                )
+    print(tree.show(stdout=False))
+    if found_capabilities:
+        print("\nFound capabilities:")
+        for capability_name, slug in found_capabilities.items():
+            print(f'{slug} = "{capability_name}"')
+    if found_attributes:
+        print("\nFound attributes:")
+        for attribute_name, slug in found_attributes.items():
+            print(f'{slug} = "{attribute_name}"')
+    print(json.dumps(missing_attribute_mapping, indent=4))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

script/sort_attribute.py

@@ -0,0 +1,22 @@
+"""Sort the Attribute enum."""
+
+import pyperclip
+
+from pysmartthings.models import Attribute
+
+
+def main() -> int:
+    """Run the script."""
+    attributes = {attr.name: attr for attr in Attribute}
+    attributes = dict(sorted(attributes.items()))
+    result = "class Attribute(StrEnum):"
+    result += '\n    """Attribute model."""\n\n'
+    for name, attribute in attributes.items():
+        result += f'    {name} = "{attribute.value}"\n'
+    pyperclip.copy(result)
+    print(result)
+    return 0
+
+
+if __name__ == "__main__":
+    main()

script/sort_capability.py

@@ -0,0 +1,36 @@
+"""Script to sort the capability constants."""
+
+import pyperclip
+
+from pysmartthings.models import Capability
+
+
+def main() -> int:
+    """Run the script."""
+    capabilities = {}
+    dot_capabilities = {}
+    for capability in Capability:
+        if "." in capability.value:
+            category = capability.value.split(".")[0]
+            if category not in dot_capabilities:
+                dot_capabilities[category] = {}
+            dot_capabilities[category][capability.value] = capability
+        else:
+            capabilities[capability.value] = capability
+    capabilities = dict(sorted(capabilities.items()))
+    result = "class Capability(StrEnum):"
+    result += '\n    """Capability model."""\n\n'
+    for name, capability in capabilities.items():
+        result += f'    {capability.name} = "{name}"\n'
+    for category_capabilities in dot_capabilities.values():
+        result += "\n"
+        capabilities = dict(sorted(category_capabilities.items()))
+        for name, capability in capabilities.items():
+            result += f'    {capability.name} = "{name}"\n'
+    print(result)
+    pyperclip.copy(result)
+    return 0
+
+
+if __name__ == "__main__":
+    main()

src/pysmartthings/const.py

@@ -2,3 +2,5 @@
 
 __title__ = "pysmartthings"
 __version__ = "0.7.8"
+
+API_BASE = "api.smartthings.com"

src/pysmartthings/device.py

@@ -147,7 +147,7 @@ def apply_data(self, data: dict) -> None:
                 self._device_type_name = dth.get("deviceTypeName")
                 self._device_type_network = dth.get("deviceNetworkType")
 
-    def get_capability(self, *capabilities: list[dict[str, Any]]) -> str | None:
+    def get_capability(self, *capabilities: str) -> str | None:
         """Return the first capability held by the device."""
         for capability in capabilities:
             if capability in self._capabilities:

src/pysmartthings/exceptions.py

@@ -0,0 +1,21 @@
+"""Asynchronous Python client for SmartThings."""
+
+
+class SmartThingsError(Exception):
+    """Generic exception."""
+
+
+class SmartThingsConnectionError(SmartThingsError):
+    """SmartThings connection exception."""
+
+
+class SmartThingsAuthenticationFailedError(SmartThingsError):
+    """SmartThings authentication failed exception."""
+
+
+class SmartThingsNotFoundError(SmartThingsError):
+    """SmartThings not found exception."""
+
+
+class SmartThingsRateLimitError(SmartThingsError):
+    """SmartThings rate limit exception."""