Merge branch 'pep257-light' into dev

homeassistant/components/light/__init__.py

@@ -1,6 +1,4 @@
 """
-homeassistant.components.light
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Provides functionality to interact with lights.
 
 For more details about this component, please refer to the documentation at
@@ -30,26 +28,26 @@ ENTITY_ID_ALL_LIGHTS = group.ENTITY_ID_FORMAT.format('all_lights')
 
 ENTITY_ID_FORMAT = DOMAIN + ".{}"
 
-# integer that represents transition time in seconds to make change
+# Integer that represents transition time in seconds to make change.
 ATTR_TRANSITION = "transition"
 
-# lists holding color values
+# Lists holding color values
 ATTR_RGB_COLOR = "rgb_color"
 ATTR_XY_COLOR = "xy_color"
 ATTR_COLOR_TEMP = "color_temp"
 
-# int with value 0 .. 255 representing brightness of the light
+# int with value 0 .. 255 representing brightness of the light.
 ATTR_BRIGHTNESS = "brightness"
 
-# String representing a profile (built-in ones or external defined)
+# String representing a profile (built-in ones or external defined).
 ATTR_PROFILE = "profile"
 
-# If the light should flash, can be FLASH_SHORT or FLASH_LONG
+# If the light should flash, can be FLASH_SHORT or FLASH_LONG.
 ATTR_FLASH = "flash"
 FLASH_SHORT = "short"
 FLASH_LONG = "long"
 
-# Apply an effect to the light, can be EFFECT_COLORLOOP
+# Apply an effect to the light, can be EFFECT_COLORLOOP.
 ATTR_EFFECT = "effect"
 EFFECT_COLORLOOP = "colorloop"
 EFFECT_RANDOM = "random"
@@ -57,7 +55,7 @@ EFFECT_WHITE = "white"
 
 LIGHT_PROFILES_FILE = "light_profiles.csv"
 
-# Maps discovered services to their platforms
+# Maps discovered services to their platforms.
 DISCOVERY_PLATFORMS = {
     wemo.DISCOVER_LIGHTS: 'wemo',
     wink.DISCOVER_LIGHTS: 'wink',
@@ -79,9 +77,8 @@ _LOGGER = logging.getLogger(__name__)
 
 
 def is_on(hass, entity_id=None):
-    """ Returns if the lights are on based on the statemachine. """
+    """Return if the lights are on based on the statemachine."""
     entity_id = entity_id or ENTITY_ID_ALL_LIGHTS
-
     return hass.states.is_state(entity_id, STATE_ON)
 
 
@@ -89,7 +86,7 @@ def is_on(hass, entity_id=None):
 def turn_on(hass, entity_id=None, transition=None, brightness=None,
             rgb_color=None, xy_color=None, color_temp=None, profile=None,
             flash=None, effect=None):
-    """ Turns all or specified light on. """
+    """Turn all or specified light on."""
     data = {
         key: value for key, value in [
             (ATTR_ENTITY_ID, entity_id),
@@ -108,7 +105,7 @@ def turn_on(hass, entity_id=None, transition=None, brightness=None,
 
 
 def turn_off(hass, entity_id=None, transition=None):
-    """ Turns all or specified light off. """
+    """Turn all or specified light off."""
     data = {
         key: value for key, value in [
             (ATTR_ENTITY_ID, entity_id),
@@ -120,7 +117,7 @@ def turn_off(hass, entity_id=None, transition=None):
 
 
 def toggle(hass, entity_id=None, transition=None):
-    """ Toggles all or specified light. """
+    """Toggle all or specified light."""
     data = {
         key: value for key, value in [
             (ATTR_ENTITY_ID, entity_id),
@@ -133,8 +130,7 @@ def toggle(hass, entity_id=None, transition=None):
 
 # pylint: disable=too-many-branches, too-many-locals, too-many-statements
 def setup(hass, config):
-    """ Exposes light control via statemachine and services. """
+    """Expose light control via statemachine and services."""
-
     component = EntityComponent(
         _LOGGER, DOMAIN, hass, SCAN_INTERVAL, DISCOVERY_PLATFORMS,
         GROUP_NAME_ALL_LIGHTS)
@@ -197,11 +193,11 @@ def setup(hass, config):
                     light.update_ha_state(True)
             return
 
-        # Processing extra data for turn light on request
+        # Processing extra data for turn light on request.
 
         # We process the profile first so that we get the desired
         # behavior that extra service data attributes overwrite
-        # profile values
+        # profile values.
         profile = profiles.get(dat.get(ATTR_PROFILE))
 
         if profile:
@@ -215,10 +211,10 @@ def setup(hass, config):
 
         if ATTR_XY_COLOR in dat:
             try:
-                # xy_color should be a list containing 2 floats
+                # xy_color should be a list containing 2 floats.
                 xycolor = dat.get(ATTR_XY_COLOR)
 
-                # Without this check, a xycolor with value '99' would work
+                # Without this check, a xycolor with value '99' would work.
                 if not isinstance(xycolor, str):
                     params[ATTR_XY_COLOR] = [float(val) for val in xycolor]
 
@@ -263,7 +259,7 @@ def setup(hass, config):
             if light.should_poll:
                 light.update_ha_state(True)
 
-    # Listen for light on and light off service calls
+    # Listen for light on and light off service calls.
     descriptions = load_yaml_config_file(
         os.path.join(os.path.dirname(__file__), 'services.yaml'))
     hass.services.register(DOMAIN, SERVICE_TURN_ON, handle_light_service,
@@ -279,32 +275,32 @@ def setup(hass, config):
 
 
 class Light(ToggleEntity):
-    """ Represents a light within Home Assistant. """
+    """Representation of a light."""
-    # pylint: disable=no-self-use
 
+    # pylint: disable=no-self-use
     @property
     def brightness(self):
-        """ Brightness of this light between 0..255. """
+        """Return the brightness of this light between 0..255."""
         return None
 
     @property
     def xy_color(self):
-        """ XY color value [float, float]. """
+        """Return the XY color value [float, float]."""
         return None
 
     @property
     def rgb_color(self):
-        """ RGB color value [int, int, int] """
+        """Return the RGB color value [int, int, int]."""
         return None
 
     @property
     def color_temp(self):
-        """ CT color value in mirads. """
+        """Return the CT color value in mirads."""
         return None
 
     @property
     def state_attributes(self):
-        """ Returns optional state attributes. """
+        """Return optional state attributes."""
         data = {}
 
         if self.is_on:

homeassistant/components/light/blinksticklight.py

@@ -1,6 +1,4 @@
 """
