homeassistant 2025.9.4__py3-none-any.whl → 2025.10.0__py3-none-any.whl

homeassistant/components/sensor/translations/zh-Hans.json

@@ -33,6 +33,7 @@
             "is_pm1": "{entity_name} PM1 \u5f53\u524d\u6d53\u5ea6\u6c34\u5e73",
             "is_pm10": "{entity_name} PM10 \u5f53\u524d\u6d53\u5ea6\u6c34\u5e73",
             "is_pm25": "{entity_name} PM2.5 \u5f53\u524d\u6d53\u5ea6\u6c34\u5e73",
+            "is_pm4": "{entity_name} PM4 \u5f53\u524d\u6d53\u5ea6\u6c34\u5e73",
             "is_power": "{entity_name} \u5f53\u524d\u529f\u7387",
             "is_power_factor": "{entity_name} \u5f53\u524d\u529f\u7387\u56e0\u6570",
             "is_precipitation": "{entity_name} \u5f53\u524d\u964d\u6c34\u91cf",
@@ -94,6 +95,7 @@
             "pm1": "{entity_name} PM1 \u6d53\u5ea6\u53d8\u5316",
             "pm10": "{entity_name} PM10 \u6d53\u5ea6\u53d8\u5316",
             "pm25": "{entity_name} PM2.5 \u6d53\u5ea6\u53d8\u5316",
+            "pm4": "{entity_name} PM4 \u6d53\u5ea6\u53d8\u5316",
             "power": "{entity_name} \u529f\u7387\u53d8\u5316",
             "power_factor": "{entity_name} \u529f\u7387\u56e0\u6570\u53d8\u5316",
             "precipitation": "{entity_name} \u964d\u6c34\u53d8\u5316",

homeassistant/components/sensor/translations/zh-Hant.json

@@ -33,6 +33,7 @@
             "is_pm1": "\u76ee\u524d{entity_name} PM1 \u6fc3\u5ea6\u72c0\u614b",
             "is_pm10": "\u76ee\u524d{entity_name} PM10 \u6fc3\u5ea6\u72c0\u614b",
             "is_pm25": "\u76ee\u524d{entity_name} PM2.5 \u6fc3\u5ea6\u72c0\u614b",
+            "is_pm4": "\u76ee\u524d{entity_name} PM4 \u6fc3\u5ea6\u72c0\u614b",
             "is_power": "\u76ee\u524d{entity_name}\u96fb\u529b",
             "is_power_factor": "\u76ee\u524d{entity_name}\u529f\u7387\u56e0\u6578",
             "is_precipitation": "\u76ee\u524d{entity_name}\u964d\u96e8\u91cf",
@@ -94,6 +95,7 @@
             "pm1": "{entity_name} PM1 \u6fc3\u5ea6\u8b8a\u5316",
             "pm10": "{entity_name} PM10 \u6fc3\u5ea6\u8b8a\u5316",
             "pm25": "{entity_name} PM2.5 \u6fc3\u5ea6\u8b8a\u5316",
+            "pm4": "{entity_name} PM4 \u6fc3\u5ea6\u8b8a\u5316",
             "power": "{entity_name}\u96fb\u529b\u8b8a\u66f4",
             "power_factor": "\u76ee\u524d{entity_name}\u529f\u7387\u56e0\u6578\u8b8a\u66f4",
             "precipitation": "{entity_name}\u964d\u96e8\u91cf\u8b8a\u66f4",
@@ -248,6 +250,9 @@
         "pm25": {
             "name": "PM2.5"
         },
+        "pm4": {
+            "name": "PM4"
+        },
         "power": {
             "name": "\u96fb\u529b"
         },

homeassistant/components/sensorpush_cloud/translations/fy.json

@@ -0,0 +1,11 @@
+{
+    "config": {
+        "step": {
+            "user": {
+                "data": {
+                    "password": "Wachtwurd"
+                }
+            }
+        }
+    }
+}

homeassistant/components/sftp_storage/__init__.py

