inspect_petri.util

Utility helpers for frontmatter-markdown collections.

Markdown Collections

MarkdownDoc

One .md file’s parsed frontmatter and body.

class MarkdownDoc(BaseModel)

Attributes

id str: Filename stem.
body str: Text after the closing --- (stripped).
metadata dict[str, Any]: Parsed YAML frontmatter (empty if the file has none).
tags list[str]: The tags list from frontmatter, or [].

Methods

to_markdown

Serialize back to frontmatter-markdown text.

Source

def to_markdown(self, *, canary: str | None = BENCHMARK_CANARY) -> str

canary str | None: Comment lines prepended inside the YAML frontmatter block so the file is detectable as benchmark data. Defaults to :data:`BENCHMARK_CANARY`; pass None to omit.

save

Write :meth:to_markdown to path.

Source

def save(self, path: str | Path, *, canary: str | None = BENCHMARK_CANARY) -> None

path str | Path: Destination .md file path.
canary str | None: Forwarded to :meth:to_markdown.

parse_markdown_file

Parse a single frontmatter .md file.

The file may optionally begin with YAML front matter delimited by --- lines. Files without front matter yield an empty metadata dict and the whole file as body.

Source

def parse_markdown_file(path: str | Path) -> MarkdownDoc

path str | Path: Path to a .md file.

read_markdown_directory

Read all .md files from a directory, optionally filtered by tag.

Files are sorted alphabetically by name for deterministic ordering.

Source

def read_markdown_directory(
    directory: str | Path,
    *,
    tags: Sequence[str] | None = None,
) -> list[MarkdownDoc]

directory str | Path: Path to a directory containing .md files.
tags Sequence[str] | None: If given, keep only docs whose frontmatter tags list intersects this set.

write_markdown_directory

Write a collection of :class:MarkdownDoc to <directory>/<id>.md.

Source

def write_markdown_directory(
    docs: Iterable[MarkdownDoc],
    directory: str | Path,
    *,
    clear: bool = False,
) -> None

docs Iterable[MarkdownDoc]: Documents to write.
directory str | Path: Destination directory (created if missing).
clear bool: If True, remove existing *.md files in the directory first so deleted docs don’t linger.