-homeassistant.components.light.blinksticklight
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Support for Blinkstick lights.
 
 For more details about this platform, please refer to the documentation at
@@ -27,9 +25,10 @@ def setup_platform(hass, config, add_devices_callback, discovery_info=None):
 
 
 class BlinkStickLight(Light):
-    """ Represents a BlinkStick light. """
+    """Representation of a BlinkStick light."""
 
     def __init__(self, stick, name):
+        """Initialize the light."""
         self._stick = stick
         self._name = name
         self._serial = stick.get_serial()
@@ -42,7 +41,7 @@ class BlinkStickLight(Light):
 
     @property
     def name(self):
-        """ The name of the light. """
+        """Return the name of the light."""
         return self._name
 
     @property
@@ -56,7 +55,7 @@ class BlinkStickLight(Light):
         return sum(self._rgb_color) > 0
 
     def update(self):
-        """ Read back the device state """
+        """Read back the device state."""
         self._rgb_color = self._stick.get_color()
 
     def turn_on(self, **kwargs):
@@ -71,5 +70,5 @@ class BlinkStickLight(Light):
                               blue=self._rgb_color[2])
 
     def turn_off(self, **kwargs):
-        """ Turn the device off """
+        """Turn the device off."""
         self._stick.turn_off()

homeassistant/components/light/demo.py

@@ -27,9 +27,11 @@ def setup_platform(hass, config, add_devices_callback, discovery_info=None):
 
 
 class DemoLight(Light):
-    """Provides a demo light."""
+    """Provide a demo light."""
+
     # pylint: disable=too-many-arguments
     def __init__(self, name, state, rgb=None, ct=None, brightness=180):
+        """Initialize the light."""
         self._name = name
         self._state = state
         self._rgb = rgb or random.choice(LIGHT_COLORS)

homeassistant/components/light/hue.py

@@ -1,6 +1,4 @@
 """
-homeassistant.components.light.hue
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Support for Hue lights.
 
 For more details about this platform, please refer to the documentation at
@@ -53,7 +51,7 @@ def _find_host_from_config(hass, filename=PHUE_CONFIG_FILE):
 
 
 def setup_platform(hass, config, add_devices_callback, discovery_info=None):
-    """ Gets the Hue lights. """
+    """Setup the Hue lights."""
     filename = config.get(CONF_FILENAME, PHUE_CONFIG_FILE)
     if discovery_info is not None:
         host = urlparse(discovery_info[1]).hostname
@@ -106,7 +104,7 @@ def setup_bridge(host, hass, add_devices_callback, filename):
 
     @util.Throttle(MIN_TIME_BETWEEN_SCANS, MIN_TIME_BETWEEN_FORCED_SCANS)
     def update_lights():
-        """ Updates the Hue light objects with latest info from the bridge. """
+        """Update the Hue light objects with latest info from the bridge."""
         try:
             api = bridge.get_api()
         except socket.error:
@@ -156,7 +154,7 @@ def request_configuration(host, hass, add_devices_callback, filename):
 
     # pylint: disable=unused-argument
     def hue_configuration_callback(data):
-        """ Actions to do when our configuration callback is called. """
+        """The actions to do when our configuration callback is called."""
         setup_bridge(host, hass, add_devices_callback, filename)
 
     _CONFIGURING[host] = configurator.request_config(
@@ -169,11 +167,12 @@ def request_configuration(host, hass, add_devices_callback, filename):
 
 
 class HueLight(Light):
-    """ Represents a Hue light """
+    """Representation of a Hue light."""
 
     # pylint: disable=too-many-arguments
     def __init__(self, light_id, info, bridge, update_lights,
                  bridge_type='hue'):
+        """Initialize the light."""
         self.light_id = light_id
         self.info = info
         self.bridge = bridge
@@ -182,35 +181,34 @@ class HueLight(Light):
 
     @property
     def unique_id(self):
-        """ Returns the id of this Hue light """
+        """Return the ID of this Hue light."""
         return "{}.{}".format(
             self.__class__, self.info.get('uniqueid', self.name))
 
     @property
     def name(self):
-        """ Get the mame of the Hue light. """
+        """Return the mame of the Hue light."""
         return self.info.get('name', DEVICE_DEFAULT_NAME)
 
     @property
     def brightness(self):
-        """ Brightness of this light between 0..255. """
+        """Return the brightness of this light between 0..255."""
         return self.info['state'].get('bri')
 
     @property
     def xy_color(self):
-        """ XY color value. """
+        """Return the XY color value."""
         return self.info['state'].get('xy')
 
     @property
     def color_temp(self):
-        """ CT color value. """
+        """Return the CT color value."""
         return self.info['state'].get('ct')
 
     @property
     def is_on(self):
-        """ True if device is on. """
+        """Return true if device is on."""
         self.update_lights()
-
         return self.info['state']['reachable'] and self.info['state']['on']
 
     def turn_on(self, **kwargs):

homeassistant/components/light/hyperion.py

@@ -1,6 +1,4 @@
 """
