docs(installed-apps): the -3 output shape is documented, not observed (t62 nit c)
Release / release (push) Successful in 11s
Test / test (push) Successful in 41s
Test / ha-api-drift (push) Successful in 28s
Test / real-ha-config-flow (push) Successful in 31s

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:<id>` 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:<id>` 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).
This commit is contained in:
engineer committed 2026-10-12 08:38:13 +01:00
1 parent 181a51af95
commit 5ae2baa618
1 file changed
+16 -2
@@ -25,6 +25,19 @@ its 24 h cache (``ShieldConnectionManager.app_label``), so discovery adds no
second naming mechanism. second naming mechanism.
Icons are best effort and explicitly heuristic — see ``icon_for_package``. 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:<id>`` 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 from __future__ import annotations
@@ -46,8 +59,9 @@ _LAUNCHER_NOISE = ("com.android.tv.settings",)
def parse_package_list(output: str | None) -> list[str]: def parse_package_list(output: str | None) -> list[str]:
"""The package ids in a ``pm list packages`` dump, in device order. """The package ids in a ``pm list packages`` dump, in device order.
Tolerant on purpose: the real output has one ``package:<id>`` per line, and Tolerant on purpose: the documented output (see the module MARK — the shape is
a shell that prepends noise (adb banners, warnings) must not lose the list. Android's documentation, not a capture) has one ``package:<id>`` per line, and a
shell that prepends noise (adb banners, warnings) must not lose the list.
Duplicates are collapsed, order preserved. Duplicates are collapsed, order preserved.
""" """
if not output: if not output: