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

esphome/loader.py

@@ -82,11 +82,10 @@ class ComponentManifest:
         return getattr(self.module, "CONFLICTS_WITH", [])
 
     @property
-    def auto_load(self) -> list[str]:
-        al = getattr(self.module, "AUTO_LOAD", [])
-        if callable(al):
-            return al()
-        return al
+    def auto_load(
+        self,
+    ) -> list[str] | Callable[[], list[str]] | Callable[[ConfigType], list[str]]:
+        return getattr(self.module, "AUTO_LOAD", [])
 
     @property
     def codeowners(self) -> list[str]:
@@ -192,7 +191,7 @@ def install_custom_components_meta_finder():
     install_meta_finder(custom_components_dir)
 
 
-def _lookup_module(domain, exception):
+def _lookup_module(domain: str, exception: bool) -> ComponentManifest | None:
     if domain in _COMPONENT_CACHE:
         return _COMPONENT_CACHE[domain]
 
@@ -219,16 +218,16 @@ def _lookup_module(domain, exception):
     return manif
 
 
-def get_component(domain, exception=False):
+def get_component(domain: str, exception: bool = False) -> ComponentManifest | None:
     assert "." not in domain
     return _lookup_module(domain, exception)
 
 
-def get_platform(domain, platform):
+def get_platform(domain: str, platform: str) -> ComponentManifest | None:
     full = f"{platform}.{domain}"
     return _lookup_module(full, False)
 
 
-_COMPONENT_CACHE = {}
+_COMPONENT_CACHE: dict[str, ComponentManifest] = {}
 CORE_COMPONENTS_PATH = (Path(__file__).parent / "components").resolve()
 _COMPONENT_CACHE["esphome"] = ComponentManifest(esphome.core.config)

esphome/pins.py

@@ -118,11 +118,11 @@ class PinRegistry(dict):
                         parent_config = fconf.get_config_for_path(parent_path)
                         final_val_fun(pin_config, parent_config)
                     allow_others = pin_config.get(CONF_ALLOW_OTHER_USES, False)
-                    if count != 1 and not allow_others:
+                    if count != 1 and not allow_others and not CORE.testing_mode:
                         raise cv.Invalid(
                             f"Pin {pin_config[CONF_NUMBER]} is used in multiple places"
                         )
-                    if count == 1 and allow_others:
+                    if count == 1 and allow_others and not CORE.testing_mode:
                         raise cv.Invalid(
                             f"Pin {pin_config[CONF_NUMBER]} incorrectly sets {CONF_ALLOW_OTHER_USES}: true"
                         )

esphome/platformio_api.py

@@ -5,6 +5,7 @@ import os
 from pathlib import Path
 import re
 import subprocess
+from typing import Any
 
 from esphome.const import CONF_COMPILE_PROCESS_LIMIT, CONF_ESPHOME, KEY_CORE
 from esphome.core import CORE, EsphomeError
@@ -18,28 +19,59 @@ def patch_structhash():
     # removed/added. This might have unintended consequences, but this improves compile
     # times greatly when adding/removing components and a simple clean build solves
     # all issues
-    from os import makedirs
-    from os.path import getmtime, isdir, join
-
     from platformio.run import cli, helpers
 
     def patched_clean_build_dir(build_dir, *args):
         from platformio import fs
         from platformio.project.helpers import get_project_dir
 
-        platformio_ini = join(get_project_dir(), "platformio.ini")
+        platformio_ini = Path(get_project_dir()) / "platformio.ini"
+
+        build_dir = Path(build_dir)
 
         # if project's config is modified
-        if isdir(build_dir) and getmtime(platformio_ini) > getmtime(build_dir):
+        if (
+            build_dir.is_dir()
+            and platformio_ini.stat().st_mtime > build_dir.stat().st_mtime
+        ):
             fs.rmtree(build_dir)
 
-        if not isdir(build_dir):
-            makedirs(build_dir)
+        if not build_dir.is_dir():
+            build_dir.mkdir(parents=True)
 
     helpers.clean_build_dir = patched_clean_build_dir
     cli.clean_build_dir = patched_clean_build_dir
 
 