-homeassistant.components.light.hyperion
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Support for Hyperion remotes.
 
 For more details about this platform, please refer to the documentation at
@@ -18,7 +16,7 @@ REQUIREMENTS = []
 
 
 def setup_platform(hass, config, add_devices_callback, discovery_info=None):
-    """ Sets up a Hyperion server remote """
+    """Setup a Hyperion server remote."""
     host = config.get(CONF_HOST, None)
     port = config.get("port", 19444)
     device = Hyperion(host, port)
@@ -30,9 +28,10 @@ def setup_platform(hass, config, add_devices_callback, discovery_info=None):
 
 
 class Hyperion(Light):
-    """ Represents a Hyperion remote """
+    """Representation of a Hyperion remote."""
 
     def __init__(self, host, port):
+        """Initialize the light."""
         self._host = host
         self._port = port
         self._name = host
@@ -46,12 +45,12 @@ class Hyperion(Light):
 
     @property
     def rgb_color(self):
-        """ Last RGB color value set. """
+        """Return last RGB color value set."""
         return self._rgb_color
 
     @property
     def is_on(self):
-        """ True if the device is online. """
+        """Return true if the device is online."""
         return self._is_available
 
     def turn_on(self, **kwargs):
@@ -82,7 +81,7 @@ class Hyperion(Light):
         return False
 
     def json_request(self, request=None, wait_for_response=False):
-        """ Communicate with the json server. """
+        """Communicate with the JSON server."""
         sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
         sock.settimeout(5)
 
@@ -93,7 +92,7 @@ class Hyperion(Light):
             return False
 
         if not request:
-            # no communication needed, simple presence detection returns True
+            # No communication needed, simple presence detection returns True
             sock.close()
             return True
 
@@ -101,11 +100,11 @@ class Hyperion(Light):
         try:
             buf = sock.recv(4096)
         except socket.timeout:
-            # something is wrong, assume it's offline
+            # Something is wrong, assume it's offline
             sock.close()
             return False
 
-        # read until a newline or timeout
+        # Read until a newline or timeout
         buffering = True
         while buffering:
             if "\n" in str(buf, "utf-8"):

homeassistant/components/light/insteon_hub.py

@@ -1,14 +1,14 @@
 """
-homeassistant.components.light.insteon
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Support for Insteon Hub lights.
-"""
 
+For more details about this platform, please refer to the documentation at
+https://home-assistant.io/components/insteon_hub/
+"""
 from homeassistant.components.insteon_hub import INSTEON, InsteonToggleDevice
 
 
 def setup_platform(hass, config, add_devices, discovery_info=None):
-    """ Sets up the Insteon Hub light platform. """
+    """Setup the Insteon Hub light platform."""
     devs = []
     for device in INSTEON.devices:
         if device.DeviceCategory == "Switched Lighting Control":

homeassistant/components/light/isy994.py

@@ -1,6 +1,4 @@
 """
-homeassistant.components.light.isy994
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Support for ISY994 lights.
 
 For more details about this platform, please refer to the documentation at
@@ -15,15 +13,15 @@ from homeassistant.const import STATE_OFF, STATE_ON
 
 
 def setup_platform(hass, config, add_devices, discovery_info=None):
-    """ Sets up the ISY994 platform. """
+    """Setup the ISY994 platform."""
     logger = logging.getLogger(__name__)
     devs = []
-    # verify connection
+
     if ISY is None or not ISY.connected:
         logger.error('A connection has not been made to the ISY controller.')
         return False
 
-    # import dimmable nodes
+    # Import dimmable nodes
     for (path, node) in ISY.nodes:
         if node.dimmable and SENSOR_STRING not in node.name:
             if HIDDEN_STRING in path:
@@ -34,7 +32,7 @@ def setup_platform(hass, config, add_devices, discovery_info=None):
 
 
 class ISYLightDevice(ISYDeviceABC):
-    """ Represents as ISY light. """
+    """Representation of a ISY light."""
 
     _domain = 'light'
     _dtype = 'analog'

homeassistant/components/light/lifx.py

