From 6a5a45dd736bad3d289ee0e2d582e3f1748cdc20 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Sat, 22 Aug 2026 23:57:02 -0500 Subject: [PATCH] Trim comments and docstrings --- esphome/espidf/size_summary.py | 19 ++++--------------- tests/unit_tests/test_size_summary.py | 12 ++++-------- 2 files changed, 8 insertions(+), 23 deletions(-) diff --git a/esphome/espidf/size_summary.py b/esphome/espidf/size_summary.py index 1006655791..60b17f6ebc 100644 --- a/esphome/espidf/size_summary.py +++ b/esphome/espidf/size_summary.py @@ -35,8 +35,6 @@ _SIZE_SUFFIXES = {"K": 1024, "M": 1024 * 1024} def _parse_size(token: str) -> int: token = token.strip() if not token: - # A blank size cell is a malformed row; naming it beats a - # meaningless "from 0 bytes" bar downstream raise ValueError("blank partition size cell") if token.startswith(("0x", "0X")): return int(token, 16) @@ -82,16 +80,11 @@ def _format_bar(used: int, total: int) -> str: def print_summary(size_json: Path, partitions_csv: Path | None) -> None: - """Print PlatformIO-shaped RAM and Flash one-liners. - - Failures are non-fatal: the build has already succeeded, we just couldn't - summarize. Logs the cause at debug level. - """ + """Print PlatformIO-shaped RAM and Flash one-liners; never fails the build.""" try: _print_summary(size_json, partitions_csv) except Exception as e: # noqa: BLE001 # pylint: disable=broad-exception-caught - # The named guards below cover the known shapes; this net keeps the - # promise for the rest (nested non-dict values, non-numeric sizes) + # Backstop for shapes the named guards below miss _LOGGER.debug("Skipping size summary: %s", e) @@ -106,8 +99,7 @@ def _print_summary(size_json: Path, partitions_csv: Path | None) -> None: return if not isinstance(data, dict): - # Valid JSON that is not an object (a hand-edited or tool-emitted - # array) has no .get; skip with the file named + # Non-object JSON has no .get _LOGGER.debug("Skipping size summary: unexpected shape in %s", size_json) return @@ -127,10 +119,7 @@ def _print_summary(size_json: Path, partitions_csv: Path | None) -> None: _LOGGER.debug("Skipping Flash summary: %s", e) return if app_size <= 0: - # Defensive backstop behind _parse_size's blank-cell rejection: a - # "from 0 bytes" denominator is meaningless to a reader. Note the - # skip costs CI's memory-impact extraction its Flash match, which - # is the loud outcome a broken partition table deserves. + # Skipping also fails CI's Flash extraction, the right outcome here _LOGGER.debug("Skipping Flash summary: app partition size is 0") return print(f"Flash: {_format_bar(image_size, app_size)}") diff --git a/tests/unit_tests/test_size_summary.py b/tests/unit_tests/test_size_summary.py index efe33dd7d5..3ca476018c 100644 --- a/tests/unit_tests/test_size_summary.py +++ b/tests/unit_tests/test_size_summary.py @@ -142,8 +142,7 @@ def test_print_summary_non_dict_json_is_skipped( def test_print_summary_unreadable_partitions_is_skipped( tmp_path: Path, capsys: pytest.CaptureFixture[str] ) -> None: - """An OSError reading the partition table skips the summary, never the - build (a missing file takes the ValueError path instead).""" + """An OSError reading the partition table skips the summary, not the build.""" size_json = tmp_path / "size.json" size_json.write_text( '{"memory_types": {"DRAM": {"used": 1, "size": 2}}, "image_size": 100}' @@ -166,8 +165,7 @@ def test_print_summary_unreadable_partitions_is_skipped( def test_print_summary_zero_app_partition_is_skipped( tmp_path: Path, capsys: pytest.CaptureFixture[str] ) -> None: - """A partition row parsing to size 0 must not render a 0% bar for CI's - memory-impact extraction to ingest.""" + """A 0-size app partition drops the Flash bar instead of rendering 0%.""" size_json = tmp_path / "size.json" size_json.write_text( '{"memory_types": {"DRAM": {"used": 1, "size": 2}}, "image_size": 100}' @@ -205,8 +203,7 @@ def test_print_summary_happy_path_prints_both_bars( def test_print_summary_nested_bad_shapes_never_raise( tmp_path: Path, capsys: pytest.CaptureFixture[str], payload: dict ) -> None: - """The blanket guard keeps nested non-dict values and non-numeric sizes - from raising past a linked build.""" + """The blanket guard keeps unexpected nested shapes from raising.""" size_json = _write_size_json(tmp_path, payload) print_summary(size_json, None) assert "Traceback" not in capsys.readouterr().err @@ -215,8 +212,7 @@ def test_print_summary_nested_bad_shapes_never_raise( def test_print_summary_blank_size_cell_names_the_row( tmp_path: Path, capsys: pytest.CaptureFixture[str] ) -> None: - """A blank size cell is reported as the malformed input it is, via the - ValueError path, instead of parsing to 0.""" + """A blank size cell raises ValueError instead of parsing to 0.""" size_json = _write_size_json( tmp_path, {"memory_types": {"DRAM": {"used": 1, "size": 2}}, "image_size": 100},