@@ -0,0 +1,155 @@
+"""Integration for SFTP Storage."""
+
+from __future__ import annotations
+
+import contextlib
+from dataclasses import dataclass, field
+import errno
+import logging
+from pathlib import Path
+
+from homeassistant.components.backup import BackupAgentError
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.core import HomeAssistant
+from homeassistant.exceptions import ConfigEntryError
+
+from .client import BackupAgentClient
+from .const import (
+    CONF_BACKUP_LOCATION,
+    CONF_HOST,
+    CONF_PASSWORD,
+    CONF_PORT,
+    CONF_PRIVATE_KEY_FILE,
+    CONF_USERNAME,
+    DATA_BACKUP_AGENT_LISTENERS,
+    DOMAIN,
+    LOGGER,
+)
+
+type SFTPConfigEntry = ConfigEntry[SFTPConfigEntryData]
+
+
+@dataclass(kw_only=True)
+class SFTPConfigEntryData:
+    """Dataclass holding all config entry data for an SFTP Storage entry."""
+
+    host: str
+    port: int
+    username: str
+    password: str | None = field(repr=False)
+    private_key_file: str | None
+    backup_location: str
+
+
+async def async_setup_entry(hass: HomeAssistant, entry: SFTPConfigEntry) -> bool:
+    """Set up SFTP Storage from a config entry."""
+
+    cfg = SFTPConfigEntryData(
+        host=entry.data[CONF_HOST],
+        port=entry.data[CONF_PORT],
+        username=entry.data[CONF_USERNAME],
+        password=entry.data.get(CONF_PASSWORD),
+        private_key_file=entry.data.get(CONF_PRIVATE_KEY_FILE, []),
+        backup_location=entry.data[CONF_BACKUP_LOCATION],
+    )
+    entry.runtime_data = cfg
+
+    # Establish a connection during setup.
+    # This will raise exception if there is something wrong with either
+    # SSH server or config.
+    try:
+        client = BackupAgentClient(entry, hass)
+        await client.open()
+    except BackupAgentError as e:
+        raise ConfigEntryError from e
+
+    # Notify backup listeners
+    def _async_notify_backup_listeners() -> None:
+        for listener in hass.data.get(DATA_BACKUP_AGENT_LISTENERS, []):
+            listener()
+
+    entry.async_on_unload(entry.async_on_state_change(_async_notify_backup_listeners))
+
+    return True
+
+
+async def async_remove_entry(hass: HomeAssistant, entry: SFTPConfigEntry) -> None:
+    """Remove an SFTP Storage config entry."""
+
+    def remove_files(entry: SFTPConfigEntry) -> None:
+        pkey = Path(entry.data[CONF_PRIVATE_KEY_FILE])
+
+        if pkey.exists():
+            LOGGER.debug(
+                "Removing private key (%s) for %s integration for host %s@%s",
+                pkey,
+                DOMAIN,
+                entry.data[CONF_USERNAME],
+                entry.data[CONF_HOST],
+            )
+            try:
+                pkey.unlink()
+            except OSError as e:
+                LOGGER.warning(
+                    "Failed to remove private key %s for %s integration for host %s@%s. %s",
+                    pkey.name,
+                    DOMAIN,
+                    entry.data[CONF_USERNAME],
+                    entry.data[CONF_HOST],
+                    str(e),
+                )
+
+        try:
+            pkey.parent.rmdir()
+        except OSError as e:
+            if e.errno == errno.ENOTEMPTY:  # Directory not empty
+                if LOGGER.isEnabledFor(logging.DEBUG):
+                    leftover_files = []
+                    # If we get an exception while gathering leftover files, make sure to log plain message.
+                    with contextlib.suppress(OSError):
+                        leftover_files = [f.name for f in pkey.parent.iterdir()]
+
+                    LOGGER.debug(
+                        "Storage directory for %s integration is not empty (%s)%s",
+                        DOMAIN,
+                        str(pkey.parent),
+                        f", files: {', '.join(leftover_files)}"
+                        if leftover_files
+                        else "",
+                    )
+            else:
+                LOGGER.warning(
+                    "Error occurred while removing directory %s for integration %s: %s at host %s@%s",
+                    str(pkey.parent),
+                    DOMAIN,
+                    str(e),
+                    entry.data[CONF_USERNAME],
+                    entry.data[CONF_HOST],
+                )
+        else:
+            LOGGER.debug(
+                "Removed storage directory for %s integration",
+                DOMAIN,
+                entry.data[CONF_USERNAME],
+                entry.data[CONF_HOST],
+            )
+
+    if bool(entry.data.get(CONF_PRIVATE_KEY_FILE)):
+        LOGGER.debug(
+            "Cleaning up after %s integration for host %s@%s",
+            DOMAIN,
+            entry.data[CONF_USERNAME],
+            entry.data[CONF_HOST],
+        )
+        await hass.async_add_executor_job(remove_files, entry)
+
+
+async def async_unload_entry(hass: HomeAssistant, entry: SFTPConfigEntry) -> bool:
+    """Unload SFTP Storage config entry."""
+    LOGGER.debug(
+        "Unloading %s integration for host %s@%s",
+        DOMAIN,
+        entry.data[CONF_USERNAME],
+        entry.data[CONF_HOST],
+    )
+    return True

