session: Reusable In-Process Conversion Sessions#

Session owns a validated configuration snapshot, configured extension load, and one assist seam.

Requests delegate to one typed reader -> degradation -> writer artifact pipeline.

One-shot public functions construct a disposable session instead of using a second pipeline.

One process-wide, fail-fast guard covers both Session setup (including extension registration) and every conversion. The public registries, extensions, and writer instances are process-global, so callers must serialize every Session and one-shot conversion in one Python process.

Reusable In-Process Conversion Sessions.

Session owns a validated configuration snapshot, configured extension load, and one assist seam.

Requests delegate to one typed reader -> degradation -> writer artifact pipeline.

One-shot public functions construct a disposable session instead of using a second pipeline.

One process-wide, fail-fast guard covers both Session setup (including extension registration) and every conversion. The public registries, extensions, and writer instances are process-global, so callers must serialize every Session and one-shot conversion in one Python process.

class myform.session.Session(*, config: MyformConfig | Mapping[str, Any] | None = None, target_path: str | Path | None = None)#

Reuse fixed conversion setup for sequential in-process requests.

Construction discovers or validates configuration once, then takes an independent deep model snapshot, loads its extensions once, and constructs one assist seam. Per-call options remain explicit inputs. The process-wide reader/writer registries, extension set, and writer objects make every Session and disposable public call one shared critical section. An overlap fails rather than claiming thread safety; a failed setup or conversion releases the guard so a later sequential request may proceed.

Parameters:

  • config – A validated config, raw config mapping, or None to discover configuration from target_path once during construction.

  • target_path – Target-oriented path from which to discover config when config is None. It is not consulted again after construction.

convert(text: str, src: str, dst: str, *, options: Mapping[str, Any] | None = None) → str#

Parse src-format text and render it as dst-format text.

Parameters:

  • text – The source document.

  • src – Registered source format name.

  • dst – Registered target format name.

  • options – Explicit per-call options, which override the session snapshot.

Returns:

Rendered target text.

Raises:

  • ArtifactRequiredError – The conversion produced an out-of-band carrier; call convert_artifact so it cannot be discarded.

  • RuntimeError – Another Session setup or conversion is already using process-global myform integration state.

convert_with_report(text: str, src: str, dst: str, *, options: Mapping[str, Any] | None = None) → tuple[str, ConversionReport]#

Convert one document and return its target text plus degradation report.

Parameters:

  • text – The source document.

  • src – Registered source format name.

  • dst – Registered target format name.

  • options – Explicit per-call options, which override the session snapshot.

Returns:

Rendered target text and the complete degradation report.

Raises:

  • ArtifactRequiredError – The conversion produced an out-of-band carrier; call convert_artifact so it cannot be discarded.

  • RuntimeError – Another Session setup or conversion is already using process-global myform integration state.

convert_artifact(text: str, src: str, dst: str, *, options: Mapping[str, Any] | None = None) → ConversionArtifact#

Convert one document without discarding out-of-band enclave carriers.

Parameters:

  • text – The source document.

  • src – Registered source format name.

  • dst – Registered target format name.

  • options – Explicit per-call options, which override the session snapshot.

Returns:

Target text, complete degradation report, and every addressed carrier.

Raises:

RuntimeError – Another Session setup or conversion is already using process-global myform integration state.

convert_in_collection(text: str, src: str, dst: str, *, collection: Collection, origin: str = '', link_style: str = 'path', link_suffix: str = '', options: Mapping[str, Any] | None = None) → tuple[str, ConversionReport, ResolutionReport]#

Convert one member of a collection, resolving its cross-document references.

The same pipeline convert_with_report runs, with the resolution pass active: references to sibling documents become concrete before the degradation engine sees them, so a construct that would otherwise be carried or dropped is rendered natively instead.

Parameters:

  • text – The source document.

  • src – Registered source format name.

  • dst – Registered target format name.

  • collection – The collection text belongs to.

  • origin – text’s own doc id, which relative references resolve against.

  • link_style – 'path' to rewrite ordinary links to output locations, 'doc-id' to rewrite them to canonical collection-rooted ids (see myform.collect.LinkStyle). Target-native wiki references retain their dialect’s own rooted-path semantics.

  • link_suffix – Extension appended to output stems under 'path' ('.html', …).

  • options – Explicit per-call options, which override the session snapshot.

Returns:

Rendered target text, the degradation report, and the resolution report – three values rather than two, because a reference the collection could not resolve is a different kind of finding from a construct the target could not express.

Raises:

  • ArtifactRequiredError – The conversion produced an out-of-band carrier; this legacy collection return shape cannot carry it.

  • RuntimeError – Another Session setup or conversion is already using process-global myform integration state.

format(text: str, format_name: str = 'myst', *, options: Mapping[str, Any] | None = None) → str#

Format text through an identity conversion in format_name.

Parameters:

  • text – The document to format.

  • format_name – Registered format used as both source and target.

  • options – Explicit per-call options, which override the session snapshot.

Returns:

Formatted text.