开发清单

介绍

在您提交任何更改之前，请根据这些需求检查您的工作

• 所有与外部设备或服务的通信都必须封装在托管在 pypi上的外部Python库中
• 新的依赖项被添加到requirements_all.txt(如果适用的话)，使用python3 -m script.gen_requirements_all
• New codeowners are added to CODEOWNERS (if applicable), using python3 -m script.hassfest
• 如果没有可用的测试，或者您的新代码使用第三方库与设备、服务通信或sensor.config_flow.py不能被排除，因为它必须被完全测试(100%覆盖)，则.coveragerc文件将被更新以排除您的平台。
• 如果.strict-typing文件确实提供了一个完整的类型提示源代码，那么它将更新为包含您的代码
• 按照这些guidelines，代码使用Black格式化。这可以通过运行命令black --fast homeassistant tests.
• Documentation is developed for home-assistant.io
  • Visit the website documentation for more information about contributing to home-assistant.io.

组件清单

添加新组件时要做的事情的清单。

并非所有现有代码都符合此检查表中的要求。这不能作为不遵循它们的理由!

通用

1. 遵守Style guidelines
2. 使用const.py中存在的常量
   1. 只有在新常量被广泛使用时才添加到const.py中。否则，将它们保持在组件级别

Requirements

1. 已添加到manifest.json
2. 内容格式为"requirements": ['phue==0.8.1']
3. 使用pypi而不是github

Configuration

1. 为configuration validation提供了丰富的模式
2. 在voluptuous模式中指定的默认参数，而不是在setup(…)
3. 使用尽可能多的通用配置键的模式,在homeassistant.const
4. 如果你的组件有平台，定义一个PLATFORM_SCHEMA而不是CONFIG_SCHEMA。
5. 如果使用的是与EntityComponent一起使用的PLATFORM_SCHEMA，请从homeassistant.helpers.config_validation导入base
6. 永远不要依赖于用户添加自定义内容来配置组件内部的行为。

Component/platform communication

1. 你可以利用hass.data[DOMAIN]与你的平台共享数据。
2. 如果组件获取了导致其相关平台实体更新的数据，您可以使用homeassistant.helpers.dispatcher中的dispatcher代码来通知它们。

Communication with devices/services

1. 所有API特定的代码都必须是托管在PyPi上的第三方库的一部分。Home Assistant应该只与对象交互，而不直接调用API。

# bad
status = requests.get(url("/status"))
# good
from phue import Bridge

bridge = Bridge(...)
status = bridge.status()

Tutorial on publishing your own PyPI package

Other noteworthy resources for publishing python packages:
Cookiecutter Project
flit
Poetry

Make your pull request as small as possible

将新集成保持在最小功能，以便人们从集成中获得价值。这允许评审人员一次只批准一小块代码，让我们更快地获得新的集成/特性。包含大型代码转储的Pull请求将不是审查的优先级，可能会被关闭。

• 限于单一平台
• 不要添加不需要直接支持单一平台的特性(如定制服务)
• 不要把清理和新功能混合在一个拉请求中。
• 不要在一个拉请求中解决几个问题。
• 不提交拉请求依赖于其他工作仍未合并

Event names

以域名为前缀的组件事件名称。例如，netatmo组件使用netatmo_person而不是person。请注意我们Data Science portal.中记录的数据结构

Tests

强烈考虑为组件添加测试，以最小化未来的回归。

平台清单

通用

同上

需求

同上

配置

1. 如果平台可以直接设置，请添加一个丰富的模式来进行 configuration validation
2. 丰富的模式从组件扩展模式(例如,hue.light.PLATFORM_SCHEMA扩展light.PLATFORM_SCHEMA)
3. 在voluptuous模式中指定的默认参数，而不是在setup_platform(…)中指定的
4. 你的PLATFORM_SCHEMA应该使用尽可能多的来自homeassistant.const的通用配置键
5. 永远不要依赖于用户添加自定义内容来配置平台内部的行为。

import voluptuous as vol

from homeassistant.const import CONF_FILENAME, CONF_HOST
from homeassistant.components.light import PLATFORM_SCHEMA
import homeassistant.helpers.config_validation as cv

CONF_ALLOW_UNREACHABLE = "allow_unreachable"
DEFAULT_UNREACHABLE = False

PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend(
    {
        vol.Required(CONF_HOST): cv.string,
        vol.Optional(CONF_ALLOW_UNREACHABLE, default=DEFAULT_UNREACHABLE): cv.boolean,
        vol.Optional(CONF_FILENAME): cv.string,
    }
)

Setup Platform

1. 验证传入的配置(user/pass/host等)是否正常。
2. 如果可能的话，将调用分组到add_devices。
3. 如果平台添加了额外的服务，格式应该是<您的集成域>。<服务名称>。因此，如果您的集成域是“awesome_sauce”，并且您正在创建一个轻量级平台，那么您将在awesome_sauce域下注册服务。确保你的服务verify permissions.

Entity

1. 从您正在为其构建平台的集成扩展实体

from homeassistant.components.light import Light


class HueLight(Light):
    """Hue light component."""

2. 避免将hass作为参数传递给实体。当实体被添加到HA时，hass将被设置在实体上。这意味着您可以通过self.hass访问
3. 不要在构造函数中调用update()，而是使用add_entities(devices, True)。
4. 不要在内部属性中执行任何I/O操作。取而代之的是在update()中的缓存值。
5. 在处理时间时，状态和/或属性不应该包含发生事件后的相对时间。相反，它应该存储UTC时间戳。
6. 利用entity lifecycle callbacks来附加事件监听器或清理连接。

Communication with devices/services

同上

集成质量