esphome 2025.9.3__py3-none-any.whl → 2025.10.0b1__py3-none-any.whl

esphome/espota2.py

@@ -1,19 +1,23 @@
 from __future__ import annotations
 
+from collections.abc import Callable
 import gzip
 import hashlib
 import io
 import logging
+from pathlib import Path
 import random
 import socket
 import sys
 import time
+from typing import Any
 
 from esphome.core import EsphomeError
 from esphome.helpers import resolve_ip_address
 
 RESPONSE_OK = 0x00
 RESPONSE_REQUEST_AUTH = 0x01
+RESPONSE_REQUEST_SHA256_AUTH = 0x02
 
 RESPONSE_HEADER_OK = 0x40
 RESPONSE_AUTH_OK = 0x41
@@ -44,6 +48,7 @@ OTA_VERSION_2_0 = 2
 MAGIC_BYTES = [0x6C, 0x26, 0xF7, 0x5C, 0x45]
 
 FEATURE_SUPPORTS_COMPRESSION = 0x01
+FEATURE_SUPPORTS_SHA256_AUTH = 0x02
 
 
 UPLOAD_BLOCK_SIZE = 8192
@@ -51,6 +56,12 @@ UPLOAD_BUFFER_SIZE = UPLOAD_BLOCK_SIZE * 8
 
 _LOGGER = logging.getLogger(__name__)
 
+# Authentication method lookup table: response -> (hash_func, nonce_size, name)
+_AUTH_METHODS: dict[int, tuple[Callable[..., Any], int, str]] = {
+    RESPONSE_REQUEST_SHA256_AUTH: (hashlib.sha256, 64, "SHA256"),
+    RESPONSE_REQUEST_AUTH: (hashlib.md5, 32, "MD5"),
+}
+
 
 class ProgressBar:
     def __init__(self):
@@ -80,18 +91,43 @@ class OTAError(EsphomeError):
     pass
 
 
-def recv_decode(sock, amount, decode=True):
+def recv_decode(
+    sock: socket.socket, amount: int, decode: bool = True
+) -> bytes | list[int]:
+    """Receive data from socket and optionally decode to list of integers.
+
+    :param sock: Socket to receive data from.
+    :param amount: Number of bytes to receive.
+    :param decode: If True, convert bytes to list of integers, otherwise return raw bytes.
+    :return: List of integers if decode=True, otherwise raw bytes.
+    """
     data = sock.recv(amount)
     if not decode:
         return data
     return list(data)
 
 
-def receive_exactly(sock, amount, msg, expect, decode=True):
-    data = [] if decode else b""
+def receive_exactly(
+    sock: socket.socket,
+    amount: int,
+    msg: str,
+    expect: int | list[int] | None,
+    decode: bool = True,
+) -> list[int] | bytes:
+    """Receive exactly the specified amount of data from socket with error checking.
+
+    :param sock: Socket to receive data from.
+    :param amount: Exact number of bytes to receive.
+    :param msg: Description of what is being received for error messages.
+    :param expect: Expected response code(s) for validation, None to skip validation.
+    :param decode: If True, return list of integers, otherwise return raw bytes.
+    :return: List of integers if decode=True, otherwise raw bytes.
+    :raises OTAError: If receiving fails or response doesn't match expected.
+    """
+    data: list[int] | bytes = [] if decode else b""
 
     try:
-        data += recv_decode(sock, 1, decode=decode)
+        data += recv_decode(sock, 1, decode=decode)  # type: ignore[operator]
     except OSError as err:
         raise OTAError(f"Error receiving acknowledge {msg}: {err}") from err
 
@@ -103,13 +139,19 @@ def receive_exactly(sock, amount, msg, expect, decode=True):
 
     while len(data) < amount:
         try:
-            data += recv_decode(sock, amount - len(data), decode=decode)
+            data += recv_decode(sock, amount - len(data), decode=decode)  # type: ignore[operator]
         except OSError as err:
             raise OTAError(f"Error receiving {msg}: {err}") from err
     return data
 
 