@@ -1,7 +1,5 @@
 """
-homeassistant.components.light.lifx
+Support for the LIFX platform that implements lights.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-LIFX platform that implements lights
 
 For more details about this platform, please refer to the documentation at
 https://home-assistant.io/components/light.lifx/
@@ -31,8 +29,11 @@ TEMP_MAX_HASS = 500           # home assistant maximum temperature
 
 
 class LIFX():
+    """Representation of a LIFX light."""
+
     def __init__(self, add_devices_callback,
                  server_addr=None, broadcast_addr=None):
+        """Initialize the light."""
         import liffylights
 
         self._devices = []
@@ -47,6 +48,7 @@ class LIFX():
             broadcast_addr)
 
     def find_bulb(self, ipaddr):
+        """Search for bulbs."""
         bulb = None
         for device in self._devices:
             if device.ipaddr == ipaddr:
@@ -56,6 +58,7 @@ class LIFX():
 
     # pylint: disable=too-many-arguments
     def on_device(self, ipaddr, name, power, hue, sat, bri, kel):
+        """Initialize the light."""
         bulb = self.find_bulb(ipaddr)
 
         if bulb is None:
@@ -74,6 +77,7 @@ class LIFX():
 
     # pylint: disable=too-many-arguments
     def on_color(self, ipaddr, hue, sat, bri, kel):
+        """Initialize the light."""
         bulb = self.find_bulb(ipaddr)
 
         if bulb is not None:
@@ -81,6 +85,7 @@ class LIFX():
             bulb.update_ha_state()
 
     def on_power(self, ipaddr, power):
+        """Initialize the light."""
         bulb = self.find_bulb(ipaddr)
 
         if bulb is not None:
@@ -89,28 +94,30 @@ class LIFX():
 
     # pylint: disable=unused-argument
     def poll(self, now):
+        """Initialize the light."""
         self.probe()
 
     def probe(self, address=None):
+        """Initialize the light."""
         self._liffylights.probe(address)
 
 
 # pylint: disable=unused-argument
 def setup_platform(hass, config, add_devices_callback, discovery_info=None):
-    """ Set up platform. """
+    """Setup the LIFX platform."""
     server_addr = config.get(CONF_SERVER, None)
     broadcast_addr = config.get(CONF_BROADCAST, None)
 
     lifx_library = LIFX(add_devices_callback, server_addr, broadcast_addr)
 
-    # register our poll service
+    # Register our poll service
     track_time_change(hass, lifx_library.poll, second=[10, 40])
 
     lifx_library.probe()
 
 
 def convert_rgb_to_hsv(rgb):
-    """ Convert HASS RGB values to HSV values. """
+    """Convert Home Assistant RGB values to HSV values."""
     red, green, blue = [_ / BYTE_MAX for _ in rgb]
 
     hue, saturation, brightness = colorsys.rgb_to_hsv(red, green, blue)
@@ -122,10 +129,12 @@ def convert_rgb_to_hsv(rgb):
 
 # pylint: disable=too-many-instance-attributes
 class LIFXLight(Light):
-    """ Provides LIFX light. """
+    """Representation of a LIFX light."""
+
     # pylint: disable=too-many-arguments
     def __init__(self, liffy, ipaddr, name, power, hue,
                  saturation, brightness, kelvin):
+        """Initialize the light."""
         _LOGGER.debug("LIFXLight: %s %s",
                       ipaddr, name)
 
@@ -142,49 +151,41 @@ class LIFXLight(Light):
 
     @property
     def name(self):
-        """ Returns the name of the device. """
+        """Return the name of the device."""
         return self._name
 
     @property
     def ipaddr(self):
-        """ Returns the ip of the device. """
+        """Return the IP address of the device."""
         return self._ip
 
     @property
     def rgb_color(self):
-        """ Returns RGB value. """
+        """Return the RGB value."""
         _LOGGER.debug("rgb_color: [%d %d %d]",
                       self._rgb[0], self._rgb[1], self._rgb[2])
-
         return self._rgb
 
     @property
     def brightness(self):
-        """ Returns brightness of this light between 0..255. """
+        """Return the brightness of this light between 0..255."""
         brightness = int(self._bri / (BYTE_MAX + 1))
-
+        _LOGGER.debug("brightness: %d", brightness)
-        _LOGGER.debug("brightness: %d",
-                      brightness)
-
         return brightness
 
     @property
     def color_temp(self):
-        """ Returns color temperature. """
+        """Return the color temperature."""
         temperature = int(TEMP_MIN_HASS + (TEMP_MAX_HASS - TEMP_MIN_HASS) *
                           (self._kel - TEMP_MIN) / (TEMP_MAX - TEMP_MIN))
 
-        _LOGGER.debug("color_temp: %d",
+        _LOGGER.debug("color_temp: %d", temperature)
-                      temperature)
-
         return temperature
 
     @property
     def is_on(self):
-        """ True if device is on. """
+        """Return true if device is on."""
-        _LOGGER.debug("is_on: %d",
+        _LOGGER.debug("is_on: %d", self._power)
-                      self._power)
-
         return self._power != 0
 
     def turn_on(self, **kwargs):
@@ -231,20 +232,16 @@ class LIFXLight(Light):
         else:
             fade = 0
 
-        _LOGGER.debug("turn_off: %s %d",
+        _LOGGER.debug("turn_off: %s %d", self._ip, fade)
-                      self._ip, fade)
-
         self._liffylights.set_power(self._ip, 0, fade)
 
     def set_name(self, name):
-        """ Set name. """
+        """Set name of the light."""
         self._name = name
 
     def set_power(self, power):
         """Set power state value."""
-        _LOGGER.debug("set_power: %d",
+        _LOGGER.debug("set_power: %d", power)
-                      power)
-
         self._power = (power != 0)
 
     def set_color(self, hue, sat, bri, kel):

homeassistant/components/light/limitlessled.py

@@ -1,6 +1,4 @@
 """
-homeassistant.components.light.limitlessled
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Support for LimitlessLED bulbs.
 
 For more details about this platform, please refer to the documentation at
@@ -49,7 +47,7 @@ def rewrite_legacy(config):
 
 
 def setup_platform(hass, config, add_devices_callback, discovery_info=None):
-    """ Gets the LimitlessLED lights. """
+    """Setup the LimitlessLED lights."""
     from limitlessled.bridge import Bridge
 
     # Two legacy configuration formats are supported to
@@ -104,7 +102,8 @@ def state(new_state):
 
 
 class LimitlessLEDGroup(Light):
