md2star.doctor module

md2star doctor — environment diagnostics.

Two layers, separated on purpose:

Pure logic (run_checks): walks the dependency list, calls shutil.which / subprocess.run / filesystem probes, returns a structured Report dataclass. No printing, no sys.exit, no colour — easy to unit-test via monkeypatch.
CLI renderer (main): formats a Report for a terminal, prints to stdout, and picks an exit code. Exits 0 unless a core dependency (Python interpreter, md2star package, pandoc) is broken; optional missing pieces produce WARNING / INFO lines but do not fail the command.

The output is deliberately scannable: one line per check, status in a fixed-width column on the left, resolved path / version on the right. A “Result” footer summarises which conversion targets actually work in this environment so a returning user can see at a glance whether they need to install anything before reaching for md2docx.

Author

[Warith HARCHAOUI](https://linkedin.com/in/warith-harchaoui/)

class md2star.doctor.Check(name, status, detail='', section='Core')[source]

Bases: object

One row in the doctor’s report.

Parameters:

name (str)
status (str)
detail (str)
section (str)

detail: str = ''

name: str

section: str = 'Core'

status: str

class md2star.doctor.Report(checks=<factory>)[source]

Bases: object

Structured doctor output. The CLI prints it; tests assert on it.

Parameters:: checks (list[Check])

add(name, status, detail='', section='Core')[source]

Append one Check row to the report.

Parameters:

name (str) – Human label shown in the leftmost report column.
status (str) – One of the STATUS_* tokens (OK / WARNING / …).
detail (str, optional) – Free-form right-column text (version, path, or install hint).
section (str, optional) – Display group (Core / Optional / Templates).

Return type:

None

checks: list[Check]

core_failing()[source]

True iff any check in the Core section is worse than WARNING.

Return type:: bool

feature_status(fmt)[source]

Return OK / PARTIAL / UNAVAILABLE for a conversion target.

docx — needs pandoc. pptx — needs pandoc. pdf — needs pandoc + soffice. mermaid — needs node + (mermaid-cli or npx).

Parameters:: fmt (str)
Return type:: str

get(name)[source]

Return the first check matching name, or None if absent.

Parameters:: name (str) – The Check.name to look up.
Returns:: The matching row, or None when no check carries that name.
Return type:: Check | None

md2star.doctor.main(argv=None)[source]

Console entry point: md2star doctor.

Parameters:: argv (list[str] | None)
Return type:: int

md2star.doctor.render(report)[source]

Format report as a human-readable multi-section string.

Parameters:: report (Report)
Return type:: str

md2star.doctor.run_checks(which=None)[source]

Walk every check and return a Report.

which defaults to shutil.which(); tests inject a fake to simulate “pandoc missing” / “soffice present” combinations without touching the real PATH.

Parameters:: which (Callable[[str], str | None] | None)
Return type:: Report