-def check_error(data, expect):
+def check_error(data: list[int] | bytes, expect: int | list[int] | None) -> None:
+    """Check response data for error codes and validate against expected response.
+
+    :param data: Response data from device (first byte is the response code).
+    :param expect: Expected response code(s), None to skip validation.
+    :raises OTAError: If an error code is detected or response doesn't match expected.
+    """
     if not expect:
         return
     dat = data[0]
@@ -124,7 +166,7 @@ def check_error(data, expect):
         raise OTAError("Error: Authentication invalid. Is the password correct?")
     if dat == RESPONSE_ERROR_WRITING_FLASH:
         raise OTAError(
-            "Error: Wring OTA data to flash memory failed. See USB logs for more "
+            "Error: Writing OTA data to flash memory failed. See USB logs for more "
             "information."
         )
     if dat == RESPONSE_ERROR_UPDATE_END:
@@ -176,7 +218,16 @@ def check_error(data, expect):
         raise OTAError(f"Unexpected response from ESP: 0x{data[0]:02X}")
 
 
-def send_check(sock, data, msg):
+def send_check(
+    sock: socket.socket, data: list[int] | tuple[int, ...] | int | str | bytes, msg: str
+) -> None:
+    """Send data to socket with error handling.
+
+    :param sock: Socket to send data to.
+    :param data: Data to send (can be list/tuple of ints, single int, string, or bytes).
+    :param msg: Description of what is being sent for error messages.
+    :raises OTAError: If sending fails.
+    """
     try:
         if isinstance(data, (list, tuple)):
             data = bytes(data)
@@ -191,7 +242,7 @@ def send_check(sock, data, msg):
 
 
 def perform_ota(
-    sock: socket.socket, password: str, file_handle: io.IOBase, filename: str
+    sock: socket.socket, password: str, file_handle: io.IOBase, filename: Path
 ) -> None:
     file_contents = file_handle.read()
     file_size = len(file_contents)
@@ -209,10 +260,14 @@ def perform_ota(
             f"Device uses unsupported OTA version {version}, this ESPHome supports {supported_versions}"
         )
 
-    # Features
-    send_check(sock, FEATURE_SUPPORTS_COMPRESSION, "features")
+    # Features - send both compression and SHA256 auth support
+    features_to_send = FEATURE_SUPPORTS_COMPRESSION | FEATURE_SUPPORTS_SHA256_AUTH
+    send_check(sock, features_to_send, "features")
     features = receive_exactly(
-        sock, 1, "features", [RESPONSE_HEADER_OK, RESPONSE_SUPPORTS_COMPRESSION]
+        sock,
+        1,
+        "features",
+        None,  # Accept any response
     )[0]
 
     if features == RESPONSE_SUPPORTS_COMPRESSION:
