md2star.logging module

Central logging surface for md2star (backed by os_helper).

Module summary

Historically md2star scattered print(..., file=sys.stderr) diagnostics across the CLI and the preprocessing modules. This module replaces them with a single, centrally-configured logging surface so verbosity is controlled from one place (--verbose / --quiet) rather than hard-wired at every call site.

The split it enforces is deliberate: diagnostics (warnings, errors, progress narration) go through this logging surface to stderr, while program output (a rendered document path, the doctor --json payload, the templates list table) stays on print/stdout. Keeping the two streams separate is what lets md2star ... | some-tool keep working — a warning must never land in the piped payload.

The actual logging setup is delegated to os_helper.init_logging() — the suite’s shared logging primitive — in its CLI-friendly mode: a named logger ("md2star"), a bare %(message)s format, a live stderr handler that re-resolves sys.stderr on each emit (so pytest’s capsys and any stream redirection keep working), idempotent so repeated calls never double-print, and propagate=True so caplog and host applications still observe records. Every md2star module gets its logger from get_logger(), whose names are dotted children of "md2star" (md2star.cli, md2star.preprocessing.lint, …) and therefore inherit that configuration.

Usage example

>>> from md2star.logging import configure, get_logger
>>> configure(verbose=False, quiet=False)   # once, at CLI startup
>>> log = get_logger(__name__)
>>> log.warning("md2star: falling back to the bundled template")

Author

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

md2star.logging.configure(*, verbose=False, quiet=False)

Configure the root "md2star" logger once, idempotently, via os_helper.

Delegates to os_helper.init_logging() in its named-logger + live-stderr mode, which attaches exactly one stderr handler and re-resolves sys.stderr on each emit (so capsys / redirection keep working). Repeated calls are a no-op on the handler set, so re-entry (PDF → DOCX, batch conversions) never double-prints.

Parameters:

• verbose (bool, optional) – When true, lower the threshold to DEBUG (show everything).

• quiet (bool, optional) – When true, raise the threshold to ERROR (suppress info + warnings). quiet wins if, defensively, both flags are set.

Returns:

The configured root md2star logger (handy for tests and callers).

Return type:

logging.Logger

Notes

The default level (neither flag) is INFO so that every message that used to be printed unconditionally in the print era stays visible — this migration is behaviour-preserving by default. Diagnostics always go to stderr so they never contaminate stdout output.

md2star.logging.get_logger(name='md2star')

Return the md2star logger for name.

Parameters:

name (str, optional) – Logger name. Pass __name__ from a module so the returned logger is a dotted child of "md2star" (the default) and inherits the level + handler installed by configure().

Returns:

The per-name singleton logger (logging.getLogger caches by name).

Return type:

logging.Logger

Examples

>>> get_logger("md2star.cli").name
'md2star.cli'