pywemo 1.4.0__py3-none-any.whl

pywemo/README.md

@@ -0,0 +1,69 @@
+# API Documentation
+
+For example usage and installation instructions see 
+[README.rst](https://github.com/pywemo/pywemo/blob/main/README.rst)
+
+## General structure of the pyWeMo API
+
+### Discovery
+
+The `pywemo.discovery` module contains methods to locate WeMo devices on a
+network. For example, use the following to discover all devices on the
+network:
+
+```python
+>>> import pywemo
+>>> devices = pywemo.discover_devices()
+>>> print(devices)
+[<WeMo Insight "AC Insight">]
+```
+
+Or, if you know the IP address of the device, use this example.
+
+```python
+>>> import pywemo
+>>> url = pywemo.setup_url_for_address("192.168.1.192")
+>>> print(url)
+http://192.168.1.192:49153/setup.xml
+>>> device = pywemo.device_from_description(url)
+>>> print(device)
+[<WeMo Insight "AC Insight">]
+```
+
+### Devices
+
+The device(s) returned by the discovery methods above will be instances of one
+of the classes below. These classes, used for communicating with the various
+WeMo devices, are in submodules under the `pywemo.ouimeaux_device` module. They
+can also be accessed as top-level members of the pywemo module.
+
+WeMo Model|Alias / Class
+----------|-------------
+  F7C031  |`pywemo.Bridge` / `pywemo.ouimeaux_device.bridge.Bridge`
+  F7C050  |`pywemo.CoffeeMaker` / `pywemo.ouimeaux_device.coffeemaker.CoffeeMaker`
+  F7C045  |`pywemo.CrockPot` / `pywemo.ouimeaux_device.crockpot.CrockPot`
+  F7C059  |`pywemo.DimmerLongPress` / `pywemo.ouimeaux_device.dimmer.DimmerLongPress`
+  WDS060  |`pywemo.DimmerV2` / `pywemo.ouimeaux_device.dimmer.DimmerV2`
+  F7C046  |`pywemo.Humidifier` / `pywemo.ouimeaux_device.humidifier.Humidifier`
+  F7C029  |`pywemo.Insight` / `pywemo.ouimeaux_device.insight.Insight`
+  F7C030  |`pywemo.LightSwitchLongPress` / `pywemo.ouimeaux_device.lightswitch.LightSwitchLongPress`
+  WLS040  |`pywemo.LightSwitchLongPress` / `pywemo.ouimeaux_device.lightswitch.LightSwitchLongPress`
+  WLS0403 |`pywemo.LightSwitchLongPress` / `pywemo.ouimeaux_device.lightswitch.LightSwitchLongPress`
+  F7C043  |`pywemo.Maker` / `pywemo.ouimeaux_device.maker.Maker`
+  F7C028  |`pywemo.Motion` / `pywemo.ouimeaux_device.motion.Motion`
+  WSP090  |`pywemo.OutdoorPlug` / `pywemo.ouimeaux_device.outdoor_plug.OutdoorPlug`
+  F7C027  |`pywemo.Switch` / `pywemo.ouimeaux_device.switch.Switch`
+  F7C063  |`pywemo.Switch` / `pywemo.ouimeaux_device.switch.Switch`
+  WSP080  |`pywemo.Switch` / `pywemo.ouimeaux_device.switch.Switch`
+
+The following are base classes of all of the above device classes.
+
+* pywemo.ouimeaux_device.Device: Provides common methods for getting/setting
+  device state.
+* pywemo.ouimeaux_device.api.xsd_types.DeviceDescription: Provides information
+  about the device name, mac address, firmware version, serial number, etc.
+
+### Subscriptions
+
+Most WeMo devices support a push/callback model for reporting state changes.
+The `pywemo.subscribe` module provides a way to subscribe to push events.

pywemo/__init__.py

@@ -0,0 +1,33 @@
+r"""Lightweight Python module to discover and control WeMo devices.
+.. include:: README.md
+"""
+# flake8: noqa F401
+
+from .discovery import (
+    device_from_description,
+    discover_devices,
+    setup_url_for_address,
+)
+from .exceptions import PyWeMoException
+from .ouimeaux_device import Device as WeMoDevice
+from .ouimeaux_device.api.long_press import LongPressMixin
+from .ouimeaux_device.api.service import Action, Service
+from .ouimeaux_device.bridge import Bridge
+from .ouimeaux_device.bridge import Group as BridgeGroup
+from .ouimeaux_device.bridge import Light as BridgeLight
+from .ouimeaux_device.coffeemaker import CoffeeMaker, CoffeeMakerMode
+from .ouimeaux_device.crockpot import CrockPot, CrockPotMode
+from .ouimeaux_device.dimmer import Dimmer, DimmerLongPress, DimmerV2
+from .ouimeaux_device.humidifier import (
+    DesiredHumidity,
+    FanMode,
+    Humidifier,
+    WaterLevel,
+)
+from .ouimeaux_device.insight import Insight, StandbyState
+from .ouimeaux_device.lightswitch import LightSwitch, LightSwitchLongPress
+from .ouimeaux_device.maker import Maker
+from .ouimeaux_device.motion import Motion
+from .ouimeaux_device.outdoor_plug import OutdoorPlug
+from .ouimeaux_device.switch import Switch
+from .subscribe import SubscriptionRegistry

pywemo/color.py

@@ -0,0 +1,79 @@
+"""Various utilities for handling colors."""
+from __future__ import annotations
+
+from typing import Tuple
+
+# Define usable ranges as bulbs either ignore or behave unexpectedly
+# when it is sent a value is outside of the range.
+TemperatureRange = Tuple[int, int]
+TEMPERATURE_PROFILES: dict[str, TemperatureRange] = dict(
+    (model, temp)
+    for models, temp in (
+        # Lightify RGBW, 1900-6500K
+        (["LIGHTIFY A19 RGBW"], (151, 555)),
+    )
+    for model in models
+)
+
+ColorXY = Tuple[float, float]
+ColorGamut = Tuple[ColorXY, ColorXY, ColorXY]
+COLOR_PROFILES: dict[str, ColorGamut] = dict(
+    (model, gamut)
+    for models, gamut in (
+        # Lightify RGBW, 1900-6500K
+        # https://flow-morewithless.blogspot.com/2015/01/osram-lightify-color-gamut-and-spectrum.html
+        (
+            ["LIGHTIFY A19 RGBW"],
+            ((0.683924, 0.315904), (0.391678, 0.501414), (0.136990, 0.051035)),
+        ),
+    )
+    for model in models
+)
+
+
+def get_profiles(model: str) -> tuple[TemperatureRange, ColorGamut]:
+    """Return the temperature and color profiles for a given model."""
+    return (
+        TEMPERATURE_PROFILES.get(model, (150, 600)),
+        COLOR_PROFILES.get(model, ((1.0, 0.0), (0.0, 1.0), (0.0, 0.0))),
+    )
+
+
+def is_same_side(p1: ColorXY, p2: ColorXY, a: ColorXY, b: ColorXY) -> bool:
+    """Test if points p1 and p2 lie on the same side of line a-b."""
+    # pylint: disable=invalid-name
+    vector_ab = [y - x for x, y in zip(a, b)]
+    vector_ap1 = [y - x for x, y in zip(a, p1)]
+    vector_ap2 = [y - x for x, y in zip(a, p2)]
+    cross_vab_ap1 = vector_ab[0] * vector_ap1[1] - vector_ab[1] * vector_ap1[0]
+    cross_vab_ap2 = vector_ab[0] * vector_ap2[1] - vector_ab[1] * vector_ap2[0]
+    return (cross_vab_ap1 * cross_vab_ap2) >= 0
+
+
+def closest_point(p: ColorXY, a: ColorXY, b: ColorXY) -> ColorXY:
+    """Test if points p1 and p2 lie on the same side of line a-b."""
+    # pylint: disable=invalid-name
+    vector_ab = [y - x for x, y in zip(a, b)]
+    vector_ap = [y - x for x, y in zip(a, p)]
+    dot_ap_ab = sum(x * y for x, y in zip(vector_ap, vector_ab))
+    dot_ab_ab = sum(x * y for x, y in zip(vector_ab, vector_ab))
+    t = max(0.0, min(dot_ap_ab / dot_ab_ab, 1.0))
+    return a[0] + vector_ab[0] * t, a[1] + vector_ab[1] * t
+
+
+def limit_to_gamut(xy: ColorXY, gamut: ColorGamut) -> ColorXY:
+    """Return the closest point within the gamut triangle for colorxy."""
+    # pylint: disable=invalid-name
+    r, g, b = gamut
+
+    # http://www.blackpawn.com/texts/pointinpoly/
+    if not is_same_side(xy, r, g, b):
+        xy = closest_point(xy, g, b)
+
+    if not is_same_side(xy, g, b, r):
+        xy = closest_point(xy, b, r)
+
+    if not is_same_side(xy, b, r, g):
+        xy = closest_point(xy, r, g)
+
+    return xy

pywemo/discovery.py

@@ -0,0 +1,194 @@
+"""Module to discover WeMo devices."""
+from __future__ import annotations
+
+import logging
+from ipaddress import ip_address
+from socket import gaierror, gethostbyname
+from typing import Any, Callable
+
+import requests
+
+from . import ssdp
+from .exceptions import (
+    InvalidSchemaError,
+    MissingServiceError,
+    PyWeMoException,
+)
+from .ouimeaux_device import Device, UnsupportedDevice, probe_wemo
+from .ouimeaux_device.api.service import REQUESTS_TIMEOUT
+from .ouimeaux_device.api.xsd_types import DeviceDescription
+from .ouimeaux_device.bridge import Bridge
+from .ouimeaux_device.coffeemaker import CoffeeMaker
+from .ouimeaux_device.crockpot import CrockPot
+from .ouimeaux_device.dimmer import Dimmer, DimmerLongPress, DimmerV2
+from .ouimeaux_device.humidifier import Humidifier
+from .ouimeaux_device.insight import Insight
+from .ouimeaux_device.lightswitch import LightSwitch, LightSwitchLongPress
+from .ouimeaux_device.maker import Maker
+from .ouimeaux_device.motion import Motion
+from .ouimeaux_device.outdoor_plug import OutdoorPlug
+from .ouimeaux_device.switch import Switch
+
+LOG = logging.getLogger(__name__)
+_uuid_seen = set()  # See _call_once_per_uuid.
+
+
+def _call_once_per_uuid(
+    uuid: str, method: Callable[..., Any], *args: Any, **kwargs: Any
+) -> None:
+    key = (uuid, method)
+    if key in _uuid_seen:
+        return
+    _uuid_seen.add(key)
+    method(*args, *kwargs)
+
+
+def discover_devices(*, debug: bool = False, **kwargs: Any) -> list[Device]:
+    """Find WeMo devices on the local network."""
+    devices = (
+        device_from_uuid_and_location(entry.udn, entry.location, debug=debug)
+        for entry in ssdp.scan(**kwargs)
+    )
+    return [d for d in devices if d is not None]
+
+
+def device_from_description(
+    description_url: str, *, debug: bool = False
+) -> Device | None:
+    """Return object representing WeMo device running at host, else None."""
+    try:
+        xml = requests.get(description_url, timeout=REQUESTS_TIMEOUT)
+    except requests.RequestException:
+        LOG.exception("Failed to fetch description %s", description_url)
+        return None
+
+    try:
+        device = DeviceDescription.from_xml(xml.content)
+    except PyWeMoException:
+        LOG.exception("Failed to parse description %s", description_url)
+        return None
+
+    return device_from_uuid_and_location(
+        device.udn, description_url, debug=debug
+    )
+
+
+def device_from_uuid_and_location(  # noqa: C901
+    # pylint: disable=too-many-branches,too-many-return-statements
+    uuid: str | None,
+    location: str | None,
+    *,
+    debug: bool = False,
+) -> Device | None:
+    """Determine device class based on the device uuid."""
+    if not (uuid and location):
+        return None
+    try:
+        if uuid.startswith("uuid:Socket"):
+            return Switch(location)
+        if uuid.startswith("uuid:Lightswitch-1_0"):
+            if not location.endswith("/setup.xml"):
+                return LightSwitch(location)
+            return LightSwitchLongPress(location)
+        if uuid.startswith("uuid:Lightswitch-2_0"):
+            return LightSwitchLongPress(location)
+        if uuid.startswith("uuid:Lightswitch-3_0"):
+            return LightSwitchLongPress(location)
+        if uuid.startswith("uuid:Lightswitch"):
+            return LightSwitch(location)
+        if uuid.startswith("uuid:Dimmer-1_0"):
+            return DimmerLongPress(location)
+        if uuid.startswith("uuid:Dimmer-2_0"):
+            return DimmerV2(location)
+        if uuid.startswith("uuid:Dimmer"):
+            return Dimmer(location)
+        if uuid.startswith("uuid:Insight"):
+            return Insight(location)
+        if uuid.startswith("uuid:Sensor"):
+            return Motion(location)
+        if uuid.startswith("uuid:Maker"):
+            return Maker(location)
+        if uuid.startswith("uuid:Bridge"):
+            return Bridge(location)
+        if uuid.startswith("uuid:CoffeeMaker"):
+            return CoffeeMaker(location)
+        if uuid.startswith("uuid:Crockpot"):
+            return CrockPot(location)
+        if uuid.startswith("uuid:Humidifier"):
+            return Humidifier(location)
+        if uuid.startswith("uuid:OutdoorPlug"):
+            return OutdoorPlug(location)
+    except (InvalidSchemaError, MissingServiceError) as err:
+        _call_once_per_uuid(
+            uuid,
+            LOG.info,
+            "pyWeMo encountered a non-WeMo device %s %s: %r",
+            uuid,
+            location,
+            err,
+        )
+        # Fall-through: Try UnsupportedDevice if debug is enabled.
+    except PyWeMoException:
+        _call_once_per_uuid(
+            uuid, LOG.exception, "Device setup failed %s %s", uuid, location
+        )
+        # Fall-through: Try UnsupportedDevice if debug is enabled.
+
+    if uuid.startswith("uuid:") and debug:
+        # unsupported device, but if this function was called from
+        # discover_devices then this should be a Belkin product and is probably
+        # a WeMo product without a custom class yet.  So attempt to return a
+        # basic object to allow manual interaction.
+        try:
+            device = UnsupportedDevice(location)
+        except PyWeMoException:
+            LOG.exception("Device setup failed %s %s", uuid, location)
+        else:
+            LOG.info(
+                "Device with %s is not supported by pywemo, returning "
+                "UnsupportedDevice object to allow manual interaction",
+                uuid,
+            )
+            return device
+
+    return None
+
+
+def hostname_lookup(hostname: str) -> str:
+    """Resolve a hostname into an IP address."""
+    try:
+        # The {host} must be resolved to an IP address; if this fails, this
+        # will throw a socket.gaierror.
+        host_address = gethostbyname(hostname)
+
+        # Reset {host} to the resolved address.
+        LOG.debug(
+            "Resolved hostname %s to IP address %s.", hostname, host_address
+        )
+        return host_address
+
+    except gaierror:
+        # The {host}-as-hostname did not resolve to an IP address.
+        LOG.debug("Could not resolve hostname %s to an IP address.", hostname)
+        return hostname
+
+
+def setup_url_for_address(host: str, port: int | None = None) -> str | None:
+    """Determine setup.xml url for a given host and port pair."""
+    # Force hostnames into IP addresses
+    try:
+        # Attempt to register {host} as an IP address; if this fails ({host} is
+        # not an IP address), this will throw a ValueError.
+        ip_address(host)
+    except ValueError:
+        # The provided {host} should be treated as a hostname.
+        host = hostname_lookup(host)
+
+    # Automatically determine the port if not provided.
+    if not port:
+        port = probe_wemo(host)
+
+    if not port:
+        return None
+
+    return f"http://{host}:{port}/setup.xml"

pywemo/exceptions.py

@@ -0,0 +1,94 @@
+"""Exceptions raised by pywemo."""
+from __future__ import annotations
+
+from lxml import etree as et
+
+
+class PyWeMoException(Exception):
+    """Base exception class for pyWeMo exceptions."""
+
+
+class ActionException(PyWeMoException):
+    """Generic exceptions when dealing with SOAP request Actions."""
+
+
+class SOAPFault(ActionException):
+    """Raised when the SOAP response contains a Fault message."""
+
+    fault_code: str = ""
+    fault_string: str = ""
+    error_code: str = ""
+    error_description: str = ""
+
+    def __init__(
+        self, message: str = "", fault_element: et._Element | None = None
+    ) -> None:
+        """Initialize from a SOAP Fault lxml.etree Element."""
+        details = ""
+        if fault_element is not None:
+            upnp_error_prefix = (
+                "detail"
+                "/{urn:schemas-upnp-org:control-1-0}UPnPError/"
+                "{urn:schemas-upnp-org:control-1-0}"
+            )
+            self.fault_code = fault_element.findtext("faultcode", "")
+            self.fault_string = fault_element.findtext("faultstring", "")
+            self.error_code = fault_element.findtext(
+                f"{upnp_error_prefix}errorCode", ""
+            )
+            self.error_description = fault_element.findtext(
+                f"{upnp_error_prefix}errorDescription", ""
+            )
+            details = (
+                f" SOAP Fault {self.fault_code}:{self.fault_string}, "
+                f"{self.error_code}:{self.error_description}"
+            )
+        super().__init__(f"{message}{details}")
+
+
+class SubscriptionRegistryFailed(PyWeMoException):
+    """General exceptions related to the subscription registry."""
+
+
+class UnknownService(PyWeMoException):
+    """Exception raised when a non-existent service is called."""
+
+
+class ResetException(PyWeMoException):
+    """Exception raised when reset fails."""
+
+
+class SetupException(PyWeMoException):
+    """Exception raised when setup fails."""
+
+
+class APNotFound(SetupException):
+    """Exception raised when the AP requested is not found."""
+
+
+class ShortPassword(SetupException):
+    """Exception raised when a password is too short (<8 characters)."""
+
+
+class HTTPException(PyWeMoException):
+    """HTTP request to the device failed."""
+
+
+class HTTPNotOkException(HTTPException):
+    """Raised when a non-200 status is returned."""
+
+
+class RulesDbError(PyWeMoException):
+    """Base class for errors related to the Rules database."""
+
+
+class RulesDbQueryError(RulesDbError):
+    """Exception when querying the rules database."""
+
+
+class InvalidSchemaError(PyWeMoException):
+    """Raised when an unexpected XML response is received."""
+
+
+class MissingServiceError(PyWeMoException):
+    """All required services were not found in the device schema."""

pywemo/ouimeaux_device/LICENSE

@@ -0,0 +1,12 @@
+Copyright (c) 2014, Ian McCracken
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+* Neither the name of ouimeaux nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.