unfoldedcircle/integration-python-library

Python API wrapper for the Unfolded Circle Integration API

integration-python-library's Issues

Simplify entity attribute updates

At the moment one has to use the ucapi.configured_entities.update_attributes method to change an entity attribute.

With the new entity command handler, this is a bit akward. The received entity object should allow direct attribute updates, which also trigger a change event. Directly modifying an attribute on the received entity will not trigger any events.

Proposed changes:

• add an update_attribute method to the entity class
  • either a generic method for all subclassed entities, or a concrete method per entity.
  • for most use cases, a single attribute update is enough. But there are cases where multiple attributes must be updated at the same time, e.g. for light color changes.
    • Either add an additional update_attributes method, or design a single method which allows both.
• changed attributes will trigger a change event

This could then be used in a command handler:

async def switch_cmd_handler(
    entity: ucapi.Switch, cmd_id: str, _params: dict[str, Any] | None
) -> ucapi.StatusCodes:
    print(f"Got {entity.id} command request: {cmd_id}")

    state = None
    if cmd_id == switch.Commands.ON:
        # implement ON logic...
        state = switch.States.ON
    elif cmd_id == switch.Commands.OFF:
        # implement OFF logic...
        state = switch.States.OFF

    if state:
        entity.update_attribute(switch.Attributes.STATE, state)

    return ucapi.StatusCodes.OK

UC_INTEGRATION_INTERFACE is an optional ENV var

The UC_INTEGRATION_INTERFACE environment variable is an optional setting to configure the listening interface.

Current behaviour is that if it is not set, the WebSocket listening doesn't work.

Expected: optional env var, if not set use 0.0.0.0

Refactor entity management

The separate backing lists for available and configured entities makes it more difficult for the integrations to properly manage entity states and attributes.
Furthermore, the get_available_entities should return all entities, no matter if the Remote Two has subscribed to certain entities or not. (This probably needs some clarifications in the WebSocket Integration-API as well).
There should only be one backing list with either additional attributes or metadata holding the subscription state.

How to use? setup.py install is deprecated

/opt/homebrew/lib/python3.11/site-packages/setuptools/_distutils/cmd.py:66: SetuptoolsDeprecationWarning: setup.py install is deprecated.
!!

        ********************************************************************************
        Please avoid running ``setup.py`` directly.
        Instead, use pypa/build, pypa/installer or other
        standards-based tools.

        See https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html for details.
        ********************************************************************************

!!

Where's the wheelfile.whl mentionend in the README pip3 install /path/to/wheelfile.whl?

As long as this library isn't published, can't it be referenced with a relative path in requirements.txt of an integration?

Integrations crash if UC_INTEGRATION_HTTP_PORT ENV var is not set

Integrations crash if UC_INTEGRATION_HTTP_PORT is not set:

  File "/Users/mzehnder/projects/personal/yio-remote/aitatoi/integration-denonavr/venv/lib/python3.11/site-packages/ucapi/api.py", line 67, in init
    self.driverInfo["driver_url"] = self.getDriverUrl(
                                    ^^^^^^^^^^^^^^^^^^
  File "/Users/mzehnder/projects/personal/yio-remote/aitatoi/integration-denonavr/venv/lib/python3.11/site-packages/ucapi/api.py", line 108, in getDriverUrl
    return "ws://" + self._interface + ":" + port
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^~~~~~
TypeError: can only concatenate str (not "NoneType") to str

Expected: no runtime error, defined error and exit code if a required setting is missing.
There should also be a default port if the integration doesn't overwrite it. AFAIK the Node library has a default port set.

Filter out base64 encoded images in json message log

Some integrations send base64 encoded images in the media_image_url field. This causes excessive logging and needs to be filtered out.

[QUESTION]: How to listen for `get_available_entities`

This may a be a daft question... how would I listen to the WsMessages.GET_AVAILABLE_ENTITIES so that I can rebuild the list of available entities? This message seems to be issued when the Reload link is clicked in the Web Configurator.

What I'm trying to achieve... As I iterate through building the integration I will be adding new entities (mainly buttons) and quite possibly removing them too. I'm looking for a way to effectively be able to build those entities for both a new setup and for an existing setup. In addition any buttons I remove should also be removed (or at the very list flagged for removal).

I hope this makes sense.