-    """ LimitessLED group. """
+    """Representation of a LimitessLED group."""
+
     def __init__(self, group):
         """Initialize a group."""
         self.group = group
@@ -124,25 +123,22 @@ class LimitlessLEDGroup(Light):
 
     @property
     def should_poll(self):
-        """ No polling needed.
+        """No polling needed."""
-
-        LimitlessLED state cannot be fetched.
-        """
         return False
 
     @property
     def name(self):
-        """ Returns the name of the group. """
+        """Return the name of the group."""
         return self.group.name
 
     @property
     def is_on(self):
-        """ True if device is on. """
+        """Return true if device is on."""
         return self._is_on
 
     @property
     def brightness(self):
-        """ Brightness property. """
+        """Return the brightness property."""
         return self._brightness
 
     @state(False)
@@ -153,7 +149,8 @@ class LimitlessLEDGroup(Light):
 
 
 class LimitlessLEDWhiteGroup(LimitlessLEDGroup):
-    """ LimitlessLED White group. """
+    """Representation of a LimitlessLED White group."""
+
     def __init__(self, group):
         """Initialize White group."""
         super().__init__(group)
@@ -167,7 +164,7 @@ class LimitlessLEDWhiteGroup(LimitlessLEDGroup):
 
     @property
     def color_temp(self):
-        """ Temperature property. """
+        """Return the temperature property."""
         return self._temperature
 
     @state(True)
@@ -187,7 +184,8 @@ class LimitlessLEDWhiteGroup(LimitlessLEDGroup):
 
 
 class LimitlessLEDRGBWGroup(LimitlessLEDGroup):
-    """ LimitlessLED RGBW group. """
+    """Representation of a LimitlessLED RGBW group."""
+
     def __init__(self, group):
         """Initialize RGBW group."""
         super().__init__(group)
@@ -201,7 +199,7 @@ class LimitlessLEDRGBWGroup(LimitlessLEDGroup):
 
     @property
     def rgb_color(self):
-        """ Color property. """
+        """Return the color property."""
         return self._color
 
     @state(True)
@@ -239,43 +237,31 @@ class LimitlessLEDRGBWGroup(LimitlessLEDGroup):
 
 
 def _from_hass_temperature(temperature):
-    """ Convert Home Assistant color temperature
+    """Convert Home Assistant color temperature units to percentage."""
-    units to percentage.
-    """
     return (temperature - 154) / 346
 
 
 def _to_hass_temperature(temperature):
-    """ Convert percentage to Home Assistant
+    """Convert percentage to Home Assistant color temperature units."""
-    color temperature units.
-    """
     return int(temperature * 346) + 154
 
 
 def _from_hass_brightness(brightness):
-    """ Convert Home Assistant brightness units
+    """Convert Home Assistant brightness units to percentage."""
-    to percentage.
-    """
     return brightness / 255
 
 
 def _to_hass_brightness(brightness):
-    """ Convert percentage to Home Assistant
+    """Convert percentage to Home Assistant brightness units."""
-    brightness units.
-    """
     return int(brightness * 255)
 
 
 def _from_hass_color(color):
-    """ Convert Home Assistant RGB list
+    """Convert Home Assistant RGB list to Color tuple."""
-    to Color tuple.
-    """
     from limitlessled import Color
     return Color(*tuple(color))
 
 
 def _to_hass_color(color):
-    """ Convert from Color tuple to
+    """Convert from Color tuple to Home Assistant RGB list."""
-    Home Assistant RGB list.
-    """
     return list([int(c) for c in color])

homeassistant/components/light/mqtt.py

@@ -119,12 +119,12 @@ class MqttLight(Light):
 
     @property
     def brightness(self):
-        """Brightness of this light between 0..255."""
+        """Return the brightness of this light between 0..255."""
         return self._brightness
 
     @property
     def rgb_color(self):
-        """RGB color value."""
+        """Return the RGB color value."""
         return self._rgb
 
     @property
@@ -134,17 +134,17 @@ class MqttLight(Light):
 
     @property
     def name(self):
-        """Name of the device if any."""
+        """Return the name of the device if any."""
         return self._name
 
     @property
     def is_on(self):
-        """True if device is on."""
+        """Return true if device is on."""
         return self._state
 
     @property
     def assumed_state(self):
-        """Return True if we do optimistic updates."""
+        """Return true if we do optimistic updates."""
         return self._optimistic
 
     def turn_on(self, **kwargs):

homeassistant/components/light/mysensors.py

@@ -56,7 +56,6 @@ class MySensorsLight(Light):
     """Represent the value of a MySensors child node."""
 
     # pylint: disable=too-many-arguments,too-many-instance-attributes
-
     def __init__(
             self, gateway, node_id, child_id, name, value_type, child_type):
         """Setup instance attributes."""
@@ -75,27 +74,27 @@ class MySensorsLight(Light):
 
     @property
     def should_poll(self):
-        """MySensor gateway pushes its state to HA."""
+        """No polling needed."""
         return False
 
     @property
     def name(self):
-        """The name of this entity."""
+        """Return the name of this entity."""
         return self._name
 
     @property
     def brightness(self):
-        """Brightness of this light between 0..255."""
+        """Return the brightness of this light between 0..255."""
         return self._brightness
 
     @property
     def rgb_color(self):
-        """RGB color value [int, int, int]."""
+        """Return the RGB color value [int, int, int]."""
         return self._rgb
 
     @property
     def rgb_white(self):  # not implemented in the frontend yet
-        """White value in RGBW, value between 0..255."""
+        """Return the white value in RGBW, value between 0..255."""
         return self._white
 
     @property
