feat: Allow integrations to provide entity icon and description

CHANGELOG.md

@@ -11,10 +11,12 @@ _Changes in the next release_
 
 ### Added
 - Media browsing and searching features to media-player entity.
+- Allow integrations to provide entity icon and description.
 
 ### Breaking Changes
 - Renamed `MediaType` to `MediaContentType` and changed enums to lowercase. See media-player entity documentation for more information.
 - Changed `str, Enum` to new Python 3.11 `StrEnum` class.
+- All entity constructors require named parameters for the optional fields.
 
 ---
 

ucapi/button.py

@@ -42,6 +42,9 @@ def __init__(
         self,
         identifier: str,
         name: str | dict[str, str],
+        *,
+        icon: str | None = None,
+        description: str | dict[str, str] | None = None,
         area: str | None = None,
         cmd_handler: CommandHandler = None,
     ):
@@ -50,6 +53,8 @@ def __init__(
 
         :param identifier: entity identifier
         :param name: friendly name, either a string or a language dictionary
+        :param icon: optional icon
+        :param description: optional description, either a string or a language dictionary
         :param area: optional area name
         :param cmd_handler: handler for entity commands
         """
@@ -59,6 +64,8 @@ def __init__(
             EntityTypes.BUTTON,
             ["press"],
             {Attributes.STATE: States.AVAILABLE},
+            icon=icon,
+            description=description,
             area=area,
             cmd_handler=cmd_handler,
         )

ucapi/climate.py

@@ -88,8 +88,11 @@ def __init__(
         name: str | dict[str, str],
         features: list[Features],
         attributes: dict[str, Any],
+        *,
         device_class: str | None = None,
         options: dict[str, Any] | None = None,
+        icon: str | None = None,
+        description: str | dict[str, str] | None = None,
         area: str | None = None,
         cmd_handler: CommandHandler = None,
     ):
@@ -102,6 +105,8 @@ def __init__(
         :param attributes: climate attributes
         :param device_class: optional climate device class
         :param options: options
+        :param icon: optional icon
+        :param description: optional description, either a string or a language dictionary
         :param area: optional area
         :param cmd_handler: handler for entity commands
         """
@@ -113,6 +118,8 @@ def __init__(
             attributes,
             device_class=device_class,
             options=options,
+            icon=icon,
+            description=description,
             area=area,
             cmd_handler=cmd_handler,
         )

ucapi/cover.py

@@ -87,8 +87,11 @@ def __init__(
         name: str | dict[str, str],
         features: list[Features],
         attributes: dict[str, Any],
+        *,
         device_class: DeviceClasses | None = None,
         options: dict[str, Any] | None = None,
+        icon: str | None = None,
+        description: str | dict[str, str] | None = None,
         area: str | None = None,
         cmd_handler: CommandHandler = None,
     ):
@@ -101,6 +104,8 @@ def __init__(
         :param attributes: cover attributes
         :param device_class: optional cover device class
         :param options: options
+        :param icon: optional icon
+        :param description: optional description, either a string or a language dictionary
         :param area: optional area
         :param cmd_handler: handler for entity commands
         """
@@ -112,6 +117,8 @@ def __init__(
             attributes,
             device_class=device_class,
             options=options,
+            icon=icon,
+            description=description,
             area=area,
             cmd_handler=cmd_handler,
         )

ucapi/entities.py

@@ -102,6 +102,10 @@ def get_all(self) -> list[dict[str, Any]]:
                 "features": entity.features,
                 "name": entity.name,
             }
+            if entity.icon:
+                res["icon"] = entity.icon
+            if entity.description:
+                res["description"] = entity.description
             if entity.device_class:
                 res["device_class"] = entity.device_class
             if entity.options:

ucapi/entity.py

@@ -82,6 +82,8 @@ def __init__(
         *,
         device_class: str | None = None,
         options: dict[str, Any] | None = None,
+        icon: str | None = None,
+        description: str | dict[str, str] | None = None,
         area: str | None = None,
         cmd_handler: CommandHandler = None,
     ):
@@ -95,12 +97,20 @@ def __init__(
         :param attributes: entity attributes
         :param device_class: entity device class
         :param options: entity options
+        :param icon: optional icon
+        :param description: optional description, either a string or a language dictionary
         :param area: optional area name
         :param cmd_handler: optional handler for entity commands
         """
         self.id = identifier
         self.name = {"en": name} if isinstance(name, str) else name
         self.entity_type = entity_type
+        self.icon = icon
+        self.description = (
+            ({"en": description} if isinstance(description, str) else description)
+            if description
+            else None
+        )
         self.device_id = None
         self.features = features
         self.attributes = attributes

ucapi/ir_emitter.py

@@ -67,6 +67,8 @@ def __init__(
         attributes: dict[str, Any],
         *,
         options: dict[str, Any] | None = None,
+        icon: str | None = None,
+        description: str | dict[str, str] | None = None,
         area: str | None = None,
         cmd_handler: CommandHandler = None,
     ):
@@ -78,6 +80,8 @@ def __init__(
         :param features: IR Emitter features
         :param attributes: IR Emitter attributes
         :param options: IR Emitter options
+        :param icon: optional icon
+        :param description: optional description, either a string or a language dictionary
         :param area: optional area
         :param cmd_handler: handler for entity commands
         """
@@ -88,6 +92,8 @@ def __init__(
             features,
             attributes,
             options=options,
+            icon=icon,
+            description=description,
             area=area,
             cmd_handler=cmd_handler,
         )

ucapi/light.py

@@ -74,8 +74,11 @@ def __init__(
         name: str | dict[str, str],
         features: list[Features],
         attributes: dict[str, Any],
+        *,
         device_class: DeviceClasses | None = None,
         options: dict[str, Any] | None = None,
+        icon: str | None = None,
+        description: str | dict[str, str] | None = None,
         area: str | None = None,
         cmd_handler: CommandHandler = None,
     ):
@@ -88,6 +91,8 @@ def __init__(
         :param attributes: light attributes
         :param device_class: optional light device class
         :param options: options
+        :param icon: optional icon
+        :param description: optional description, either a string or a language dictionary
         :param area: optional area
         :param cmd_handler: handler for entity commands
         """
@@ -99,6 +104,8 @@ def __init__(
             attributes,
             device_class=device_class,
             options=options,
+            icon=icon,
+            description=description,
             area=area,
             cmd_handler=cmd_handler,
         )

ucapi/media_player.py

@@ -669,8 +669,11 @@ def __init__(
         name: str | dict[str, str],
         features: list[Features],
         attributes: dict[str, Any],
+        *,
         device_class: DeviceClasses | None = None,
         options: dict[str, Any] | None = None,
+        icon: str | None = None,
+        description: str | dict[str, str] | None = None,
         area: str | None = None,
         cmd_handler: CommandHandler = None,
     ):
@@ -683,6 +686,8 @@ def __init__(
         :param attributes: media-player attributes
         :param device_class: optional media-player device class
         :param options: options
+        :param icon: optional icon
+        :param description: optional description, either a string or a language dictionary
         :param area: optional area
         :param cmd_handler: handler for entity commands
         """
@@ -694,6 +699,8 @@ def __init__(
             attributes,
             device_class=device_class,
             options=options,
+            icon=icon,
+            description=description,
             area=area,
             cmd_handler=cmd_handler,
         )

ucapi/remote.py

@@ -128,9 +128,12 @@ def __init__(
         name: str | dict[str, str],
         features: list[Features],
         attributes: dict[str, Any],
+        *,
         simple_commands: list[str] | None = None,
         button_mapping: list[DeviceButtonMapping | dict[str, Any]] | None = None,
         ui_pages: list[UiPage | dict[str, Any]] | None = None,
+        icon: str | None = None,
+        description: str | dict[str, str] | None = None,
         area: str | None = None,
         cmd_handler: CommandHandler = None,
     ):
@@ -146,6 +149,8 @@ def __init__(
                Either with DeviceButtonMapping items or plain dictionary items.
         :param ui_pages: optional user interface page definitions.
                Either with UiPage items or plain dictionary items.
+        :param icon: optional icon
+        :param description: optional description, either a string or a language dictionary
         :param area: optional area
         :param cmd_handler: handler for entity commands
         """
@@ -163,6 +168,8 @@ def __init__(
             features,
             attributes,
             options=options,
+            icon=icon,
+            description=description,
             area=area,
             cmd_handler=cmd_handler,
         )

ucapi/select.py

@@ -65,6 +65,8 @@ def __init__(
         name: str | dict[str, str],
         attributes: dict[str, Any],
         *,
+        icon: str | None = None,
+        description: str | dict[str, str] | None = None,
         area: str | None = None,
         cmd_handler: CommandHandler = None,
     ):
@@ -74,6 +76,8 @@ def __init__(
         :param identifier: entity identifier
         :param name: friendly name
         :param attributes: select attributes
+        :param icon: optional icon
+        :param description: optional description, either a string or a language dictionary
         :param area: optional area
         :param cmd_handler: handler for entity commands
         """
@@ -83,6 +87,8 @@ def __init__(
             EntityTypes.SELECT,
             [],
             attributes,
+            icon=icon,
+            description=description,
             area=area,
             cmd_handler=cmd_handler,
         )

ucapi/sensor.py

@@ -108,8 +108,11 @@ def __init__(
         name: str | dict[str, str],
         features: list[Features],
         attributes: dict[str, Any],
+        *,
         device_class: DeviceClasses | None = None,
         options: dict[str, Any] | None = None,
+        icon: str | None = None,
+        description: str | dict[str, str] | None = None,
         area: str | None = None,
     ):
         """
@@ -121,6 +124,8 @@ def __init__(
         :param attributes: sensor attributes
         :param device_class: optional sensor device class
         :param options: options
+        :param icon: optional icon
+        :param description: optional description, either a string or a language dictionary
         :param area: optional area
         """
         super().__init__(
@@ -131,5 +136,7 @@ def __init__(
             attributes,
             device_class=device_class,
             options=options,
+            icon=icon,
+            description=description,
             area=area,
         )

ucapi/switch.py

@@ -70,8 +70,11 @@ def __init__(
         name: str | dict[str, str],
         features: list[Features],
         attributes: dict[str, Any],
+        *,
         device_class: DeviceClasses | None = None,
         options: dict[str, Any] | None = None,
+        icon: str | None = None,
+        description: str | dict[str, str] | None = None,
         area: str | None = None,
         cmd_handler: CommandHandler = None,
     ):
@@ -84,6 +87,8 @@ def __init__(
         :param attributes: switch attributes
         :param device_class: optional switch device class
         :param options: options
+        :param icon: optional icon
+        :param description: optional description, either a string or a language dictionary
         :param area: optional area
         :param cmd_handler: handler for entity commands
         """
@@ -95,6 +100,8 @@ def __init__(
             attributes,
             device_class=device_class,
             options=options,
+            icon=icon,
+            description=description,
             area=area,
             cmd_handler=cmd_handler,
         )

ucapi/voice_assistant.py

@@ -300,7 +300,10 @@ def __init__(
         name: str | dict[str, str],
         features: list[Features],
         attributes: dict[str, Any],
+        *,
         options: dict[str, Any] | VoiceAssistantEntityOptions | None = None,
+        icon: str | None = None,
+        description: str | dict[str, str] | None = None,
         area: str | None = None,
         cmd_handler: CommandHandler = None,
     ) -> None:
@@ -311,6 +314,8 @@ def __init__(
         :param features: voice assistant features
         :param attributes: voice assistant attributes
         :param options: voice assistant options
+        :param icon: optional icon
+        :param description: optional description, either a string or a language dictionary
         :param area: optional area
         :param cmd_handler: handler for entity commands
         """
@@ -325,6 +330,8 @@ def __init__(
                 if isinstance(options, dict)
                 else (None if options is None else asdict(options))
             ),
+            icon=icon,
+            description=description,
             area=area,
             cmd_handler=cmd_handler,
         )