## dumps()


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


Usage

``` python
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](loads.md#cane_format.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](LossyConversionWarning.md#cane_format.LossyConversionWarning) naming each), `"raise"` ([UnrepresentableError](UnrepresentableError.md#cane_format.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](loads.md#cane_format.loads)' defaults. Variant and dialect must be the ones given here.

`lossy: Literal[``"warn", `<span class="st">`"ignore"``]`</span>` = ``"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"`.