From cdde9dd230c838b81b30f697ef7447b4a4bf902d Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Sat, 22 Aug 2026 11:39:54 -0500 Subject: [PATCH] Trim comment essays and hoist function-local test imports --- esphome/arduino8266/framework.py | 52 +++++-------------- .../unit_tests/test_arduino8266_framework.py | 10 ++-- tests/unit_tests/test_writer.py | 2 - 3 files changed, 18 insertions(+), 46 deletions(-) diff --git a/esphome/arduino8266/framework.py b/esphome/arduino8266/framework.py index 5ca305e0ef..f680815c31 100644 --- a/esphome/arduino8266/framework.py +++ b/esphome/arduino8266/framework.py @@ -6,14 +6,9 @@ ESP-IDF install in ``esphome.espidf.framework``): /arduino8266/frameworks// framework-arduinoespressif8266 /arduino8266/toolchains// toolchain-xtensa (gcc 10.3) -ninja itself comes from PATH or the ninja PyPI wheel (a requirements.txt -dependency), so only the two packages above are downloaded, via the shared -PlatformIO-registry installer in ``esphome.platformio.registry``. - -Sources default to the PlatformIO registry (the exact packages the PlatformIO -toolchain has always used, so the bits are identical); the -``ESPHOME_ARDUINO8266_*_MIRRORS`` environment variables override the URLs with -``{VERSION}`` / ``{SYSTEM}`` substitution. +Packages come from the PlatformIO registry (identical bits to the PlatformIO +backend); ``ESPHOME_ARDUINO8266_*_MIRRORS`` overrides the URLs. ninja comes +from PATH or the ninja PyPI wheel. """ from __future__ import annotations @@ -31,9 +26,8 @@ from esphome.platformio.registry import install_package FRAMEWORK_PACKAGE = "framework-arduinoespressif8266" TOOLCHAIN_PACKAGE = "toolchain-xtensa" -# gcc 10.3, the toolchain Arduino core 3.x builds with. The compile flags in -# the build generator are tuned to it; treat version changes as a full -# reinstall (the install dir is keyed on the version). +# gcc 10.3, the toolchain Arduino core 3.x builds with; the build +# generator's compile flags are tuned to it. TOOLCHAIN_VERSION = "2.100300.220621" ESPHOME_ARDUINO8266_FRAMEWORK_MIRRORS = str_to_lst_of_str( @@ -56,31 +50,20 @@ MIN_FRAMEWORK_VERSION = Version(3, 1, 1) def framework_package_version(ver: Version) -> str: - """Map an Arduino core version (e.g. 3.1.2) to its package version. + """Map an Arduino core version to its registry package version (3.1.2 -> + 3.30102.0; the leading 3 is the package major). - The PlatformIO registry's encoding for cores newer than 2.6.2 (3.1.2 -> - 3.30102.0, and 2.7.4 -> 3.20704.0: the leading 3 is the package major, - not the core major). Exact registry names only from 3.0.2 up: 2.6.3, - 3.0.0 and 3.0.1 ship as 3.20603.200130 / 3.30000.210519 / - 3.30001.210627, which this formula cannot produce. Safe for the - PlatformIO caller (a ~ range) and for check_and_install (floored at - MIN_FRAMEWORK_VERSION); an exact lookup below that floor must not use - this helper. A future core 4.x needs its own encoding and toolchain pin - rather than a registry lookup for a package that cannot exist. + Exact registry names only for cores > 2.6.2 and >= 3.0.2; callers floor + at MIN_FRAMEWORK_VERSION. """ if ver.major > 3: - # Backend-neutral: this also fires on the PlatformIO validation path - # (via _format_framework_arduino_version), where switching toolchains - # would not help raise EsphomeError( f"Arduino core {ver} is not supported yet; " "the newest known core series is 3.x" ) if ver <= Version(2, 6, 2): - # Same boundary as _format_framework_arduino_version's era guard (a - # 2.6.2 pre-release sorts above 2.6.2 and belongs to this encoding). - # Older cores use the 1.x/2.x package-major encodings; never encode - # them wrongly for a caller that skipped that guard + # Cores <= 2.6.2 use the older 1.x/2.x package-major encodings (same + # boundary as _format_framework_arduino_version's era guard) raise EsphomeError( f"Arduino core {ver} uses an older package encoding than this " "helper implements (newer than 2.6.2)" @@ -141,10 +124,7 @@ def check_and_install(framework_version: Version) -> InstalledPaths: ) -# Sentinel: "resolve for me" (None is a real value meaning disabled). -# The native run_compile (a later PR in the chain) will resolve once and -# thread the result so one build never pays the PATH scan and runnability -# probe three times. +# Sentinel: "resolve for me"; None is a real value meaning disabled. CCACHE_UNRESOLVED: Any = object() @@ -176,8 +156,7 @@ def get_build_env( def ccache_path() -> str | None: """The ccache binary to prefix compiles with, or None when disabled. - Deliberately uncached (matching espidf): the decision reads - ESPHOME_CCACHE_ENABLE and PATH, which can change between builds in a + Deliberately uncached: env/PATH can change between builds in a long-lived host process. """ return resolve_ccache_path() @@ -186,10 +165,7 @@ def ccache_path() -> str | None: def ccache_env(ccache: str | None = CCACHE_UNRESOLVED) -> dict[str, str]: """Return ccache settings for the build subprocess (not os.environ). - Mirrors ``espidf.framework._ccache_env``: cache under the machine-global - tools dir, depend mode (gcc emits depfiles via -MMD), and CCACHE_BASEDIR - scoped to the build dir so devices share framework cache entries. Values - the user already set in the environment are respected. + Values the user already set in the environment are respected. """ if ccache is CCACHE_UNRESOLVED: ccache = ccache_path() diff --git a/tests/unit_tests/test_arduino8266_framework.py b/tests/unit_tests/test_arduino8266_framework.py index c173fb27f2..2837be1905 100644 --- a/tests/unit_tests/test_arduino8266_framework.py +++ b/tests/unit_tests/test_arduino8266_framework.py @@ -26,9 +26,8 @@ def test_framework_package_version() -> None: # A future major bump needs its own encoding, not a doomed registry lookup with pytest.raises(EsphomeError, match="not supported yet"): framework.framework_package_version(cv.Version(4, 0, 0)) - # Cores up to 2.6.2 use other encodings; the helper is total, not wrong, - # and its boundary matches the PlatformIO era guard: a 2.6.2 pre-release - # sorts above 2.6.2 and keeps the package-major-3 encoding + # The boundary matches the PlatformIO era guard; a 2.6.2 pre-release + # keeps this encoding with pytest.raises(EsphomeError, match="older package encoding"): framework.framework_package_version(cv.Version(2, 6, 2)) assert framework.framework_package_version(cv.Version(2, 6, 2, "b1")) == "3.20602.0" @@ -102,9 +101,8 @@ def test_get_build_env_prepends_toolchain_bin(tmp_path: Path) -> None: def test_ccache_path_delegates_uncached( monkeypatch: pytest.MonkeyPatch, ) -> None: - """The wrapper delegates to the shared policy (covered in - build_helpers/test_ccache.py) on every call: the env/PATH decision - must not freeze for the process lifetime in a long-lived host.""" + """Delegates on every call; the env/PATH decision must not freeze for + the process lifetime.""" monkeypatch.delenv("ESPHOME_CCACHE_ENABLE", raising=False) with patch.object( framework, "resolve_ccache_path", return_value="/usr/bin/ccache" diff --git a/tests/unit_tests/test_writer.py b/tests/unit_tests/test_writer.py index 6c05fc330b..9ccfc4f4ab 100644 --- a/tests/unit_tests/test_writer.py +++ b/tests/unit_tests/test_writer.py @@ -1051,8 +1051,6 @@ def test_clean_all_removes_global_arduino8266_install( config_dir = tmp_path / "config" config_dir.mkdir() - from esphome.writer import clean_all - with caplog.at_level("INFO"): clean_all([str(config_dir)])