Home Assistant 中文网

Style guidelines

Home Assistant enforces strict PEP8 style and PEP 257 (Docstring Conventions) compliance on all code submitted. We automatically test every pull request as part of the linting process with Coveralls and Travis CI.

Summary of the most relevant points:

  • Line length is limited to 79 characters (see below).
  • Use 4 spaces per indentation level. We don’t use tabs.
  • Comments should be full sentences and end with a period.
  • Imports should be ordered.
  • Constants and the content of lists and dictionaries should be in alphabetical order.
  • Avoid trailing whitespace but surround binary operators with a single space.
  • Line separator should be set to LF.

The maximum line length comes directly from the PEP8 style guide, and is also used by the Python standard library. All code must pass these linting checks, and no exceptions will be made. There have already been numerous requests to increase the maximum line length, but after evaluating the options, the Home Assistant maintainers have decided to stay at 79 characters. This decision is final.

Those points may require that you adjust your IDE or editor settings.

Our recommandations

For some cases PEPs don’t make a statement. This section covers our recommendations about the code style. Those points were collected from the exisiting code and based on what contributors and developers were using the most. This is basically a majority decision, thus you may not agree with it. But we would like to encourage you follow those recommandations to keep the code unified.

Quotes

Use single quotes ' for single word and " for multiple words or sentences.

ATTR_WATERLEVEL = 'level'
CONF_ATTRIBUTION = "Data provided by the WUnderground weather service"
SENSOR_TYPES = {
    'alerts': ['Alerts', None],
}

File headers

The docstring in the file header should contain a link to the documentation to make it easy to find further information, especially about the configuration or details which are not mentioned in the code.

"""
Support for MQTT lights.

For more details about this platform, please refer to the documentation at
https://home-assistant.io/components/light.mqtt/
"""

Requirements

Please place Platform requirements right after the imports.

[...]
from homeassistant.helpers.entity import Entity

REQUIREMENTS = ['xmltodict==0.11.0']

Log messages

There is no need to add the platform or component name to the log messages. This will be added automatically. Like syslog messages there shouldn’t be no period at the end. Try to avoid brackets and additional quotes around the output to make it easier for users to parse the log. A widely style is shown below but you are free to compose the messages as you like.

_LOGGER.error("No route to device: %s", self._resource)

2017-05-01 14:28:07 ERROR [homeassistant.components.sensor.arest] No route to device: 192.168.0.18

Don’t print out wrong API keys, tokens, usernames, or passwords.