@@ -113,17 +112,17 @@ class MySensorsLight(Light):
 
     @property
     def available(self):
-        """Return True if entity is available."""
+        """Return true if entity is available."""
         return self.value_type in self._values
 
     @property
     def assumed_state(self):
-        """Return True if unable to access real state of entity."""
+        """Return true if unable to access real state of entity."""
         return self.gateway.optimistic
 
     @property
     def is_on(self):
-        """True if device is on."""
+        """Return true if device is on."""
         return self._state
 
     def _turn_on_light(self):

homeassistant/components/light/rfxtrx.py

@@ -1,6 +1,4 @@
 """
-homeassistant.components.light.rfxtrx
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Support for RFXtrx lights.
 
 For more details about this platform, please refer to the documentation at
@@ -120,8 +118,10 @@ def setup_platform(hass, config, add_devices_callback, discovery_info=None):
 
 
 class RfxtrxLight(Light):
-    """ Provides a RFXtrx light. """
+    """Represenation of a RFXtrx light."""
+
     def __init__(self, name, event, datas, signal_repetitions):
+        """Initialize the light."""
         self._name = name
         self._event = event
         self._state = datas[ATTR_STATE]
@@ -136,22 +136,22 @@ class RfxtrxLight(Light):
 
     @property
     def name(self):
-        """ Returns the name of the light if any. """
+        """Return the name of the light if any."""
         return self._name
 
     @property
     def should_fire_event(self):
-        """ Returns is the device must fire event"""
+        """Return true if the device must fire event."""
         return self._should_fire_event
 
     @property
     def is_on(self):
-        """ True if light is on. """
+        """Return true if light is on."""
         return self._state
 
     @property
     def brightness(self):
-        """ Brightness of this light between 0..255. """
+        """Return the brightness of this light between 0..255."""
         return self._brightness
 
     @property
@@ -179,7 +179,6 @@ class RfxtrxLight(Light):
 
     def turn_off(self, **kwargs):
         """Turn the light off."""
-
         if not self._event:
             return
 

homeassistant/components/light/scsgate.py

@@ -1,6 +1,4 @@
 """
-homeassistant.components.light.scsgate
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Support for SCSGate lights.
 
 For more details about this platform, please refer to the documentation at
@@ -17,7 +15,6 @@ DEPENDENCIES = ['scsgate']
 
 def setup_platform(hass, config, add_devices_callback, discovery_info=None):
     """Add the SCSGate swiches defined inside of the configuration file."""
-
     devices = config.get('devices')
     lights = []
     logger = logging.getLogger(__name__)
@@ -42,8 +39,10 @@ def setup_platform(hass, config, add_devices_callback, discovery_info=None):
 
 
 class SCSGateLight(Light):
-    """ Provides a SCSGate light. """
+    """representation of a SCSGate light."""
+
     def __init__(self, scs_id, name, logger):
+        """Initialize the light."""
         self._name = name
         self._scs_id = scs_id
         self._toggled = False
@@ -51,7 +50,7 @@ class SCSGateLight(Light):
 
     @property
     def scs_id(self):
-        """ SCS ID """
+        """Return the SCS ID."""
         return self._scs_id
 
     @property
@@ -61,12 +60,12 @@ class SCSGateLight(Light):
 
     @property
     def name(self):
-        """ Returns the name of the device if any. """
+        """Return the name of the device if any."""
         return self._name
 
     @property
     def is_on(self):
-        """ True if light is on. """
+        """Return true if light is on."""
         return self._toggled
 
     def turn_on(self, **kwargs):
@@ -94,7 +93,7 @@ class SCSGateLight(Light):
         self.update_ha_state()
 
     def process_event(self, message):
