protonfs.commands.doctor module

protonfs doctor — check that this host can actually run proton-drive.

Written for the headless case, because that is where everything that “just works” on a desktop quietly stops working: no session bus, no Secret Service, or a Secret Service whose default collection is sealed with a password from a graphical login that this user will never perform. Each check reports what it found; –fix additionally bootstraps the keyring rather than only describing the problem.

Added in version 1.0.0.

class protonfs.commands.doctor.Check(name, ok, detail, hint=None, warn=False)

Bases: object

One doctor check result.

Variables:

• name – short label for the thing checked (e.g. "session bus").

• ok – whether the check passed; only ok=False fails doctor’s exit code.

• detail – the concrete finding shown after the label.

• hint – optional remediation advice, printed under the result.

• warn – render as [warn] rather than [ok] – advisory only, never fails the exit code; meaningful only alongside ok=True.

detail: str

hint: str | None = None

name: str

ok: bool

warn: bool = False

protonfs.commands.doctor.doctor(fix=False)

Run the checks, print them, and return whether the host can run proton-drive.

Parameters:

fix (bool) – when true, bootstrap the keyring rather than only reporting on it.

Return type:

bool

Returns:

True when every check passed (warnings allowed).

See also

run_doctor() (the checks) and render() (the output).

protonfs.commands.doctor.pass_store_drive_compat_check(drive)

Fail when the active store is pass but the installed proton-drive predates it.

proton-drive only honours PROTON_DRIVE_CREDENTIALS_STORE=pass from PASS_STORE_MIN_DRIVE; an older binary silently ignores it and uses its keychain store, so the managed pass store protonfs set up is never read. Only meaningful on the pass path (the caller invokes it inside that branch).

Return type:

Check

protonfs.commands.doctor.render(checks, console_echo=<function echo>)

Print each check as [ok]/[warn]/[FAIL] and return overall success.

Parameters:

• checks (list[Check]) – the results from run_doctor().

• console_echo – sink for each line (defaults to click.echo(); overridable for tests).

Return type:

bool

Returns:

True when no check failed ([warn] results do not count as failures).

protonfs.commands.doctor.repo_currency_checks(root)

Inside a protonfs root: index schema version, pending repo-state migrations (#67 registry), and config layering sanity. Empty when root is not a protonfs root – there is nothing to check.

Return type:

list[Check]

protonfs.commands.doctor.run_doctor(fix=False, root=None)

Run every doctor check and return the results (does not print anything).

Covers the runtime environment (proton-drive binary, D-Bus session bus, Secret Service keyring) and, from #73, version/state currency (support matrix, upstream advisory, index schema, pending migrations, config layering).

Parameters:

• fix (bool) – when true, actively bootstrap the keyring rather than only reporting on it.

• root (Path | None) – the directory whose repo-currency is checked; defaults to the cwd.

Return type:

list[Check]

Returns:

the ordered list of Check results.

See also

render() to print these, doctor() for the full command.

protonfs.commands.doctor.shell_exports()

VAR=value lines that make the current shell match the environment protonfs hands proton-drive (the resolved credentials store: bus for keychain, or the pass vars). Only needed to run the proton-drive binary by hand; every protonfs command sets this up for itself.

Return type:

list[str]

protonfs.commands.doctor.upstream_currency_check(upstream_fetch=None)

Advisory on upstream’s Stable release vs highest_supported() – same message contract as protonfs upgrade (#66). Fails soft offline: an unreachable manifest is an [ok] ‘unknown’, never a failure.

Return type:

Check

protonfs.commands.doctor.version_currency_check(drive)

proton-drive’s installed version against this release’s support matrix (#65): ok at highest_supported(), warn when older-but-supported, fail when unsupported or unparseable.

Return type:

Check