dumps()

Write a document’s entities as CANE text, e.g. for a few-shot example.

Usage

Source

dumps(
    doc,
    *,
    variant,
    context=1,
    handles=False,
    on_unrepresentable="raise",
    on_mismatch="warn",
    parse_options=None,
    lossy="warn",
    dialect=ENGLISH
)

Entities are written in reading order: by start, outer before nested, then by label and ID. Every record is parsed back as loads with parse_options would parse it. A record that would not ground on its own spans (a repeated string without an anchor, an anchor of context units that occurs more than once, a part that reads as two) is still written as is and handled by on_mismatch. Two entities that would give the same record are written once, with the lossy warning.

Parameters

doc: Document

The document to write.

variant: Variant | str

"base", "disco", "context" or "full".

context: int = 1

Anchor size in whitespace-separated units on each side (anchored variants).

handles: bool = False

Prefix each record with a handle T1, T2, … in output order.

on_unrepresentable: OnUnrepresentable = "raise"

What to do with an entity the variant cannot express (no label, a label that is not one token, or discontinuous in Base/Context): "raise", or "skip", "first" (first span only) or "hull" (one span covering the gaps), which warn. Entities with label problems are skipped by any of these.

on_mismatch: OnMismatch = "warn"

A record that does not parse back on its own spans: "warn" (one LossyConversionWarning naming each), "raise" (UnrepresentableError), or "ignore" (the check is not run).

parse_options: ParseOptions | None = None

How the output will be parsed (match, prefer_whole_words, anchor_fallback, …); by default loads’ defaults. Variant and dialect must be the ones given here.

lossy: Literal["warn", "ignore"] = "warn"

"warn" once about information CANE cannot carry, or "ignore".

dialect: Dialect = ENGLISH

The surface vocabulary.

Raises

UnrepresentableError

An entity cannot be written and no strategy allows dropping it, or a record does not parse back and on_mismatch="raise".