md2star.doctor module

md2star doctor, environment diagnostics.

Two layers, separated on purpose:

1. 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.

2. 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')

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>)

Bases: object

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

Parameters:

checks (list[Check])

add(name, status, detail='', section='Core')

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()

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

Return type:

bool

feature_status(fmt)

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)

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.render(report)

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

This is the one place the report is translated, and deliberately so: the section names double as dictionary keys and the statuses are tokens a script greps, so both stay English in the data and in --json. Only what a person reads goes through the catalogue — and a detail already composed with a version and a path matches no entry, so it passes through untouched while the fixed prose (“Needed for md2pdf…”) does not.

Parameters:

report (Report)

Return type:

str

md2star.doctor.run(*, as_json=False)

Run every check and print the result. Returns the process exit code.

The md2star doctor command’s whole body. It used to own an argparse parser for its one flag; since 3.10.0 click parses that flag (there is one command line in this package) and hands the decision here as a bool.

Parameters:

as_json (bool, optional) – Emit the machine-readable payload instead of the human-readable table. The JSON deliberately stays English: section names double as keys and the statuses are tokens a script greps.

Returns:

1 when a Core check is broken, 0 otherwise — so CI can gate on md2star being usable while tolerating missing optional tools.

Return type:

int

md2star.doctor.run_checks(which=None)

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