+def patch_file_downloader():
+    """Patch PlatformIO's FileDownloader to retry on PackageException errors."""
+    from platformio.package.download import FileDownloader
+    from platformio.package.exception import PackageException
+
+    original_init = FileDownloader.__init__
+
+    def patched_init(self, *args: Any, **kwargs: Any) -> None:
+        max_retries = 3
+
+        for attempt in range(max_retries):
+            try:
+                return original_init(self, *args, **kwargs)
+            except PackageException as e:
+                if attempt < max_retries - 1:
+                    _LOGGER.warning(
+                        "Package download failed: %s. Retrying... (attempt %d/%d)",
+                        str(e),
+                        attempt + 1,
+                        max_retries,
+                    )
+                else:
+                    # Final attempt - re-raise
+                    raise
+        return None
+
+    FileDownloader.__init__ = patched_init
+
+
 IGNORE_LIB_WARNINGS = f"(?:{'|'.join(['Hash', 'Update'])})"
 FILTER_PLATFORMIO_LINES = [
     r"Verbose mode can be enabled via `-v, --verbose` option.*",
@@ -70,14 +102,19 @@ FILTER_PLATFORMIO_LINES = [
     r" - tool-esptool.* \(.*\)",
     r" - toolchain-.* \(.*\)",
     r"Creating BIN file .*",
+    r"Warning! Could not find file \".*.crt\"",
+    r"Warning! Arduino framework as an ESP-IDF component doesn't handle the `variant` field! The default `esp32` variant will be used.",
+    r"Warning: DEPRECATED: 'esptool.py' is deprecated. Please use 'esptool' instead. The '.py' suffix will be removed in a future major release.",
+    r"Warning: esp-idf-size exited with code 2",
+    r"esp_idf_size: error: unrecognized arguments: --ng",
 ]
 
 
 def run_platformio_cli(*args, **kwargs) -> str | int:
     os.environ["PLATFORMIO_FORCE_COLOR"] = "true"
-    os.environ["PLATFORMIO_BUILD_DIR"] = os.path.abspath(CORE.relative_pioenvs_path())
+    os.environ["PLATFORMIO_BUILD_DIR"] = str(CORE.relative_pioenvs_path().absolute())
     os.environ.setdefault(
-        "PLATFORMIO_LIBDEPS_DIR", os.path.abspath(CORE.relative_piolibdeps_path())
+        "PLATFORMIO_LIBDEPS_DIR", str(CORE.relative_piolibdeps_path().absolute())
     )
     # Suppress Python syntax warnings from third-party scripts during compilation
     os.environ.setdefault("PYTHONWARNINGS", "ignore::SyntaxWarning")
@@ -92,11 +129,12 @@ def run_platformio_cli(*args, **kwargs) -> str | int:
     import platformio.__main__
 
     patch_structhash()
+    patch_file_downloader()
     return run_external_command(platformio.__main__.main, *cmd, **kwargs)
 
 
 def run_platformio_cli_run(config, verbose, *args, **kwargs) -> str | int:
-    command = ["run", "-d", CORE.build_path]
+    command = ["run", "-d", str(CORE.build_path)]
     if verbose:
         command += ["-v"]
     command += list(args)
@@ -128,8 +166,8 @@ def _run_idedata(config):
 
 
 def _load_idedata(config):
-    platformio_ini = Path(CORE.relative_build_path("platformio.ini"))
-    temp_idedata = Path(CORE.relative_internal_path("idedata", f"{CORE.name}.json"))
+    platformio_ini = CORE.relative_build_path("platformio.ini")
+    temp_idedata = CORE.relative_internal_path("idedata", f"{CORE.name}.json")
 
     changed = False
     if (
@@ -299,7 +337,7 @@ def process_stacktrace(config, line, backtrace_state):
 
 @dataclass
 class FlashImage:
-    path: str
+    path: Path
     offset: str
 
 
@@ -308,17 +346,17 @@ class IDEData:
         self.raw = raw
 
     @property
-    def firmware_elf_path(self):
-        return self.raw["prog_path"]
+    def firmware_elf_path(self) -> Path:
+        return Path(self.raw["prog_path"])
 
     @property
-    def firmware_bin_path(self) -> str:
-        return str(Path(self.firmware_elf_path).with_suffix(".bin"))
+    def firmware_bin_path(self) -> Path:
+        return self.firmware_elf_path.with_suffix(".bin")
 
     @property
     def extra_flash_images(self) -> list[FlashImage]:
         return [
-            FlashImage(path=entry["path"], offset=entry["offset"])
+            FlashImage(path=Path(entry["path"]), offset=entry["offset"])
             for entry in self.raw["extra"]["flash_images"]
         ]
 

esphome/storage_json.py

@@ -1,11 +1,11 @@
 from __future__ import annotations
 
 import binascii
-import codecs
 from datetime import datetime
 import json
 import logging
 import os
+from pathlib import Path
 
 from esphome import const
 from esphome.const import CONF_DISABLED, CONF_MDNS
@@ -16,30 +16,35 @@ from esphome.types import CoreType
 _LOGGER = logging.getLogger(__name__)
 
 
-def storage_path() -> str:
-    return os.path.join(CORE.data_dir, "storage", f"{CORE.config_filename}.json")
+def storage_path() -> Path:
+    return CORE.data_dir / "storage" / f"{CORE.config_filename}.json"
 
 
-def ext_storage_path(config_filename: str) -> str:
-    return os.path.join(CORE.data_dir, "storage", f"{config_filename}.json")
+def ext_storage_path(config_filename: str) -> Path:
+    return CORE.data_dir / "storage" / f"{config_filename}.json"
 
 
-def esphome_storage_path() -> str:
-    return os.path.join(CORE.data_dir, "esphome.json")
+def esphome_storage_path() -> Path:
+    return CORE.data_dir / "esphome.json"
 
 
-def ignored_devices_storage_path() -> str:
-    return os.path.join(CORE.data_dir, "ignored-devices.json")
+def ignored_devices_storage_path() -> Path:
+    return CORE.data_dir / "ignored-devices.json"
 
 
-def trash_storage_path() -> str:
+def trash_storage_path() -> Path:
     return CORE.relative_config_path("trash")
 
 
-def archive_storage_path() -> str:
+def archive_storage_path() -> Path:
     return CORE.relative_config_path("archive")
 
 
+def _to_path_if_not_none(value: str | None) -> Path | None:
+    """Convert a string to Path if it's not None."""
+    return Path(value) if value is not None else None
+
+
 class StorageJSON:
     def __init__(
         self,
@@ -52,8 +57,8 @@ class StorageJSON:
         address: str,
         web_port: int | None,
         target_platform: str,
-        build_path: str | None,
-        firmware_bin_path: str | None,
+        build_path: Path | None,
+        firmware_bin_path: Path | None,
         loaded_integrations: set[str],
         loaded_platforms: set[str],
         no_mdns: bool,
@@ -107,8 +112,8 @@ class StorageJSON:
             "address": self.address,
             "web_port": self.web_port,
             "esp_platform": self.target_platform,
-            "build_path": self.build_path,
-            "firmware_bin_path": self.firmware_bin_path,
+            "build_path": str(self.build_path),
+            "firmware_bin_path": str(self.firmware_bin_path),
             "loaded_integrations": sorted(self.loaded_integrations),
             "loaded_platforms": sorted(self.loaded_platforms),
             "no_mdns": self.no_mdns,
@@ -176,8 +181,8 @@ class StorageJSON:
         )
 
     @staticmethod
-    def _load_impl(path: str) -> StorageJSON | None:
-        with codecs.open(path, "r", encoding="utf-8") as f_handle:
+    def _load_impl(path: Path) -> StorageJSON | None:
+        with path.open("r", encoding="utf-8") as f_handle:
             storage = json.load(f_handle)
         storage_version = storage["storage_version"]
         name = storage.get("name")
@@ -190,8 +195,8 @@ class StorageJSON:
         address = storage.get("address")
         web_port = storage.get("web_port")
         esp_platform = storage.get("esp_platform")
-        build_path = storage.get("build_path")
-        firmware_bin_path = storage.get("firmware_bin_path")
+        build_path = _to_path_if_not_none(storage.get("build_path"))
+        firmware_bin_path = _to_path_if_not_none(storage.get("firmware_bin_path"))
         loaded_integrations = set(storage.get("loaded_integrations", []))
         loaded_platforms = set(storage.get("loaded_platforms", []))
         no_mdns = storage.get("no_mdns", False)
@@ -217,7 +222,7 @@ class StorageJSON:
         )
 
     @staticmethod
-    def load(path: str) -> StorageJSON | None:
+    def load(path: Path) -> StorageJSON | None:
         try:
             return StorageJSON._load_impl(path)
         except Exception:  # pylint: disable=broad-except
@@ -268,7 +273,7 @@ class EsphomeStorageJSON:
 
     @staticmethod
     def _load_impl(path: str) -> EsphomeStorageJSON | None:
-        with codecs.open(path, "r", encoding="utf-8") as f_handle:
+        with Path(path).open("r", encoding="utf-8") as f_handle:
             storage = json.load(f_handle)
         storage_version = storage["storage_version"]
         cookie_secret = storage.get("cookie_secret")

esphome/types.py

@@ -1,8 +1,10 @@
 """This helper module tracks commonly used types in the esphome python codebase."""
 
-from typing import TypedDict
+import abc
+from collections.abc import Sequence
+from typing import Any, TypedDict
 
-from esphome.core import ID, EsphomeCore, Lambda
+from esphome.core import ID, EsphomeCore, Lambda, TimePeriod
 
 ConfigFragmentType = (
     str
@@ -20,6 +22,32 @@ CoreType = EsphomeCore
 ConfigPathType = str | int
 
 
+class Expression(abc.ABC):
+    __slots__ = ()
+
+    @abc.abstractmethod
+    def __str__(self):
+        """
+        Convert expression into C++ code
+        """
+
+
+SafeExpType = (
+    Expression
+    | bool
+    | str
+    | int
+    | float
+    | TimePeriod
+    | type[bool]
+    | type[int]
+    | type[float]
+    | Sequence[Any]
+)
+
+TemplateArgsType = list[tuple[SafeExpType, str]]
+
+
 class EntityMetadata(TypedDict):
     """Metadata stored for each entity to help with duplicate detection."""
 

esphome/util.py

@@ -1,20 +1,30 @@
 import collections
+from collections.abc import Callable
 import io
 import logging
-import os
 from pathlib import Path
 import re
 import subprocess
 import sys
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from esphome import const
 
 _LOGGER = logging.getLogger(__name__)
 
+if TYPE_CHECKING:
+    from esphome.config_validation import Schema
+    from esphome.cpp_generator import MockObjClass
+
 
 class RegistryEntry:
-    def __init__(self, name, fun, type_id, schema):
+    def __init__(
+        self,
+        name: str,
+        fun: Callable[..., Any],
+        type_id: "MockObjClass",
+        schema: "Schema",
+    ):
         self.name = name
         self.fun = fun
         self.type_id = type_id
@@ -39,8 +49,8 @@ class Registry(dict[str, RegistryEntry]):
         self.base_schema = base_schema or {}
         self.type_id_key = type_id_key
 
-    def register(self, name, type_id, schema):
-        def decorator(fun):
+    def register(self, name: str, type_id: "MockObjClass", schema: "Schema"):
+        def decorator(fun: Callable[..., Any]):
             self[name] = RegistryEntry(name, fun, type_id, schema)
             return fun
 
@@ -48,8 +58,8 @@ class Registry(dict[str, RegistryEntry]):
 
 
 class SimpleRegistry(dict):
-    def register(self, name, data):
-        def decorator(fun):
+    def register(self, name: str, data: Any):
+        def decorator(fun: Callable[..., Any]):
             self[name] = (fun, data)
             return fun
 
@@ -86,7 +96,10 @@ def safe_input(prompt=""):
     return input()
 
 
-def shlex_quote(s):
+def shlex_quote(s: str | Path) -> str:
+    # Convert Path objects to strings
+    if isinstance(s, Path):
+        s = str(s)
     if not s:
         return "''"
     if re.search(r"[^\w@%+=:,./-]", s) is None:
@@ -272,25 +285,28 @@ class OrderedDict(collections.OrderedDict):
         return dict(self).__repr__()
 
 
-def list_yaml_files(configs: list[str]) -> list[str]:
-    files: list[str] = []
+def list_yaml_files(configs: list[str | Path]) -> list[Path]:
+    files: list[Path] = []
     for config in configs:
-        if os.path.isfile(config):
+        config = Path(config)
+        if not config.exists():
+            raise FileNotFoundError(f"Config path '{config}' does not exist!")
+        if config.is_file():
             files.append(config)
         else:
-            files.extend(os.path.join(config, p) for p in os.listdir(config))
+            files.extend(config.glob("*"))
     files = filter_yaml_files(files)
     return sorted(files)
 
 
-def filter_yaml_files(files: list[str]) -> list[str]:
+def filter_yaml_files(files: list[Path]) -> list[Path]:
     return [
         f
         for f in files
         if (
-            os.path.splitext(f)[1] in (".yaml", ".yml")
-            and os.path.basename(f) not in ("secrets.yaml", "secrets.yml")
-            and not os.path.basename(f).startswith(".")
+            f.suffix in (".yaml", ".yml")
+            and f.name not in ("secrets.yaml", "secrets.yml")
+            and not f.name.startswith(".")
         )
     ]
 

esphome/vscode.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from io import StringIO
 import json
-import os
+from pathlib import Path
 from typing import Any
 
 from esphome.config import Config, _format_vol_invalid, validate_config
@@ -67,24 +67,24 @@ def _read_file_content_from_json_on_stdin() -> str:
     return data["content"]
 
 
-def _print_file_read_event(path: str) -> None:
+def _print_file_read_event(path: Path) -> None:
     """Print a file read event."""
     print(
         json.dumps(
             {
                 "type": "read_file",
-                "path": path,
+                "path": str(path),
             }
         )
     )
 
 
-def _request_and_get_stream_on_stdin(fname: str) -> StringIO:
+def _request_and_get_stream_on_stdin(fname: Path) -> StringIO:
     _print_file_read_event(fname)
     return StringIO(_read_file_content_from_json_on_stdin())
 
 
-def _vscode_loader(fname: str) -> dict[str, Any]:
+def _vscode_loader(fname: Path) -> dict[str, Any]:
     raw_yaml_stream = _request_and_get_stream_on_stdin(fname)
     # it is required to set the name on StringIO so document on start_mark
     # is set properly. Otherwise it is initialized with "<file>"
@@ -92,7 +92,7 @@ def _vscode_loader(fname: str) -> dict[str, Any]:
     return parse_yaml(fname, raw_yaml_stream, _vscode_loader)
 
 
-def _ace_loader(fname: str) -> dict[str, Any]:
+def _ace_loader(fname: Path) -> dict[str, Any]:
     raw_yaml_stream = _request_and_get_stream_on_stdin(fname)
     return parse_yaml(fname, raw_yaml_stream)
 
@@ -120,10 +120,10 @@ def read_config(args):
             return
         CORE.vscode = True
         if args.ace:  # Running from ESPHome Compiler dashboard, not vscode
-            CORE.config_path = os.path.join(args.configuration, data["file"])
+            CORE.config_path = Path(args.configuration) / data["file"]
             loader = _ace_loader
         else:
-            CORE.config_path = data["file"]
+            CORE.config_path = Path(data["file"])
             loader = _vscode_loader
 
         file_name = CORE.config_path

esphome/wizard.py

@@ -1,4 +1,4 @@
-import os
+from pathlib import Path
 import random
 import string
 from typing import Literal, NotRequired, TypedDict, Unpack
@@ -213,7 +213,7 @@ class WizardWriteKwargs(TypedDict):
     file_text: NotRequired[str]
 
 
-def wizard_write(path: str, **kwargs: Unpack[WizardWriteKwargs]) -> bool:
+def wizard_write(path: Path, **kwargs: Unpack[WizardWriteKwargs]) -> bool:
     from esphome.components.bk72xx import boards as bk72xx_boards
     from esphome.components.esp32 import boards as esp32_boards
     from esphome.components.esp8266 import boards as esp8266_boards
@@ -256,13 +256,13 @@ def wizard_write(path: str, **kwargs: Unpack[WizardWriteKwargs]) -> bool:
         file_text = wizard_file(**kwargs)
 
     # Check if file already exists to prevent overwriting
-    if os.path.exists(path) and os.path.isfile(path):
+    if path.exists() and path.is_file():
         safe_print(color(AnsiFore.RED, f'The file "{path}" already exists.'))
         return False
 
     write_file(path, file_text)
     storage = StorageJSON.from_wizard(name, name, f"{name}.local", hardware)
-    storage_path = ext_storage_path(os.path.basename(path))
+    storage_path = ext_storage_path(path.name)
     storage.save(storage_path)
 
     return True
@@ -301,7 +301,7 @@ def strip_accents(value: str) -> str:
     )
 
 
-def wizard(path: str) -> int:
+def wizard(path: Path) -> int:
     from esphome.components.bk72xx import boards as bk72xx_boards
     from esphome.components.esp32 import boards as esp32_boards
     from esphome.components.esp8266 import boards as esp8266_boards
@@ -309,14 +309,14 @@ def wizard(path: str) -> int:
     from esphome.components.rp2040 import boards as rp2040_boards
     from esphome.components.rtl87xx import boards as rtl87xx_boards
 
-    if not path.endswith(".yaml") and not path.endswith(".yml"):
+    if path.suffix not in (".yaml", ".yml"):
         safe_print(
-            f"Please make your configuration file {color(AnsiFore.CYAN, path)} have the extension .yaml or .yml"
+            f"Please make your configuration file {color(AnsiFore.CYAN, str(path))} have the extension .yaml or .yml"
         )
         return 1
-    if os.path.exists(path):
+    if path.exists():
         safe_print(
-            f"Uh oh, it seems like {color(AnsiFore.CYAN, path)} already exists, please delete that file first or chose another configuration file."
+            f"Uh oh, it seems like {color(AnsiFore.CYAN, str(path))} already exists, please delete that file first or chose another configuration file."
         )
         return 2
 
@@ -549,7 +549,7 @@ def wizard(path: str) -> int:
     safe_print()
     safe_print(
         color(AnsiFore.CYAN, "DONE! I've now written a new configuration file to ")
-        + color(AnsiFore.BOLD_CYAN, path)
+        + color(AnsiFore.BOLD_CYAN, str(path))
     )
     safe_print()
     safe_print("Next steps:")