-        """ Handle a SCSGate message related with this light """
+        """Handle a SCSGate message related with this light."""
         if self._toggled == message.toggled:
             self._logger.info(
                 "Light %s, ignoring message %s because state already active",

homeassistant/components/light/tellstick.py

@@ -1,6 +1,4 @@
 """
-homeassistant.components.light.tellstick
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Support for Tellstick lights.
 
 For more details about this platform, please refer to the documentation at
@@ -15,8 +13,7 @@ SIGNAL_REPETITIONS = 1
 
 # pylint: disable=unused-argument
 def setup_platform(hass, config, add_devices_callback, discovery_info=None):
-    """ Find and return Tellstick lights. """
+    """Setup Tellstick lights."""
-
     import tellcore.telldus as telldus
     from tellcore.library import DirectCallbackDispatcher
     import tellcore.constants as tellcore_constants
@@ -32,7 +29,7 @@ def setup_platform(hass, config, add_devices_callback, discovery_info=None):
             lights.append(TellstickLight(switch, signal_repetitions))
 
     def _device_event_callback(id_, method, data, cid):
-        """ Called from the TelldusCore library to update one device """
+        """Called from the TelldusCore library to update one device."""
         for light_device in lights:
             if light_device.tellstick_device.id == id_:
                 # Execute the update in another thread
@@ -42,7 +39,7 @@ def setup_platform(hass, config, add_devices_callback, discovery_info=None):
     callback_id = core.register_device_event(_device_event_callback)
 
     def unload_telldus_lib(event):
-        """ Un-register the callback bindings """
+        """Un-register the callback bindings."""
         if callback_id is not None:
             core.unregister_callback(callback_id)
 
@@ -52,9 +49,10 @@ def setup_platform(hass, config, add_devices_callback, discovery_info=None):
 
 
 class TellstickLight(Light):
-    """ Represents a Tellstick light. """
+    """Representation of a Tellstick light."""
 
     def __init__(self, tellstick_device, signal_repetitions):
+        """Initialize the light."""
         import tellcore.constants as tellcore_constants
 
         self.tellstick_device = tellstick_device
@@ -70,28 +68,28 @@ class TellstickLight(Light):
 
     @property
     def name(self):
-        """ Returns the name of the switch if any. """
+        """Return the name of the switch if any."""
         return self.tellstick_device.name
 
     @property
     def is_on(self):
-        """ True if switch is on. """
+        """Return true if switch is on."""
         return self._brightness > 0
 
     @property
     def brightness(self):
-        """ Brightness of this light between 0..255. """
+        """Return the brightness of this light between 0..255."""
         return self._brightness
 
     def turn_off(self, **kwargs):
-        """ Turns the switch off. """
+        """Turn the switch off."""
         for _ in range(self.signal_repetitions):
             self.tellstick_device.turn_off()
         self._brightness = 0
         self.update_ha_state()
 
     def turn_on(self, **kwargs):
-        """ Turns the switch on. """
+        """Turn the switch on."""
         brightness = kwargs.get(ATTR_BRIGHTNESS)
 
         if brightness is None:
@@ -123,10 +121,10 @@ class TellstickLight(Light):
 
     @property
     def should_poll(self):
-        """ Tells Home Assistant not to poll this entity. """
+        """No polling needed."""
         return False
 
     @property
     def assumed_state(self):
-        """  Tellstick devices are always assumed state """
+        """Tellstick devices are always assumed state."""
         return True

homeassistant/components/light/vera.py

@@ -1,6 +1,4 @@
 """
-homeassistant.components.light.vera
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Support for Vera lights.
 
 For more details about this platform, please refer to the documentation at
@@ -23,7 +21,7 @@ _LOGGER = logging.getLogger(__name__)
 
 # pylint: disable=unused-argument
 def setup_platform(hass, config, add_devices_callback, discovery_info=None):
-    """ Find and return Vera lights. """
+    """Setup Vera lights."""
     import pyvera as veraApi
 
     base_url = config.get('vera_controller_url')
@@ -40,7 +38,7 @@ def setup_platform(hass, config, add_devices_callback, discovery_info=None):
 
     if created:
         def stop_subscription(event):
-            """ Shutdown Vera subscriptions and subscription thread on exit"""
+            """Shutdown Vera subscriptions and subscription thread on exit."""
             _LOGGER.info("Shutting down subscriptions.")
             vera_controller.stop()
 
@@ -53,7 +51,7 @@ def setup_platform(hass, config, add_devices_callback, discovery_info=None):
             'On/Off Switch',
             'Dimmable Switch'])
     except RequestException:
-        # There was a network related error connecting to the vera controller
+        # There was a network related error connecting to the vera controller.
         _LOGGER.exception("Error communicating with Vera API")
         return False
 
@@ -69,9 +67,10 @@ def setup_platform(hass, config, add_devices_callback, discovery_info=None):
 
 
 class VeraLight(Light):
-    """ Represents a Vera Light, including dimmable. """
+    """Representation of a Vera Light, including dimmable."""
 
     def __init__(self, vera_device, controller, extra_data=None):
+        """Initialize the light."""
         self.vera_device = vera_device
         self.extra_data = extra_data
         self.controller = controller
@@ -89,16 +88,17 @@ class VeraLight(Light):
 
     @property
     def name(self):
-        """ Get the mame of the switch. """
+        """Return the name of the light."""
         return self._name
 
     @property
     def brightness(self):
-        """Brightness of the light."""
+        """Return the brightness of the light."""
         if self.vera_device.is_dimmable:
             return self.vera_device.get_brightness()
 
     def turn_on(self, **kwargs):
+        """Turn the light on."""
         if ATTR_BRIGHTNESS in kwargs and self.vera_device.is_dimmable:
             self.vera_device.set_brightness(kwargs[ATTR_BRIGHTNESS])
         else:
@@ -108,12 +108,14 @@ class VeraLight(Light):
         self.update_ha_state(True)
 
     def turn_off(self, **kwargs):
+        """Turn the light off."""
         self.vera_device.switch_off()
         self._state = STATE_OFF
         self.update_ha_state()
 
     @property
     def device_state_attributes(self):
+        """Return the state attributes."""
         attr = {}
 
         if self.vera_device.has_battery:
@@ -138,12 +140,12 @@ class VeraLight(Light):
 
     @property
     def should_poll(self):
-        """ Tells Home Assistant not to poll this entity. """
+        """No polling needed."""
         return False
 
     @property
     def is_on(self):
-        """ True if device is on. """
+        """Return true if device is on."""
         return self._state == STATE_ON
 
     def update(self):

homeassistant/components/light/wemo.py