@@ -221,31 +276,52 @@ def perform_ota(
     else:
         upload_contents = file_contents
 
-    (auth,) = receive_exactly(
-        sock, 1, "auth", [RESPONSE_REQUEST_AUTH, RESPONSE_AUTH_OK]
-    )
-    if auth == RESPONSE_REQUEST_AUTH:
+    def perform_auth(
+        sock: socket.socket,
+        password: str,
+        hash_func: Callable[..., Any],
+        nonce_size: int,
+        hash_name: str,
+    ) -> None:
+        """Perform challenge-response authentication using specified hash algorithm."""
         if not password:
             raise OTAError("ESP requests password, but no password given!")
-        nonce = receive_exactly(
-            sock, 32, "authentication nonce", [], decode=False
-        ).decode()
-        _LOGGER.debug("Auth: Nonce is %s", nonce)
-        cnonce = hashlib.md5(str(random.random()).encode()).hexdigest()
-        _LOGGER.debug("Auth: CNonce is %s", cnonce)
+
+        nonce_bytes = receive_exactly(
+            sock, nonce_size, f"{hash_name} authentication nonce", [], decode=False
+        )
+        assert isinstance(nonce_bytes, bytes)
+        nonce = nonce_bytes.decode()
+        _LOGGER.debug("Auth: %s Nonce is %s", hash_name, nonce)
+
+        # Generate cnonce
+        cnonce = hash_func(str(random.random()).encode()).hexdigest()
+        _LOGGER.debug("Auth: %s CNonce is %s", hash_name, cnonce)
 
         send_check(sock, cnonce, "auth cnonce")
 
-        result_md5 = hashlib.md5()
-        result_md5.update(password.encode("utf-8"))
-        result_md5.update(nonce.encode())
-        result_md5.update(cnonce.encode())
-        result = result_md5.hexdigest()
-        _LOGGER.debug("Auth: Result is %s", result)
+        # Calculate challenge response
+        hasher = hash_func()
+        hasher.update(password.encode("utf-8"))
+        hasher.update(nonce.encode())
+        hasher.update(cnonce.encode())
+        result = hasher.hexdigest()
+        _LOGGER.debug("Auth: %s Result is %s", hash_name, result)
 
         send_check(sock, result, "auth result")
         receive_exactly(sock, 1, "auth result", RESPONSE_AUTH_OK)
 
+    (auth,) = receive_exactly(
+        sock,
+        1,
+        "auth",
+        [RESPONSE_REQUEST_AUTH, RESPONSE_REQUEST_SHA256_AUTH, RESPONSE_AUTH_OK],
+    )
+
+    if auth != RESPONSE_AUTH_OK:
+        hash_func, nonce_size, hash_name = _AUTH_METHODS[auth]
+        perform_auth(sock, password, hash_func, nonce_size, hash_name)
+
     # Set higher timeout during upload
     sock.settimeout(30.0)
 
@@ -309,12 +385,16 @@ def perform_ota(
 
 
 def run_ota_impl_(
-    remote_host: str | list[str], remote_port: int, password: str, filename: str
+    remote_host: str | list[str], remote_port: int, password: str, filename: Path
 ) -> tuple[int, str | None]:
+    from esphome.core import CORE
+
     # Handle both single host and list of hosts
     try:
         # Resolve all hosts at once for parallel DNS resolution
-        res = resolve_ip_address(remote_host, remote_port)
+        res = resolve_ip_address(
+            remote_host, remote_port, address_cache=CORE.address_cache
+        )
     except EsphomeError as err:
         _LOGGER.error(
             "Error resolving IP address of %s. Is it connected to WiFi?",
@@ -356,7 +436,7 @@ def run_ota_impl_(
 
 
 def run_ota(
-    remote_host: str | list[str], remote_port: int, password: str, filename: str
+    remote_host: str | list[str], remote_port: int, password: str, filename: Path
 ) -> tuple[int, str | None]:
     try:
         return run_ota_impl_(remote_host, remote_port, password, filename)

esphome/external_files.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 from datetime import datetime
 import logging
-import os
 from pathlib import Path
 
 import requests
@@ -23,11 +22,11 @@ CONTENT_DISPOSITION = "content-disposition"
 TEMP_DIR = "temp"
 
 
-def has_remote_file_changed(url, local_file_path):
-    if os.path.exists(local_file_path):
+def has_remote_file_changed(url: str, local_file_path: Path) -> bool:
+    if local_file_path.exists():
         _LOGGER.debug("has_remote_file_changed: File exists at %s", local_file_path)
         try:
-            local_modification_time = os.path.getmtime(local_file_path)
+            local_modification_time = local_file_path.stat().st_mtime
             local_modification_time_str = datetime.utcfromtimestamp(
                 local_modification_time
             ).strftime("%a, %d %b %Y %H:%M:%S GMT")
@@ -65,9 +64,9 @@ def has_remote_file_changed(url, local_file_path):
     return True
 
 
-def is_file_recent(file_path: str, refresh: TimePeriodSeconds) -> bool:
-    if os.path.exists(file_path):
-        creation_time = os.path.getctime(file_path)
+def is_file_recent(file_path: Path, refresh: TimePeriodSeconds) -> bool:
+    if file_path.exists():
+        creation_time = file_path.stat().st_ctime
         current_time = datetime.now().timestamp()
         return current_time - creation_time <= refresh.total_seconds
     return False

esphome/git.py

@@ -13,6 +13,9 @@ from esphome.core import CORE, TimePeriodSeconds
 
 _LOGGER = logging.getLogger(__name__)
 
+# Special value to indicate never refresh
+NEVER_REFRESH = TimePeriodSeconds(seconds=-1)
+
 
 def run_git_command(cmd, cwd=None) -> str:
     _LOGGER.debug("Running git command: %s", " ".join(cmd))
@@ -85,6 +88,11 @@ def clone_or_update(
 
     else:
         # Check refresh needed
+        # Skip refresh if NEVER_REFRESH is specified
+        if refresh == NEVER_REFRESH:
+            _LOGGER.debug("Skipping update for %s (refresh disabled)", key)
+            return repo_dir, None
+
         file_timestamp = Path(repo_dir / ".git" / "FETCH_HEAD")
         # On first clone, FETCH_HEAD does not exists
         if not file_timestamp.exists():

esphome/helpers.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import codecs
 from contextlib import suppress
 import ipaddress
 import logging
@@ -8,11 +7,16 @@ import os
 from pathlib import Path
 import platform
 import re
+import shutil
 import tempfile
+from typing import TYPE_CHECKING
 from urllib.parse import urlparse
 
 from esphome.const import __version__ as ESPHOME_VERSION
 
+if TYPE_CHECKING:
+    from esphome.address_cache import AddressCache
+
 # Type aliases for socket address information
 AddrInfo = tuple[
     int,  # family (AF_INET, AF_INET6, etc.)
@@ -136,16 +140,16 @@ def run_system_command(*args):
         return rc, stdout, stderr
 
 
-def mkdir_p(path):
+def mkdir_p(path: Path):
     if not path:
         # Empty path - means create current dir
         return
     try:
-        os.makedirs(path)
+        path.mkdir(parents=True, exist_ok=True)
     except OSError as err:
         import errno
 
-        if err.errno == errno.EEXIST and os.path.isdir(path):
+        if err.errno == errno.EEXIST and path.is_dir():
             pass
         else:
             from esphome.core import EsphomeError
@@ -173,7 +177,24 @@ def addr_preference_(res: AddrInfo) -> int:
     return 1
 
 
-def resolve_ip_address(host: str | list[str], port: int) -> list[AddrInfo]:
+def _add_ip_addresses_to_addrinfo(
+    addresses: list[str], port: int, res: list[AddrInfo]
+) -> None:
+    """Helper to add IP addresses to addrinfo results with error handling."""
+    import socket
+
+    for addr in addresses:
+        try:
+            res += socket.getaddrinfo(
+                addr, port, proto=socket.IPPROTO_TCP, flags=socket.AI_NUMERICHOST
+            )
+        except OSError:
+            _LOGGER.debug("Failed to parse IP address '%s'", addr)
+
+
+def resolve_ip_address(
+    host: str | list[str], port: int, address_cache: AddressCache | None = None
+) -> list[AddrInfo]:
     import socket
 
     # There are five cases here. The host argument could be one of:
@@ -194,47 +215,69 @@ def resolve_ip_address(host: str | list[str], port: int) -> list[AddrInfo]:
         hosts = [host]
 
     res: list[AddrInfo] = []
+
+    # Fast path: if all hosts are already IP addresses
     if all(is_ip_address(h) for h in hosts):
-        # Fast path: all are IP addresses, use socket.getaddrinfo with AI_NUMERICHOST
-        for addr in hosts:
-            try:
-                res += socket.getaddrinfo(
-                    addr, port, proto=socket.IPPROTO_TCP, flags=socket.AI_NUMERICHOST
-                )
-            except OSError:
-                _LOGGER.debug("Failed to parse IP address '%s'", addr)
+        _add_ip_addresses_to_addrinfo(hosts, port, res)
         # Sort by preference
         res.sort(key=addr_preference_)
         return res
 
-    from esphome.resolver import AsyncResolver
-
-    resolver = AsyncResolver(hosts, port)
-    addr_infos = resolver.resolve()
-    # Convert aioesphomeapi AddrInfo to our format
-    for addr_info in addr_infos:
-        sockaddr = addr_info.sockaddr
-        if addr_info.family == socket.AF_INET6:
-            # IPv6
-            sockaddr_tuple = (
-                sockaddr.address,
-                sockaddr.port,
-                sockaddr.flowinfo,
-                sockaddr.scope_id,
-            )
+    # Process hosts
+    cached_addresses: list[str] = []
+    uncached_hosts: list[str] = []
+    has_cache = address_cache is not None
+
+    for h in hosts:
+        if is_ip_address(h):
+            if has_cache:
+                # If we have a cache, treat IPs as cached
+                cached_addresses.append(h)
+            else:
+                # If no cache, pass IPs through to resolver with hostnames
+                uncached_hosts.append(h)
+        elif address_cache and (cached := address_cache.get_addresses(h)):
+            # Found in cache
+            cached_addresses.extend(cached)
         else:
-            # IPv4
-            sockaddr_tuple = (sockaddr.address, sockaddr.port)
-
-        res.append(
-            (
-                addr_info.family,
-                addr_info.type,
-                addr_info.proto,
-                "",  # canonname
-                sockaddr_tuple,
+            # Not cached, need to resolve
+            if address_cache and address_cache.has_cache():
+                _LOGGER.info("Host %s not in cache, will need to resolve", h)
+            uncached_hosts.append(h)
+
+    # Process cached addresses (includes direct IPs and cached lookups)
+    _add_ip_addresses_to_addrinfo(cached_addresses, port, res)
+
+    # If we have uncached hosts (only non-IP hostnames), resolve them
+    if uncached_hosts:
+        from esphome.resolver import AsyncResolver
+
+        resolver = AsyncResolver(uncached_hosts, port)
+        addr_infos = resolver.resolve()
+        # Convert aioesphomeapi AddrInfo to our format
+        for addr_info in addr_infos:
+            sockaddr = addr_info.sockaddr
+            if addr_info.family == socket.AF_INET6:
+                # IPv6
+                sockaddr_tuple = (
+                    sockaddr.address,
+                    sockaddr.port,
+                    sockaddr.flowinfo,
+                    sockaddr.scope_id,
+                )
+            else:
+                # IPv4
+                sockaddr_tuple = (sockaddr.address, sockaddr.port)
+
+            res.append(
+                (
+                    addr_info.family,
+                    addr_info.type,
+                    addr_info.proto,
+                    "",  # canonname
+                    sockaddr_tuple,
+                )
             )
-        )
 
     # Sort by preference
     res.sort(key=addr_preference_)
@@ -256,14 +299,7 @@ def sort_ip_addresses(address_list: list[str]) -> list[str]:
     # First "resolve" all the IP addresses to getaddrinfo() tuples of the form
     # (family, type, proto, canonname, sockaddr)
     res: list[AddrInfo] = []
-    for addr in address_list:
-        # This should always work as these are supposed to be IP addresses
-        try:
-            res += socket.getaddrinfo(
-                addr, 0, proto=socket.IPPROTO_TCP, flags=socket.AI_NUMERICHOST
-            )
-        except OSError:
-            _LOGGER.info("Failed to parse IP address '%s'", addr)
+    _add_ip_addresses_to_addrinfo(address_list, 0, res)
 
     # Now use that information to sort them.
     res.sort(key=addr_preference_)
@@ -295,16 +331,15 @@ def is_ha_addon():
     return get_bool_env("ESPHOME_IS_HA_ADDON")
 
 
-def walk_files(path):
+def walk_files(path: Path):
     for root, _, files in os.walk(path):
         for name in files:
-            yield os.path.join(root, name)
+            yield Path(root) / name
 
 
-def read_file(path):
+def read_file(path: Path) -> str:
     try:
-        with codecs.open(path, "r", encoding="utf-8") as f_handle:
-            return f_handle.read()
+        return path.read_text(encoding="utf-8")
     except OSError as err:
         from esphome.core import EsphomeError
 
@@ -315,13 +350,15 @@ def read_file(path):
         raise EsphomeError(f"Error reading file {path}: {err}") from err
 
 
-def _write_file(path: Path | str, text: str | bytes):
+def _write_file(
+    path: Path,
+    text: str | bytes,
+    private: bool = False,
+) -> None:
     """Atomically writes `text` to the given path.
 
     Automatically creates all parent directories.
     """
-    if not isinstance(path, Path):
-        path = Path(path)
     data = text
     if isinstance(text, str):
         data = text.encode()
@@ -329,42 +366,54 @@ def _write_file(path: Path | str, text: str | bytes):
     directory = path.parent
     directory.mkdir(exist_ok=True, parents=True)
 
-    tmp_path = None
+    tmp_filename: Path | None = None
+    missing_fchmod = False
     try:
+        # Modern versions of Python tempfile create this file with mode 0o600
         with tempfile.NamedTemporaryFile(
             mode="wb", dir=directory, delete=False
         ) as f_handle:
-            tmp_path = f_handle.name
             f_handle.write(data)
-        # Newer tempfile implementations create the file with mode 0o600
-        os.chmod(tmp_path, 0o644)
-        # If destination exists, will be overwritten
-        os.replace(tmp_path, path)
+            tmp_filename = Path(f_handle.name)
+
+            if not private:
+                try:
+                    os.fchmod(f_handle.fileno(), 0o644)
+                except AttributeError:
+                    # os.fchmod is not available on Windows
+                    missing_fchmod = True
+        shutil.move(tmp_filename, path)
+        if missing_fchmod:
+            path.chmod(0o644)
     finally:
-        if tmp_path is not None and os.path.exists(tmp_path):
+        if tmp_filename and tmp_filename.exists():
             try:
-                os.remove(tmp_path)
+                tmp_filename.unlink()
             except OSError as err:
-                _LOGGER.error("Write file cleanup failed: %s", err)
+                # If we are cleaning up then something else went wrong, so
+                # we should suppress likely follow-on errors in the cleanup
+                _LOGGER.error(
+                    "File replacement cleanup failed for %s while saving %s: %s",
+                    tmp_filename,
+                    path,
+                    err,
+                )
 
 
-def write_file(path: Path | str, text: str):
+def write_file(path: Path, text: str | bytes, private: bool = False) -> None:
     try:
-        _write_file(path, text)
+        _write_file(path, text, private=private)
     except OSError as err:
         from esphome.core import EsphomeError
 
         raise EsphomeError(f"Could not write file at {path}") from err
 
 
-def write_file_if_changed(path: Path | str, text: str) -> bool:
+def write_file_if_changed(path: Path, text: str) -> bool:
     """Write text to the given path, but not if the contents match already.
 
     Returns true if the file was changed.
     """
-    if not isinstance(path, Path):
-        path = Path(path)
-
     src_content = None
     if path.is_file():
         src_content = read_file(path)
@@ -374,12 +423,10 @@ def write_file_if_changed(path: Path | str, text: str) -> bool:
     return True
 
 
-def copy_file_if_changed(src: os.PathLike, dst: os.PathLike) -> None:
-    import shutil
-
+def copy_file_if_changed(src: Path, dst: Path) -> None:
     if file_compare(src, dst):
         return
-    mkdir_p(os.path.dirname(dst))
+    dst.parent.mkdir(parents=True, exist_ok=True)
     try:
         shutil.copyfile(src, dst)
     except OSError as err:
@@ -404,12 +451,12 @@ def list_starts_with(list_, sub):
     return len(sub) <= len(list_) and all(list_[i] == x for i, x in enumerate(sub))
 
 
-def file_compare(path1: os.PathLike, path2: os.PathLike) -> bool:
+def file_compare(path1: Path, path2: Path) -> bool:
     """Return True if the files path1 and path2 have the same contents."""
     import stat
 
     try:
-        stat1, stat2 = os.stat(path1), os.stat(path2)
+        stat1, stat2 = path1.stat(), path2.stat()
     except OSError:
         # File doesn't exist or another error -> not equal
         return False
@@ -426,7 +473,7 @@ def file_compare(path1: os.PathLike, path2: os.PathLike) -> bool:
 
     bufsize = 8 * 1024
     # Read files in blocks until a mismatch is found
-    with open(path1, "rb") as fh1, open(path2, "rb") as fh2:
+    with path1.open("rb") as fh1, path2.open("rb") as fh2:
         while True:
             blob1, blob2 = fh1.read(bufsize), fh2.read(bufsize)
             if blob1 != blob2: