ha-deprecation-fixes

用途

该技能面向 Home Assistant 自定义集成的维护与升级场景，用于修复弃用警告（deprecation warnings），并将集成适配到更新的 Home Assistant 版本。触发时机为：遇到已弃用的导入、类型注解或代码模式时。

弃用机制说明

Home Assistant 的弃用遵循固定模式：

• Deprecated（弃用）：记录警告，功能仍可使用。
• Removed（移除）：功能不再可用，通常在弃用约 1 年之后。

主要能力（涵盖的具体弃用项）

ServiceInfo 导入位置迁移（2025.1 弃用，2026.2 移除）

旧写法（已弃用）：

from homeassistant.components.zeroconf import ZeroconfServiceInfo
from homeassistant.components.ssdp import SsdpServiceInfo
from homeassistant.components.dhcp import DhcpServiceInfo
from homeassistant.components.usb import UsbServiceInfo

新写法（应使用）：

from homeassistant.helpers.service_info.zeroconf import ZeroconfServiceInfo
from homeassistant.helpers.service_info.ssdp import SsdpServiceInfo
from homeassistant.helpers.service_info.dhcp import DhcpServiceInfo
from homeassistant.helpers.service_info.usb import UsbServiceInfo

注意：Bluetooth 的 ServiceInfo 不属于 2025.1 的迁移范围，仍保留在 from homeassistant.components.bluetooth import BluetoothServiceInfo。

hass.data[DOMAIN] 改为 runtime_data（2024.8+）

旧模式：

async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    coordinator = MyCoordinator(hass, entry)
    await coordinator.async_config_entry_first_refresh()
    hass.data.setdefault(DOMAIN, {})[entry.entry_id] = coordinator

async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    if unload_ok := await hass.config_entries.async_unload_platforms(entry, PLATFORMS):
        hass.data[DOMAIN].pop(entry.entry_id)
    return unload_ok

新模式：

type MyConfigEntry = ConfigEntry[MyCoordinator]

async def async_setup_entry(hass: HomeAssistant, entry: MyConfigEntry) -> bool:
    coordinator = MyCoordinator(hass, entry)
    await coordinator.async_config_entry_first_refresh()
    entry.runtime_data = coordinator  # 直接赋值

async def async_unload_entry(hass: HomeAssistant, entry: MyConfigEntry) -> bool:
    # 无需清理 - runtime_data 会自动清除
    return await hass.config_entries.async_unload_platforms(entry, PLATFORMS)

OptionsFlow 的 init 弃用（2024.12 弃用，2025.12 移除）

旧写法（已弃用）：

class MyOptionsFlow(OptionsFlow):
    def __init__(self, config_entry: ConfigEntry) -> None:
        self.config_entry = config_entry

新写法（应使用）：

class MyOptionsFlow(OptionsFlow):
    # 无需 __init__ - self.config_entry 自动可用
    async def async_step_init(self, user_input=None):
        current_value = self.config_entry.options.get("key", "default")

DataUpdateCoordinator._async_setup（2024.8+）

class MyCoordinator(DataUpdateCoordinator[dict[str, Any]]):
    async def _async_setup(self) -> None:
        """初始化协调器（在首次更新前运行一次）。"""
        self.device_info = await self.client.async_get_device_info()

    async def _async_update_data(self) -> dict[str, Any]:
        """获取数据（每次更新时运行）。"""
        return await self.client.async_get_data()

VacuumActivity 枚举（2025.1 弃用，2026.1 移除）

旧写法（已弃用）：

from homeassistant.components.vacuum import STATE_CLEANING, STATE_DOCKED
class MyVacuum(StateVacuumEntity):
    @property
    def state(self) -> str:
        return STATE_CLEANING

新写法：

from homeassistant.components.vacuum import VacuumActivity
class MyVacuum(StateVacuumEntity):
    @property
    def activity(self) -> VacuumActivity | None:
        return VacuumActivity.CLEANING

Camera WebRTC 变更（2024.12 弃用，2025.6 移除）

旧写法（已弃用）：

class MyCamera(Camera):
    @property
    def frontend_stream_type(self) -> StreamType:
        return StreamType.WEB_RTC

    async def async_handle_web_rtc_offer(self, offer_sdp: str) -> str:
        pass

新写法：

class MyCamera(Camera):
    async def async_handle_async_webrtc_offer(
        self, offer_sdp: str, session_id: str, send_message: Callable
    ) -> None:
        pass

类型注解更新（Python 3.9+）

旧写法（Python 3.9 之前）：

from typing import List, Dict, Optional, Union

def my_func(items: List[str]) -> Dict[str, int]: ...
def optional_param(value: Optional[str] = None) -> None: ...

新写法：

from __future__ import annotations

def my_func(items: list[str]) -> dict[str, int]: ...
def optional_param(value: str | None = None) -> None: ...

使用方式

迁移检查清单（2025.x 兼容）

• 在所有文件中加入 from __future__ import annotations
• 将 List[]、Dict[]、Optional[X]、Union[X, Y] 替换为现代语法
• 将 ServiceInfo 导入更新为 helpers.service_info.*
• 将 hass.data[DOMAIN] 替换为 entry.runtime_data
• 如果 OptionsFlow 的 __init__ 仅用于存储 config_entry，则移除它
• 使用 VacuumActivity 枚举替代 STATE_* 常量
• 将 Camera 更新为使用异步 WebRTC 方法

自动检测

# 检测常见弃用项
python3 scripts/check-patterns.py custom_components/my_integration/
# 可检测：旧导入、弃用类型提示、阻塞式 I/O、hass.data 用法

相关技能

• Config entry 迁移 → ha-config-migration
• Coordinator 模式 → ha-coordinator

限制

本资料未提供该技能的安装命令、许可、收费方式及适用平台等信息。