From a47d6c944ebe6bfb41b0eaefbbc95a681debd2d6 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Tue, 23 Feb 2016 21:31:38 +0100 Subject: [PATCH] Update docstrings to match PEP257 --- config/custom_components/example.py | 27 ++++++++++++------------ config/custom_components/hello_world.py | 16 +++++++------- config/custom_components/mqtt_example.py | 26 ++++++++++------------- 3 files changed, 32 insertions(+), 37 deletions(-) diff --git a/config/custom_components/example.py b/config/custom_components/example.py index 08b3f4c2a83..3f961b99569 100644 --- a/config/custom_components/example.py +++ b/config/custom_components/example.py @@ -1,6 +1,5 @@ """ -custom_components.example -~~~~~~~~~~~~~~~~~~~~~~~~~ +Example of a custom component. Example component to target an entity_id to: - turn it on at 7AM in the morning @@ -37,21 +36,21 @@ import homeassistant.components as core from homeassistant.components import device_tracker from homeassistant.components import light -# The domain of your component. Should be equal to the name of your component +# The domain of your component. Should be equal to the name of your component. DOMAIN = "example" -# List of component names (string) your component depends upon +# List of component names (string) your component depends upon. # We depend on group because group will be loaded after all the components that # initialize devices have been setup. DEPENDENCIES = ['group', 'device_tracker', 'light'] -# Configuration key for the entity id we are targetting +# Configuration key for the entity id we are targeting. CONF_TARGET = 'target' -# Variable for storing configuration parameters +# Variable for storing configuration parameters. TARGET_ID = None -# Name of the service that we expose +# Name of the service that we expose. SERVICE_FLASH = 'flash' # Shortcut for the logger @@ -59,16 +58,16 @@ _LOGGER = logging.getLogger(__name__) def setup(hass, config): - """ Setup example component. """ + """Setup example component.""" global TARGET_ID - # Validate that all required config options are given + # Validate that all required config options are given. if not validate_config(config, {DOMAIN: [CONF_TARGET]}, _LOGGER): return False TARGET_ID = config[DOMAIN][CONF_TARGET] - # Validate that the target entity id exists + # Validate that the target entity id exists. if hass.states.get(TARGET_ID) is None: _LOGGER.error("Target entity id %s does not exist", TARGET_ID) @@ -78,13 +77,13 @@ def setup(hass, config): TARGET_ID = None return False - # Tell the bootstrapper that we initialized successfully + # Tell the bootstrapper that we initialized successfully. return True @track_state_change(device_tracker.ENTITY_ID_ALL_DEVICES) def track_devices(hass, entity_id, old_state, new_state): - """ Called when the group.all devices change state. """ + """Called when the group.all devices change state.""" # If the target id is not set, return if not TARGET_ID: return @@ -94,7 +93,7 @@ def track_devices(hass, entity_id, old_state, new_state): core.turn_on(hass, TARGET_ID) - # If all people leave the house and the entity is on, turn it off + # If all people leave the house and the entity is on, turn it off. elif new_state.state == STATE_NOT_HOME and core.is_on(hass, TARGET_ID): core.turn_off(hass, TARGET_ID) @@ -116,7 +115,7 @@ def wake_up(hass, now): @track_state_change(light.ENTITY_ID_ALL_LIGHTS, STATE_ON, STATE_OFF) def all_lights_off(hass, entity_id, old_state, new_state): - """ If all lights turn off, turn off. """ + """If all lights turn off, turn off.""" if not TARGET_ID: return diff --git a/config/custom_components/hello_world.py b/config/custom_components/hello_world.py index a3d4ce762bb..f24971a1462 100644 --- a/config/custom_components/hello_world.py +++ b/config/custom_components/hello_world.py @@ -1,7 +1,7 @@ """ -custom_components.hello_world -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Implements the bare minimum that a component should implement. +The "hello world" custom component. + +This component implements the bare minimum that a component should implement. Configuration: @@ -11,18 +11,18 @@ configuration.yaml file. hello_world: """ -# The domain of your component. Should be equal to the name of your component +# The domain of your component. Should be equal to the name of your component. DOMAIN = "hello_world" -# List of component names (string) your component depends upon +# List of component names (string) your component depends upon. DEPENDENCIES = [] def setup(hass, config): - """ Setup our skeleton component. """ + """Setup our skeleton component.""" - # States are in the format DOMAIN.OBJECT_ID + # States are in the format DOMAIN.OBJECT_ID. hass.states.set('hello_world.Hello_World', 'Works!') - # return boolean to indicate that initialization was successful + # Return boolean to indicate that initialization was successfully. return True diff --git a/config/custom_components/mqtt_example.py b/config/custom_components/mqtt_example.py index 98e16b6bfa9..b4e5e89a977 100644 --- a/config/custom_components/mqtt_example.py +++ b/config/custom_components/mqtt_example.py @@ -1,6 +1,6 @@ """ -custom_components.mqtt_example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Example of a custom MQTT component. + Shows how to communicate with MQTT. Follows a topic on MQTT and updates the state of an entity to the last message received on that topic. @@ -15,45 +15,41 @@ configuration.yaml file. mqtt_example: topic: home-assistant/mqtt_example - """ import homeassistant.loader as loader -# The domain of your component. Should be equal to the name of your component +# The domain of your component. Should be equal to the name of your component. DOMAIN = "mqtt_example" -# List of component names (string) your component depends upon +# List of component names (string) your component depends upon. DEPENDENCIES = ['mqtt'] - CONF_TOPIC = 'topic' DEFAULT_TOPIC = 'home-assistant/mqtt_example' def setup(hass, config): - """ Setup our mqtt_example component. """ + """Setup the MQTT example component.""" mqtt = loader.get_component('mqtt') topic = config[DOMAIN].get('topic', DEFAULT_TOPIC) entity_id = 'mqtt_example.last_message' - # Listen to a message on MQTT - + # Listen to a message on MQTT. def message_received(topic, payload, qos): - """ A new MQTT message has been received. """ + """A new MQTT message has been received.""" hass.states.set(entity_id, payload) mqtt.subscribe(hass, topic, message_received) hass.states.set(entity_id, 'No messages') - # Service to publish a message on MQTT - + # Service to publish a message on MQTT. def set_state_service(call): - """ Service to send a message. """ + """Service to send a message.""" mqtt.publish(hass, topic, call.data.get('new_state')) - # Register our service with Home Assistant + # Register our service with Home Assistant. hass.services.register(DOMAIN, 'set_state', set_state_service) - # return boolean to indicate that initialization was successful + # Return boolean to indicate that initialization was successfully. return True