From 2bcaf016b34abd1cbcb4550ca2053052dda67fde Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Thu, 8 Oct 2026 06:36:00 -1000 Subject: [PATCH] [core] Trim the discovery helper comments --- esphome/components/packages/__init__.py | 5 ++--- esphome/yaml_util.py | 24 ++++++++---------------- 2 files changed, 10 insertions(+), 19 deletions(-) diff --git a/esphome/components/packages/__init__.py b/esphome/components/packages/__init__.py index 8d3ce463627..e38de88b07a 100644 --- a/esphome/components/packages/__init__.py +++ b/esphome/components/packages/__init__.py @@ -65,10 +65,9 @@ def _get_data() -> PackagesData: def get_remote_package_sources() -> tuple[RemotePackageSource, ...]: - """Remote sources fetched while processing this config, in fetch order. + """Remote sources fetched for this config, in fetch order. - Consumers (e.g. store_yaml) use this to tell which parts of the config - came from remote repositories rather than local files. + store_yaml uses them to tell remote parts of the config from local files. """ if (data := CORE.data.get(DOMAIN)) is None: return () diff --git a/esphome/yaml_util.py b/esphome/yaml_util.py index 25b1f2acb59..5bdbee3c8ba 100644 --- a/esphome/yaml_util.py +++ b/esphome/yaml_util.py @@ -423,11 +423,8 @@ def _load_include_candidates( try: loaded = include.with_file(candidate.as_posix()).load() except (EsphomeError, Invalid) as err: - # A matched on-disk candidate that fails to load is a genuine user - # error; callers that report ``result.errors`` themselves pass - # warn_on_load_error=False so it is not logged twice. The file - # itself is still tracked (the load listener fires before - # parsing), only its nested includes go undiscovered. + # A real user error. The file stays tracked (the listener fires + # before parsing); only its nested includes are missed. (_LOGGER.warning if warn_on_load_error else _LOGGER.debug)( "Failed to load candidate %s for !include %s: %s", candidate, @@ -461,11 +458,9 @@ def find_secret_references(text: str) -> set[str]: class ForceLoadResult(NamedTuple): - """Outcome of :func:`force_load_include_files`. + """Templated includes that matched no file, and includes that failed to load. - ``unresolved`` lists ``!include`` path strings with substitution variables or - expressions that matched no candidate file; ``errors`` lists includes that failed - to load. Either being non-empty means the walk was incomplete. + Either being non-empty means the walk was incomplete. """ unresolved: list[str] @@ -489,9 +484,8 @@ def force_load_include_files( expression could select. By default a warning is logged when no candidate exists; pass ``warn_on_unresolved=False`` (used by discovery paths that run on a fresh re-parse where substitutions haven't been applied yet) to - demote it to a debug log. Includes that fail to load are logged as - warnings too; callers that report ``errors`` themselves pass - ``warn_on_load_error=False`` so each failure is shown once. + demote it to a debug log. Callers that report ``errors`` themselves pass + ``warn_on_load_error=False`` so load failures are not logged twice. """ result = ForceLoadResult([], []) _force_load_include_files( @@ -601,10 +595,8 @@ class DiscoveredYamlFiles: were re-parsing the user's config; ``secrets`` is the subset whose *un-resolved* filename matched :data:`esphome.const.SECRETS_FILES` (so a ``secrets.yaml`` symlinked to a differently-named target is still - flagged as secrets). ``unresolved`` lists ``!include`` path strings that - contain substitution variables and therefore could not be loaded, and - ``load_errors`` lists files that failed to parse or load — consumers - should treat ``files`` as incomplete when either is non-empty. + flagged as secrets). ``files`` is incomplete when ``unresolved`` (templated + include paths) or ``load_errors`` is non-empty. """ files: list[Path] = field(default_factory=list)