app.domain.frontmatter

YAML frontmatter splitting and loading for Markdown ADR files.

A document has frontmatter when its first line is ---; the block ends at the next line that is --- (or ...). YAML is loaded with a yaml.SafeLoader variant that does not turn unquoted dates into datetime.date objects: decision-date: 2024-13-01 would otherwise make the whole block unparseable. Dates stay strings and are validated by app.domain.records.

Public API:

type app.domain.frontmatter.JsonValue = str | int | float | bool | None | list[JsonValue] | dict[str, JsonValue]
class app.domain.frontmatter.FrontmatterSplit(yaml_text, body, unclosed=False)

Bases: object

Result of splitting a document into frontmatter and body.

Parameters:

  • yaml_text (str | None) – Text between the delimiters, or None when the document has no (closed) frontmatter block.

  • body (str) – Markdown body. The whole text if there is no block.

  • unclosed (bool) – True when an opening --- has no closing line.

yaml_text: str | None
body: str
unclosed: bool
class app.domain.frontmatter.LoadedFrontmatter(fields, issue=None)

Bases: object

Result of loading a frontmatter block.

Parameters:

  • fields (dict[str, object]) – The parsed mapping (empty on failure).

  • issue (Issue | None) – A bad_yaml issue when loading failed, else None.

fields: dict[str, object]
issue: Issue | None
app.domain.frontmatter.split_frontmatter(text)

Split canonical (LF-only) text into frontmatter and body.

Parameters:

text (str) – Canonical document text.

Return type:

FrontmatterSplit

Returns:

The split result; never raises.

app.domain.frontmatter.load_frontmatter(yaml_text)

Load a frontmatter block as a mapping of field names to values.

Parameters:

yaml_text (str) – The text between the delimiters.

Return type:

LoadedFrontmatter

Returns:

The loaded fields, or an empty mapping plus a bad_yaml issue. Never raises for malformed content.

app.domain.frontmatter.json_safe(value)

Convert a loaded YAML value into a JSON-serialisable value.

Mappings get string keys, sequences and sets become lists, dates use ISO format and any other unexpected scalar is rendered with str.

Parameters:

value (object) – A value produced by the YAML loader.

Return type:

JsonValue

Returns:

An equivalent JSON-serialisable value.