esphome 2025.8.4__py3-none-any.whl → 2025.9.0__py3-none-any.whl

esphome/coroutine.py

@@ -42,7 +42,10 @@ Here everything is combined in `yield` expressions. You await other coroutines u
 the last `yield` expression defines what is returned.
 """
 
+from __future__ import annotations
+
 from collections.abc import Awaitable, Callable, Generator, Iterator
+import enum
 import functools
 import heapq
 import inspect
@@ -53,6 +56,79 @@ from typing import Any
 _LOGGER = logging.getLogger(__name__)
 
 
+class CoroPriority(enum.IntEnum):
+    """Execution priority stages for ESPHome code generation.
+
+    Higher values run first. These stages ensure proper dependency
+    resolution during code generation.
+    """
+
+    # Platform initialization - must run first
+    # Examples: esp32, esp8266, rp2040
+    PLATFORM = 1000
+
+    # Network infrastructure setup
+    # Examples: network (201)
+    NETWORK = 201
+
+    # Network transport layer
+    # Examples: async_tcp (200)
+    NETWORK_TRANSPORT = 200
+
+    # Core system components
+    # Examples: esphome core, most entity base components (cover, update, datetime,
+    # valve, alarm_control_panel, lock, event, binary_sensor, button, climate, fan,
+    # light, media_player, number, select, sensor, switch, text_sensor, text),
+    # microphone, speaker, audio_dac, touchscreen, stepper
+    CORE = 100
+
+    # Diagnostic and debugging systems
+    # Examples: logger (90)
+    DIAGNOSTICS = 90
+
+    # Status and monitoring systems
+    # Examples: status_led (80)
+    STATUS = 80
+
+    # Communication protocols and services
+    # Examples: web_server_base (65), captive_portal (64), wifi (60), ethernet (60),
+    # mdns (55), ota_updates (54), web_server_ota (52)
+    COMMUNICATION = 60
+
+    # Application-level services
+    # Examples: safe_mode (50)
+    APPLICATION = 50
+
+    # Web and UI services
+    # Examples: web_server (40)
+    WEB = 40
+
+    # Automations and user logic
+    # Examples: esphome core automations (30)
+    AUTOMATION = 30
+
+    # Bus and peripheral setup
+    # Examples: i2c (1)
+    BUS = 1
+
+    # Standard component priority (default)
+    # Components without explicit priority run at 0
+    COMPONENT = 0
+
+    # Components that need others to be registered first
+    # Examples: globals (-100)
+    LATE = -100
+
+    # Platform-specific workarounds and fixes
+    # Examples: add_arduino_global_workaround (-999), esp8266 pin states (-999)
+    WORKAROUNDS = -999
+
+    # Final setup that requires all components to be registered
+    # Examples: add_includes, _add_platformio_options, _add_platform_defines (all -1000),
+    # esp32_ble_tracker feature defines (-1000)
+    FINAL = -1000
+
+
 def coroutine(func: Callable[..., Any]) -> Callable[..., Awaitable[Any]]:
     """Decorator to apply to methods to convert them to ESPHome coroutines."""
     if getattr(func, "_esphome_coroutine", False):
@@ -95,15 +171,16 @@ def coroutine(func: Callable[..., Any]) -> Callable[..., Awaitable[Any]]:
     return coro
 
 
-def coroutine_with_priority(priority: float):
+def coroutine_with_priority(priority: float | CoroPriority):
     """Decorator to apply to functions to convert them to ESPHome coroutines.
 
     :param priority: priority with which to schedule the coroutine, higher priorities run first.