@@ -1,6 +1,4 @@
 """
-homeassistant.components.light.wemo
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Support for Belkin WeMo lights.
 
 For more details about this component, please refer to the documentation at
@@ -22,7 +20,7 @@ _LOGGER = logging.getLogger(__name__)
 
 
 def setup_platform(hass, config, add_devices_callback, discovery_info=None):
-    """Probe WeMo bridges and register connected lights."""
+    """Setup WeMo bridges and register connected lights."""
     import pywemo.discovery as discovery
 
     if discovery_info is not None:
@@ -40,8 +38,7 @@ def setup_bridge(bridge, add_devices_callback):
 
     @util.Throttle(MIN_TIME_BETWEEN_SCANS, MIN_TIME_BETWEEN_FORCED_SCANS)
     def update_lights():
-        """Updates the WeMo led objects with latest info from the bridge."""
+        """Update the WeMo led objects with latest info from the bridge."""
-
         bridge.bridge_get_lights()
 
         new_lights = []
@@ -61,9 +58,10 @@ def setup_bridge(bridge, add_devices_callback):
 
 
 class WemoLight(Light):
-    """Represents a WeMo light"""
+    """Representation of a WeMo light."""
 
     def __init__(self, bridge, light_id, info, update_lights):
+        """Initialize the light."""
         self.bridge = bridge
         self.light_id = light_id
         self.info = info
@@ -71,18 +69,18 @@ class WemoLight(Light):
 
     @property
     def unique_id(self):
-        """Returns the id of this light"""
+        """Return the ID of this light."""
         deviceid = self.bridge.light_get_id(self.info)
         return "{}.{}".format(self.__class__, deviceid)
 
     @property
     def name(self):
-        """Get the name of the light."""
+        """Return the name of the light."""
         return self.bridge.light_name(self.info)
 
     @property
     def brightness(self):
-        """Brightness of this light between 0..255."""
+        """Return the brightness of this light between 0..255."""
         state = self.bridge.light_get_state(self.info)
         return int(state['dim'])
 

homeassistant/components/light/wink.py

@@ -1,6 +1,4 @@
 """
-homeassistant.components.light.wink
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Support for Wink lights.
 
 For more details about this platform, please refer to the documentation at
@@ -15,7 +13,7 @@ REQUIREMENTS = ['python-wink==0.6.2']
 
 
 def setup_platform(hass, config, add_devices_callback, discovery_info=None):
-    """ Find and return Wink lights. """
+    """Setup Wink lights."""
     import pywink
 
     token = config.get(CONF_ACCESS_TOKEN)
@@ -34,44 +32,44 @@ def setup_platform(hass, config, add_devices_callback, discovery_info=None):
 
 
 class WinkLight(Light):
-    """ Represents a Wink light. """
+    """Representation of a Wink light."""
 
     def __init__(self, wink):
+        """Initialize the light."""
         self.wink = wink
 
     @property
     def unique_id(self):
-        """ Returns the id of this Wink switch. """
+        """Return the ID of this Wink light."""
         return "{}.{}".format(self.__class__, self.wink.device_id())
 
     @property
     def name(self):
-        """ Returns the name of the light if any. """
+        """Return the name of the light if any."""
         return self.wink.name()
 
     @property
     def is_on(self):
-        """ True if light is on. """
+        """Return true if light is on."""
         return self.wink.state()
 
     @property
     def brightness(self):
-        """Brightness of the light."""
+        """Return the brightness of the light."""
         return int(self.wink.brightness() * 255)
 
     # pylint: disable=too-few-public-methods
     def turn_on(self, **kwargs):
-        """ Turns the switch on. """
+        """Turn the switch on."""
         brightness = kwargs.get(ATTR_BRIGHTNESS)
 
         if brightness is not None:
             self.wink.set_state(True, brightness=brightness / 255)
-
         else:
             self.wink.set_state(True)
 
     def turn_off(self):
-        """ Turns the switch off. """
+        """Turn the switch off."""
         self.wink.set_state(False)
 
     def update(self):

homeassistant/components/light/zigbee.py

@@ -1,7 +1,5 @@
 """
-homeassistant.components.light.zigbee
+Functionality to use a ZigBee device as a light.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Contains functionality to use a ZigBee device as a light.
 
 For more details about this platform, please refer to the documentation at
 https://home-assistant.io/components/light.zigbee/
@@ -21,8 +19,6 @@ def setup_platform(hass, config, add_entities, discovery_info=None):
 
 
 class ZigBeeLight(ZigBeeDigitalOut, Light):
-    """
+    """Use ZigBeeDigitalOut as light."""
-    Use multiple inheritance to turn an instance of ZigBeeDigitalOut into a
+
-    Light.
-    """
     pass

homeassistant/components/light/zwave.py

@@ -1,6 +1,4 @@
 """
-homeassistant.components.light.zwave
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Support for Z-Wave lights.
 
 For more details about this platform, please refer to the documentation at
@@ -37,10 +35,7 @@ def setup_platform(hass, config, add_devices, discovery_info=None):
 
 
 def brightness_state(value):
-    """
+    """Return the brightness and state."""
-    Returns the brightness and state according to the current data of given
-    value.
-    """
     if value.data > 0:
         return (value.data / 99) * 255, STATE_ON
     else:
@@ -48,9 +43,11 @@ def brightness_state(value):
 
 
 class ZwaveDimmer(ZWaveDeviceEntity, Light):
-    """ Provides a Z-Wave dimmer. """
+    """Representation of a Z-Wave dimmer."""
+
     # pylint: disable=too-many-arguments
     def __init__(self, value):
+        """Initialize the light."""
         from openzwave.network import ZWaveNetwork
         from pydispatch import dispatcher
 
@@ -89,17 +86,16 @@ class ZwaveDimmer(ZWaveDeviceEntity, Light):
 
     @property
     def brightness(self):
-        """ Brightness of this light between 0..255. """
+        """Return the brightness of this light between 0..255."""
         return self._brightness
 
     @property
     def is_on(self):
-        """ True if device is on. """
+        """Return true if device is on."""
         return self._state == STATE_ON
 
     def turn_on(self, **kwargs):
         """Turn the device on."""
-
         if ATTR_BRIGHTNESS in kwargs:
             self._brightness = kwargs[ATTR_BRIGHTNESS]