API reference

The public API is small: activate the import hook once, then read what Lucen decided through the fallback report and the errors mode. Everything below is importable from the top-level lucen package.

Activation

lucen.activate(experimental=())

Install the import hook. Idempotent.

lucen.deactivate()

Uninstall the hook; already-imported modules keep their rewrites.

For a script you launch directly, skip activate() and run the file with the lucen run command, which rewrites and executes it in one step.

Reading what happened

lucen.get_fallback_report()

Every fallback recorded so far: one FallbackRecord per block that ran sequentially or downgraded, each with its error, file, line, and reason.

lucen.clear_fallback_report()

Discard all recorded fallback records.

lucen.get_collected_errors(key=None)

Per-iteration exceptions gathered by blocks running under on_error=collect.

With no key, returns a mapping of block key to its collected errors; with a (filename, line) key, returns that block's list.

Error mode

lucen.set_errors_mode(mode)

Set the process-wide fallback mode, by ErrorsMode or its string name.

lucen.get_errors_mode()

Return the current process-wide fallback mode.

lucen.ErrorsMode

Bases: Enum

How a fallback is surfaced: REPORT (default, recorded quietly), QUIET (recorded, no report), or HARD (raised).

Exceptions

lucen.LucenError

Bases: Exception

Base class for every Lucen error; carries the file and line of the marked block it concerns.

lucen.ClauseValueError

Bases: LucenError