+                     Can be a float or a CoroPriority enum value.
     """
 
     def decorator(func):
         coro = coroutine(func)
-        coro.priority = priority
+        coro.priority = float(priority)
         return coro
 
     return decorator
@@ -173,7 +250,7 @@ class _Task:
         self.iterator = iterator
         self.original_function = original_function
 
-    def with_priority(self, priority: float) -> "_Task":
+    def with_priority(self, priority: float) -> _Task:
         return _Task(priority, self.id_number, self.iterator, self.original_function)
 
     @property

esphome/cpp_generator.py

@@ -253,6 +253,19 @@ class StringLiteral(Literal):
         return cpp_string_escape(self.string)
 
 
+class LogStringLiteral(Literal):
+    """A string literal that uses LOG_STR() macro for flash storage on ESP8266."""
+
+    __slots__ = ("string",)
+
+    def __init__(self, string: str) -> None:
+        super().__init__()
+        self.string = string
+
+    def __str__(self) -> str:
+        return f"LOG_STR({cpp_string_escape(self.string)})"
+
+
 class IntLiteral(Literal):
     __slots__ = ("i",)
 

esphome/cpp_helpers.py

@@ -9,7 +9,7 @@ from esphome.const import (
 )
 from esphome.core import CORE, ID, coroutine
 from esphome.coroutine import FakeAwaitable
-from esphome.cpp_generator import add, get_variable
+from esphome.cpp_generator import LogStringLiteral, add, get_variable
 from esphome.cpp_types import App
 from esphome.types import ConfigFragmentType, ConfigType
 from esphome.util import Registry, RegistryEntry
@@ -76,7 +76,7 @@ async def register_component(var, config):
             "Error while finding name of component, please report this", exc_info=e
         )
     if name is not None:
-        add(var.set_component_source(name))
+        add(var.set_component_source(LogStringLiteral(name)))
 
     add(App.register_component(var))
     return var

esphome/dashboard/web_server.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 import base64
+import binascii
 from collections.abc import Callable, Iterable
 import datetime
 import functools
@@ -490,7 +491,17 @@ class WizardRequestHandler(BaseHandler):
         kwargs = {
             k: v
             for k, v in json.loads(self.request.body.decode()).items()
-            if k in ("name", "platform", "board", "ssid", "psk", "password")
+            if k
+            in (
+                "type",
+                "name",
+                "platform",
+                "board",
+                "ssid",
+                "psk",
+                "password",
+                "file_content",
+            )
         }
         if not kwargs["name"]:
             self.set_status(422)
@@ -498,19 +509,65 @@ class WizardRequestHandler(BaseHandler):
             self.write(json.dumps({"error": "Name is required"}))
             return
 
+        if "type" not in kwargs:
+            # Default to basic wizard type for backwards compatibility
+            kwargs["type"] = "basic"
+
         kwargs["friendly_name"] = kwargs["name"]
         kwargs["name"] = friendly_name_slugify(kwargs["friendly_name"])
-
-        kwargs["ota_password"] = secrets.token_hex(16)
-        noise_psk = secrets.token_bytes(32)
-        kwargs["api_encryption_key"] = base64.b64encode(noise_psk).decode()
+        if kwargs["type"] == "basic":
+            kwargs["ota_password"] = secrets.token_hex(16)
+            noise_psk = secrets.token_bytes(32)
+            kwargs["api_encryption_key"] = base64.b64encode(noise_psk).decode()
+        elif kwargs["type"] == "upload":
+            try:
+                kwargs["file_text"] = base64.b64decode(kwargs["file_content"]).decode(
+                    "utf-8"
+                )
+            except (binascii.Error, UnicodeDecodeError):
+                self.set_status(422)
+                self.set_header("content-type", "application/json")
+                self.write(
+                    json.dumps({"error": "The uploaded file is not correctly encoded."})
+                )
+                return
+        elif kwargs["type"] != "empty":
+            self.set_status(422)
+            self.set_header("content-type", "application/json")
+            self.write(
+                json.dumps(
+                    {"error": f"Invalid wizard type specified: {kwargs['type']}"}
+                )
+            )
+            return
         filename = f"{kwargs['name']}.yaml"
         destination = settings.rel_path(filename)
-        wizard.wizard_write(path=destination, **kwargs)
-        self.set_status(200)
-        self.set_header("content-type", "application/json")
-        self.write(json.dumps({"configuration": filename}))
-        self.finish()
+
+        # Check if destination file already exists
+        if os.path.exists(destination):
+            self.set_status(409)  # Conflict status code
+            self.set_header("content-type", "application/json")
+            self.write(
+                json.dumps({"error": f"Configuration file '{filename}' already exists"})
+            )
+            self.finish()
+            return
+
+        success = wizard.wizard_write(path=destination, **kwargs)
+        if success:
+            self.set_status(200)
+            self.set_header("content-type", "application/json")
+            self.write(json.dumps({"configuration": filename}))
+            self.finish()
+        else:
+            self.set_status(500)
+            self.set_header("content-type", "application/json")
+            self.write(
+                json.dumps(
+                    {"error": "Failed to write configuration, see logs for details"}
+                )
+            )
+            self.finish()
 
 
 class ImportRequestHandler(BaseHandler):
@@ -981,12 +1038,9 @@ class ArchiveRequestHandler(BaseHandler):
         shutil.move(config_file, os.path.join(archive_path, configuration))
 
         storage_json = StorageJSON.load(storage_path)
-        if storage_json is not None:
+        if storage_json is not None and storage_json.build_path:
             # Delete build folder (if exists)
-            name = storage_json.name
-            build_folder = os.path.join(settings.config_dir, name)
-            if build_folder is not None:
-                shutil.rmtree(build_folder, os.path.join(archive_path, name))
+            shutil.rmtree(storage_json.build_path, ignore_errors=True)
 
 
 class UnArchiveRequestHandler(BaseHandler):

esphome/espota2.py

@@ -308,8 +308,12 @@ def perform_ota(
     time.sleep(1)
 
 
-def run_ota_impl_(remote_host, remote_port, password, filename):
+def run_ota_impl_(
+    remote_host: str | list[str], remote_port: int, password: str, filename: str
+) -> tuple[int, str | None]:
+    # 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)
     except EsphomeError as err:
         _LOGGER.error(
@@ -340,19 +344,22 @@ def run_ota_impl_(remote_host, remote_port, password, filename):
                 perform_ota(sock, password, file_handle, filename)
             except OTAError as err:
                 _LOGGER.error(str(err))
-                return 1
+                return 1, None
             finally:
                 sock.close()
 
-        return 0
+        # Successfully uploaded to sa[0]
+        return 0, sa[0]
 
     _LOGGER.error("Connection failed.")
-    return 1
+    return 1, None
 
 
-def run_ota(remote_host, remote_port, password, filename):
+def run_ota(
+    remote_host: str | list[str], remote_port: int, password: str, filename: str
+) -> tuple[int, str | None]:
     try:
         return run_ota_impl_(remote_host, remote_port, password, filename)
     except OTAError as err:
         _LOGGER.error(err)
-        return 1
+        return 1, None

esphome/helpers.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import codecs
 from contextlib import suppress
 import ipaddress
@@ -11,6 +13,18 @@ from urllib.parse import urlparse
 
 from esphome.const import __version__ as ESPHOME_VERSION
 
+# Type aliases for socket address information
+AddrInfo = tuple[
+    int,  # family (AF_INET, AF_INET6, etc.)
+    int,  # type (SOCK_STREAM, SOCK_DGRAM, etc.)
+    int,  # proto (IPPROTO_TCP, etc.)
+    str,  # canonname
+    tuple[str, int] | tuple[str, int, int, int],  # sockaddr (IPv4 or IPv6)
+]
+IPv4SockAddr = tuple[str, int]  # (host, port)
+IPv6SockAddr = tuple[str, int, int, int]  # (host, port, flowinfo, scope_id)
+SockAddr = IPv4SockAddr | IPv6SockAddr
+
 _LOGGER = logging.getLogger(__name__)
 
 IS_MACOS = platform.system() == "Darwin"
@@ -147,32 +161,7 @@ def is_ip_address(host):
         return False
 
 
-def _resolve_with_zeroconf(host):
-    from esphome.core import EsphomeError
-    from esphome.zeroconf import EsphomeZeroconf
-
-    try:
-        zc = EsphomeZeroconf()
-    except Exception as err:
-        raise EsphomeError(
-            "Cannot start mDNS sockets, is this a docker container without "
-            "host network mode?"
-        ) from err
-    try:
-        info = zc.resolve_host(f"{host}.")
-    except Exception as err:
-        raise EsphomeError(f"Error resolving mDNS hostname: {err}") from err
-    finally:
-        zc.close()
-    if info is None:
-        raise EsphomeError(
-            "Error resolving address with mDNS: Did not respond. "
-            "Maybe the device is offline."
-        )
-    return info
-
-
-def addr_preference_(res):
+def addr_preference_(res: AddrInfo) -> int:
     # Trivial alternative to RFC6724 sorting. Put sane IPv6 first, then
     # Legacy IP, then IPv6 link-local addresses without an actual link.
     sa = res[4]
@@ -184,66 +173,70 @@ def addr_preference_(res):
     return 1
 
 
-def resolve_ip_address(host, port):
+def resolve_ip_address(host: str | list[str], port: int) -> list[AddrInfo]:
     import socket
 
-    from esphome.core import EsphomeError
-
     # There are five cases here. The host argument could be one of:
     #  • a *list* of IP addresses discovered by MQTT,
     #  • a single IP address specified by the user,
     #  • a .local hostname to be resolved by mDNS,
     #  • a normal hostname to be resolved in DNS, or
     #  • A URL from which we should extract the hostname.
-    #
-    # In each of the first three cases, we end up with IP addresses in
-    # string form which need to be converted to a 5-tuple to be used
-    # for the socket connection attempt. The easiest way to construct
-    # those is to pass the IP address string to getaddrinfo(). Which,
-    # coincidentally, is how we do hostname lookups in the other cases
-    # too. So first build a list which contains either IP addresses or
-    # a single hostname, then call getaddrinfo() on each element of
-    # that list.
-
-    errs = []
+
+    hosts: list[str]
     if isinstance(host, list):
-        addr_list = host
-    elif is_ip_address(host):
-        addr_list = [host]
+        hosts = host
     else:
-        url = urlparse(host)
-        if url.scheme != "":
-            host = url.hostname
-
-        addr_list = []
-        if host.endswith(".local"):
+        if not is_ip_address(host):
+            url = urlparse(host)
+            if url.scheme != "":
+                host = url.hostname
+        hosts = [host]
+
+    res: list[AddrInfo] = []
+    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:
-                _LOGGER.info("Resolving IP address of %s in mDNS", host)
-                addr_list = _resolve_with_zeroconf(host)
-            except EsphomeError as err:
-                errs.append(str(err))
-
-        # If not mDNS, or if mDNS failed, use normal DNS
-        if not addr_list:
-            addr_list = [host]
-
-    # Now we have a list containing either IP addresses or a hostname
-    res = []
-    for addr in addr_list:
-        if not is_ip_address(addr):
-            _LOGGER.info("Resolving IP address of %s", host)
-        try:
-            r = socket.getaddrinfo(addr, port, proto=socket.IPPROTO_TCP)
-        except OSError as err:
-            errs.append(str(err))
-            raise EsphomeError(
-                f"Error resolving IP address: {', '.join(errs)}"
-            ) from err
-
-        res = res + r
+                res += socket.getaddrinfo(
+                    addr, port, proto=socket.IPPROTO_TCP, flags=socket.AI_NUMERICHOST
+                )
+            except OSError:
+                _LOGGER.debug("Failed to parse IP address '%s'", addr)
+        # 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,
+            )
+        else:
+            # IPv4
+            sockaddr_tuple = (sockaddr.address, sockaddr.port)
+
+        res.append(
+            (
+                addr_info.family,
+                addr_info.type,
+                addr_info.proto,
+                "",  # canonname
+                sockaddr_tuple,
+            )
+        )
 
-    # Zeroconf tends to give us link-local IPv6 addresses without specifying
-    # the link. Put those last in the list to be attempted.
+    # Sort by preference
     res.sort(key=addr_preference_)
     return res
 
@@ -262,15 +255,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[
-        tuple[
-            int,
-            int,
-            int,
-            str | None,
-            tuple[str, int] | tuple[str, int, int, int],
-        ]
-    ] = []
+    res: list[AddrInfo] = []
     for addr in address_list:
         # This should always work as these are supposed to be IP addresses
         try:

esphome/resolver.py

@@ -0,0 +1,67 @@
+"""DNS resolver for ESPHome using aioesphomeapi."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+
+from aioesphomeapi.core import ResolveAPIError, ResolveTimeoutAPIError
+import aioesphomeapi.host_resolver as hr
+
+from esphome.core import EsphomeError
+
+RESOLVE_TIMEOUT = 10.0  # seconds
+
+
+class AsyncResolver(threading.Thread):
+    """Resolver using aioesphomeapi that runs in a thread for faster results.
+
+    This resolver uses aioesphomeapi's async_resolve_host to handle DNS resolution,
+    including proper .local domain fallback. Running in a thread allows us to get
+    the result immediately without waiting for asyncio.run() to complete its
+    cleanup cycle, which can take significant time.
+    """
+
+    def __init__(self, hosts: list[str], port: int) -> None:
+        """Initialize the resolver."""
+        super().__init__(daemon=True)
+        self.hosts = hosts
+        self.port = port
+        self.result: list[hr.AddrInfo] | None = None
+        self.exception: Exception | None = None
+        self.event = threading.Event()
+
+    async def _resolve(self) -> None:
+        """Resolve hostnames to IP addresses."""
+        try:
+            self.result = await hr.async_resolve_host(
+                self.hosts, self.port, timeout=RESOLVE_TIMEOUT
+            )
+        except Exception as e:  # pylint: disable=broad-except
+            # We need to catch all exceptions to ensure the event is set
+            # Otherwise the thread could hang forever
+            self.exception = e
+        finally:
+            self.event.set()
+
+    def run(self) -> None:
+        """Run the DNS resolution."""
+        asyncio.run(self._resolve())
+
+    def resolve(self) -> list[hr.AddrInfo]:
+        """Start the thread and wait for the result."""
+        self.start()
+
+        if not self.event.wait(
+            timeout=RESOLVE_TIMEOUT + 1.0
+        ):  # Give it 1 second more than the resolver timeout
+            raise EsphomeError("Timeout resolving IP address")
+
+        if exc := self.exception:
+            if isinstance(exc, ResolveTimeoutAPIError):
+                raise EsphomeError(f"Timeout resolving IP address: {exc}") from exc
+            if isinstance(exc, ResolveAPIError):
+                raise EsphomeError(f"Error resolving IP address: {exc}") from exc
+            raise exc
+
+        return self.result

esphome/util.py

@@ -272,12 +272,15 @@ class OrderedDict(collections.OrderedDict):
         return dict(self).__repr__()
 
 
-def list_yaml_files(folders: list[str]) -> list[str]:
-    files = filter_yaml_files(
-        [os.path.join(folder, p) for folder in folders for p in os.listdir(folder)]
-    )
-    files.sort()
-    return files
+def list_yaml_files(configs: list[str]) -> list[str]:
+    files: list[str] = []
+    for config in configs:
+        if os.path.isfile(config):
+            files.append(config)
+        else:
+            files.extend(os.path.join(config, p) for p in os.listdir(config))
+    files = filter_yaml_files(files)
+    return sorted(files)
 
 
 def filter_yaml_files(files: list[str]) -> list[str]: