From c4ddad023775ee3734726dfb50aad90d53e12318 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Sun, 23 Aug 2026 12:57:59 -0500 Subject: [PATCH] Trim comments and docstrings --- esphome/build_helpers/idedata.py | 49 ++++++++++---------------------- 1 file changed, 15 insertions(+), 34 deletions(-) diff --git a/esphome/build_helpers/idedata.py b/esphome/build_helpers/idedata.py index 28700f3071..5e4d1cd25d 100644 --- a/esphome/build_helpers/idedata.py +++ b/esphome/build_helpers/idedata.py @@ -21,9 +21,8 @@ import subprocess from esphome.core import EsphomeError from esphome.helpers import write_file -# Everything idedata generation may raise after a successful link. Broad on -# purpose, and shared by every consumer: idedata is a bonus artifact, so -# these must be caught and warned about, never allowed to fail the build. +# Everything idedata generation may raise after a successful link; idedata +# is a bonus artifact, so consumers warn instead of failing the build IDEDATA_BEST_EFFORT_ERRORS = ( EsphomeError, LookupError, @@ -44,12 +43,8 @@ _ESPHOME_SRC_MARKER = "/src/esphome/" def _is_esphome_src(file: str) -> bool: - """Whether ``file`` is an ESPHome C++ translation unit. - - ``compile_commands.json`` ``file`` paths use the OS-native separator, so on - Windows they contain backslashes; normalize to ``/`` before testing the - marker, otherwise no source matches and the build-include union is empty. - """ + """Whether ``file`` is an ESPHome C++ translation unit; normalized to + ``/`` first since Windows compile DBs use backslashes.""" return _ESPHOME_SRC_MARKER in file.replace("\\", "/") and file.endswith( _CXX_SUFFIXES ) @@ -120,11 +115,8 @@ def _expand_response_files(tokens: list[str], directory: Path) -> list[str]: def _pick_entry(entries: list[dict]) -> dict: - """Pick a representative ESPHome C++ translation unit. - - All ESPHome sources share the same component flags/defines, so any one of - them yields the cxx_path / cxx_flags / defines we need. - """ + """Pick a representative ESPHome C++ TU; all share the same component + flags/defines.""" for entry in entries: if _is_esphome_src(entry["file"]): return entry @@ -151,11 +143,8 @@ def parse_entry( tokens = _expand_response_files(_split_command(entry["command"]), directory) def _include(raw: str) -> str: - # Include paths in compile_commands are interpreted relative to the - # entry's ``directory`` (e.g. build-local ``-Iconfig``); resolve them - # so the cached idedata is usable regardless of the consumer's cwd. - # Emit forward slashes (``normpath`` yields ``\`` on Windows) so the - # paths match the absolute, already-forward-slash entries in the JSON. + # Resolve against the entry's ``directory`` so cached idedata works + # from any cwd; emit forward slashes to match the JSON's own entries raw = raw.strip() if raw and not Path(raw).is_absolute(): raw = os.path.normpath(directory / raw) @@ -165,14 +154,11 @@ def parse_entry( if launcher is not None and tokens[:1] == [launcher]: tokens = tokens[1:] if not tokens: - # _split_command("") is [] by design, and a command that is only - # the launcher strips to nothing; fail like _pick_entry does - # instead of an IndexError traceback + # An empty command, or one that was only the launcher; fail by name raise ValueError(f"empty compile command for {entry.get('file')}") if _is_launcher(tokens[0]) and len(tokens) > 1 and not tokens[1].startswith("-"): - # A stale compile DB built with a launcher the current run no longer - # configures: the real compiler is the next token. Warn: the DB is - # stale and worth regenerating. + # Stale DB built with a launcher this run no longer configures; the + # real compiler is the next token _LOGGER.warning("Stripping unconfigured launcher %s", tokens[0]) tokens = tokens[1:] # token0 is the compiler path; the rest of the command already uses forward @@ -316,11 +302,8 @@ def load_or_build_idedata( def reject_launcher_compiler(cxx_path: str) -> None: - """Reject a compile DB that names a launcher (ccache) as the compiler. - - Reject before the toolchain probe, which would fail opaquely on a - launcher; the unusable compile DB must never be cached or consumed. - """ + """Reject a compile DB naming a launcher (ccache) as the compiler; it + must never be probed, cached, or consumed.""" if _is_launcher(cxx_path): raise EsphomeError( f"compile_commands.json names the launcher {cxx_path} as the " @@ -382,10 +365,8 @@ def idedata_from_build(compile_commands: Path, launcher: str | None = None) -> d build_includes.setdefault(inc, None) if not has_esphome_tu: - # _pick_entry fell back to an arbitrary C++ entry: idedata built - # from it breaks clang-tidy/IDE consumers, and a one-time warning - # would be cached into permanence. The best-effort call sites - # downgrade this to a build warning. + # An arbitrary fallback TU breaks clang-tidy/IDE consumers, and a + # warning would be cached into permanence; call sites downgrade this raise EsphomeError( f"No ESPHome translation unit found in {compile_commands}; " "refusing to cache unusable idedata"