From 5ae2baa6189b6bc40795353130a95cfe7fbce65c Mon Sep 17 00:00:00 2001 From: engineer Date: Mon, 12 Oct 2026 08:38:13 +0100 Subject: [PATCH] docs(installed-apps): the -3 output shape is documented, not observed (t62 nit c) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The mark t2's acceptance (c) asked for lived in connection.py's discovery section and the README, but the parser for that output is this module, so a reader looking at the parser met the claim ("the real output has one `package:` per line") without its provenance. It is now stated where that reader starts: the module docstring carries a "MARK — documented, not observed (t62 nit c)" paragraph saying that `pm list packages -3` printing `package:` lines and `resolve-activity --brief` printing `package/activity` are Android's documented shapes, not a captured run — no real Shield was available when discovery was written (t57), and no fixture in this repo captures either command — and `parse_package_list`'s tolerance note now points at that mark instead of calling the shape "real". Wording mirrors the state=6 buffering inference (ha_adb_common/media_session.py, echoed in media_player.py) and the existing connection.py mark. Docstrings only: stripping every docstring leaves an AST identical to HEAD's, so no behaviour changes. The two existing marks stay accurate and are untouched (connection.py still says the shapes are Android's documentation and the parsers in ha_adb_common.installed_apps are deliberately tolerant; the README still marks every discovery output shape as documented-not-observed). --- .../ha_adb_common/installed_apps.py | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/custom_components/nvidia_shield/ha_adb_common/installed_apps.py b/custom_components/nvidia_shield/ha_adb_common/installed_apps.py index 44ce0f5..717cfd3 100644 --- a/custom_components/nvidia_shield/ha_adb_common/installed_apps.py +++ b/custom_components/nvidia_shield/ha_adb_common/installed_apps.py @@ -25,6 +25,19 @@ its 24 h cache (``ShieldConnectionManager.app_label``), so discovery adds no second naming mechanism. Icons are best effort and explicitly heuristic — see ``icon_for_package``. + +MARK — documented, not observed (t62 nit c): the output SHAPES this module parses +— ``pm list packages -3`` printing ``package:`` lines, and +``resolve-activity --brief`` printing ``package/activity`` — are Android's +documentation, not a captured run. No real Shield was available when discovery was +written (t57), and no fixture in this repo is a device capture of either command +(``tests/fixtures`` holds activity, wakefulness and media-session dumps instead), so +everything below is exercised from the hand-built fixtures in +``tests/test_installed_apps.py``. That is why the parsers are deliberately tolerant: +an output shape we have never seen degrades to an empty list rather than to a wrong +one. Same mark as the state=6 buffering inference — the dataclass note in +``ha_adb_common/media_session.py``, echoed in ``media_player.py`` — and as the +discovery section of ``connection.py``. """ from __future__ import annotations @@ -46,8 +59,9 @@ _LAUNCHER_NOISE = ("com.android.tv.settings",) def parse_package_list(output: str | None) -> list[str]: """The package ids in a ``pm list packages`` dump, in device order. - Tolerant on purpose: the real output has one ``package:`` per line, and - a shell that prepends noise (adb banners, warnings) must not lose the list. + Tolerant on purpose: the documented output (see the module MARK — the shape is + Android's documentation, not a capture) has one ``package:`` per line, and a + shell that prepends noise (adb banners, warnings) must not lose the list. Duplicates are collapsed, order preserved. """ if not output: