md2star.errors module

md2star — typed exceptions for the CLI / pipeline.

Two purposes:

1. Carry an actionable hint. Every subclass takes a hint= keyword whose string is printed below the headline error so the user knows what to do, not just what went wrong. The CLI’s top-level handler renders this as a multi-line block (see md2star.cli.handle_known_error()) instead of a Python stacktrace.

2. Mark which failures are “expected”. Anything that subclasses Md2starError is something we predicted and want to render cleanly. Anything else genuinely is a bug and the CLI re-raises with the original traceback so the user can file an issue.

Author

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

exception md2star.errors.ConversionError(message, *, hint=None)

Bases: Md2starError

Pandoc / soffice / mermaid-cli exited non-zero.

Wraps the failing subprocess’s stderr so the user sees the real cause without us re-rendering a Python traceback.

Parameters:

• message (str)

• hint (str | None)

Return type:

None

default_hint: str = 'If the failure mentions a missing engine (xelatex, soffice, mmdc), install it and re-run. Otherwise the file `--verbose` above contains the full pandoc / soffice stderr.'

exception md2star.errors.InvalidInputError(message, *, hint=None)

Bases: Md2starError

Input file doesn’t exist, isn’t readable, or has a wrong extension.

Parameters:

• message (str)

• hint (str | None)

Return type:

None

default_hint: str = 'md2star accepts a single .md / .markdown file. Pass the path as the first positional argument.'

exception md2star.errors.Md2starError(message, *, hint=None)

Bases: Exception

Base class for every md2star-defined, user-actionable error.

The CLI top-level handler renders these with the hint string on a second line and exits non-zero. Subclasses set a sensible hint default so callers don’t have to repeat the boilerplate.

Parameters:

• message (str)

• hint (str | None)

Return type:

None

default_hint: str = ''

exception md2star.errors.MissingDependencyError(message, *, hint=None)

Bases: Md2starError

Required external program (pandoc, soffice, node, …) not found on PATH.

Raised when md2star is about to invoke a system binary that is not installed. Carries the binary name and the suggested install command.

Parameters:

• message (str)

• hint (str | None)

Return type:

None

default_hint: str = 'Run `md2star doctor` for a full environment report and install instructions per platform.'

exception md2star.errors.RemoteResourceDisabledError(message, *, hint=None)

Bases: Md2starError

An online fetch was needed but blocked by –offline.

Remote images stay opt-in (--allow-remote-images). Remote templates are fetched by default (v2.5.0+); --offline is the hard kill-switch that blocks every network touch, and the CLI surfaces that here.

Parameters:

• message (str)

• hint (str | None)

Return type:

None

default_hint: str = 'md2star fetches remote resources it needs, but --offline is on. Drop --offline (and use --allow-remote-images for remote images) to allow the fetch, or keep --offline to make the rejection explicit in scripts.'

exception md2star.errors.TemplateNotFoundError(message, *, hint=None)

Bases: Md2starError

Requested reference template (template.docx / template.pptx) not located.

Distinct from a missing bundled template (which is a MissingDependencyError because it means the wheel is corrupted). This one fires when the user asks for a template that isn’t where they said it’d be.

Parameters:

• message (str)

• hint (str | None)

Return type:

None

default_hint: str = 'Run `md2star templates list` to see which templates are discoverable, or pass --reference-doc /path/to/template.docx explicitly.'

exception md2star.errors.UnsafePathError(message, *, hint=None)

Bases: Md2starError

Filesystem path escapes the operation’s sandbox (GUI folder browser).

Parameters:

• message (str)

• hint (str | None)

Return type:

None

default_hint: str = "Paths supplied to the GUI's /fs/* endpoints must stay inside the open folder root. `..` segments, absolute paths, and symlinks that resolve outside the root are rejected."