homeassistant/components/sftp_storage/backup.py

@@ -0,0 +1,153 @@
+"""Backup platform for the SFTP Storage integration."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable, Coroutine
+from typing import Any
+
+from asyncssh.sftp import SFTPError
+
+from homeassistant.components.backup import (
+    AgentBackup,
+    BackupAgent,
+    BackupAgentError,
+    BackupNotFound,
+)
+from homeassistant.core import HomeAssistant, callback
+
+from . import SFTPConfigEntry
+from .client import BackupAgentClient
+from .const import DATA_BACKUP_AGENT_LISTENERS, DOMAIN, LOGGER
+
+
+async def async_get_backup_agents(
+    hass: HomeAssistant,
+) -> list[BackupAgent]:
+    """Register the backup agents."""
+    entries: list[SFTPConfigEntry] = hass.config_entries.async_loaded_entries(DOMAIN)
+    return [SFTPBackupAgent(hass, entry) for entry in entries]
+
+
+@callback
+def async_register_backup_agents_listener(
+    hass: HomeAssistant,
+    *,
+    listener: Callable[[], None],
+    **kwargs: Any,
+) -> Callable[[], None]:
+    """Register a listener to be called when agents are added or removed."""
+    hass.data.setdefault(DATA_BACKUP_AGENT_LISTENERS, []).append(listener)
+
+    @callback
+    def remove_listener() -> None:
+        """Remove the listener."""
+        hass.data[DATA_BACKUP_AGENT_LISTENERS].remove(listener)
+        if not hass.data[DATA_BACKUP_AGENT_LISTENERS]:
+            del hass.data[DATA_BACKUP_AGENT_LISTENERS]
+
+    return remove_listener
+
+
+class SFTPBackupAgent(BackupAgent):
+    """SFTP Backup Storage agent."""
+
+    domain = DOMAIN
+
+    def __init__(self, hass: HomeAssistant, entry: SFTPConfigEntry) -> None:
+        """Initialize the SFTPBackupAgent backup sync agent."""
+        super().__init__()
+        self._entry: SFTPConfigEntry = entry
+        self._hass: HomeAssistant = hass
+        self.name: str = entry.title
+        self.unique_id: str = entry.entry_id
+
+    async def async_download_backup(
+        self,
+        backup_id: str,
+        **kwargs: Any,
+    ) -> AsyncIterator[bytes]:
+        """Download a backup file from SFTP."""
+        LOGGER.debug(
+            "Establishing SFTP connection to remote host in order to download backup id: %s",
+            backup_id,
+        )
+        try:
+            # Will raise BackupAgentError if failure to authenticate or SFTP Permissions
+            async with BackupAgentClient(self._entry, self._hass) as client:
+                return await client.iter_file(backup_id)
+        except FileNotFoundError as e:
+            raise BackupNotFound(
+                f"Unable to initiate download of backup id: {backup_id}. {e}"
+            ) from e
+
+    async def async_upload_backup(
+        self,
+        *,
+        open_stream: Callable[[], Coroutine[Any, Any, AsyncIterator[bytes]]],
+        backup: AgentBackup,
+        **kwargs: Any,
+    ) -> None:
+        """Upload a backup."""
+        LOGGER.debug("Received request to upload backup: %s", backup)
+        iterator = await open_stream()
+
+        LOGGER.debug(
+            "Establishing SFTP connection to remote host in order to upload backup"
+        )
+
+        # Will raise BackupAgentError if failure to authenticate or SFTP Permissions
+        async with BackupAgentClient(self._entry, self._hass) as client:
+            LOGGER.debug("Uploading backup: %s", backup.backup_id)
+            await client.async_upload_backup(iterator, backup)
+        LOGGER.debug("Successfully uploaded backup id: %s", backup.backup_id)
+
+    async def async_delete_backup(
+        self,
+        backup_id: str,
+        **kwargs: Any,
+    ) -> None:
+        """Delete a backup file from SFTP Storage."""
+        LOGGER.debug("Received request to delete backup id: %s", backup_id)
+
+        try:
+            LOGGER.debug(
+                "Establishing SFTP connection to remote host in order to delete backup"
+            )
+            # Will raise BackupAgentError if failure to authenticate or SFTP Permissions
+            async with BackupAgentClient(self._entry, self._hass) as client:
+                await client.async_delete_backup(backup_id)
+        except FileNotFoundError as err:
+            raise BackupNotFound(str(err)) from err
+        except SFTPError as err:
+            raise BackupAgentError(
+                f"Failed to delete backup id: {backup_id}: {err}"
+            ) from err
+
+        LOGGER.debug("Successfully removed backup id: %s", backup_id)
+
+    async def async_list_backups(self, **kwargs: Any) -> list[AgentBackup]:
+        """List backups stored on SFTP Storage."""
+
+        # Will raise BackupAgentError if failure to authenticate or SFTP Permissions
+        async with BackupAgentClient(self._entry, self._hass) as client:
+            try:
+                return await client.async_list_backups()
+            except SFTPError as err:
+                raise BackupAgentError(
+                    f"Remote server error while attempting to list backups: {err}"
+                ) from err
+
+    async def async_get_backup(
+        self,
+        backup_id: str,
+        **kwargs: Any,
+    ) -> AgentBackup:
+        """Return a backup."""
+        backups = await self.async_list_backups()
+
+        for backup in backups:
+            if backup.backup_id == backup_id:
+                LOGGER.debug("Returning backup id: %s. %s", backup_id, backup)
+                return backup
+
+        raise BackupNotFound(f"Backup id: {backup_id} not found")

homeassistant/components/sftp_storage/client.py

@@ -0,0 +1,311 @@
+"""Client for SFTP Storage integration."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+import json
+from types import TracebackType
+from typing import TYPE_CHECKING, Self
+
+from asyncssh import (
+    SFTPClient,
+    SFTPClientFile,
+    SSHClientConnection,
+    SSHClientConnectionOptions,
+    connect,
+)
+from asyncssh.misc import PermissionDenied
+from asyncssh.sftp import SFTPNoSuchFile, SFTPPermissionDenied
+
+from homeassistant.components.backup import (
+    AgentBackup,
+    BackupAgentError,
+    suggested_filename,
+)
+from homeassistant.core import HomeAssistant
+
+from .const import BUF_SIZE, LOGGER
+
+if TYPE_CHECKING:
+    from . import SFTPConfigEntry, SFTPConfigEntryData
+
+
+def get_client_options(cfg: SFTPConfigEntryData) -> SSHClientConnectionOptions:
+    """Use this function with `hass.async_add_executor_job` to asynchronously get `SSHClientConnectionOptions`."""
+
+    return SSHClientConnectionOptions(
+        known_hosts=None,
+        username=cfg.username,
+        password=cfg.password,
+        client_keys=cfg.private_key_file,
+    )
+
+
+class AsyncFileIterator:
+    """Returns iterator of remote file located in SFTP Server.
+
+    This exists in order to properly close remote file after operation is completed
+    and to avoid premature closing of file and session if `BackupAgentClient` is used
+    as context manager.
+    """
+
+    _client: BackupAgentClient
+    _fileobj: SFTPClientFile
+
+    def __init__(
+        self,
+        cfg: SFTPConfigEntry,
+        hass: HomeAssistant,
+        file_path: str,
+        buffer_size: int = BUF_SIZE,
+    ) -> None:
+        """Initialize `AsyncFileIterator`."""
+        self.cfg: SFTPConfigEntry = cfg
+        self.hass: HomeAssistant = hass
+        self.file_path: str = file_path
+        self.buffer_size = buffer_size
+        self._initialized: bool = False
+        LOGGER.debug("Opening file: %s in Async File Iterator", file_path)
+
+    async def _initialize(self) -> None:
+        """Load file object."""
+        self._client: BackupAgentClient = await BackupAgentClient(
+            self.cfg, self.hass
+        ).open()
+        self._fileobj: SFTPClientFile = await self._client.sftp.open(
+            self.file_path, "rb"
+        )
+
+        self._initialized = True
+
+    def __aiter__(self) -> AsyncIterator[bytes]:
+        """Return self as iterator."""
+        return self
+
+    async def __anext__(self) -> bytes:
+        """Return next bytes as provided in buffer size."""
+        if not self._initialized:
+            await self._initialize()
+
+        chunk: bytes = await self._fileobj.read(self.buffer_size)
+        if not chunk:
+            try:
+                await self._fileobj.close()
+                await self._client.close()
+            finally:
+                raise StopAsyncIteration
+        return chunk
+
+
+@dataclass(kw_only=True)
+class BackupMetadata:
+    """Represent single backup file metadata."""
+
+    file_path: str
+    metadata: dict[str, str | dict[str, list[str]]]
+    metadata_file: str
+
+
+class BackupAgentClient:
+    """Helper class that manages SSH and SFTP Server connections."""
+
+    sftp: SFTPClient
+
+    def __init__(self, config: SFTPConfigEntry, hass: HomeAssistant) -> None:
+        """Initialize `BackupAgentClient`."""
+        self.cfg: SFTPConfigEntry = config
+        self.hass: HomeAssistant = hass
+        self._ssh: SSHClientConnection | None = None
+        LOGGER.debug("Initialized with config: %s", self.cfg.runtime_data)
+
+    async def __aenter__(self) -> Self:
+        """Async context manager entrypoint."""
+
+        return await self.open()  # type: ignore[return-value]  # mypy will otherwise raise an error
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Async Context Manager exit routine."""
+        if self.sftp:
+            self.sftp.exit()
+            await self.sftp.wait_closed()
+
+        if self._ssh:
+            self._ssh.close()
+
+            await self._ssh.wait_closed()
+
+    async def _load_metadata(self, backup_id: str) -> BackupMetadata:
+        """Return `BackupMetadata` object`.
+
+        Raises:
+        ------
+        `FileNotFoundError` -- if metadata file is not found.
+
+        """
+
+        # Test for metadata file existence.
+        metadata_file = (
+            f"{self.cfg.runtime_data.backup_location}/.{backup_id}.metadata.json"
+        )
+        if not await self.sftp.exists(metadata_file):
+            raise FileNotFoundError(
+                f"Metadata file not found at remote location: {metadata_file}"
+            )
+
+        async with self.sftp.open(metadata_file, "r") as f:
+            return BackupMetadata(
+                **json.loads(await f.read()), metadata_file=metadata_file
+            )
+
+    async def async_delete_backup(self, backup_id: str) -> None:
+        """Delete backup archive.
+
+        Raises:
+        ------
+        `FileNotFoundError` -- if either metadata file or archive is not found.
+
+        """
+
+        metadata: BackupMetadata = await self._load_metadata(backup_id)
+
+        # If for whatever reason, archive does not exist but metadata file does,
+        # remove the metadata file.
+        if not await self.sftp.exists(metadata.file_path):
+            await self.sftp.unlink(metadata.metadata_file)
+            raise FileNotFoundError(
+                f"File at provided remote location: {metadata.file_path} does not exist."
+            )
+
+        LOGGER.debug("Removing file at path: %s", metadata.file_path)
+        await self.sftp.unlink(metadata.file_path)
+        LOGGER.debug("Removing metadata at path: %s", metadata.metadata_file)
+        await self.sftp.unlink(metadata.metadata_file)
+
+    async def async_list_backups(self) -> list[AgentBackup]:
+        """Iterate through a list of metadata files and return a list of `AgentBackup` objects."""
+
+        backups: list[AgentBackup] = []
+
+        for file in await self.list_backup_location():
+            LOGGER.debug(
+                "Evaluating metadata file at remote location: %s@%s:%s",
+                self.cfg.runtime_data.username,
+                self.cfg.runtime_data.host,
+                file,
+            )
+
+            try:
+                async with self.sftp.open(file, "r") as rfile:
+                    metadata = BackupMetadata(
+                        **json.loads(await rfile.read()), metadata_file=file
+                    )
+                    backups.append(AgentBackup.from_dict(metadata.metadata))
+            except (json.JSONDecodeError, TypeError) as e:
+                LOGGER.error(
+                    "Failed to load backup metadata from file: %s. %s", file, str(e)
+                )
+                continue
+
+        return backups
+
+    async def async_upload_backup(
+        self,
+        iterator: AsyncIterator[bytes],
+        backup: AgentBackup,
+    ) -> None:
+        """Accept `iterator` as bytes iterator and write backup archive to SFTP Server."""
+
+        file_path = (
+            f"{self.cfg.runtime_data.backup_location}/{suggested_filename(backup)}"
+        )
+        async with self.sftp.open(file_path, "wb") as f:
+            async for b in iterator:
+                await f.write(b)
+
+        LOGGER.debug("Writing backup metadata")
+        metadata: dict[str, str | dict[str, list[str]]] = {
+            "file_path": file_path,
+            "metadata": backup.as_dict(),
+        }
+        async with self.sftp.open(
+            f"{self.cfg.runtime_data.backup_location}/.{backup.backup_id}.metadata.json",
+            "w",
+        ) as f:
+            await f.write(json.dumps(metadata))
+
+    async def close(self) -> None:
+        """Close the `BackupAgentClient` context manager."""
+        await self.__aexit__(None, None, None)
+
+    async def iter_file(self, backup_id: str) -> AsyncFileIterator:
+        """Return Async File Iterator object.
+
+        `SFTPClientFile` object (that would be returned with `sftp.open`) is not an iterator.
+        So we return custom made class - `AsyncFileIterator` that would allow iteration on file object.
+
+        Raises:
+        ------
+        - `FileNotFoundError` -- if metadata or backup archive is not found.
+
+        """
+
+        metadata: BackupMetadata = await self._load_metadata(backup_id)
+        if not await self.sftp.exists(metadata.file_path):
+            raise FileNotFoundError("Backup archive not found on remote location.")
+        return AsyncFileIterator(self.cfg, self.hass, metadata.file_path, BUF_SIZE)
+
+    async def list_backup_location(self) -> list[str]:
+        """Return a list of `*.metadata.json` files located in backup location."""
+        files = []
+        LOGGER.debug(
+            "Changing directory to: `%s`", self.cfg.runtime_data.backup_location
+        )
+        await self.sftp.chdir(self.cfg.runtime_data.backup_location)
+
+        for file in await self.sftp.listdir():
+            LOGGER.debug(
+                "Checking if file: `%s/%s` is metadata file",
+                self.cfg.runtime_data.backup_location,
+                file,
+            )
+            if file.endswith(".metadata.json"):
+                LOGGER.debug("Found metadata file: `%s`", file)
+                files.append(f"{self.cfg.runtime_data.backup_location}/{file}")
+        return files
+
+    async def open(self) -> BackupAgentClient:
+        """Return initialized `BackupAgentClient`.
+
+        This is to avoid calling `__aenter__` dunder method.
+        """
+
+        # Configure SSH Client Connection
+        try:
+            self._ssh = await connect(
+                host=self.cfg.runtime_data.host,
+                port=self.cfg.runtime_data.port,
+                options=await self.hass.async_add_executor_job(
+                    get_client_options, self.cfg.runtime_data
+                ),
+            )
+        except (OSError, PermissionDenied) as e:
+            raise BackupAgentError(
+                "Failure while attempting to establish SSH connection. Please check SSH credentials and if changed, re-install the integration"
+            ) from e
+
+        # Configure SFTP Client Connection
+        try:
+            self.sftp = await self._ssh.start_sftp_client()
+            await self.sftp.chdir(self.cfg.runtime_data.backup_location)
+        except (SFTPNoSuchFile, SFTPPermissionDenied) as e:
+            raise BackupAgentError(
+                "Failed to create SFTP client. Re-installing integration might be required"
+            ) from e
+
+        return self