Tool need: read every Steam library
Some checks are pending
md-naming / markdown naming convention (push) Waiting to run
pre-commit / pre-commit (${{ matrix.group }}) (mypy, mypy, ) (push) Waiting to run
pre-commit / pre-commit (${{ matrix.group }}) (pylint, pylint, ) (push) Waiting to run
pre-commit / pre-commit (${{ matrix.group }}) (rest, , mypy,pylint,dependency-freshness) (push) Waiting to run
Tests / test (push) Waiting to run
Tests / web-coverage (push) Waiting to run
repo-contract / repo contract (push) Waiting to run

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Krzysztof Rudnicki 2026-11-22 15:04:27 +01:00
parent 01d750f36d
commit 19954a1eae
6 changed files with 241 additions and 13 deletions

View File

@ -3,8 +3,9 @@
Steamworks Common Redistributables, Steam Linux Runtime 4.0 and Proton
Experimental stay in :data:`PROTECTED_APP_IDS`, so no sweep or guard ever
treats them as an unauthorized game. This module names the one case where they
may still go (kuhy's rule): Steam is closed, and every installed game is mapped
to ``proton-cachyos-native``, which is itself installed.
may still go (kuhy's rule): Steam is closed, no steam-game-installer run is
live, and every installed game in every library is mapped to
``proton-cachyos-native``, which is itself installed.
An earlier version removed Steam Linux Runtime 4.0 while a game needed it, so
every doubt (a read error, a malformed file, a missing key, an exception)
@ -15,6 +16,7 @@ the file or an AppID, never a line of it.
from __future__ import annotations
from dataclasses import dataclass
from pathlib import Path
import re
from typing import TYPE_CHECKING, Final
@ -22,10 +24,11 @@ from steam_backlog_enforcer import _steam_state
from steam_backlog_enforcer._fail_safe import FAIL_SAFE_ERRORS
from steam_backlog_enforcer._protected_apps import PROTECTED_APP_IDS
from steam_backlog_enforcer._steam_client import steam_client_running
from steam_backlog_enforcer._steam_restart_guard import fast_install_running
from steam_backlog_enforcer._vdf_text import VdfNode, lookup, parse_vdf
if TYPE_CHECKING:
from pathlib import Path
from collections.abc import Iterable
STEAM_TOOLS: Final = {
228980: "Steamworks Common Redistributables",
@ -66,14 +69,62 @@ def _compat_mapping(steam_root: Path) -> dict[str, VdfNode] | ToolNeed:
return mapping
def _libraries(steamapps: Path) -> list[tuple[str, Path]] | ToolNeed:
"""Every library's steamapps, keyed as libraryfolders.vdf names them.
The default library always comes first. A missing libraryfolders.vdf means
it is the only one; one that exists but cannot be used keeps the tools.
"""
libraries = [("default", steamapps)]
folders = steamapps / "libraryfolders.vdf"
if not folders.exists():
return libraries
try:
text = folders.read_text(encoding="utf-8")
except OSError, UnicodeDecodeError:
return _keep("libraryfolders.vdf unreadable")
try:
block = lookup(parse_vdf(text), "libraryfolders")
except ValueError:
return _keep("libraryfolders.vdf malformed")
if not isinstance(block, dict):
return _keep("libraryfolders.vdf has no libraryfolders block")
for key, entry in block.items():
if not key.isdigit():
continue # e.g. the old format's "TimeNextStatsReport"
# Old Steam wrote "1" "<path>"; current Steam a block with "path".
path = entry if isinstance(entry, str) else lookup(entry, "path")
if not isinstance(path, str) or not path:
return _keep(f"library {key} has no path")
libraries.append((key, Path(path) / "steamapps"))
return libraries
def _manifests(libraries: Iterable[tuple[str, Path]]) -> list[Path] | ToolNeed:
"""Every appmanifest in *libraries*, or the reason to keep the tools."""
found: list[Path] = []
for key, steamapps in libraries:
# iterdir, not glob: glob reads an unlistable directory as empty,
# which would read as "no game installed".
try:
entries = sorted(steamapps.iterdir())
except OSError:
return _keep(f"library {key} steamapps unlistable")
found += [e for e in entries if _MANIFEST.fullmatch(e.name)]
return found
def _unmapped(steamapps: Path, mapping: dict[str, VdfNode]) -> ToolNeed | int:
"""The reason to keep the tools, or how many installed games are mapped."""
games = 0
# iterdir, not glob: glob reads an unlistable directory as empty, which
# would read as "no game installed".
for manifest in sorted(steamapps.iterdir()):
if not _MANIFEST.fullmatch(manifest.name):
continue
libraries = _libraries(steamapps)
if isinstance(libraries, ToolNeed):
return libraries
manifests = _manifests(libraries)
if isinstance(manifests, ToolNeed):
return manifests
# A library listed twice (the default is usually key "0") counts once.
games: set[str] = set()
for manifest in manifests:
try:
tree = parse_vdf(manifest.read_text(encoding="utf-8"))
except OSError, ValueError:
@ -85,16 +136,28 @@ def _unmapped(steamapps: Path, mapping: dict[str, VdfNode]) -> ToolNeed | int:
continue
if lookup(mapping, app_id, "name") != NATIVE_TOOL:
return _keep(f"AppID={app_id} has no {NATIVE_TOOL} mapping")
games += 1
return games
games.add(app_id)
return len(games)
def _decide(steamapps: Path) -> ToolNeed:
def _busy() -> ToolNeed | None:
"""Why Steam's state is not ours to judge right now, if it is not."""
running = steam_client_running()
if running is None:
return _keep("cannot tell whether Steam runs")
if running:
return ToolNeed(needed=True, reason="Steam running", deferred=True)
# The installer closes Steam while it works, and the game it is landing
# may have no manifest yet. Its /proc scan raising means "cannot tell".
if fast_install_running():
return _keep("fast install running")
return None
def _decide(steamapps: Path) -> ToolNeed:
busy = _busy()
if busy is not None:
return busy
steam_root = steamapps.parent
mapping = _compat_mapping(steam_root)
if isinstance(mapping, ToolNeed):

View File

@ -31,6 +31,7 @@ _RUNNING_BINDINGS = (
"steam_backlog_enforcer.game_install.fast_install_running",
"steam_backlog_enforcer._steam_client.fast_install_running",
"steam_backlog_enforcer._steam_launch.fast_install_running",
"steam_backlog_enforcer._tool_need.fast_install_running",
)

View File

@ -71,3 +71,24 @@ def make_home(
tool_dir.mkdir(parents=True)
(tool_dir / "toolmanifest.vdf").write_text('"manifest"\n{\n}\n')
return steamapps
def add_library(
steamapps: Path, libraries: dict[str, Path], moved: dict[int, Path]
) -> None:
"""Write ``libraryfolders.vdf`` and move games into the extra libraries.
Args:
steamapps: The default library (holds libraryfolders.vdf).
libraries: libraryfolders key -> library root.
moved: Game app id -> the library root its manifest moves to.
"""
blocks = "".join(
f'\t"{key}"\n\t{{\n\t\t"path"\t\t"{path}"\n\t\t"label"\t\t""\n\t}}\n'
for key, path in libraries.items()
)
(steamapps / "libraryfolders.vdf").write_text(f'"libraryfolders"\n{{\n{blocks}}}\n')
for app_id, lib_root in moved.items():
(lib_root / "steamapps").mkdir(parents=True, exist_ok=True)
name = f"appmanifest_{app_id}.acf"
(steamapps / name).rename(lib_root / "steamapps" / name)

View File

@ -100,6 +100,22 @@ def test_unreadable_config_keeps_and_says_why(
assert _messages(caplog) == ["kept Steam tools: config.vdf unreadable"]
def test_fast_install_running_keeps_the_tools(
home: Path, caplog: pytest.LogCaptureFixture
) -> None:
"""A live fast install keeps them with one line saying so."""
steamapps = make_home(home, {10: NATIVE_TOOL})
with (
caplog.at_level(logging.INFO, logger=PKG),
patch(
"steam_backlog_enforcer._tool_need.fast_install_running", return_value=True
),
):
assert remove_unneeded_tools() == 0
assert _tools_left(steamapps) == set(STEAM_TOOLS)
assert _messages(caplog) == ["kept Steam tools: fast install running"]
def test_no_tools_installed_is_silent(
home: Path, caplog: pytest.LogCaptureFixture
) -> None:

View File

@ -79,6 +79,22 @@ def test_unknown_steam_state_keeps(root: Path) -> None:
assert need == ToolNeed(needed=True, reason="cannot tell whether Steam runs")
def test_fast_install_running_keeps(root: Path) -> None:
"""A live steam-game-installer run keeps them: its game may lack a manifest."""
steamapps = make_home(root, {10: NATIVE_TOOL})
with patch(f"{PKG}.fast_install_running", return_value=True):
need = tool_need(steamapps)
assert need == ToolNeed(needed=True, reason="fast install running")
def test_unreadable_proc_keeps(root: Path) -> None:
"""A /proc scan that fails cannot tell, so it keeps them."""
steamapps = make_home(root, {10: NATIVE_TOOL})
with patch(f"{PKG}.fast_install_running", side_effect=PermissionError):
need = tool_need(steamapps)
assert need == ToolNeed(needed=True, reason="check failed (PermissionError)")
@pytest.mark.parametrize("damage", ["directory", "binary", "missing"])
def test_unreadable_config_keeps(root: Path, damage: str) -> None:
"""C22: an unreadable config.vdf keeps the tools and says why."""
@ -148,7 +164,7 @@ def test_unlistable_steamapps_keeps(root: Path) -> None:
shutil.rmtree(steamapps)
steamapps.write_text("not a directory")
assert tool_need(steamapps) == ToolNeed(
needed=True, reason="check failed (NotADirectoryError)"
needed=True, reason="library default steamapps unlistable"
)

View File

@ -0,0 +1,111 @@
"""Tests for _tool_need across every library in libraryfolders.vdf."""
from __future__ import annotations
from typing import TYPE_CHECKING
from unittest.mock import patch
import pytest
from steam_backlog_enforcer._tool_need import NATIVE_TOOL, ToolNeed, tool_need
from steam_backlog_enforcer.tests._tool_home import add_library, make_home
if TYPE_CHECKING:
from collections.abc import Iterator
from pathlib import Path
PKG = "steam_backlog_enforcer._tool_need"
ALL_MAPPED = ToolNeed(
needed=False, reason=f"every installed game runs on {NATIVE_TOOL}"
)
@pytest.fixture(name="root")
def fixture_root(tmp_path: Path) -> Path:
"""A fixture Steam root (conftest already owns tmp_path/steamapps)."""
return tmp_path / "Steam"
@pytest.fixture(autouse=True)
def _steam_closed() -> Iterator[None]:
"""Steam is closed unless a test says otherwise: never ask the live pgrep."""
with patch(f"{PKG}.steam_client_running", return_value=False):
yield
def test_mapped_game_in_a_second_library(root: Path, tmp_path: Path) -> None:
"""A mapped game in another library still lets the tools go."""
steamapps = make_home(root, {10: NATIVE_TOOL, 50: NATIVE_TOOL})
add_library(steamapps, {"0": root, "1": tmp_path / "lib"}, {50: tmp_path / "lib"})
assert tool_need(steamapps) == ALL_MAPPED
def test_unmapped_game_in_a_second_library_keeps(root: Path, tmp_path: Path) -> None:
"""An unmapped game in another library keeps them."""
steamapps = make_home(root, {10: NATIVE_TOOL, 50: None})
add_library(steamapps, {"0": root, "1": tmp_path / "lib"}, {50: tmp_path / "lib"})
assert tool_need(steamapps) == ToolNeed(
needed=True, reason=f"AppID=50 has no {NATIVE_TOOL} mapping"
)
def test_legacy_string_entries_are_scanned(root: Path, tmp_path: Path) -> None:
"""Old Steam wrote ``"1" "<path>"``; that library is scanned too."""
steamapps = make_home(root, {10: NATIVE_TOOL, 50: None})
add_library(steamapps, {}, {50: tmp_path / "lib"})
(steamapps / "libraryfolders.vdf").write_text(
f'"LibraryFolders" {{ "TimeNextStatsReport" "1" "1" "{tmp_path / "lib"}" }}'
)
assert tool_need(steamapps).reason == f"AppID=50 has no {NATIVE_TOOL} mapping"
def test_listed_library_that_cannot_be_listed_keeps(root: Path, tmp_path: Path) -> None:
"""A listed library whose steamapps is gone keeps them."""
steamapps = make_home(root, {10: NATIVE_TOOL})
add_library(steamapps, {"0": root, "1": tmp_path / "unplugged"}, {})
assert tool_need(steamapps) == ToolNeed(
needed=True, reason="library 1 steamapps unlistable"
)
def test_library_without_a_path_keeps(root: Path) -> None:
"""A library block with no path keeps them."""
steamapps = make_home(root, {10: NATIVE_TOOL})
(steamapps / "libraryfolders.vdf").write_text(
'"libraryfolders" { "1" { "label" "" } }'
)
assert tool_need(steamapps) == ToolNeed(needed=True, reason="library 1 has no path")
@pytest.mark.parametrize(
("damage", "reason"),
[
("directory", "libraryfolders.vdf unreadable"),
("binary", "libraryfolders.vdf unreadable"),
("truncated", "libraryfolders.vdf malformed"),
("no-block", "libraryfolders.vdf has no libraryfolders block"),
],
)
def test_damaged_libraryfolders_keeps(root: Path, damage: str, reason: str) -> None:
"""A libraryfolders.vdf that exists but cannot be used keeps them."""
steamapps = make_home(root, {10: NATIVE_TOOL})
folders = steamapps / "libraryfolders.vdf"
if damage == "directory":
folders.mkdir()
else:
folders.write_bytes(
{
"binary": b'"libraryfolders" { "\xff" }',
"truncated": b'"libraryfolders" { "0"',
"no-block": b'"other" { }',
}[damage]
)
assert tool_need(steamapps) == ToolNeed(needed=True, reason=reason)
def test_missing_libraryfolders_means_default_only(root: Path, tmp_path: Path) -> None:
"""No libraryfolders.vdf: an unmapped game elsewhere is not seen."""
steamapps = make_home(root, {10: NATIVE_TOOL, 50: None})
add_library(steamapps, {}, {50: tmp_path / "lib"})
(steamapps / "libraryfolders.vdf").unlink()
assert tool_need(steamapps) == ALL_MAPPED